Content
# Brainstem
**Local-first knowledge backend for AI agents.**
Connect any MCP host — Claude Code, Cursor, or your own agent harness — to a
personal knowledge engine: an Obsidian-compatible wiki with indexed retrieval,
token-budgeted memory recall, and secure ingestion. Your agents get quality
context; you keep your knowledge on your machine.
```
┌────────────┐ MCP (stdio/sse) ┌───────────────────────────────┐
│ Your agent │ ◄─────────────────► │ Brainstem │
│ (Claude │ 27 tools │ · search + read + write wiki │
│ Code, │ (12 read-only) │ · memory tree recall (BM25 + │
│ Cursor…) │ │ vectors, token-budgeted) │
└────────────┘ │ · code graph over your repos │
│ · vault = plain Markdown │
└───────────────────────────────┘
```
## Install
```sh
# Run without installing (recommended)
uvx brainstem-mcp init
# Or install
pip install brainstem-mcp
brainstem init
```
`brainstem init` creates a vault at `~/.brainstem/vault` (override with
`--root`) and prints the exact one-liner to connect your agent:
```sh
claude mcp add brainstem -- uvx brainstem-mcp mcp --root ~/.brainstem/vault
```
That's it. No API key is required to serve, search, and read — your agent
brings its own model.
## Docker
```sh
docker build -t brainstem .
docker run -i -v ~/.brainstem/vault:/vault brainstem # stdio
docker run -p 8765:8765 -v ~/.brainstem/vault:/vault brainstem \
mcp --root /vault --transport sse # sse
```
## What your agent can do
- **Search & read** — `search_wiki_index`, `read_wiki_file`, cross-references,
orphan detection over a plain-Markdown Obsidian-compatible vault.
- **Remember & recall** — a hierarchical memory tree with BM25 + vector search
and token-budgeted `memory_tree_recall`, built for agent context windows.
- **Write knowledge** — structured pages with YAML frontmatter, index upkeep,
supersession instead of duplication.
- **Understand code** — ingest a repository and query its architecture
(`ask_repo`, code-graph overview/impact) as part of your agent's context.
## Read-only profile
Expose only the 12 safe read tools (no writes, no publishing):
```sh
brainstem mcp --readonly
```
## Security posture
Brainstem treats everything it ingests as **untrusted input**: ingested content
cannot trigger writes or publishing on its own, and outbound actions are
draft-only by design. The vault is plain Markdown on your disk — no cloud, no
telemetry, single-tenant by architecture.
## Brainstem vs. OpenWiki
OpenWiki generates documentation that agents read as files. Brainstem is a
**live backend**: your agent queries an indexed knowledge base through MCP
tools at run time — retrieval, memory, and ingestion as part of the harness,
not a batch-generated artifact.
## License
MIT
