CC Agent Brain

English | 中文

A local-first memory engine for coding agents. It captures what you and the
agent actually do, distills it into versioned long-term memory, and recalls it
automatically — fully offline, with zero third-party dependencies, and
exposed to any tool through MCP. Installs as a namespaced add-on and never
replaces your existing .claude/ directory.

English

What is CC Agent Brain

CC Agent Brain turns a stateless coding agent into one that remembers you across
sessions and across tools — all locally, no cloud, no API key.

user prompts / assistant replies / tool actions
        ↓ automatic hooks
append-only event stream (SQLite + FTS5)  +  readable Wiki (Markdown)
        ↓ distill
versioned long-term memory (layered, bi-temporal, auditable)
        ↓ BM25 + RRF retrieval, project DB first / global DB fallback
automatic recall in future sessions
        ↓ MCP server
the same memory in Claude Code, Cursor, Codex, Gemini CLI, Claude Desktop…

Why it exists (2026 memory landscape)

Agent memory is becoming standard infrastructure, but existing choices force a
trade-off: cloud memory APIs send your data away; heavy self-hosted stacks need
vector/graph databases; plain Markdown memory does not actually search or
version itself. CC Agent Brain occupies the middle:

• Zero-dependency engine — Python stdlib sqlite3 + FTS5 (BM25), including
  CJK bigram tokenization, so Chinese and English retrieval both work offline.
• Real capture loop — user prompts and assistant replies / tool calls are
  indexed (Stop hook reads the transcript; idempotent).
• Versioned, trustworthy memory — facts are superseded/expired, never
  silently overwritten; a timeline shows what changed and when.
• MCP-native, tool-agnostic — one memory store for every MCP client.
• Human-readable projection — Markdown Wiki and generated indexes keep you
  in control; the DB is a single portable file.
• Private by construction — common secret shapes are redacted at capture
  time; personal data is git-ignored.

Quick install

git clone https://github.com/syiibfs-hash/cc-agent-brain.git
cd cc-agent-brain
python installer/install.py --target /path/to/your/project
# preview first:
python installer/install.py --target /path/to/your/project --dry-run

Or paste the install prompt from prompts/install-from-github.md into Claude Code.

What gets installed

my-project/
├── .claude/
│   ├── settings.json                         ← merged, not replaced (+ backup)
│   ├── skills/cc-agent-brain-*/              ← 6 skills
│   ├── agents/cc-agent-brain-*.md            ← 3 agents
│   └── hooks/cc-agent-brain/                 ← 6 hooks + engine + _utils
│       ├── brain_store.py                    ← SQLite/FTS5 engine + MCP server
│       ├── transcript_capture.py             ← indexes assistant/tool actions
│       └── …
├── .cc-agent-brain/brain.db                  ← local engine DB (git-ignored)
├── .mcp.json                                 ← Claude Code stdio MCP, merged
├── .cursor/mcp.json                          ← Cursor stdio MCP, merged
├── .codex/config.toml                        ← Codex MCP table, merged
├── memory/     compressed long-term memory + generated index
├── wiki/       detailed human-readable context
├── private/    local sensitive notes
└── templates/  writing templates

Running the installer again refreshes the namespaced hooks, skills, and agents,
migrates an existing brain.db, and merges the three MCP entries. It does not
overwrite memory/, wiki/, private/, existing templates, or the database file.

The engine CLI

BRAIN="python .claude/hooks/cc-agent-brain/brain_store.py"
$BRAIN init
$BRAIN search "deployment decision" --human
$BRAIN memory add --title "..." --body "..." --layer semantic --confidence high
$BRAIN memory add ... --supersedes <old-id>   # replace, keep history
$BRAIN audit / timeline / stats / candidates
$BRAIN sync-md                                # regenerate memory projection
$BRAIN serve-mcp                              # MCP server over stdio

Full reference: docs/memory-engine.md, MCP setup:
docs/mcp.md.

Components

6 Hooks

6 Skills — onboarding, wiki update/search, memory distill/audit, material distill.
3 Agents — memory curator, wiki compiler, material distiller.

Memory model

Four layers — working (current task), episodic (timestamped events),
semantic (distilled facts/preferences), procedural (reusable workflows).
Each memory has status (active/superseded/expired/archived), validity window,
confidence, source and supersede chain. See docs/memory-design.md.

Uninstall

python installer/uninstall.py --target /path/to/your/project

Only framework files tracked by the manifest are removed. Your memory/,
wiki/, private/ and brain.db are preserved.

Roadmap

Privacy

Open-source framework, no personal data inside. Everything runs on your machine;
there is no telemetry and no network call. memory/, wiki/, private/ and
*.db are git-ignored. See docs/product-analysis.md
for the product rationale.

License

MIT

中文

CC Agent Brain 是什么

给编码 Agent 用的本地记忆引擎：自动捕获你和 Agent 的真实工作过程，蒸馏成带版本的长期记忆，并在后续会话自动召回——全程离线、零第三方依赖，并通过 MCP 把同一份记忆提供给任意工具。以命名空间插件方式安装，绝不覆盖你已有的 .claude/。

用户提示 / 助手回复 / 工具动作
        ↓ 钩子自动捕获
只增事件流（SQLite + FTS5） + 可读 Wiki（Markdown）
        ↓ 蒸馏
带版本的长期记忆（分层、双时间、可审计）
        ↓ BM25 + RRF 检索，项目库优先 / 全局库兜底
后续会话自动召回
        ↓ MCP 服务
同一套记忆服务 Claude Code、Cursor、Codex、Gemini CLI、Claude Desktop…

为什么做它（2026 记忆赛道现状）

Agent 记忆正在成为基础设施，但现有方案都要你做取舍：云记忆 API 要上传数据；重型自建方案要装向量/图数据库；纯 Markdown 记忆既不能真正检索也没有版本。CC Agent Brain 取中间路线：

• 零依赖引擎：仅用 Python 标准库 sqlite3 + FTS5（BM25），内置中文 bigram 分词，中英文检索全部离线可用。
• 完整捕获闭环：不只存用户提问，Stop 钩子读取会话记录，把助手回复与工具调用一并索引（幂等）。
• 可信的版本化记忆：事实变更走"取代/失效"而非静默覆盖，时间线可查"何时因为什么改了结论"。
• MCP 原生、不绑工具：一套记忆，所有 MCP 客户端复用。
• 人类可读投影：Markdown Wiki 与生成式索引让你始终掌控；数据库只是一个可拷贝的文件。
• 隐私内建：常见密钥形态在捕获时即脱敏，个人数据默认 git 忽略。

快速安装

git clone https://github.com/syiibfs-hash/cc-agent-brain.git
cd cc-agent-brain
python installer/install.py --target /path/to/your/project
# 先预览：
python installer/install.py --target /path/to/your/project --dry-run

也可以把 prompts/install-from-github.md 中的安装提示词粘贴给 Claude Code。

安装内容

my-project/
├── .claude/
│   ├── settings.json                         ← 增量合并（自动备份）
│   ├── skills/cc-agent-brain-*/              ← 6 个技能
│   ├── agents/cc-agent-brain-*.md            ← 3 个代理
│   └── hooks/cc-agent-brain/                 ← 6 个钩子 + 引擎 + 工具库
│       ├── brain_store.py                    ← SQLite/FTS5 引擎 + MCP 服务
│       ├── transcript_capture.py             ← 索引助手回复/工具动作
│       └── …
├── .cc-agent-brain/brain.db                  ← 本地引擎库（git 忽略）
├── .mcp.json                                 ← Claude Code stdio MCP，只合并本服务
├── .cursor/mcp.json                          ← Cursor stdio MCP，只合并本服务
├── .codex/config.toml                        ← Codex MCP 表，只合并本服务
├── memory/     压缩长期记忆 + 生成式索引
├── wiki/       详细的人类可读上下文
├── private/    本地敏感笔记
└── templates/  写作模板

再次运行安装器会刷新命名空间内的钩子、技能和代理，对已有 brain.db 做迁移，并合并上面三个 MCP 条目。它不会覆盖 memory/、wiki/、private/、已有模板或数据库文件本身。

引擎命令行

BRAIN="python .claude/hooks/cc-agent-brain/brain_store.py"
$BRAIN init
$BRAIN search "部署方案的决策" --human
$BRAIN memory add --title "..." --body "..." --layer semantic --confidence high
$BRAIN memory add ... --supersedes <旧id>     # 取代并保留历史
$BRAIN audit / timeline / stats / candidates
$BRAIN sync-md                                # 重新生成记忆投影
$BRAIN serve-mcp                              # 以 stdio 启动 MCP 服务

完整说明见 docs/memory-engine.md，MCP 接入见 docs/mcp.md。

组件

6 个 Hooks

6 个 Skills：初始化、Wiki 更新/检索、记忆蒸馏/审计、素材蒸馏。
3 个 Agents：记忆策展人、Wiki 编纂者、素材提炼者。

记忆模型

四层——working（当前任务）、episodic（带时间戳的事件）、semantic（蒸馏事实与偏好）、procedural（可复用流程）。每条记忆带状态（active/superseded/expired/archived）、有效期、置信度、来源与取代链。详见 docs/memory-design.md。

卸载

python installer/uninstall.py --target /path/to/your/project

只删除清单中记录的框架文件；memory/、wiki/、private/ 与 brain.db 全部保留。

路线图

隐私

开源框架，仓库内不含任何个人数据。所有计算在本机完成，无遥测、无网络请求。memory/、wiki/、private/ 与 *.db 均被 git 忽略。产品层面的完整分析见 docs/product-analysis.md。

协议

MIT