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…

LLM Mart 1 views 129 listing impressions

English | 中文

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.

  1. Auto-capture is Claude Code. The six hooks are Claude Code events (SessionStart, UserPromptSubmit, PreCompact, Stop) merged into .claude/settings.json. transcript_capture.py reads the Claude Code transcript JSONL (transcript_path) and indexes assistant text plus tool_use name/input. It skips tool_result payloads. 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 same serve-mcp. Those entries do not capture sessions. Gemini CLI and Claude Desktop get no config from the installer.
  2. 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.db exists, 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 of search today. "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.
  3. Validity columns are stored. As-of queries are not implemented. Each memory row has valid_from, valid_to, created_at, and updated_at. memory add --supersedes and memory expire keep the old row, set its status, and fill valid_to. search returns rows with status='active' only. timeline lists recent memory rows ordered by updated_at. No command takes a past timestamp and returns the store as of that time.
  4. The MCP server speaks both 2024-11-05 and 2026-07-28 on one stdio process. initialize, with no modern envelope, still returns protocolVersion 2024-11-05, capabilities: {tools: {}}, and serverInfo.version "2" (the schema id). ping, tools/list, and tools/call on that path omit resultType. A request whose params._meta has both io.modelcontextprotocol/protocolVersion (string) and io.modelcontextprotocol/clientCapabilities (object) is

From the project's README.

Related servers

Fetch Official

Fetch a web page and hand the agent readable text instead of raw HTML.

stdio
mcp-server-fetch 33 views
Filesystem Official

Give an agent scoped read and write access to directories you choose.

stdio
@modelcontextprotocol/server-filesystem 29 views
Git Official

Read repository history, diffs and branches as tools an agent can call.

stdio
mcp-server-git 27 views

Read-only MCP server for the OrchestKit docs: full-text search + Markdown fetch. No auth.

24 views