brain
A local-first personal knowledge base with task management and memory retrieval, exposing token-budgeted tools to AI agents over MCP.
Why brain?
Long-running AI agents face a hard constraint: context windows are finite, and filling them with irrelevant content wastes both money and reasoning quality. Research on agentic memory systems — MemGPT, Generative Agents, Mem0 — has converged on the same insight: agents need explicit mechanisms to control what they read and how much they read, not just better retrieval.
Existing tools don't solve this well:
- Knowledge graph tools (Obsidian plugins, etc.) are built for human navigation with no concept of token budgets or machine-readable retrieval APIs.
- RAG-as-a-service (Pinecone, Weaviate cloud) requires network calls, incurs per-query costs, and sends your notes to third parties — with only simple top-k vector search.
- Local vector databases (sqlite-vec, Chroma) provide semantic similarity but miss keyword search, recency, link structure, and tag matching. A query for "meeting notes from last Tuesday" fails entirely on pure vector search.
brain takes a different position: run everything locally, combine all retrieval signals into a hybrid score, enforce token budgets at the API level, and treat Markdown files as the durable source of truth.
Overview
brain is a Rust daemon that manages tasks, records, and Markdown notes. It incrementally indexes content into a dual-store system (SQLite for full-text search and metadata, LanceDB for 384-dim vector embeddings) and serves retrieval tools over MCP stdio JSON-RPC.
Token budgeting is a first-class constraint. memory.retrieve supports three levels of detail (L0 extractive abstracts ~100 tokens, L1 LLM summaries ~2000 tokens, L2 full source). Agents choose their budget upfront and get LOD-adjusted content in a single call, spending context window space efficiently.
Hybrid scoring combines six signals — vector similarity, BM25 keyword ranking, recency decay, backlink count, tag match, and importance — into a single relevance score. A strategy parameter shifts signal weights per query type: lookup upweights keyword precision; planning upweights recency and link structure; synthesis upweights semantic similarity.
Everything runs on-device. No network calls, no API keys, no ongoing cost after the initial ~130MB model download. The entire index can be rebuilt from the Markdown files at any time.
Features
Tasks
An event-sourced task system with dependencies, labels, and comments. Tasks are automatically indexed into the memory system as they are created or updated, making them semantically searchable alongside notes.
Memory & Search
Hybrid retrieval combining vector search (LanceDB) and keyword search (SQLite FTS5). Supports episodic memory (episodes), procedural memory (procedures), and reflective synthesis (reflections).
Records
Content-addressed storage for typed work products and snapshots. Records can be linked to tasks or note chunks, providing a durable audit trail of documents, analyses, plans, and state captures.
Notes
Markdown-based knowledge base. brain watches your note directories and incrementally indexes changes, extracting wiki-links, tags, and heading-aware chunks.
Jobs
An internal job system for deferred and recurring work. Handles background tasks like embedding stale content, generating summaries, and consolidating episodic memories into reflections.
Installation
Install the brain CLI before the plugin marketplace step. The Claude Code plugin's hooks (SessionStart, UserPromptSubmit, PreCompact, Stop, PreToolUse) shell out to the brain binary. If the CLI is not installed first, all hooks will silently no-op — no error will appear in Claude Code.
Homebrew (macOS)
brew install benediktms/brain/brain
Shell installer (macOS / Linux)
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/benediktms/brain/releases/latest/download/brain-installer.sh | sh
From source
Requires Rust (stable, edition 2024), just, and protobuf (brew install protobuf or apt install protobuf-compiler).
git clone https://github.com/benediktms/brain.git
cd brain
just install # builds the binary, symlinks it to ~/bin, installs hooks
just docs # regenerates AGENTS.md + CLAUDE.md for AI agents
AGENTS.md and CLAUDE.md are generated locally from a template in crates/cli/src/commands/init.rs and are not checked into git — fresh clones don't have them until just docs runs. The pre-commit hook keeps them refreshed on every commit.
Quick Start
brain init ~/notes
brain daemon start
