claude-braind

A local, always-on "second brain" daemon for AI coding agents. It keeps one durable, searchable copy of everything a long-running project accumulates — docs, notes, decisions, a work board, agent memories — and serves it to Claude Code (or any MCP client) as shared grounding, so every session and every subagent starts from the same source of truth instead of re-deriving it or drifting.

I built this for my own multi-project work and I'm releasing it in case it's useful to anyone else running agents for weeks at a time on the same codebase. It is deliberately small: Python 3.12, stdlib for the core, a couple of optional dependencies for semantic search.

Why it exists

Long agent sessions lose things. Context windows compact, a session ends, a new one starts cold, and the hard-won "here's where we are and why" evaporates. Status written by hand drifts from what's actually on disk. Two agents working the same repo can't see each other's notes. BrainD is the fix I wanted: everything keepable goes to disk immediately, gets indexed, and is served back on demand — so the knowledge outlives any single session, and status is generated from disk rather than typed by someone hoping it's still true.

What it does

• Grounding pack (/context) — one assembled brief every agent reads first: the project's rules, an evidence discipline, where we are now, the top of the work board, and pointers into the store. Prepend it to every subagent you spawn and they all share the same footing.
• Full-text search (/search) — SQLite FTS5 over all your docs, notes, and memories. Instant, stdlib.
• Optional semantic search — the same store plus sqlite-vec + FastEmbed (bge-small, 384-dim) for meaning-based recall when a keyword misses. Opt-in; keyword search works without it.
• Work board (/worklist) — a make/fix/port/whatever board that's the project's source of truth for what's open, with a small HTML view.
• Status from disk (/status) — daemon health, a token-spend ledger read from your session transcripts, and reconciliation checks that compare what a status doc claims against what's actually on disk (so a stale doc can't lie to you).
• Multi-project — the daemon is generic; your projects are data in brain.config.json. It maps each session to its project by the session's working directory and serves that project's rules and board. New project directories are auto-registered the first time an agent asks for grounding.
• Model-fit ping — you tell it which kinds of work suit which model tier; when the session's live model disagrees with the work at hand, it surfaces a one-line nudge (you stay in control of /model).
• A resource governor (Windows) — when it detects a game running, it throttles a chosen background app (default: the Claude desktop app) onto the slowest CPU cores at low priority + EcoQoS and boosts the game onto the fastest cores, then restores everything the instant the game closes. Optional, off by config on non-Windows.
• MCP bridge — registers brain_context, brain_search, brain_status, brain_worklist, and a few more as MCP tools so Claude Code can call them directly.

If the daemon is off, everything degrades to reading the files on disk directly — nothing is trapped behind a running process.

Install

Requires Python 3.12+. The core daemon is stdlib only.

git clone https://github.com/DegradingAnt/claude-braind
cd claude-braind

# 1. Copy the example config + policy + index roots, then edit them for your machine:
cp brain.config.example.json          brain.config.json
cp 60-CONTEXT/policy.example.json      60-CONTEXT/policy.json
cp 40-TOOLS/brain_roots.example.json   40-TOOLS/brain_roots.json

# 2. (for the MCP bridge) install the MCP SDK:
python -m pip install -r 40-TOOLS/requirements.txt
# 2b. (optional) semantic search:
python -m pip install -r 40-TOOLS/requirements-semantic.txt

# 3. Start the daemon (HTTP on 127.0.0.1:8777):
python 40-TOOLS/brain_server.py

Point the paths in brain.config.json at your setup — the whole config is documented inline. All tools resolve their paths from that one file (or the BRAIND_ROOT environment variable); there are no hardcoded paths in the code.

Register the MCP tools with Claude Code

claude mcp add braind --scope user -- python /path/to/claude-braind/40-TOOLS/brain_mcp.py

Then brain_context, brain_search, etc. are available to every session.

Layout

40-TOOLS/     the daemon + tools (brain_server.py is the entry point)
60-CONTEXT/   policy, context packs, and runtime state (state is git-ignored)
90-WORKLIST/  the work board
10-DOCS/      your knowledge docs (indexed for search)
00-INDEX/     generated search index (git-ignored, rebuilt from disk)

The numeric prefixes are just an ordering convention from where this grew up; the code refers to these directory names, so keep them.

Status — read this

This is an initial open-source extraction of a tool I run on my own machine. It works for me, every file compiles, and it has been scrubbed of my project-specific data. But:

• It has not yet been tested end-to-end on a clean, unfamiliar machine, so expect rough edges on first run.
• The resource governor is Windows-only (it uses Win32 priority/affinity APIs). On other platforms the daemon runs fine; just leave the governor disabled.
• Some modules (upstream-fetch digests, disk-status reconciliation, backup) carry defaults shaped by my own workflow — they're generic now, but you may want to point them at your own paths.
• There is no packaged installer yet. It's clone-and-run.

Issues and PRs welcome. If something assumes a path or convention that only makes sense for me, that's a bug — please flag it.

License

Apache License 2.0 — see LICENSE and NOTICE.

---

This is an AI-assisted project: much of the code and these docs were written with Claude (Anthropic), directed and reviewed by me.