Big Brain

big-brain 🧠

让你使用的每个 AI 助手都拥有同一份记忆：你的笔记、项目和任务，以纯 Markdown 格式保存，由你掌控。

每个 AI 工具都会单独保存关于你的私有记忆，彼此之间互不共享。big-brain 彻底改变了这一点。指定一个 Markdown 文件夹（新建的知识库，或你已有的 Obsidian 知识库），Claude Code、Claude Desktop、Cursor、Codex 或任何其他 MCP 客户端都可以搜索、读取和记录内容，并随时更新你的项目和任务。想切换模型时尽管切换；你的上下文会随你而行。

_{使用演示知识库重现的一段真实 Claude Code 对话（对话记录，由 scripts/demo-ai.mjs 录制）；时长仅作示意。}

60 秒快速开始

npx @jzhao234/big-brain setup

这一条命令会安装 big-brain，在 ~/brain 创建知识库；如果你安装了 Claude Code 和 Codex，还会为它们配置连接（MCP 服务以及 /brain、/capture 和 /weekly 技能），并输出可粘贴到 Claude Desktop 或 Cursor 的配置。传入文件夹即可使用其他位置，例如你的 Obsidian 知识库：npx @jzhao234/big-brain setup ~/Obsidian。可以安全地重复运行（已完成的配置会保持不变），而 --dry-run 会显示执行计划，不做任何更改。

然后重启你的助手，并询问 “我正在做什么？” 或 “记录：周五给牙医打电话”。其他客户端以及 claude.ai 和 ChatGPT 等浏览器聊天工具的配置方法，请参阅连接你的 AI 工具。

想手动操作？以下三行就是 setup 为 Claude Code 执行的内容：

npm install -g @jzhao234/big-brain
big-brain init ~/brain
claude mcp add --scope user big-brain -- big-brain-mcp --vault ~/brain

已经在使用 Obsidian？ big-brain 会直接读取现有知识库：无需配置文件，无需迁移，并且只有在你要求更改时才会写入内容（setup 也不会向其中写入任何内容）。之后可以添加 brain.config.json 来映射文件夹名称，每个文件夹对应一项（例如，"folders": {"projects": "Projects", "inbox": "Inbox"}），这样项目和记录就会存放在你指定的位置。参阅 docs/vault-spec.md。

你将获得

• 纯 Markdown 文件。 没有数据库，也不会被锁定。可在 Obsidian 中打开知识库、用 grep 搜索，或将其放入 git。
• 包含 23 个工具的 MCP 服务： 搜索、捕捉、每日日志、项目、任务、链接图谱、相关笔记和知识库健康检查。
• 面向用户的 CLI： big-brain status、big-brain capture、big-brain tasks 等。
• 适用于 Claude Code 和 Codex 的技能（/brain、/capture、/weekly），一条命令即可安装。
• 以项目作为工作单元。 每个项目都是一个文件，包含目标、复选框任务和持续更新的日志。
• 优先采用确定性检索： 支持标题加权的模糊全文搜索、[[wikilink]] 反向链接、标签和 frontmatter 筛选。无需 API 密钥，可离线使用。
• 可选的本地语义搜索。 开启 embeddings.enabled 后，小型设备端模型（通过 @huggingface/transformers）会添加基于含义的匹配结果，并通过 Reciprocal Rank Fusion 与全文搜索融合。释义也能匹配，精确词语仍会计入，而且内容不会离开你的设备。它也为 related_notes 提供支持。请参阅 docs/vault-spec.md。
• 可选的 git 自动提交和推送。 开启 git.autoCommit 后，任何工具每次写入笔记时都只会提交被修改的文件；再开启 git.autoPush，即可在后台推送，让你的其他设备保持同步。git 操作失败不会阻止保存：若提交失败，笔记仍会保存；若推送失败，提交会保留在本地，直到下次推送。
• 不会损坏笔记的编辑。 写入采用原子操作，并按笔记加锁；保留每篇笔记的换行符；绝不写入代码块或 frontmatter 内部；无法解析 frontmatter 时拒绝重写；并且拒绝写入解析后位于知识库之外的任何路径（例如经由符号链接）。docs/vault-spec.md 列出了这些措施无法覆盖的边缘情况。

需要 Node 20 或更高版本。big-brain 尚未达到 1.0 版本：它每天都在使用中，但次要版本仍可能改变行为；请参阅更新日志。

安装

npm install -g @jzhao234/big-brain

这会在你的 PATH 上添加三个命令：big-brain（CLI）、big-brain-mcp（通过 stdio 运行的 MCP 服务）和 big-brain-mcp-http（下文介绍的远程预览服务）。若想不安装直接试用，也可以运行 npx @jzhao234/big-brain status --vault ~/brain。

基础安装不包含语义搜索及其原生依赖。要启用本地嵌入，请将附加包安装到同一位置，然后在 brain.config.json 中将 embeddings.enabled 设为 true：

npm install -g @jzhao234/big-brain @huggingface/transformers@^3.8.1

若要参与 big-brain 本身的开发，请改为从源代码安装：git clone https://github.com/jzhao234/big-brain.git && cd big-brain && npm install && npm run build && npm link。请参阅 CONTRIBUTING.md。

快速开始

big-brain init ~/brain --name "My Brain"   # scaffold a vault
cd ~/brain
big-brain status                           # look around
big-brain install-skills                   # add the /brain, /capture, /weekly skills

然后连接一个 AI 工具（见下文），还可以选择从现有 AI 历史记录中填充知识库。

连接你的 AI 工具

对于本地客户端，运行 big-brain-mcp。通过 --vault <dir> 或 BIG_BRAIN_VAULT 环境变量选择知识库。

Claude Code

claude mcp add --scope user big-brain -- big-brain-mcp --vault ~/brain
claude mcp list        # expect: big-brain ... ✔ Connected

Claude Desktop / Cursor / 其他 MCP 客户端：将以下内容添加到 MCP 配置中（例如 claude_desktop_config.json）。请使用绝对命令路径：GUI 应用启动时不会继承 shell 的 PATH，因此可能无法解析裸写的 big-brain-mcp（运行 which big-brain-mcp 获取路径）。

{
  "mcpServers": {
    "big-brain": {
      "command": "/absolute/path/to/big-brain-mcp",
      "args": ["--vault", "/absolute/path/to/brain"]
    }
  }
}

**其他本地 MCP 客户端：**任何通过 stdio 使用 MCP 的客户端都可以采用相同方式。对于不支持 MCP 的客户端，CLI 的 --json 输出可让知识库支持脚本化操作。

**远程 MCP 预览：**Big Brain 可通过经过身份验证的 Streamable HTTP 端点提供相同的 23 个工具：

export BIG_BRAIN_MCP_TOKEN="$(openssl rand -hex 32)"
big-brain mcp-http --vault ~/brain
# endpoint: http://127.0.0.1:3333/mcp

默认情况下，服务绑定到 localhost，并会在解析 JSON 前检查 Authorization: Bearer <token>。请求正文上限为 1 MB（更大的请求会返回带有 JSON-RPC 错误的 HTTP 413）。允许不带 Origin 的请求；带有 Origin 的请求则必须与 --allowed-origins / BIG_BRAIN_MCP_ALLOWED_ORIGINS 中的某个值完全匹配。该配置默认为空，因此会拒绝浏览器来源的请求。请将其置于 HTTPS 反向代理或安全隧道之后；切勿直接暴露纯 HTTP 监听器。静态令牌是可自托管传输方案的首个里程碑，并非 OAuth 实现，因此仍需使用支持 OAuth 的网关来连接要求 OAuth 的浏览器连接器。请参阅 docs/mcp-setup.md。

**浏览器备用方案（claude.ai / ChatGPT）：**零基础设施方案是将 AI 连接到你的知识库 GitHub 仓库，让它直接读取 Markdown，并在连接器允许的地方写入（某些 GitHub 连接器仅支持读取；由于这是原始文件访问，你也无法使用计算生成的概览、搜索和任务工具）。请参阅 docs/browser-github-connector.md，并粘贴 prompts/browser-github-instructions.md。

接下来，教助手如何使用知识库：在知识库文件夹内工作时，Claude Code 会自动读取知识库的 CLAUDE.md；在其他位置工作时，以及使用其他工具时，请将 prompts/agent-instructions.md 粘贴到它们的自定义指令中。

使用方法：加载和保存

核心是无需反复重新输入上下文。助手会按需加载少量相关内容，并在工作过程中保存零散信息。你只需与它对话。

**加载：**开始时了解概况，并按需获取详情：

你想要……	在 Claude Code 中	CLI
“我在做什么？”	/brain	big-brain status
查找关于 X 的笔记	“在我的大脑中搜索 X”	big-brain search X
阅读一条笔记	“阅读 Auth 项目”	big-brain show "Auth"
查看任务／项目	“有哪些任务快到期了？”	big-brain tasks、big-brain projects
获取周边上下文	“有哪些内容与 X 相关？”	big-brain related X

保存决策、进展和想法（优先追加；绝不破坏性修改）：

你想要……	在 Claude Code 中	CLI
暂存一个零散想法	/capture <text>	big-brain capture "…"
记录决策／进展	“记录一下我已交付 X”	big-brain daily --log "…"
添加任务	“为项目 Y 添加一项任务”	big-brain task add "…" --note Y
完成任务	“标记为已完成”	big-brain task done <id>
启动项目	“新建项目：……”	big-brain project new "…"
添加到笔记	“把这条内容添加到 Auth 笔记的 Log 中”	big-brain append "Auth" --heading Log -- "- …"
修改元数据	“将 Auth 的截止日期设为……”	big-brain frontmatter "Auth" due=2026-11-01
归档笔记	“归档那条笔记”	big-brain archive "Auth"

回顾：/weekly 会引导你完成一轮检查：整理收件箱、精简项目、重新安排逾期任务、修复失效链接，并进行整合：big-brain doctor 会标记臃肿的笔记和近似重复项，回顾流程会提出拆分／合并／清理过时事实的建议，供你批准。捕获和搜索让大脑保持实用；整合让它值得信赖。

技能

三项技能将工具封装为命令，适用于 Claude Code（/brain）和 Codex（$brain）：

• **brain：**加载概览，并在本次会话中切换到具备大脑上下文的模式
• **capture：**以零阻力方式捕获内容到收件箱
• **weekly：**引导完成每周回顾

big-brain agents install claude codex 会为两个 Agent 安装这些技能（见下文）。big-brain install-skills 仍会将 Claude 版本复制到 ~/.claude/skills（--force 会覆盖）。这些技能与路径无关：它们会调用 big-brain CLI／MCP 工具，并从 BIG_BRAIN_VAULT（或 --vault）解析知识库，因此同一技能可在每台机器上使用。

Agent 配置：保存在知识库中的 Agent 设置

编码 Agent 的个人设置（技能、全局指令、钩子、状态栏和一些设置）也可以保存在知识库中，这样每台机器都能通过一条命令获得相同的设置，并且在一台机器上所做的更改会通过 git 同步到其他机器。

agents/claude/instructions.md   -> ~/.claude/CLAUDE.md
agents/claude/skills/<name>/    -> ~/.claude/skills/<name>   (one link per skill)
agents/claude/files/**          -> ~/.claude/**              (one link per file: statusline.sh, hooks/…)
agents/claude/settings.json     -> merged into ~/.claude/settings.json
agents/codex/instructions.md    -> ~/.codex/AGENTS.md
agents/codex/skills/<name>/     -> ~/.codex/skills/<name>
agents/codex/config.toml        -> merged into ~/.codex/config.toml

big-brain agents status                    # linked, missing, edited here, or only on this machine
big-brain agents install --dry-run         # show the plan
big-brain agents install                   # link everything (agents with a profile; or name them)
big-brain agents save claude statusline.sh --setting statusLine    # capture a local change
big-brain agents save codex skills/my-skill --setting tui.status_line

安全保障：

• 创建链接，而非副本。 在知识库中（或通过链接）编辑技能或脚本，执行 git pull 后，每台机器都会获得更新。~/.claude / ~/.codex 中的其他所有内容（其他技能、历史记录、凭据）都不会被触碰。
• 除非你明确要求，否则不会替换未受管理的内容。 如果有文件妨碍操作，系统会报告；--replace 会将其移到 ~/.local/state/big-brain/backups 下带时间戳的备份中（该目录位于所有 Agent 文件夹之外，因此备份的技能绝不会被加载），并生成恢复清单，然后再链接到知识库中的文件。
• 设置会以三方方式合并。 big-brain 会记住它在每台机器上应用的设置：本地编辑过的值会被报告，而不会覆盖（使用 --replace 则采用知识库中的值）；从未改动过的值会跟随知识库；从知识库中删除的键只有在未被编辑过时才会移除。Claude 钩子会根据事件、匹配器和命令进行匹配，因此更改超时时间会更新钩子，而不是重复注册。TOML 会逐行编辑（注释、信任条目和钩子哈希都会保留），任何会更改受管理键以外内容的编辑都会被拒绝。
• 先规划，再写入，失败时回滚。 所有链接和设置更改都会在首次写入前验证；如果操作被拒绝，机器不会受到影响；如果某个步骤仍在中途失败，已完成的步骤会被撤销（如果连撤销也失败，则不会删除任何内容，并会说明原始文件的位置）。不会通过符号链接文件夹写入内容，作为符号链接保留的设置文件（例如位于 dotfiles 仓库中的文件）也会继续保持为符号链接。--prune 会移除知识库文件已被删除的链接。
• save 会拒绝已知的机密文件和状态文件。 整个设置文件、.credentials.json、auth.json、.env 文件、历史记录、会话、缓存和数据库都会被拒绝；请使用 --setting 保存单项设置。它不会检查文件内容，因此请检查要保存的文件和 --setting 值（例如，env.API_KEY 设置会原样复制）。
• Codex 钩子仍保留在本地。 Codex 要求你在每台机器上信任每个钩子，因此 Codex 的钩子注册不会受到管理。Claude Code 用户：请通过 /hooks 检查新钩子。如果 Codex 的 AGENTS.override.md 覆盖了 AGENTS.md，状态会发出警告。

系统会遵循 CLAUDE_CONFIG_DIR 和 CODEX_HOME。文件夹名称在 brain.config.json 中通过 folders.agents 设置（默认为 agents），且永远不会作为笔记被索引。

在多台机器上使用

知识库是 git 仓库，因此这只需使用 git：在每台机器上克隆它，然后每台机器都使用自己的克隆运行 big-brain-mcp。 Git 会让它们保持同步。

• 写入端：自动同步。 在 brain.config.json 中设置 git.autoCommit（和 git.autoPush），这样来自任何机器上任何工具的每次笔记写入都会被提交并推送（尽力而为）。请参阅 docs/vault-spec.md。

• 读取端：开始前先拉取。 添加一个 SessionStart 钩子，确保每次会话启动时都使用最新版本：

  // ~/.claude/settings.json
  "hooks": { "SessionStart": [ { "hooks": [ { "type": "command",
    "command": "git -C \"$HOME/brain\" pull --ff-only --quiet 2>/dev/null || true" } ] } ] }
  

  --ff-only 表示拉取绝不会覆盖本地工作。（也可以手动运行 git -C ~/brain pull。）

在新机器上：安装 big-brain（见上文），git clone 你的知识库，运行 big-brain agents install，注册 MCP 服务。四条命令，就能让你的笔记、技能、指令、钩子和状态栏与其他机器保持一致。

从你已有的 AI 历史记录中播种

空白的大脑毫无用处；要让它发挥作用，最快的方法就是提取你的大模型已经了解的关于你的信息。你频繁使用的每个助手（ChatGPT、Claude、Gemini）都在记忆和聊天记录中保存着数月来关于你的项目、偏好和目标的上下文。播种会一次性将这些内容提取到你拥有的文件中。

1. 在你使用的每个大模型中运行播种访谈。 将 prompts/seed-interview.md 中的提示词复制到每个助手中，最好选择历史记录最多且已启用记忆/个性化功能的账号。这是一场结构化的导出访谈，涵盖个人资料、当前项目、技术栈、你喜欢如何与 AI 协作、目标、人际关系、日常惯例、长期约束、待处理事项和盲点。它会要求模型提供具体信息、将推断标记为 (inferred)，并在没有信息时写上 "No data"，而不是凭空编造，因此输出足够可信，可以据此继续整理。

2. 将每份输出保存到知识库的 inbox/ 中，每个模型保存为一个文件（inbox/seed-chatgpt.md、inbox/seed-claude.md，等等）。暂时不要整理任何内容：先捕捉，这是收件箱的核心理念。

3. 分类处理。 请连接了知识库的助手运行 process-inbox MCP 提示词（或者直接说 "triage my inbox" / 在 Claude Code 中运行 /weekly）。它会合并不同模型中的重复内容（不同大模型了解你的不同侧面，它们的内容大多互为补充，而非相互冲突），然后将材料整理成清晰的结构：为所有正在进行的项目建立项目记录和任务、创建 people/ 笔记、创建可供 Agent 指令引用的偏好笔记、为你的技术栈/设置创建参考笔记，并将待处理事项转为任务。你可以逐项确认；原始导出内容可保存在 archive/ 中，以保留来源记录。

4. 偶尔重复执行。 模型会不断积累关于你的上下文；每隔几个月重新运行访谈并分类处理差异，可让知识库始终领先于任何单一服务提供商的记忆。

另外还有两种值得了解的播种方式：如果你已经在使用 Obsidian 知识库，big-brain 可以直接接管并在原处使用它（添加 brain.config.json，通过 folders 配置映射文件夹名称；参见 docs/vault-spec.md）；而且，与连接了知识库的 Agent 进行工作会话，也会顺带完成播种：Agent 指令会让它在协作过程中创建项目并记录事实，因此即使跳过访谈，大脑也会根据真实活动逐步填充。

知识库

brain/
├── BRAIN.md          # index & ground rules
├── CLAUDE.md         # agent instructions (picked up by Claude Code)
├── brain.config.json
├── inbox/            # capture now, organize later
├── daily/            # one note per day: focus, log, tasks
├── projects/         # one file per project: goal, tasks, log
├── areas/            # ongoing responsibilities
├── notes/            # evergreen knowledge, densely [[linked]]
├── people/           # one note per person
├── reference/        # external facts, docs, how-tos
├── archive/          # nothing is deleted, only archived
└── templates/        # daily/project/note/person templates

笔记采用 Markdown 格式，并带有 YAML frontmatter（type、tags、status、due 等）。任务使用 - [ ] 复选框，并带有类似 Obsidian Tasks 的元数据：📅 2026-03-01 表示到期日，⏫ 表示优先级，✅ 表示完成日期。完整详情见 docs/vault-spec.md。

MCP 工具

工具	功能
brain_overview	了解当前情况：活跃项目、到期/逾期任务、收件箱、近期笔记
search_notes	全文搜索，并可按类型/标签/文件夹/状态筛选
read_note / list_notes	按路径、标题或别名读取；按文件夹/类型/标签浏览
create_note / append_note / replace_note_body	写入笔记（默认安全方式为追加）
update_frontmatter / archive_note	修改元数据；非破坏性删除
capture	快速捕捉内容到收件箱
daily_note / daily_log	日记和带时间戳的工作日志
list_projects / create_project / set_project_status	项目生命周期管理
list_tasks / add_task / complete_task / update_task	管理整个知识库中的复选框任务；update_task 可就地重新安排、调整优先级、改写、重新打开或取消任务
note_links	笔记的外链和反向链接
related_notes	显示相关笔记及其关联原因：链接、共同引用、少见的共有标签、标题提及、语义相似度
list_tags / vault_health	标签统计；检查失效链接、无法解析的 frontmatter、过时项目、臃肿/重复笔记和逾期任务

此外还有三个 MCP 提示词：orient、weekly-review、process-inbox。

命令行

big-brain setup [dir]           one-step install + connect
big-brain init [dir]            scaffold a vault        big-brain tasks [-p X] [-t tag] [--due-by D]
big-brain status                overview                big-brain task add|done ...
big-brain search <query>        search (hybrid if on)   big-brain projects [--status active]
big-brain show <note>           print a note            big-brain project new|status ...
big-brain new <title>           create a note           big-brain links <note>
big-brain related <note>        related notes + why     big-brain tags
big-brain capture <text>        quick capture           big-brain doctor
big-brain daily [--log "..."]   daily note / journal    big-brain index [--status|--rebuild]
big-brain append <note> <text>  append [--heading H]    big-brain frontmatter <note> k=v ...
big-brain archive <note>        archive (non-destructive delete)
big-brain agents status|install|save   agent setup from the vault (see Agent profiles)
big-brain install-skills        add Claude Code skills  big-brain mcp   run the MCP server

search、related、tasks、projects 和 doctor 支持使用 --json 进行脚本处理。task done 和 task update 可接受任务 ID 或任务文本：若某个任务的完整文本包含在较长任务中，则优先匹配该任务；若片段存在歧义，则会列出候选项。在以 -（列表项）开头的 append 文本前加上 --，否则它会被当作选项读取。frontmatter 会将每个值解析为 YAML，与文件中的 key: value 格式相同：'tags=[work, llm]' 是一个列表，due=2026-11-01 会保留为日期字符串，而 key=null（或 key=）会移除该键。为包含空格的赋值加上引号，否则 shell 会将它拆分成多个参数。

设计原则

1. 文件胜过数据库。 30 年后仍可阅读的 Markdown 胜过任何应用。
2. 知识库由人掌控；Agent 是访客。 Agent 可以自由追加和捕获内容，但重写和归档应谨慎进行。
3. 确定性胜过巧妙。 搜索 + 链接 + 标签可可靠检索并支持离线使用；语义层是可选的、完全本地的，并且与精确搜索融合，而非取而代之。
4. 从设计上与模型无关。 所有操作都通过 MCP 或文件系统完成；不会依赖任何特定的 AI 供应商。

贡献与支持

欢迎提交错误报告和范围明确的拉取请求；请先阅读 CONTRIBUTING.md，其中说明了项目的受理范围。请按照 SECURITY.md 中的说明私下报告安全问题，不要在公开 issue 中报告。

npm install
npm run typecheck && npm run lint && npm test
npm run build

持续关注

big-brain 是一个以开源方式开发的副项目。如果它对你有用，点个星标可以帮助其他人发现它。想了解新版本以及我接下来开发的内容，可以在此仓库中使用 Watch → Custom → Releases，或在 GitHub 上关注 @jzhao234。

MIT © Junhao Zhao