Cc Agent Brain
Local-first memory engine for coding agents (Claude Code/Cursor/Codex): SQLite+FTS5 retrieval, versioned bi-temporal memories, full-session capture, zero depend…
A local memory add-on for Claude Code. Hooks under .claude/ append
prompts, assistant text, and tool-call inputs to a SQLite + FTS5 file, and a
UserPromptSubmit hook prints keyword matches back into later Claude Code
sessions. Long-term memories are written only when you or a skill runs
memory add. A stdio MCP server and a CLI read the same file. The installer
merges a cc-agent-brain namespace into an existing project and does not
replace .claude/.
Python standard library only (sqlite3). No network calls, no API key.
English
What this tree does
Claude Code hooks (.claude/settings.json)
UserPromptSubmit prompt_capture.py user prompt → event + wiki/sessions
UserPromptSubmit wiki_context_hint.py FTS recall printed for Claude Code
Stop transcript_capture.py assistant text + tool_use inputs
Stop memory_audit.py SQL audit report
PreCompact pre_compact_save.py marker file + system event
SessionStart session_start.py onboarding check + engine stats
↓
.cc-agent-brain/brain.db (events + memories, FTS5 / BM25)
↓
search fuses lexical hit lists with RRF
active memories, events, and the same two lists from
~/.cc-agent-brain/brain.db when that file already exists
↓
long-term rows appear after an explicit `memory add`
(no model in this repository distills them for you)
↓
optional `serve-mcp` stdio; initialize → 2024-11-05, or 2026-07-28 via _meta
Current scope
These limits match package/claude/hooks/cc-agent-brain/ and installer/ in
this repository.
- Auto-capture is Claude Code. The six hooks are Claude Code events
(
SessionStart,UserPromptSubmit,PreCompact,Stop) merged into.claude/settings.json.transcript_capture.pyreads the Claude Code transcript JSONL (transcript_path) and indexes assistant text plustool_usename/input. It skipstool_resultpayloads. Cursor, Codex, Gemini CLI, and Claude Desktop have no capture hooks and no automatic recall. The installer does write project MCP entries for Claude Code, Cursor, and Codex that launch this sameserve-mcp. Those entries do not capture sessions. Gemini CLI and Claude Desktop get no config from the installer. - Retrieval is lexical multi-path FTS. Active memories and events are
ranked with FTS5
bm25()after CJK-bigram tokenization. Reciprocal rank fusion (rrf_fuse) merges those ranked lists: project memories, project events, and, when~/.cc-agent-brain/brain.dbexists, the global memories and events as well. Both sides are keyword search. This is not lexical-plus-vector hybrid retrieval. No embedding model and no vector index are queried. A vector channel is later work and is not part ofsearchtoday. "Project first, global fallback" is also inaccurate: when the global file exists, its lists are fused in the same RRF call, not used only after the project search misses. - Validity columns are stored. As-of queries are not implemented. Each
memory row has
valid_from,valid_to,created_at, andupdated_at.memory add --supersedesandmemory expirekeep the old row, set its status, and fillvalid_to.searchreturns rows withstatus='active'only.timelinelists recent memory rows ordered byupdated_at. No command takes a past timestamp and returns the store as of that time. - The MCP server speaks both
2024-11-05and2026-07-28on one stdio process.initialize, with no modern envelope, still returnsprotocolVersion2024-11-05,capabilities: {tools: {}}, andserverInfo.version"2"(the schema id).ping,tools/list, andtools/callon that path omitresultType. A request whoseparams._metahas bothio.modelcontextprotocol/protocolVersion(string) andio.modelcontextprotocol/clientCapabilities(object) is
From the project's README.