A home for your agents.
Self-hosted AI agent runtime — personal assistants, autonomous workers, and everything in between.
Setup Guide · Architecture · Configuration · Worker Guide · API Reference
Nerve is a self-hosted runtime for AI agents, built around the Claude Agent SDK. It gives agents everything they need to be useful long-term: persistent memory, scheduled execution, task management, learnable skills, and channels to reach you through — web UI, Telegram, or autonomous cron jobs.
Ship a personal assistant that develops a personality, remembers your preferences, and manages your inbox. Or deploy a worker agent that monitors your CI, reviews PRs, and fixes flaky tests — all plan-driven with human approval. Same engine, different mission.
curl -fsSL https://raw.githubusercontent.com/ClickHouse/nerve/main/install.sh | bash
The installer handles everything — installs dependencies (Python, Node.js, uv), clones the repo, builds the web UI, and launches the interactive setup wizard.
nerve upgrade
nerve restart
Runs git pull
, reinstalls Python deps, and rebuilds the web UI in one shot. Use --no-pull
, --no-deps
, or --no-frontend
to skip steps. For Docker deployments, rebuild the image instead: git pull && docker compose build && docker compose up -d
.
No API key? Use your Claude subscription instead
A full-featured assistant for one human. Syncs your email, remembers your preferences, develops personality over time. Comes with a web UI, Telegram bot, memory, cron jobs, and notifications out of the box.
"You're not a chatbot. You're becoming someone."— from the Personal SOUL template
- Workspace files define personality (
SOUL.md
), identity (IDENTITY.md
), and user context (USER.md
) - Memory categories are life-oriented: relationships, finances, travel, health, work
- Default crons: inbox processor, task planner, memory maintenance
- The agent develops opinions, follows up on past conversations, and gets better the longer you use it
A task-focused autonomous agent for teams or programmatic deployment. Monitors something, proposes fixes, implements after approval. Plan-driven with a full audit trail.
"You're a specialist, not a script."— from the Worker SOUL template
Self-configuring: give it a plain-English task description and it researches, writes its ownTASK.md
, creates skills, sets up cron jobs, and starts working- Memory categories are operational: patterns, procedures, decisions, approvals, infrastructure
- No
IDENTITY.md
orUSER.md
— workers execute a mission, not build a relationship - Built for reliability: plan before acting, verify after executing, log everything
nerve init --mode worker
🧠 Memory that persists | Dual-layer memory: curated hot memory loaded every session + semantic search over your entire history. Agents remember context, preferences, and lessons learned — permanently. | 🔧 Self-evolving skills | Agents watch for repeated workflows and propose reusable skills automatically. Skills are plain Markdown — agents read, create, and improve their own procedures over time. | 📋 Autonomous task planning | A background planner explores open tasks, researches codebases, and proposes implementation plans — without being asked. You review and approve; the agent executes. | 📡 Multi-source awareness | Gmail, GitHub, and Telegram flow into a unified inbox with Kafka-style cursors. Multiple consumers process the same data independently — inbox triage, digest generation, task extraction. | ⚡ Single process, zero ops | No Docker required, no message queues, no service mesh. FastAPI + uvicorn + asyncio. Runs on a Raspberry Pi. | 🔑 No API key required | Optional OAuth proxy routes through your Claude Max/Pro subscription. Zero API costs. | 🔄 Session persistence | Sessions survive server restarts. Fork conversations, resume from any point, run up to 4 concurrent agent sessions. | 🛡️ Human-in-the-loop | Agents can mid-turn to ask questions via any channel. Plans require approval before execution. Destructive actions need explicit consent. |
Every channel shares the same agent engine, memory, and tools.
Full React + Vite + TailwindCSS frontend served by FastAPI. Real-time streaming over WebSocket.
- Chat with session history, branching, and resume
- Inline diff viewer for file changes (no git required)
- Task manager, memory browser, skill editor
- Source inbox, notification center, cron logs
- Plan review with approval/decline/revision workflow
- JWT auth, self-signed HTTPS via mkcert
Powered by python-telegram-bot
v21+.
- Streaming responses via edit-in-place
- Inline keyboard buttons for interactive tool questions
/reply
command for free-text answers- Configurable DM policy (
open
orpairing
)
Scheduled AI sessions via APScheduler. Three session modes:
| Mode | Behavior |
|---|---|
| Isolated | |
| Fresh session per run. No prior context. Best for briefings, cleanup, reports. | |
| Persistent | |
| Accumulates context across runs. Optional rotation to manage token usage. Reminder mode for lightweight follow-ups. | |
| Main | |
| Runs inside the user's primary conversation — full context access. |
Built-in crons (personal mode): skill-extractor
(12h), skill-reviser
(weekly), inbox-processor
(15min), task-planner
(4h). Worker mode ships with skill-reviser
, skill-extractor
, and task-planner
by default; additional crons are configured during onboarding.
Cursor-based data ingestion pipeline. Each source runs as an independent APScheduler job.
Telegram— Telethon user-account API (updates.getDifference
)Gmail—gog
CLI with 2-step fetch and LLM condensationGitHub Notifications—gh api
enriched with PR/issue contentGitHub Events— Pushes, PRs, reviews, comments
Multiple independent consumers read the same inbox at their own pace. Content is prefixed with untrusted-data warnings to prevent prompt injection.
Two layers, one seamless experience.
L1 — Hot Memory (MEMORY.md) Curated facts injected into every system prompt. Active projects, current deadlines, operational lessons. Tagged with dates, automatically evicted when stale.
L2 — Deep Memory (memU) Semantic search over everything — conversations, facts, preferences, events. SQLite-persisted. Uses vector embeddings when an OpenAI key is configured, or LLM-based ranking with Anthropic models only.
- Four memory types:
profile
,event
,knowledge
,behavior
- Automatic conversation indexing on session close
- Pre-recall: relevant memories injected into system prompt when sessions start
- 3-level quality filtering prevents generic facts from polluting memory
- Semantic deduplication (cosine similarity 0.85 threshold)
- Full audit log of all mutations
Memory categories adapt to mode — personal agents track relationships, health, and finances; workers track patterns, procedures, and approvals.
Markdown files backed by SQLite FTS5 full-text search.
- Statuses:
pending
→in_progress
→done
/deferred
- Duplicate detection: exact URL match + fuzzy FTS fallback
- Escalation reminders: deadline → +30min follow-up → +2h URGENT (respects quiet hours)
- Full markdown editor in the web UI
The agent's procedural knowledge. Pure Markdown files that agents read, create, and update themselves.
workspace/skills/
└── my-skill/
├── SKILL.md # Instructions (YAML frontmatter + markdown)
├── references/ # On-demand documentation
├── scripts/ # Executable code (30s timeout)
└── assets/ # Supporting files
- Progressive disclosure: only name + description in system prompt; full content loaded on demand
skill-extractor
cron proposes new skills from repeated workflowsskill-reviser
cron reviews existing skills for accuracy- Usage statistics tracked per skill
Proactive task planning with human-in-the-loop approval.
- Planner cron picks open tasks autonomously
- Agent explores codebase, researches approaches, proposes implementation plan
- User reviews → approves / declines / requests revision
- Approved plans spawn implementation sessions automatically
Revisions happen in the same persistent planner session — full context preserved.
Async communication between agent and human, delivered to both web UI and Telegram.
— Fire-and-forget alerts (status updates, completions, reminders)notify
— Questions with predefined options, rendered as buttonsask_user
- Priority levels:
urgent
,high
,normal
,low
nerve (single Python process)
│
├── Gateway (FastAPI)
│ ├── REST API — sessions, tasks, memory, plans, sources, diagnostics
│ ├── WebSocket — real-time streaming, answer routing
│ └── Static files — serves the React web UI
│
├── Agent Engine (Claude Agent SDK)
│ ├── ~30 custom MCP tools (tasks, memory, skills, sources, notifications)
│ ├── Interactive mid-turn pausing (AskUserQuestion, plan approval)
│ ├── File snapshot hooks → session-scoped diffs without git
│ ├── Session lifecycle: created → active → idle → stopped → archived
│ └── Up to 4 concurrent sessions (configurable)
│
├── Channels
│ ├── Web — passive WebSocket channel
│ └── Telegram — bot with streaming + inline keyboards
│
├── Cron (APScheduler)
│ ├── AI jobs (isolated / persistent / main session modes)
│ └── Source sync jobs (Telegram, Gmail, GitHub)
│
├── Memory
│ ├── File-based hot memory (L1)
│ └── memU semantic index (L2, SQLite + embeddings)
│
├── Tasks — Markdown + SQLite FTS5
├── Skills — Filesystem + DB index + usage tracking
├── Plans — SQLite with approval workflow
├── Notifications — Multi-channel delivery
└── Proxy (optional) — Claude OAuth, no API key needed
Two config files:
config.yaml
— Template settings (committed)config.local.yaml
— Secrets and overrides (gitignored)
See docs/config.md for all options.
Python3.13+uv(recommended package manager)Node.js18+ (for web UI build)Claude Code CLI(bundled withclaude-agent-sdk
)- Anthropic API key or Claude subscription viaCLIProxyAPIproxy - Optional: OpenAI API key (for vector-based memory search — without it, LLM-based recall is used), Telegram bot token, gogCLI,ghCLI
| Doc | Description |
|---|---|
SetupConfigWorker GuideAPI ReferenceSDK SessionsSourcesTasksMemoryCronPlansWeb UI
pytest tests/ -v
MIT