使用说明

     ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
    ██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
    ██║     ██║     ███████║██║   ██║██║  ██║█████╗
    ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝
    ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗
     ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝
    ██████╗ ██████╗  █████╗ ██╗███╗   ██╗
    ██╔══██╗██╔══██╗██╔══██╗██║████╗  ██║
    ██████╔╝██████╔╝███████║██║██╔██╗ ██║
    ██╔══██╗██╔══██╗██╔══██║██║██║╚██╗██║
    ██████╔╝██║  ██║██║  ██║██║██║ ╚████║
    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝

AI编码代理的自主上下文管理

永远不要重复解释你的项目。 代理启动每个会话时已经知道决策、错误、惯例——以及它自己过去的错误。持久项目内存+认知防火墙+树型代码图，作为53个MCP工具公开。

问题

AI编码代理有两个基本限制：

1.会话之间没有内存。 每个会话都从零开始。

Session 1:  "Let's use JWT for auth"     ─── decision made
Session 2:  "Let's use session cookies"  ─── decision contradicted
Session 3:  "Why is auth broken?"        ─── bug reintroduced

2.会话中上下文填满。 随着谈话的深入，早期的决定会被压缩或驱逐。项目越大，关键信息淹没在噪音中的速度就越快。

解决方案

Claude Brain是一个MCP服务器，它为代理提供 结构化、可查询的知识库 加上a 代码结构图 --因此，代理不会将所有内容都填充到上下文窗口中，而是在相关时准确检索相关内容。

三个子系统：

子系统	它做什么
项目记忆	决策、错误、实现、模式、经验教训、计划和研究以Markdown+YAML的形式存储在 `.brain/`，链接到键入的知识图中
认知防火墙	预编辑风险评分(`brain_preflight`)以及编辑后验证(`brain_validate_change`)基于从经验教训和错误中提取的规则
代码图	树型AST解析（JS/TS/Python/Rust）为图形学图：符号、调用、导入、社区、爆炸半径、上帝节点

快速开始

git clone https://github.com/Xattaus/claude-brain.git
cd claude-brain && npm install

# Install into your project
node install.js /path/to/your/project

重新启动克劳德代码。安装程序设置代理所需的一切：

.mcp.json 在项目根目录中——注册大脑MCP服务器（这是Claude Code实际读取的文件；旧版本写入 settings.local.json，Claude Code忽略了这一点——安装程序会自动迁移它）
CLAUDE.md / GEMINI.md --代理的工作流说明（何时记录、何时检查冲突、如何使用代码图）
钩子 --SessionStart上下文注入，PreToolUse文件编辑前的防火墙检查，PostToolUse文档提醒，停止时间“你保存了吗？”检查，PreCompact上下文保留
技能+代理人 --大脑工作流程技能，策展人/文档管理员/审稿人/积压维护代理
权限 — mcp__brain__* 允许，因此工具调用不会提示

证实 claude mcp list --你应该看看 brain: ✔ Connected.

专为自主性而设计

这不是一款带有API的笔记应用程序。每一块都存在，所以代理人使用大脑 未经询问:

会话开始 --SessionStart钩子注入概述；代理人打电话来 brain_get_overview + brain_get_lessons 并了解该项目的历史及其过去的错误。
编辑前 --PreTool使用钩子读取 .brain/index.json 直接将匹配规则、相关决策、开放/修复的错误和风险评分注入代理的上下文中——即使代理忘记调用 brain_preflight.
编辑后 --PostToolUse钩子提醒代理记录重大更改。在连续10次非大脑工具调用后，活动计数器会轻推。
关于错误 --代理人用具体规则记录一节课；防火墙对这些文件的每次后续编辑都会对规则进行索引和执行。
停车时 --Stop钩子阻塞一次，并要求代理验证所有内容是否已保存。

认知防火墙

                    ┌─────────────────────┐
                    │   Agent wants to    │
                    │   edit a file       │
                    └─────────┬───────────┘
                              ▼
                    ┌─────────────────────┐
                    │  brain_preflight()  │
                    │   rules + bugs +    │
                    │  lessons + conflicts│
                    └─────────┬───────────┘
                 ┌────────────┼────────────┐
                 ▼            ▼            ▼
           ┌──────────┐ ┌──────────┐ ┌──────────┐
           │ LOW  <40 │ │ MED 40-69│ │ HIGH ≥70 │
           │ Proceed  │ │ Careful  │ │ STOP +   │
           └──────────┘ └──────────┘ │ ask user │
                                     └──────────┘

编辑之后， brain_validate_change() 检查没有违反任何规定。规则有三种形式： DO （要求）， DONT （禁令）， GUARD （修复了不得重新引入的错误）。

代码图谱

brain_code_build 使用树型WASM语法解析项目，并使用以下语法构建文件、类、函数和方法的有向多重图 contains / calls / imports / inherits 边缘、Louvain社区检测和每个文件的AST缓存。

brain_code_query("auth middleware")   → IDF-ranked subgraph, token-budgeted for context
brain_code_blast(["src/util.js"])     → affected nodes, communities, risk score
brain_code_path("a.js", "b.js")       → shortest dependency path
brain_code_gods()                     → over-connected symbols (refactoring candidates)
brain_code_surprises()                → unexpected cross-module / cross-language edges
brain_bridge_auto()                   → links brain entries to the code nodes they describe

支持的语言： JavaScript、TypeScript、Python、Rust桥层连接两个图——关于 auth.js 与实际情况相关联 auth.js 节点，因此文件级上下文检索需要散文和结构。

53 MCP工具

Core — Query & Discovery 5

工具	它做什么
`brain_get_overview`	项目概述+积极决策+开放错误。会话开始时呼叫。
`brain_search`	带有相关性排名的全文搜索（MiniSearch+TF-IDF）
`brain_get_entry`	按ID检索包含内容和关系的单个条目
`brain_list`	按类型、状态和标签筛选的列表条目
`brain_get_lessons`	按严重程度分组的活动课程及其规则

Recording — Capture Knowledge 6

工具	它做什么
`brain_record_decision`	ADR格式的架构决策（支持 `supersedes`)
`brain_record_bug`	Bug修复，包括症状、根本原因和修复
`brain_record_implementation`	实施细节和代码更改
`brain_record_pattern`	可重用的模式和惯例
`brain_record_lesson`	从错误中吸取教训，制定规则防止再次发生
`brain_record_research`	探索替代方案、拒绝和结论

Context & Relationships 5

工具	它做什么
`brain_link_entries`	双向类型链接(`implements`, `fixes`, `supersedes`, …)
`brain_get_context_for_files`	特定文件的所有决策、错误和实现
`brain_traverse_graph`	浏览知识图谱——遍历、路径、影响、循环
`brain_check_conflicts`	拟议的变更是否与现有决策相冲突？
`brain_get_history`	更改所有大脑操作的日志

Cognitive Firewall 3

工具	它做什么
`brain_preflight`	预编辑风险评估：规则+冲突+经验教训+回归风险
`brain_validate_change`	根据DO/DONT/GUARD规则进行编辑后验证
`brain_rebuild_rules`	从所有条目中重新提取防火墙规则索引

Planning & Sessions 4

工具	它做什么
`brain_record_plan`	会议计划，包括范围、已实施和延期项目
`brain_update_plan`	更新计划状态，完成项目，添加下一步
`brain_get_backlog`	按优先级排序的不完整计划
`brain_get_session_summary`	本次会议记录的所有内容（之前使用/压缩）

Environment & Sync 3

工具	它做什么
`brain_sync`	同步超级大国风格文档中的大脑条目
`brain_get_environment`	可用的MCP服务器、技能和代理
`brain_scan_environment`	重新扫描并保存环境

Maintenance 9

工具	它做什么
`brain_update_entry`	更新条目的状态、标题、内容或关系
`brain_review_entry`	将条目标记为已审阅，但不更改内容
`brain_health`	陈旧的条目、孤儿、断开的链接
`brain_rebuild_index`	从入口文件重建index.json（损坏恢复）
`brain_get_metrics`	工具调用计数、创建的条目、活动
`brain_create_snapshot`	备份大脑状态
`brain_list_snapshots`	列出可用快照
`brain_restore_snapshot`	还原快照（首先备份当前状态）
`brain_update`	将brain安装升级至最新版本

Advanced 4

工具	它做什么
`brain_mine_sessions`	从过去的Claude Code会话日志中提取上下文
`brain_auto_document`	查找未记录的git提交并建议条目
`brain_coordinate_team`	为捆绑的代理生成维护运行列表
`brain_visualize`	在浏览器中打开知识图

Code Graph 14

工具	它做什么
`brain_code_build`	构建/重建图形（树状图，按文件缓存）
`brain_code_query`	IDF加权搜索，令牌预算输出
`brain_code_node`	与邻居的节点详细信息
`brain_code_neighbors`	节点的传入/传出边
`brain_code_path`	两个符号之间的最短路径
`brain_code_community`	检测到的社区中的节点
`brain_code_stats`	节点、边、语言、类型
`brain_code_blast`	爆炸半径+更改文件的风险评分
`brain_code_gods`	过连接节点（P99度）
`brain_code_surprises`	意外的跨社区/跨语言边缘
`brain_code_health`	图表是否已构建且新鲜？
`brain_code_visualize`	在浏览器中打开代码图
`brain_bridge`	手动将大脑条目链接到代码节点
`brain_bridge_auto`	自动检测条目↔ 代码链接

它是如何存储的

.brain/
├── overview.md              Project description (auto-generated, overridable)
├── index.json               Fast lookup index + firewall rules
├── text-index.json          Persisted full-text search index
├── decisions/               DEC-001-use-jwt.md … (ADR format)
├── implementations/         What was built and how
├── bugs/                    Symptoms, root causes, fixes
├── patterns/                Reusable conventions
├── lessons/                 Mistakes + rules that prevent them
├── plans/                   Session plans and deferred tasks
├── research/                Alternatives explored and rejected
├── snapshots/               Point-in-time backups
├── code-graph/              graph.json, communities, analysis, AST cache
└── history/changelog.md     Full change log

简单的Markdown+YAML frontmatter——人类可读，git可区分，无需数据库。写入是文件锁定的（正确的锁文件），索引是原子写入的。

命令行界面

大脑也可以在没有代理的情况下从命令行工作：

node cli.js overview                                  # project overview
node cli.js search "authentication"                   # full-text search
node cli.js read DEC-001                              # read single entry
node cli.js check "Switch JWT to session cookies"     # conflict check
node cli.js decide "Use Postgres" "Need RDBMS" "v14"  # record decision
node cli.js link IMPL-005 DEC-002 implements          # link entries
node cli.js visualize                                 # browser graph view

可视化工具(brain_visualize / brain_code_visualize / node cli.js visualize)为任一图形提供基于画布的力定向视图。这为人类检查代理积累的内容提供了便利——代理本身使用查询工具，而不是可视化工具。

测试

npm test          # 280 tests across 6 suites (node:test, no test deps)

套件：核心大脑操作、知识图遍历、Zod验证、MCP处理程序、库内部、性能基准。代码图子系统在下面有自己的套件 tests/code-graph/.

项目结构

claude-brain/
├── mcp-server.js            MCP server — 53 tools
├── install.js               Installer: .mcp.json, hooks, skills, agents, CLAUDE.md
├── mcp-installer.js         brain-installer MCP server (install via tool call)
├── cli.js                   Command-line interface
├── visualize.js             Browser visualizer (brain + code graph)
├── lib/
│   ├── brain-manager.js     CRUD, locking, index, snapshots
│   ├── handlers/            Tool handlers by category (core, recording, safety, …)
│   ├── code-graph/          scan → extract (tree-sitter) → build → cluster → analyze
│   │   ├── languages/       JS / TS / Python / Rust configs
│   │   └── wasm/            tree-sitter grammar binaries
│   ├── search.js            Search with boost scoring
│   ├── text-index.js        Persisted MiniSearch index
│   ├── rule-index.js        Cognitive firewall rule engine
│   ├── conflict-checker.js  Decision conflict detection
│   ├── change-validator.js  Post-edit rule validation
│   ├── integrations/        Environment scanner, sync engine
│   └── schemas.js           Zod input validation for all tools
├── templates/
│   ├── CLAUDE.md.template   Agent instructions injected into projects
│   ├── hooks/               SessionStart / PreToolUse / PostToolUse / Stop / PreCompact
│   ├── agents/              curator, documenter, reviewer, backlog, architect, …
│   └── skills/              brain-workflow, auto-document, brain-health-fix
└── tests/

需求

Node.js≥18
MCP客户端（为 Claude 代码；还支持Gemini CLI注册）

Apache许可证2.0 ·专为 Claude 代码 ·与任何MCP客户端兼容

使用说明

问题

解决方案

快速开始

专为自主性而设计

认知防火墙

代码图谱

53 MCP工具

它是如何存储的

命令行界面

测试

项目结构

需求

相关 MCP

知识图谱记忆服务器

实时文档检索服务

AI持久记忆服务器

代码索引分析工具

知识图谱存储服务

百度优选