brain-core

brain-core

为你的 Claude Code Agent 提供跨会话留存的记忆。 一个本地 MCP 服务、五个工具、一个可供你阅读的 Markdown 知识库，以及一项验证记忆召回能力的评测。只需一条命令即可安装。

brain-core 为 Claude Code Agent 提供存储在本地磁盘上的长期记忆。你为 Agent 命名，告诉它你是谁；从那以后，每次会话开始时都会显示昨日简报、你做过的决定、发生变化的事实，以及你给出的纠正。它通过写入 Markdown 文件来记忆，你可以在任意编辑器中打开这些文件；还可以通过本地 SQLite 索引和 Hindsight（可自托管的向量记忆）再次找到相关内容。除了你已经在使用的大模型调用外，任何数据都不会离开你的电脑。

它面向在自己的电脑上运行一个或多个 Agent 的个人用户：独立开发者、创业者，以及任何厌倦了每天早上都要重新解释项目的人。它不是托管服务，也不是团队产品。

它是 MCP 服务还是工具？

两者都是。一个 Python 包，三种使用方式：

组成部分	它是什么	使用者
brain serve	一个 MCP 服务，由 Claude Code 从 Agent 的 .mcp.json 启动，并提供五个工具	Agent 在每次会话中自动使用，你无需操作
brain 命令	一个命令行工具：brain init、brain doctor、brain index、brain hindsight install、brain cron install、brain daily、brain weekly	你在初始设置时使用一次，之后由 cron 执行
brain_core.Agent	上述两种方式所依托的 Python 库	评测运行器、演示脚本，以及你自己的脚本

对于 Claude Code 用户：这是一个带有五个记忆工具和单行安装命令的 MCP 服务。对于 Python 开发者：这是一个带 MCP 前端的记忆库。

curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex

---

问题

每次与编码 Agent 开始会话时，它都一无所知。你得重新解释项目、重新说明上周做过的决定，还得再次指出它周二犯的错误。虽然有记忆插件，但它们会把你的笔记存到别人的云端，提供 30 个 Agent 无法取舍的工具，而且没有人展示评测结果。

brain-core 则恰恰相反：数据存储在本地，只有五个工具，Markdown 文件由你掌控，还有一套会报告命中率的测试集。

工作原理

1. brain init 会搭建 Agent 文件夹。 它会写入一个 CLAUDE.md，其中包含 Agent 和你的名字；五个规则文件（身份、原则、权限、记忆、系统）；三个技能；一个安全钩子；一个 .mcp.json；以及一个空知识库。Claude Code 会将该文件夹作为项目读取，因此 Agent 从第一条消息起就知道如何使用自己的记忆。
2. brain serve 会在 Claude Code 中作为 MCP 服务运行。 它会准确提供五个工具。Agent 调用这些工具的方式与调用其他工具一样；你无需手动运行它们。
3. 每次会话都有固定流程。 Agent 通过 brain_session('start') 开始会话，该命令会返回一个信息块：今日简报、执行状态、心智模型、每项进行中任务的回忆，以及上一场会话是否崩溃的标记。会话结束时，Agent 会调用 brain_session('end')，归档当天内容并重写次日状态。
4. 记忆是写入的，而非推断出来的。 当你说了值得保留的内容，Agent 会调用 brain_remember(text, kind)。内容会先写入知识库，再写入 SQLite 索引、Hindsight 和关系表；回复会说明每一层分别做了什么。重复内容会被跳过。如果事实的值发生变化，就会显示 ⚠ Fact changed 横幅，并保留旧内容，以便查看历史记录。
5. 一次查询即可检索所有存储。 brain_recall(query) 会同时搜索知识库、索引和 Hindsight，去重后按相关性和近期程度排序，并将回复限制在 6k 个 token，以免上下文被塞满。
6. 两个 cron 任务负责日常维护。 brain daily 会撰写次日早晨的简报并备份 Hindsight。brain weekly 会将超过 30 天的会话归档到月度摘要中，并刷新心智模型。

flowchart LR
    CC[Claude Code] -->|MCP, 5 tools| B[brain serve]
    B --> V[(vault/ markdown)]
    B --> S[(brain.db SQLite + FTS)]
    B --> H[(Hindsight vector memory)]
    B --> G[(relations table)]
    CRON[brain daily / weekly] --> V
    CRON --> H

五个工具

工具	一次调用会执行的操作
brain_session('start')	返回完整的启动信息块：每日简报、执行状态、心智模型、每项任务的回忆、收件箱计数，以及上一场会话是否崩溃的标记
brain_recall(query, scope)	一次查询即可搜索所有存储、此文件夹的 Claude Code 转录记录，以及包含的任何 stores.notes 文件夹；结果会去重、按相关性和近期程度排序，并限制在 6k 个 token 以内；scope='transcript' 用于检索过去会话中说过和运行过的内容，在第一天很有用
brain_remember(text, kind)	按知识库 → SQLite → Hindsight → 图谱的顺序写入，并报告每一层的结果。近似重复内容会被跳过；值发生变化时会显示 ⚠ Fact changed 横幅，并保留旧内容
brain_distill(source)	将 URL、GitHub 仓库、YouTube 视频、PDF、文件或粘贴的文本保存到不可变的 raw/ 文件夹，供 Agent 整理
brain_session('end')	清空队列，关闭当天的会话文件，重写状态和复盘内容，并写入正常关闭标记

此外，brain_status() 可通过一次调用检查运行状况：哪些存储正常运行、始终加载的上下文消耗了多少 token、会话是否已开启，以及有哪些决策在等待你处理。

安装

开始之前

需要	原因	检查方式
macOS，或使用 systemd 的 Linux	安装程序会设置后台服务和 cron	uname
约 2 GB 磁盘空间和 10 分钟	Hindsight 内置了嵌入式 Postgres 和 CPU 嵌入模型
Anthropic API 密钥，或 Claude Code 登录	Hindsight 使用大模型对记忆进行推理	echo $ANTHROPIC_API_KEY
Claude Code	Agent 在其中运行；如果缺少，安装程序会添加	claude --version

运行命令前，先选好两个名字：Agent 的名字（--agent）会成为它的文件夹名和身份；你自己的名字（--user）则决定 Agent 如何称呼你。之后都可以通过编辑 CLAUDE.md 来更改。

macOS，一行命令

curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex

执行顺序如下。重新运行时会跳过已完成的步骤，因此失败后只需修复原因，再运行同一行命令。

== 1/8 Xcode command line tools      present
== 2/8 Homebrew                      present
== 3/8 uv, gh, gitleaks, node, Claude Code
== 4/8 brain-core (v0.4.0)           installed with uv tool
== 5/8 Agent Atlas at ~/Agents/Atlas  31 files written
== 6/8 Hindsight (required store)    service: healthy
== 7/8 Cron                          daily 06:07, weekly Sun 07:13
== 8/8 Doctor                        Health check: OK

步骤	执行内容	如果在此处停止
1	通过 Xcode 命令行工具检查是否有 git	macOS 会打开安装对话框；完成安装后重新运行
2	如果尚未安装 Homebrew，则安装它	Homebrew 会自行提示输入密码
3	使用 Homebrew 安装 uv、gh、gitleaks、node 和 Claude Code	已安装的内容会保留
4	使用 uv tool 从 PyPI 安装 brain 命令	--ref v0.4.0 会改为固定到一个 git 标签
5	运行 brain init 并写入 Agent 文件夹	绝不会覆盖已有的 brain.yaml
6	将 Hindsight 安装为运行在 127.0.0.1:8888 上的 launchd 服务	首次启动会下载嵌入模型；请等待几分钟
7	将 brain daily 和 brain weekly 安装为 launchd Agent
8	对新建的 Agent 运行 brain doctor	随时运行 brain doctor ~/Agents/Atlas 可再次检查

安装程序运行后

有两件事安装程序无法替你完成：

export ANTHROPIC_API_KEY=sk-ant-...     # add it to ~/.zshrc too
brain hindsight install                 # copies the key into ~/.config/hindsight/env (mode 600) and restarts the service
claude                                  # sign in to Claude Code once

如果运行安装程序时密钥不在你的 shell 环境中，安装程序会打印提示。如果你不想使用 API 密钥，可以传入 --provider claude-code，让 Hindsight 改用你的 Claude Code 登录信息。此模式仅供个人使用。

标志	含义
--agent NAME	Agent 的名称（必填）
--user Alex	Agent 称呼你的方式
--dir PATH	Agent 所在位置，默认为 ~/Agents/NAME
--provider	anthropic（默认）、openai 或 claude-code（使用你的 Claude Code 登录信息；仅供个人使用）
--api-key-env VAR	从 <PROVIDER>_API_KEY 以外的变量读取密钥
--profile DIR	最后复制到通用规则之上的文件夹，用作你自己的原则
--dashboard	Hindsight 网页界面，位于 http://localhost:9999
--ref v0.4.0	固定到一个 git 标签，而非 PyPI 发布版本

Linux

同样是一行命令。需要预先安装 git 和 curl。随后会从 astral.sh 安装 uv；如果已安装 node，则会使用 npm 安装 Claude Code；将 Hindsight 作为 systemd --user 服务运行；并将两个任务写入用户 crontab，作为带标签的行，以便重新运行时查找并替换。

手动安装，适用于任何平台

uv tool install brain-core-mcp   # or: uv tool install git+https://github.com/xy-claude/[email protected]
brain init Atlas --path ~/Agents/Atlas --user Alex
brain hindsight install          # launchd on macOS, systemd --user on Linux
brain cron install ~/Agents/Atlas
brain doctor ~/Agents/Atlas

检查是否成功

brain doctor ~/Agents/Atlas

它会打印 Agent 名称、配置路径、每张表的行数，以及 Health check: OK。存储健康状态会显示在首次 brain_session('start') 回复中，也会显示在 brain_status() 中。常见问题如下：

现象	原因	解决方法
brain: command not found	uv tool 的 bin 文件夹不在你的 PATH 中	运行 uv tool update-shell，然后打开一个新终端
ERROR: no brain.yaml at ...	路径错误	传入 Agent 文件夹，或其中的 brain.yaml
hindsight unreachable at http://127.0.0.1:8888	服务仍在启动，或尚未安装	等待一分钟；如果仍无法连接，运行 brain hindsight install
安装程序提示 ANTHROPIC_API_KEY is not set in this shell	安装服务时密钥不在 shell 环境中	导出密钥，然后再次运行 brain hindsight install；它会重写 ~/.config/hindsight/env
Claude Code 中没有 brain 工具	Claude Code 是在 Agent 文件夹之外启动的	运行 cd ~/Agents/Atlas && claude，然后运行 /mcp 确认

首次会话

cd ~/Agents/Atlas && claude

Agent 的 CLAUDE.md 会告诉它先调用 brain_session('start')。返回结果如下：

{
  "session_id": "s-20261102-a1b2c3",
  "brief": "# Daily Brief — 2026-11-02 ...",
  "executive_state": "## Primary Objective ... ## Top Missions ... ## Pending Decisions ...",
  "mental_models": {"active-priorities": "..."},
  "missions": {"M-001 first mission": [ ...3 recall hits... ]},
  "inbox": 0,
  "recovery": null
}

第一天，简报是空的，执行状态则是模板。这是预期情况。首次会话时，告诉 Agent 你正在做什么：项目、技术栈、已做出的决定，以及你喜欢的工作方式。每条重要信息都会变成一次 brain_remember 调用，回复会显示每一层的处理结果：

{"status": "written", "layers": {"vault": {"status": "written", "detail": "facts.md › System"},
                                 "sqlite": {"status": "written"},
                                 "hindsight": {"status": "written", "detail": "op 162bdbaa"}}}

首次会话可以尝试以下操作：

• 陈述一个事实，然后更正它。“API 监听端口是 8887。”稍后说：“更正，应该是 8888。”第二次写入会返回 ⚠ Fact changed 横幅，并且 vault/facts.md 会保留两行记录。
• **提供来源。**粘贴一个 URL 或 GitHub 仓库，并让它提炼内容。页面会原样保存到 vault/raw/，Agent 会在 vault/knowledge/ 中整理出一个页面。
• 询问之前提过的内容。“我们之前对数据库做了什么决定？”只需调用一次 brain_recall，每条命中结果都会标明来源文件。
• **在编辑器中打开知识库。**你刚才看到的每次写入，都是 Markdown 文件中的一行。如果 Agent 写错了，可以直接编辑。

说“谢谢，今天就到这里”，它就会运行 brain_session('end')。明天 06:07，brain daily 会根据你今天的工作生成下一份简报，而下一次 claude 会话会从这份简报开始。

Agent 文件夹中有什么

~/Agents/Atlas
├── CLAUDE.md                 identity and the five-tool protocol (3k tokens always loaded)
├── .claude/
│   ├── rules/                01-identity 02-doctrine 03-authority 04-memory 05-system
│   ├── skills/               distill, session-end, brain-check
│   └── hooks/                block-dangerous-bash.sh (rm -rf, force-push, curl|sh …)
│                             + recall of past sessions when a command fails
├── .mcp.json                 brain serve . + Hindsight
├── brain.yaml                stores, session files, cron schedule
├── vault/                    facts.md patterns.md decisions_log.md corrections.md
│   ├── sessions/             one file per day (HSAM)
│   ├── knowledge/ raw/       the LLM-wiki: immutable sources, compiled pages
│   └── executive_state.md    objective, missions, pending decisions
└── data/brain.db             SQLite + FTS5 + relations + transcript index

所有内容都是 Markdown 或 SQLite。可以在 Obsidian 中打开知识库、搜索、提交或删除一行。Agent 不会介意。

效果如何？

评测属于测试套件的一部分，并会在 CI 中运行。

集合	命中数
合成测试知识库上的 28 项召回任务（CI），分层包括：20 项单跳、2 项多跳、1 项知识更新、2 项拒答、3 项时间相关任务；每项运行三次（pass^3）	28 / 28
作者真实知识库上的 20 项调优任务 + 10 项留出召回任务，涵盖 7 个月的会话	20 / 20 和 10 / 10
11 项写入场景：去重、值变更横幅、关系路由、拒绝处理机密信息	11 / 11
增长：经过 30 天会话后，CI 中的测试知识库脑在每项可信的特质信号上，得分都高于第一天的同一知识库	成立

这些测试切片正是记忆基准测试（LoCoMo、LongMemEval）指出单一命中率会掩盖的情况：值发生变化时，新的值必须优先于过时值；无法回答的问题必须不返回任何结果；询问某一天的情况时，必须找出那天的归档。使用 Hindsight 时，每次召回查询约需 1.7 秒；完整的启动内容块约需 4 秒，且少于 6k 个令牌。

python tests/eval/run_recall.py --config ~/Agents/Atlas/brain.yaml   # your own vault

十二种特质：先天与成长

brain-core Agent 天生具备十二种特质，并通过经验不断成长。先天特质是 brain init 初始化时提供的内容，也是清空知识库后冷启动仍会保留的内容；成长特质则是在知识库中不断积累的内容。brain_status() 会根据磁盘上的证据为每项特质评分，而 brain daily 每天记录一行，以便观察数周内的变化曲线。

记忆	控制	社交
工作记忆	学习	用户模型
情景记忆	推理与规划	权威性
语义记忆	决策
程序性记忆	元认知
	执行
	目标管理

特质不会只对应一个数字，而是由多个信号组成，每个信号都有样本量和判定：如果答案依据来自 Agent 在该会话中未写入的文件，则判定为可信；如果指标是大小或年龄，则判定为成本；如果尚无相关证据，则判定为待定。产物数量和自我写入的评分不属于信号。特质列表及其研究依据：docs/TRAITS.md。

记忆的组织方式

类型	存放位置	写入格式
事实	vault/facts.md 中的 ## Domain 下	- text (date)
模式	vault/patterns.md	- **title** — text (date)
决策	vault/decisions_log.md	## date — title + Decision / Reason / Classification / Confidence
更正	vault/corrections.md	### [date] title + Error / Correction / Implied rule / Theme
笔记	vault/sessions/YYYY-MM-DD.md	HSAM 部分下的一条项目符号
关系	data/brain.db	主体 —[谓词]→ 对象
原始数据	vault/raw/	带有 sha256 的不可变来源；Agent 会编译 vault/knowledge/

规则：按内容哈希保证幂等，只追加，不删除；任何存储接收内容前都会拒绝机密信息。详情见 docs/VAULT_SCHEMA.md。

要求

• 安装程序需要 macOS 或 Linux；只要能运行 Python 3.12，库和 MCP 就能运行
• Hindsight（MIT）作为向量存储，由安装程序为你安装。Postgres 已内嵌；嵌入在 CPU 上运行
• 用于 Hindsight 推理的大模型密钥，或供个人使用的 Claude Code 登录

在 PyPI 上，软件包名为 brain-core-mcp（普通名称与一个无关项目冲突）；命令仍为 brain，导入名称仍为 brain_core。

路线图

• 提供仅使用 SQLite 的模式，以便首次运行时无需 Hindsight
• 支持对现有笔记文件夹执行 import

与 claude-mem、mem0 OpenMemory 及普通 CLAUDE.md 的比较：docs/COMPARISON.md。已发布的里程碑：docs/MILESTONES.md。设计：docs/SPEC_v0.2.md。针对会读取不可信文本的记忆的威胁模型：docs/THREAT_MODEL.md。

贡献

欢迎提交问题和拉取请求。运行 uv sync --all-extras --all-groups，然后运行 ruff check、mypy、pytest。详见 CONTRIBUTING.md。

许可证

MIT。