# Show HN: Nerve – self hosted runtime for AI agents

> Source: <https://github.com/ClickHouse/nerve>
> Published: 2026-05-25 22:46:43+00:00

**A home for your agents.**

Self-hosted AI agent runtime — personal assistants, autonomous workers, and everything in between.

[Setup Guide](/ClickHouse/nerve/blob/main/docs/setup.md) ·
[Architecture](/ClickHouse/nerve/blob/main/docs/architecture.md) ·
[Configuration](/ClickHouse/nerve/blob/main/docs/config.md) ·
[Worker Guide](/ClickHouse/nerve/blob/main/docs/worker-guide.md) ·
[API Reference](/ClickHouse/nerve/blob/main/docs/api.md)

Nerve is a self-hosted runtime for AI agents, built around the [Claude Agent SDK](https://github.com/anthropics/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 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
```

🧠 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 pause 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`

or`pairing`

)

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 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.

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 workflows`skill-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 buttons`ask_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](/ClickHouse/nerve/blob/main/docs/config.md) for all options.

[Python](https://www.python.org/)3.13+[uv](https://docs.astral.sh/uv/)(recommended package manager)[Node.js](https://nodejs.org/)18+ (for web UI build)[Claude Code CLI](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)(bundled with`claude-agent-sdk`

)- Anthropic API key
**or** Claude subscription via[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)proxy - Optional: OpenAI API key (for vector-based memory search — without it, LLM-based recall is used), Telegram bot token,
[gog](https://github.com/googleworkspace/cli)CLI,[gh](https://cli.github.com/)CLI

| Doc | Description |
|---|---|
|

[Setup](/ClickHouse/nerve/blob/main/docs/setup.md)[Config](/ClickHouse/nerve/blob/main/docs/config.md)[Worker Guide](/ClickHouse/nerve/blob/main/docs/worker-guide.md)[API Reference](/ClickHouse/nerve/blob/main/docs/api.md)[SDK Sessions](/ClickHouse/nerve/blob/main/docs/sdk-sessions.md)[Sources](/ClickHouse/nerve/blob/main/docs/sources.md)[Tasks](/ClickHouse/nerve/blob/main/docs/tasks.md)[Memory](/ClickHouse/nerve/blob/main/docs/memory.md)[Cron](/ClickHouse/nerve/blob/main/docs/cron.md)[Plans](/ClickHouse/nerve/blob/main/docs/plans.md)[Web UI](/ClickHouse/nerve/blob/main/docs/web-ui.md)

```
pytest tests/ -v
```

MIT