Second Brain

🧠 自主 Agent 第二大脑 — Graph-RAG 记忆核心

一个零依赖、离线优先的 Graph-RAG 记忆系统，支持自主 AI Agent 共享长期记忆、积累研究成果并协调工作流。

它旨在直接在文件系统中以 Obsidian 库的形式运行，并提供简洁的 REST API 和 Javascript SDK。它将记忆表示为互联节点（[[wikilinks]]），并将图遍历、关键词搜索、可选的语义相似度和时效性融合为一个排序信号，从而筛选并向大模型提供精准上下文：在令牌预算范围内，仅返回与查询相关的笔记，而非整个文件或目录。

⚡ 快速开始（MCP）

只需一行，即可为 Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端提供共享的持久记忆。需要 Node 22.5+；无需安装，也无需 API 密钥。

claude mcp add second-brain -- npx -y mind-mri-second-brain

其他客户端：将 {"mcpServers":{"second-brain":{"command":"npx","args":["-y","mind-mri-second-brain"]}}} 添加到其 MCP 配置中。你的笔记是 ~/.second-brain/vault 中的纯 Markdown 文件，因此你可以在 Obsidian 中打开该文件夹，阅读或编辑 Agent 记住的所有内容。工具列表和选项请参阅 MCP 服务。

会话示例（来自工具的真实输出，已精简）：

brain_remember   title "Decision - Use SQLite for the cache", type decision,
                 content "We chose SQLite over Redis ... See [[Project - Atlas]]."
                 → { "success": true, "id": "agents/atlas/Decision - Use SQLite for the cache", "version": 1 }

brain_recall     query "what database does Atlas use and why", hops 1
                 → 2 notes, ~77 tokens:
                   ### Decision - Use SQLite for the cache [DECISION]
                   We chose SQLite over Redis for the local cache: zero ops, one file ...
                   ### Project - Atlas [MEMORY]            ← pulled in through the [[wikilink]]
                   Atlas is the internal reporting service. Stack: Node, SQLite ...

brain_node_update  id "agents/atlas/Decision - Use SQLite ...", content "Update: confirmed after load test, p95 read latency 3 ms."
                 → { "success": true, "mode": "append" }

召回功能只返回相关笔记及其链接的笔记，并将内容控制在令牌预算范围内；同时会将其作为参考数据而非指令提供给模型。

---

🚀 项目亮点（作品集精选）

本项目展示了多项高级后端工程原则和数据建模架构：

• **零依赖 Node.js 后端：**使用纯原生 Node.js ES Modules（http、fs、path、child_process、node:sqlite、node:test）构建。可在数毫秒内启动，能有效抵御依赖漏洞链攻击，且具有极强的可移植性。自 1.0 以来添加的每项功能——语义搜索、去重、任务队列、消息传递、沙箱执行——都遵循同一原则：永远不需要 npm 依赖。可选依赖（云端嵌入密钥、Docker、@huggingface/transformers）缺失时只会优雅地降级为“不可用”，绝不会导致崩溃。
• **Graph-RAG 与 Flat-RAG：**Flat RAG 系统（使用简单的向量相似度）会产生彼此割裂、丢失上下文的文本块。此引擎会解析 Obsidian 风格的维基链接（[[Page Name]]）来构建邻接映射，追踪不同想法之间的逻辑关联。
• 通过 Reciprocal Rank Fusion 实现混合搜索：/search 和 /recall 使用 Reciprocal Rank Fusion 融合关键词分支（原有的缓存 TF-IDF 引擎，保持不变）与可选的语义相似度分支（基于缓存嵌入的余弦相似度）。这是一种基于排名的合并技术，用于组合相互独立、不可比较的排名信号，无需对原始分数进行跨信号归一化。未配置嵌入提供方时，结果可证明与原有的纯关键词行为完全一致：语义分支会直接返回空结果，融合结果也会完全回退到普通 TF-IDF 的返回结果。
• **Token 经济性（优化上下文）：**Agent 不必将原始文件结构（约 50k tokens）或任意文本块输入大模型的上下文窗口，而是可以查询 /recall，获取预先组装且受自定义 token 预算（约 300–2,000 tokens）限制的上下文载荷，避免模型注意力下降。
• **原生文件系统热重载（fs.watch()）：**当文件被编辑时（无论是在 Obsidian 中手动编辑，还是通过 API 以编程方式编辑），都会自动实时使记忆索引失效并刷新。该功能使用原生文件系统事件，并通过防抖计时器确保针对内存索引的查询速度。
• **缓存 TF-IDF 搜索引擎优化：**为保持搜索速度，后端会在加载图缓存时预先对知识库内容进行分词，并预先计算逆文档频率（IDF）和向量模长，避免每次搜索时都进行 O(N) 分词和正则表达式解析。
• **由 SQLite 支持的语义嵌入：**通过 node:sqlite 可选地为每个节点存储向量（内置于 Node ≥22.5，无需安装或原生编译）——执行真正的索引化逐行读写和实际事务，而非使用单个不断增长的 JSON 文件。多提供方获取嵌入（OpenAI、Gemini），并可选用本地模型作为最后手段，因此不会仅仅因为云端密钥用尽配额，就导致语义搜索完全不可用。
• **乐观并发控制（OCC）：**防止并发写入相互覆盖。节点的 YAML frontmatter 中包含 version 属性，实际更新时该属性会递增。包含 version 的 PATCH 请求必须与当前版本一致；若笔记已被并发修改，则请求会以 409 Conflict 失败（省略 version 可跳过检查）。
• **严格的节点 Schema 验证：**写入磁盘前验证传入的载荷（title 文件名字符、type 枚举值、importance 范围和 tags 格式）。标题会成为文件名，因此 API 会拒绝 < > : " / \ | ? * 及控制字符；SDK 则会自动将其规范化为 -。
• **细粒度读写身份验证安全：**配置 BRAIN_KEY 后，所有端点都会强制执行 Bearer Token 身份验证，包括搜索、回忆和图视图。遥测流端点（/stream）要求提供匹配的 ?token= 参数，以防止通过公开 URL 暴露原始数据。
• PII 和机密信息防护：sdk/safeguard.js 是一个独立的正则表达式脱敏工具（涵盖约 20 家提供方的 API 密钥、数据库连接字符串、PEM 私钥、JWT、SSN、经过 Luhn 校验的信用卡号），项目中的任何代码路径都可以在记录、存储或回显文本前调用它。
• 近似重复记忆协调：sdk/dedup.js 先通过低成本的嵌入相似度检查筛选候选项，再询问 LLM 裁判两条相似笔记是否确实描述同一事实（合并并保留所有细节），还是存在实质性差异（两条都保留）。任何错误都会按开放式失败处理——去重失败绝不会阻止正常记忆写入。POST /dedup/scan 会报告整个知识库中的候选项，但绝不会自动合并。
• **多 Agent 协调基础组件：**由知识库支持的任务队列（状态标签、基于依赖关系的阻塞与级联释放）和 Agent 间消息传递器（将收件箱/发件箱作为知识库节点），以及根据知识库中已有的 persona 标签/frontmatter 只读生成的组织结构图。这些是轻量级协调基础组件——共享、可审计、以 Markdown 为基础的任务列表和收件箱——并非完整的自主编排器；仍需其他组件监视 pending 任务并执行工作。
• 沙箱代码执行：POST /sandbox/execute 会在禁用网络、限制资源、只读且运行后自动移除的 Docker 容器中执行代码。没有 Docker 时，除非显式设置 SANDBOX_ALLOW_LOCAL=1，否则不会执行任何内容；设置后会启用不受隔离的本地子进程，且仅由关键词黑名单防护——黑名单并非安全边界，因此只有在完全可信的环境中才应启用该功能。
• 弹性、按路径限定的 Git 同步：sdk/git_sync.js 将简单的“暂存整个知识库文件夹”自动提交方式，替换为只暂存调用方指定为实际更改的文件（因此，其他尚未提交的编辑不会被误纳入他人的提交），并对并发写入进行串行化和排队，避免同时争用 .git/index.lock。
• 统一的多提供方 LLM 路由器：sdk/llm_router.js 通过统一接口调用 Anthropic、兼容 OpenAI 的服务、Gemini、NVIDIA NIM 或本地 Ollama；发生任何故障时，会按可配置的优先级链切换提供方，并修复小型模型输出近似有效 JSON 时最常见的问题（字符串内未转义的控制字符）。
• MCP 服务与 CLI：mcp/server.js 是一个零依赖的 stdio JSON-RPC MCP 服务，可将此 REST API 作为 MCP 工具提供给任何兼容 MCP 的客户端；如果 API 服务尚未运行，它会自动启动该服务。sdk/cli.js（npm run brain -- <command>）封装了同一 API，方便在终端中快速使用。
• 交互式 Agent 模拟器 UI：仪表板中提供一个精致的侧边栏表单，可用于模拟多 Agent 记忆写入，并在 D3.js 可视化中动态观察节点、链接和 EventSource 遥测的更新——现在还新增了第二个使用 vendored Preact + htm 构建的组织结构图选项卡（参见UI 架构）。
• **人类与 Agent 参与的协作：**由于记忆以纯 Markdown 文件（.md）和 YAML frontmatter 的形式序列化，人类可以在 Obsidian 中打开同一文件夹，审查 Agent 的推理、编辑笔记，或直接向图中添加指南。
• **测试套件与 CI：**基于 node:test 的测试套件（同样不依赖测试框架）覆盖上述所有模块，并通过临时目录、模拟的 fetch 和环境变量覆盖来隔离副作用。GitHub Actions 会在每次向 main 推送或提交 PR 时，使用 Node 22.x/24.x 运行测试，并扫描 api/、sdk/、mcp/ 中所有文件的语法。

---

⚙️ 技术架构

graph TD
    subgraph Client Environments
        Agent1[Research Agent] -->|SDK: remember/recall| API[🧠 Second Brain REST API]
        Agent2[Pipeline Agent] -->|SDK: remember/recall| API
        Human[Human Operator] -->|Edits Notes| Obs[Obsidian Editor]
        MCPClient[MCP-aware Client] -->|stdio JSON-RPC| MCP[mcp/server.js]
        CLI[sdk/cli.js] -->|REST| API
        MCP -->|auto-spawns / proxies| API
    end

    subgraph API Server
        API --> Engine[Graph Engine]
        Engine --> Search[Hybrid Search: TF-IDF + Semantic RRF]
        Engine --> Cache[In-Memory Graph Cache]
        Engine --> FS[Local FS Watcher]
        API --> Tasks[Task Queue]
        API --> Msg[Messenger]
        API --> Org[Org Chart]
        API --> Dedup[Dedup Scan]
        API --> Sandbox[Sandboxed Execution]
    end

    subgraph Storage Layer
        FS -->|Reads/Writes| Vault[(Markdown Vault)]
        Search -->|Vectors| EmbedDB[(SQLite: .embeddings.db)]
        Obs -->|Reads/Writes| Vault
        Engine -->|Optional Async Sync| Git[Path-Scoped Git Sync]
    end

    subgraph LLM Layer
        Dedup --> Router[LLM Router: Anthropic / OpenAI / Gemini / NVIDIA / Ollama]
    end

    Git -->|Auto Commit & Push| GitHub[Private GitHub Repo]

---

🎨 UI 架构

该项目包含一个动态的高科技仪表盘，分为两个标签页：

• Graph 标签页（原有）： 使用 D3.js (v7) 和 Marked.js 构建。采用力导向图模拟（节点大小按链接度确定，颜色按类型区分），提供交互式上下文面板，用于阅读节点的 Markdown 内容并浏览其出链和反向链接；还提供实时筛选和通过 /reload 实现的实时重载。
• Org Chart 标签页（新增）： 使用 vendored Preact + htm（ui/preact.min.js、ui/htm.min.js — 本地文件，无 CDN，无需构建步骤）构建。htm.bind(preact.h) 将普通的标签模板转换为 JSX 会生成的相同 VNode 树，并通过 preact.render 将其渲染为真正的组件树（OrgMember、DepartmentCard、OrgChartView），从 GET /org-chart 获取数据。这是今后在此文件中添加任何新视图时的推荐模式——ui/index.html 的其余部分（Graph 标签页）有意保留原生 JS/innerHTML 实现，而非追溯性地重写。

---

📡 REST API 与接口目录

方法	端点	载荷 / 查询参数	描述
GET	/health	—	返回服务统计信息、端口以及知识库节点和边的数量。
GET	/nodes	—	获取所有索引节点的列表及精简预览。
GET	/node/:id	—	获取特定笔记正文、解析后的出链和入链。
GET	/search	?q=query&limit=10	混合关键词与语义搜索（倒数排名融合），并与原始 TF-IDF 排名融合。
GET	/recall	?q=query&hops=1	核心 Agent 上下文： 在令牌预算内组装图上下文，并以混合搜索结果作为种子。
GET	/graph	—	返回完整的邻接图节点和边。
POST	/remember	{title, content, type, agent}	将新的 Markdown 节点写入知识库目录。
PATCH	/node/:id	{title, content, type, tags}	修改现有文件的文本内容或 YAML frontmatter 元数据（通过 version 实现 OCC）。
DELETE	/node/:id	—	从磁盘删除笔记。
POST	/tasks/submit	{prompt, agents, priority, dependencies}	将任务提交到由知识库支持的任务队列。
GET	/tasks	?status=pending	列出任务，可按状态标签筛选。
PATCH	/tasks/:id	{status, content}	更新任务状态；自动释放后续任务或级联处理。
POST	/messages/send	{fromAgent, toAgent, content, subject}	发送 Agent 间消息。
GET	/messages/:agent	?unread=false	查看 Agent 的收件箱。
GET	/org-chart	—	根据角色标签和 frontmatter 推导部门及负责人结构。
POST	/dedup/scan	{dryRun, judge}	报告疑似重复节点；绝不自动合并。
POST	/sandbox/execute	{code, language, timeoutMs}	在沙箱中运行代码片段（使用 Docker，或受限的本地回退方案）。
POST	/embeddings/reindex	{}	在后台为知识库重新计算语义向量。
GET	/type/:type、/tag/:tag、/agent/:name、/tags	—	按节点类型、标签或 Agent 查询；列出所有标签。
POST	/consolidate	{agent?, type?}	使用 Gemini 将 memory 笔记合并为一条笔记，并归档原始笔记（需要 GEMINI_API_KEY）。
GET	/export	—	完整的 JSON 导出。
POST	/reload	—	手动刷新内存缓存。

---

📦 SDK 快速入门与代码质量

客户端 SDK 使用原生 fetch，以简洁、现代的 Javascript 编写。

import { SecondBrain } from './sdk/index.js';

// Initialize Client (Reads optional BRAIN_API & BRAIN_KEY env variables)
const brain = new SecondBrain({
  agent: 'pipeline-agent',
  api: 'http://localhost:3747',
  apiKey: process.env.BRAIN_KEY
});

/**
 * Workflow Scenario: Context Recall -> Task Execution -> Memory Write
 */
async function runAutoPipeline() {
  // 1. Fetch relevant context within 1 Graph Hop and 1500 token budget
  const context = await brain.recall('API rate limiting design', 1, 1500);
  
  // 2. Inject context directly into your LLM prompt
  const llmPrompt = `
    ${context.systemPrompt}
    
    Task: Design rate limiter middleware for backend services.
  `;
  const result = await myLlmClient.generate(llmPrompt);
  
  // 3. Save learnings back to the shared memory bank for other agents
  await brain.remember(result, {
    title: 'Rate Limiting Middleware Specification',
    type: 'research',
    tags: ['infrastructure', 'security', 'rate-limit']
  });
}

CLI

npm run brain -- status
npm run brain -- recall "API rate limiting design"
npm run brain -- tasks submit "Investigate rate limiting approaches" --agents=pipeline-agent
npm run brain -- org-chart

MCP 服务

mcp/server.js 是一个零依赖的 stdio MCP 服务，可为任何 MCP 客户端（Claude Desktop、Claude Code、Cursor 等）提供共享的持久化记忆。需要 Node 22.5 或更高版本。

安装 —— 将以下内容添加到客户端的 MCP 配置中（例如 claude_desktop_config.json 或 .cursor/mcp.json）：

{
  "mcpServers": {
    "second-brain": {
      "command": "npx",
      "args": ["-y", "mind-mri-second-brain"]
    }
  }
}

对于 Claude Code：claude mcp add second-brain -- npx -y mind-mri-second-brain。在原生 Windows 上（非 WSL），Claude Code 需要用 cmd /c 包装 npx：claude mcp add second-brain -- cmd /c npx -y mind-mri-second-brain。请在**命令提示符（cmd.exe）**中运行此命令：Windows PowerShell 5.1 会吞掉 -- 分隔符并报错 unknown option '-y'（PowerShell 7 则没有问题）。在 JSON 配置中对应的写法是 "command": "cmd", "args": ["/c", "npx", "-y", "mind-mri-second-brain"]。

从克隆的仓库运行？请使用 "command": "node", "args": ["/path/to/repo/mcp/server.js"]。

首次运行。 首次调用工具时，MCP 服务会在后台启动本地 API（api/server.js，仅绑定到 127.0.0.1），并保持其运行。笔记是纯 Markdown 文件：通过 npm 安装时位于 ~/.second-brain/vault，从克隆的仓库运行时位于 ./vault。可通过 BRAIN_VAULT 覆盖。可选配置：BRAIN_PORT（默认值为 3747）和 BRAIN_KEY（要求使用 Bearer 令牌）。

工具	用途	是否写入？
brain_recall	查询的 Graph-RAG 上下文（wikilink 跳转、令牌预算）	否
brain_search	按相关性排序的关键词搜索（如已配置，也可进行语义搜索）	否
brain_node_get	获取一条笔记及其出链和反向链接	否
brain_node_update	追加到或替换现有笔记（会检查版本，因此并发写入者不会丢失修改）	是
brain_remember	保存新笔记（创建新文件；绝不覆盖）	是
brain_tasks_submit / brain_tasks_list / brain_tasks_update	共享的 Markdown 任务队列：添加任务（含依赖项）、查找待处理工作、认领并完成任务且记录结果；完成任务后会解除对其有所依赖的任务的阻塞	提交、更新
brain_messages_send / brain_messages_get / brain_messages_mark_read	Agent 对 Agent 的收件箱	发送、标记为已读
brain_health	服务和知识库统计信息	否

只读工具带有 MCP readOnlyHint 注解。没有工具会删除笔记；只有 brain_node_update 可以覆盖现有文本（在 replace 模式下），因此只有它被标记为破坏性操作，客户端在运行前会询问。

---

🔒 安全与身份验证设置

默认情况下，服务以本地／开发模式运行，不启用身份验证。在云部署、多 Agent 网络或公开暴露 REST API 端点时，应启用 Bearer 令牌身份验证：

1. 设置密钥： 在系统或服务器上定义 BRAIN_KEY 环境变量：

   export BRAIN_KEY="your-highly-secure-secret-token"
   

2. 强制保护： 设置 BRAIN_KEY 后，所有会修改数据的端点（POST /remember、POST /reload、POST /consolidate、PATCH /node/:id、DELETE /node/:id，以及任务／消息／去重／沙盒端点等）都会阻止未经授权的请求，并返回 401 Unauthorized。
3. Authorization 标头： 传入的请求必须在 Authorization 标头中包含令牌：

   Authorization: Bearer your-highly-secure-secret-token
   

4. 客户端 SDK 配置： 初始化 Javascript 客户端 SDK 时，使用 apiKey 配置选项注入令牌：

   const brain = new SecondBrain({
     api: 'http://localhost:3747',
     apiKey: process.env.BRAIN_KEY // Or pass the token directly
   });
   

5. 安全默认设置： 服务绑定到 127.0.0.1，不提供通配符 CORS 标头，限制请求正文大小，不返回绝对文件系统路径，并将笔记写入和静态文件访问限制在知识库和 ui/ 中。仪表板会转义所有笔记文本，并清理渲染后的 Markdown。
6. PII／密钥防护： sdk/safeguard.js 中的 sanitizeContent() 可用于任何需要在持久化或回显文本前对 API 密钥、数据库 URL、PEM 密钥、JWT、SSN 或信用卡号进行脱敏的代码路径（自定义端点、数据摄取流水线、日志记录等）。

🧩 可选能力（优雅降级）

以下能力均为附加选项，需选择启用——如果没有配置任何一项，服务的行为与纯粹的零依赖 TF-IDF/图记忆存储完全相同，这仍是默认行为。

能力	启用方式	未设置时的行为
语义搜索分支、去重相似度门槛	设置 OPENAI_API_KEY 和／或 GEMINI_API_KEY（或者安装 @huggingface/transformers，以便使用本地的最后备用模型）	语义分支不会返回候选项；搜索／回忆与仅使用关键词 TF-IDF 时完全相同。
由大模型判断去重、大模型路由调用	设置以下任意一项：ANTHROPIC_API_KEY、OPENAI_API_KEY／OPENROUTER_API_KEY、GEMINI_API_KEY、NVIDIA_API_KEY，或在 OLLAMA_HOST 运行本地 Ollama	按提供商链依次尝试，最后回退到 Ollama；如果没有任何提供商可用，则调用方（例如去重判断器）将采用开放失败策略。
通过 Docker 沙盒执行	正在运行的 Docker 守护进程	/sandbox/execute 返回错误。设置 SANDBOX_ALLOW_LOCAL=1 可允许回退到未隔离的本地执行（仅限可信环境）。
自动 Git 同步	AUTO_GIT_SYNC=true	不执行任何操作；不会提交或推送内容。

环境设置

变量	说明	默认值
BRAIN_PORT	REST API 监听的端口。	3747
BRAIN_HOST	REST API 绑定的地址。默认仅限环回地址；仅在同时设置 BRAIN_KEY 时才设为 0.0.0.0。	127.0.0.1
BRAIN_VAULT	Vault 文件夹（不存在时会创建）。	./vault
BRAIN_ALLOW_ANY_VAULT	仅适用于 MCP 服务。默认情况下，如果正在运行的 Second Brain 使用的 Vault 与其预期不符（或版本过旧，无法确认），则拒绝使用，以免笔记被写入错误的 Vault。设置为 1 即可继续使用该服务。	未设置
BRAIN_CORS_ORIGIN	允许来自此来源的跨域浏览器访问。默认关闭；内置仪表板与 API 同源，无需配置。	未设置
BRAIN_MAX_BODY_BYTES	请求正文的最大大小（超过后返回 413）。	2097152
SANDBOX_ALLOW_LOCAL	设为 1 可在没有 Docker 的情况下执行 /sandbox/execute（未隔离；仅限可信环境）。	未设置
BRAIN_KEY	可选。设置后，除 /health、/stream（通过 ?token= 传入令牌）和静态仪表板外，所有端点都需要匹配的 bearer 令牌。	""
AUTO_GIT_SYNC	可选。设为 true 后，服务会将修改提交并推送到 GitHub（限定路径、串行执行——参见 sdk/git_sync.js）。	false
OPENAI_API_KEY / GEMINI_API_KEY	可选。启用语义搜索／去重嵌入分支。	未设置
ANTHROPIC_API_KEY / OPENROUTER_API_KEY / NVIDIA_API_KEY / OLLAMA_HOST	可选。配置大模型路由器的提供商链（sdk/models_config.js）。	未设置／http://localhost:11434
LLM_PROVIDER_ORDER	可选。覆盖路由器的回退优先级顺序。	anthropic,nvidia,gemini,openai,ollama

---

🛠️ 配置与设置

要求

• Node.js（>= 22.5.0——sdk/embeddings.js 使用内置的 node:sqlite 模块，该模块从此版本开始提供）
• Web 浏览器（用于可视化工具界面）

安装

克隆仓库：

git clone https://github.com/ara-5/mind-mri-agent-second-brain.git
cd mind-mri-agent-second-brain

启动服务

# Production start
npm start

# Development watch mode
npm run dev

启动可视化工具界面

npm run ui

（打开由正在运行的 API 服务提供的仪表板——请先运行 npm start。仪表板与 API 同源，因此无需配置 CORS。）

运行测试

npm test

运行完整的 node:test 测试套件（test/*.test.js）——无需依赖测试框架；通过临时目录、模拟的 fetch 和环境变量覆盖来隔离副作用。CI（.github/workflows/ci.yml）会在每次向 main 推送或提交 PR 时，使用 Node 22.x/24.x 运行测试。

Vault 迁移

有关每项迁移单独使用一个文件、保持幂等且绝不伪造数据的约定，请参阅 migrations/README.md；首个实际迁移（根据明确无歧义的人设头衔关键词分配组织结构图中的负责人）见 migrations/001-assign-department-leads.mjs。