Nucleus Mcp

.brain — 可移植的决策日志

AI 工具都能读取的可移植决策日志。一个 MCP 服务。适用于任何 AI 工具。纯文件。

每次 AI 编码会话开始时，都要重新解释上一场会话已经了解的上下文。.brain 是仓库中的一个文件夹，Claude Code、Cursor 和 Codex 都能通过同一个 MCP 服务读取。决策、策略、计划——只需记录一次，就能在每场会话和每种工具中持续保留。

采用 MIT 许可。基于文件（纯 JSON + markdown）。无需嵌入。不受供应商锁定。

---

还包括：nucleus-rabbithole

nucleus-mcp 还附带第二个完全独立的工具：nucleus-rabbithole， 一款为容易分心的开发者打造的注意力深度追踪器。

它为 AI 提供深度栈的压入／弹出操作、上下文切换过载检测器、 开放循环外部化工具和每周回顾——所有数据都由本地 SQLite 支持， 无需网络，也无需守护进程。

# Already installed with nucleus-mcp — just run:
nucleus-rabbithole

Claude Code .mcp.json 代码片段：

{
  "mcpServers": {
    "nucleus-rabbithole": {
      "command": "nucleus-rabbithole",
      "args": []
    }
  }
}

完整文档：docs/RABBITHOLE.md — 也会随软件包一起安装，位于 <site-packages>/mcp_server_nucleus/docs/RABBITHOLE.md。

---

三大前沿

让 AI 可靠性随时间不断累积的核心循环：

  GROUND              ALIGN               COMPOUND
  ──────              ─────               ────────
  Machine verifies    Human corrects      System learns

  AI writes code  →  You fix a mistake →  Delta recorded
  GROUND checks   →  Verdict stored    →  DPO pair created
  Receipt logged  →  Event emitted     →  Training data grows
       │                   │                    │
       └───────────────────┴────────────────────┘
                    Reliability improves

GROUND — 5 层执行验证。语法、导入、测试、运行时。走出形式系统，检查 AI 的工作成果。

ALIGN — 一次调用即可纠正。nucleus review 会针对先前的决策记录评估结果，并将其转化为训练样本对和事件。

COMPOUND — 差异用于衡量意图与现实之间的差距。重复出现的模式会成为策略。负向差异会成为训练信号。

每个工具的响应都会显示前沿健康状况：

[frontiers: GROUND 42 | ALIGN 12 | COMPOUND 28]

---

快速开始

目前无法使用托管访问。 远程 MCP 端点已撤下，正在等待访问控制审查。请使用下方的本地安装方式。

本地安装（Cursor、Windsurf、Claude Desktop）：

pip install nucleus-mcp
nucleus init --recipe founder

两条命令。Nucleus 即开始运行。nucleus init 会初始化 .brain/、写入项目本地的 .mcp.json，并询问是否要配置已安装的所有 AI 客户端。选择“是”，然后重启客户端。

nucleus build 还需要 PATH 中有一个编码 Agent CLI——以下任选其一：claude（npm i -g @anthropic-ai/claude-code）、devin 或 agy，并且已完成身份验证（分别运行一次 claude/devin/agy login）。如果没有，build 会停在计划阶段。如果 build 报告 status='error'，但原因不明确，供应商 CLI 自身的错误（例如登录已过期）会写入 .brain/relay/cross_vendor/*.json——请检查其中最新的文件。

---

功能介绍

涵盖 16 个门面中的 30 个 MCP 工具，提供 210 个操作，此外还有 19 个 brain:// 资源和 8 个提示词。请运行 python3 tools_audit/count_surface.py 重新生成这些内容，而不要手动编辑——该脚本问世前，三个手动维护的副本中的数字曾经彼此不一致。

• GROUND — 执行验证（5 个层级：差异、语法、导入、测试、运行时）
• ALIGN — 人工修正（一次调用即可完成判定 + 差异 + DPO + 事件）
• Memory — 可跨会话持久保存的 Engram。写入一次，永久回忆。
• Sessions — 保存上下文，以后继续。会话轨迹展示最近 3 个会话。
• Tasks — 带有升级机制、HITL 门控和心跳监控的优先级队列。
• Governance — 紧急停止开关、合规配置（EU DORA、MAS TRM、SOC2）、审计追踪。
• Orchestration — Agent 槽位、多脑同步、任务分发。
• Archive — 训练流程（SFT + DPO）、差异追踪、前沿健康状况仪表板。

基准测试： decision-retention-evals — 你的 AI Agent 是否记得代码为何如此编写？（当前镜像请在 Discord 上询问）

---

Nucleus Pro

以上所有内容均免费（MIT）。Nucleus Pro 提供可验证的治理功能：

nucleus trial                              # 14-day free trial
nucleus compliance-check                   # Score your AI governance
nucleus audit-report --format html -o report.html   # Audit report

每月 $19 或 每年 $149 — nucleusos.dev/pricing

	免费版	Pro
30 个工具、19 个资源、8 个提示词	是	是
持久记忆	是	是
治理与 HITL	是	是
审计追踪（DSoR）	是	是
签名审计报告	-	尚未推出
合规导出	仅评分	完整 PDF/HTML
优先处理问题	-	是

---

安装

pip install nucleus-mcp      # or:  uvx nucleus-mcp  ·  pipx install nucleus-mcp
nucleus init                 # seeds .brain/, then offers to configure your AI clients

需要 Python ≥3.10；在 3.14 上，某些依赖项（例如 watchdog）会从源代码构建——3.11–3.13 可顺利安装预编译 wheel。init 会将其在 PATH 上首先解析到的 nucleus 二进制文件写入生成的配置中——如果虚拟环境旁边有过时的全局安装，pipx/uvx 或 which nucleus 会确保使用正确的版本。

nucleus init 始终会执行三项操作：初始化 .brain/、写入 Claude Code 在该文件夹中读取的项目本地 .mcp.json，并运行记忆写入与回忆自测，让你在信任它之前先确认其正常工作。

随后，它会在交互式终端中询问是否要配置其他 AI 客户端。回答是，它就会将 nucleus 条目写入所有检测到已安装的客户端——Claude Desktop、Claude Code、Cursor、Windsurf、Antigravity、Devin——并备份每个被修改的文件。它会告知已配置的客户端数量；如果数量为零，也会明确说明，不让你猜测。

使用 --no-wizard 运行，或在无法提问的脚本中运行时，它只会初始化 brain 并写入项目本地配置。此时请使用 nucleus setup 配置客户端。

然后重启 AI 客户端。验证方式：客户端的工具列表中应显示 nucleus_* 工具，或者运行 nucleus doctor。

除非传入 --force，否则绝不会修改现有的 nucleus 条目。对于大多数客户端，编辑前会创建一份 <config>.json.bak 副本。Claude Code 的 ~/.claude.json 则采用不同且有意为之的处理方式：nucleus 会写入临时文件，再以原子方式替换原文件，因此写入失败时原文件会保持原样，旁边也不会留下 .bak 文件。对于已安装但从未配置过 MCP 的客户端，会为其创建配置；对于你没有安装的客户端，则完全不会改动。如果 ~/.claude.json 不存在，也绝不会擅自创建。 已经有 .brain 目录？运行 nucleus setup 即可配置客户端而不重新初始化；先使用 --dry-run 预览具体改动。

Claude Desktop — 一键安装包

Claude Desktop 的一键 nucleus.mcpb 安装包通过 bash scripts/build_mcpb.sh 构建（发布工作流支持后，它将附在发行版中）。使用 Claude Desktop 打开该安装包时，会调用 Claude 内置的 uv 运行时来获取并运行 nucleus-mcp——无需配置 Python 环境。

托管／无需安装的访问方式

目前不可用。远程 MCP 端点已撤下，正在进行访问控制审查；请使用本地安装。

手动配置（备用方案）

如果客户端未被自动检测到，请运行 nucleus setup --dry-run，以打印 nucleus 会查找的所有位置以及它将写入的确切 mcpServers 配置块，然后将该配置块粘贴到客户端的配置中。即使未检测到任何客户端，nucleus setup --create 也会写入 Claude Code 配置。完整的手动操作指南位于 docs/QUICK_START.md，随软件包一起提供，路径为 <site-packages>/mcp_server_nucleus/docs/QUICK_START.md。

路径发现

Nucleus 会自动查找你的 .brain：

1. NUCLEUS_BRAIN_PATH 环境变量（显式指定）
2. 从当前工作目录开始逐级向上查找 .brain/ 目录
3. 回退到 $HOME/.nucleus/brain

此查找顺序适用于正在运行的服务。nucleus init 则会在你运行命令的目录（或 path 参数指定的目录）中创建 .brain/ — 如果希望服务查找位于其他位置的 brain，请随后设置 NUCLEUS_BRAIN_PATH。

---

命令行界面

除了 MCP 工具外，Nucleus 还提供完整的命令行界面。会自动检测 TTY（表格输出）还是管道（JSON）。

# Memory
nucleus engram write my_key "insight here" --context Decision --intensity 7
nucleus engram search "compliance"
nucleus engram query --context Strategy --limit 10

# Tasks
nucleus task list --status READY
nucleus task add "Ship the feature" --priority 1

# Sessions
nucleus session save "Working on auth refactor"
nucleus session resume

# Health
nucleus status --health
nucleus sovereign

# Compliance
nucleus comply --jurisdiction eu-dora
nucleus audit-report --format html -o report.html

# Chat (multi-provider: Gemini, Anthropic, Groq)
nucleus chat

适用于管道：

nucleus engram search "test" | jq '.key'
nucleus task list --format tsv | cut -f1,3

---

合规性

通过一条命令配置监管框架：

nucleus comply --jurisdiction eu-dora       # EU DORA
nucleus comply --jurisdiction sg-mas-trm    # Singapore MAS TRM
nucleus comply --jurisdiction us-soc2       # US SOC2

管辖区	保留期限	HITL 操作	紧急停止开关
eu-dora	7 年	5 种	必需
sg-mas-trm	5 年	5 种	必需
us-soc2	1 年	3 种	可选
global-default	90 天	2 种	可选

---

遥测

Nucleus 会收集匿名的汇总使用统计信息（命令名称、耗时、错误类型、版本、操作系统）。绝不收集记忆内容、文件路径、提示词、API 密钥或个人身份信息（PII）。

nucleus config --no-telemetry
# or: NUCLEUS_ANON_TELEMETRY=false

详情请参阅 TELEMETRY.md。

---

参与贡献

• 发现 Bug？ 请发送邮件至 [email protected]，或在 Discord 上反馈
• 有功能创意？ 欢迎在 Discord 上提出
• 想贡献代码？ 请参阅 CONTRIBUTING.md
• 想交流？ Discord

许可证

MIT © 2026 | [email protected]

配套仓库（可选）

某些部署会将配套脚本保存在本仓库旁边的另一个仓库中。可通过以下任一方式让 nucleus 使用这些脚本：

export NUCLEUS_SIBLING_REPOS="$HOME/repo-a:$HOME/repo-b"     # os.pathsep-separated
# or, one path per line:
printf '%s\n' "$HOME/repo-a" "$HOME/repo-b" > ~/.config/nucleus/siblings

如果两者都未设置，nucleus 只会在自身仓库中搜索 — 不会对宿主环境作任何假设。 如果找不到某个作业的脚本，操作会失败，并在错误中列出尝试过的所有位置。

隐私

记忆的存储位置取决于你选择的快速入门选项。

选项 B — 本地安装。 Nucleus 以本地优先。Engram、记忆和项目状态会写入你设备上的 .brain/。除非你自行配置中继，否则不会发送任何内容。

选项 A — 无需安装（relay.nucleusos.dev）。 这是由我们运营的托管服务。你的 Engram 存储在我们的服务器上，而不是你的设备上；存储的内容是每条记忆的完整内容——value 字段，而不只是键或时间戳——以及其上下文标签、强度、版本和时间戳。此模式下没有本地 .brain/；中继就是大脑。

我们会隔离各租户，且只有使用你自己的 bearer token 才能访问。但“本地优先”并不能描述选项 A，若让这个词涵盖选项 A，就会造成误导：如果你不愿将某些内容放在我们运营的服务器上，那么通过此方式连接时，就不要把它存入记忆。请为此使用选项 B。

本节的早期版本只描述了本地使用场景，并低估了中继会接收的内容。现已更正。

遥测： 仅收集匿名汇总使用统计信息（命令名称、耗时、错误类型、版本、操作系统）。绝不收集 Engram 内容、文件路径、提示词、API 密钥或个人身份信息。可通过 nucleus config --no-telemetry 或 NUCLEUS_ANON_TELEMETRY=false 禁用。此项独立于你选择上述哪种选项，也不受其影响。

可自托管的中继（可选，选项 B）： 如果你将 Nucleus 指向由你运营的中继端点，完整的 Engram 内容会同步到该处——记录结构与上文相同。该服务器归你所有。

联系： 隐私相关问题 → [email protected]