Metadata-Version: 2.4
Name: brainstem-mcp
Version: 0.3.1
Summary: Brainstem — local-first knowledge backend for AI agents. Connect any MCP host (Claude Code, Cursor) to an Obsidian-compatible wiki with indexed retrieval, token-budgeted recall, and secure ingestion.
Author: DarkCodePE
License: MIT
Project-URL: Repository, https://github.com/DarkCodePE/second-brain-wiki
Project-URL: Issues, https://github.com/DarkCodePE/second-brain-wiki/issues
Project-URL: Roadmap, https://github.com/DarkCodePE/second-brain-wiki/blob/main/docs/swarm-investigation/2026-05-22-openhuman-vs-sbw/backlog/ROADMAP.md
Keywords: knowledge-base,obsidian,deep-agents,langgraph,mcp,rag
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: News/Diary
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: deepagents<0.6,>=0.5.3
Requires-Dist: langchain<2.0,>=1.0
Requires-Dist: langchain-core<2.0,>=1.0
Requires-Dist: langchain-anthropic>=1.0
Requires-Dist: langgraph<2.0,>=1.0
Requires-Dist: langsmith>=0.3.0
Requires-Dist: langgraph-checkpoint-sqlite
Requires-Dist: fastembed>=0.4.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: markdownify>=0.14.0
Requires-Dist: pypdf>=4.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: watchdog>=4.0
Requires-Dist: click>=8.1
Requires-Dist: keyring>=24.0
Requires-Dist: structlog>=24.0
Provides-Extra: ollama
Requires-Dist: langchain-ollama>=0.3.0; extra == "ollama"
Provides-Extra: ingest
Provides-Extra: observability
Requires-Dist: sentry-sdk>=2.0; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.28; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.28; extra == "observability"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-benchmark>=5.0; extra == "dev"
Requires-Dist: diff-cover>=9.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Dynamic: license-file

# 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
