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.

Quick Start

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.

git clone https://github.com/ClickHouse/nerve.git && cd nerve
uv venv --python 3.13 && source .venv/bin/activate
uv pip install -e .
cd web && npm ci && npm run build && cd ..
nerve init
nerve start -f

Upgrading

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

Two Modes

🧑 Personal Mode

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

🔧 Worker Mode

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 own TASK.md, creates skills, sets up cron jobs, and starts working
• Memory categories are operational: patterns, procedures, decisions, approvals, infrastructure
• No IDENTITY.md or USER.md — workers execute a mission, not build a relationship
• Built for reliability: plan before acting, verify after executing, log everything

# Spin up a worker that monitors CI and fixes flaky tests
nerve init --mode worker
# → Wizard asks for a task description
# → Agent onboards itself on first boot

Why Nerve?

Channels

Every channel shares the same agent engine, memory, and tools.

💬 Web UI

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

🤖 Telegram Bot

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 or pairing)

⏰ Cron Jobs

Scheduled AI sessions via APScheduler. Three session modes:

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.

📡 Source Sync

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 condensation
• GitHub Notifications — gh api enriched with PR/issue content
• GitHub 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.

Core Systems

🧠 Memory

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.

📋 Tasks

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

🔧 Skills

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 workflows
• skill-reviser cron reviews existing skills for accuracy
• Usage statistics tracked per skill

📐 Plans

Proactive task planning with human-in-the-loop approval.

1. Planner cron picks open tasks autonomously
2. Agent explores codebase, researches approaches, proposes implementation plan
3. User reviews → approves / declines / requests revision
4. Approved plans spawn implementation sessions automatically

Revisions happen in the same persistent planner session — full context preserved.

🔔 Notifications

Async communication between agent and human, delivered to both web UI and Telegram.

• notify — Fire-and-forget alerts (status updates, completions, reminders)
• ask_user — Questions with predefined options, rendered as buttons
• Priority levels: urgent, high, normal, low

Architecture

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

Configuration

Two config files:

• config.yaml — Template settings (committed)
• config.local.yaml — Secrets and overrides (gitignored)

See docs/config.md for all options.

Requirements

• Python 3.13+
• uv (recommended package manager)
• Node.js 18+ (for web UI build)
• Claude Code CLI (bundled with claude-agent-sdk)
• Anthropic API key or Claude subscription via CLIProxyAPI proxy
• Optional: OpenAI API key (for vector-based memory search — without it, LLM-based recall is used), Telegram bot token, gog CLI, gh CLI

Documentation

Testing

pytest tests/ -v

License

MIT