second-brain-mcp

把本地的 Markdown 笔记库变成可检索、可对话写入的「第二大脑」， 通过 MCP（Model Context Protocol）交给 Claude Code 等 AI 客户端按需调用。

你不再需要每次把笔记全量塞进 prompt——AI 会在需要时自动检索最相关的几个片段。 全程本地运行、本地索引，检索不调用任何外部 API，也不产生额外费用。

适合谁：手上有一堆 Markdown 笔记（Obsidian / Logseq / 纯文件夹都行）， 想让 AI 真正「记得」它们，又不想把笔记上传到任何云端服务的人。

特性

• 增量建索引 — 只重新处理内容变过的文件（md5 判断），大库日常更新秒级完成

• 零操作的自动同步 — 服务在启动后与每次检索前按需补差，改完笔记直接提问就行， 不需要挂着任何后台进程（陈旧判断只看目录 stat，代价极小）

• 索引离线建、在线只读 — BM25 倒排索引在维护阶段构建并落盘，服务端不常驻笔记原文， 检索时内存里只有倒排表；索引过期靠「分片数 + 指纹」签名发现，能捕捉「数量没变但内容变了」

• 混合检索 — BM25 关键词路（中文走 jieba 分词）∥ 语义向量路，RRF 融合 + 余弦阈值过滤，兼顾「字面命中」和「语义相关」

• 语言自适应 — 中文（jieba 缺失时自动降级为字/双字 bigram）与英文知识库都开箱即用，中英混排也没问题

• 本地优先 — Embedding 本地跑（默认 bge-small-zh-v1.5，约 100MB、CPU 秒出、离线可用），笔记不出本机

• 隐私默认 — 不向 Chroma / HuggingFace 发送遥测，离线模式常开

• 对话反向写入 — AI 可以把新内容追加到指定笔记并立刻重建索引（可写名单可配置，只追加、不删除）

• 跨平台 — Windows / macOS / Linux，CPU / GPU 双依赖清单

Related MCP server: MCPedia

工作原理

   Markdown 知识库 (kb_dir)
        │                       ▲
        │ ① 检索前自动补差        │ ③ 对话追加写入
        ▼                       │
   mcp_server.py ──MCP (stdio)──► Claude Code / 任意 MCP 客户端
        │
        │ ② 只读检索：BM25 关键词 ∥ 语义向量 → RRF 融合 → 余弦阈值过滤
        ▼
   ┌───────────────────────────────┐
   │ chroma_store   向量索引         │
   │ bm25_index     倒排索引（落盘）  │
   └───────────────────────────────┘
        ▲
        └── 首次建档：python ingest.py（要联网下 embedding 模型）
            可选预建：python watcher.py（仅当索引需要随时保持新鲜）

索引什么时候更新

这是本项目最容易被误解的一点，所以单独说清楚：索引只在被读取的那一刻才有必要是新鲜的。

因此同步发生在读取侧——mcp_server.py 在启动后、以及每次检索前各做一次增量补差：

1. 遍历目录，比对每个文件的 mtime + size（不读文件内容）

2. stat 没变 → 直接跳过

3. stat 变了才读文件算 md5；md5 没变（touch 过、编辑器原子保存）→ 只刷新 stat，不重新 embedding

4. md5 也变了 → 只重建这一个文件的分片

因为第 1 步只是一次目录遍历（几千个笔记通常是几十毫秒），它可以被频繁调用而感觉不到。 启动那次跑在后台线程里，等你开口提问时通常已经完成。

所以你不需要挂任何后台进程，也不需要记得重跑脚本。 改完笔记，直接提问。

python ingest.py 只在两种情况下需要手动跑：首次建档（要向 HuggingFace 下载模型， 而服务是离线模式运行的，下不了），以及想一次性补齐大量改动时。

快速开始（5 步，约 5 分钟）

Python 3.10+；建议用独立虚拟环境（conda / venv），别污染 base。

# 1. 进入项目，装依赖（有 NVIDIA 显卡想 GPU 加速就换成 requirements-cuda.txt）
cd second-brain-mcp
pip install -r requirements.txt

# 2. 首次运行：自动生成 config.yaml（从 config.example.yaml 复制）
python ingest.py --kb-dir D:/my-notes

#    如果过了几秒提示 kb_dir 为空——先编辑 config.yaml，把 kb_dir 指到你的笔记目录：
#    # config.yaml
#    kb_dir: D:/my-notes
#    再跑一次 python ingest.py 就会建索引（首次自动下载模型约 100MB，之后离线）

# 3. 注册 MCP 服务到 Claude Code
#    Windows:  双击 register_mcp.bat（或用 register_mcp.bat "你的python.exe"）
#    macOS/Linux: ./register_mcp.sh
#    上一步 ingest 跑过、模型已下载，注册才能避开离线问题

# 4. 验证注册
claude mcp list          # 应看到 second-brain（或你改的服务名）

# 5. （可选）自测检索，不启动 MCP 直接跑一遍完整流程
python mcp_server.py --search "第二大脑是什么"

然后正常启动 claude 聊天。问到笔记里已有内容时，AI 会自动调用 search_my_knowledge_base；说「帮我记一下……」时会调用 update_knowledge_base 追加写入。

先跑 ingest.py 再注册，顺序很重要：首次建档会下载 embedding 模型， 而 MCP 服务是固定离线模式运行的；不先下载，检索时模型加载会失败。

之后就什么都不用管了。 改完笔记直接提问即可——服务会在检索前自动把改动补进索引， 不用手动重跑脚本，也不用挂后台进程。原因见上面「索引什么时候更新」。

配置参考（config.yaml）

可用环境变量临时覆盖（KB_DIR、KB_TOP_K、KB_EMBED_MODEL、KB_BM25_INDEX_FILE、 KB_SYNC_CHECK_INTERVAL、KB_SERVER_NAME 等， 完整清单见 kb_config.py 顶部注释），适合 CI 或临时换库。

日常维护

日常不需要任何维护。 改完笔记直接提问，服务会在检索前自动补差。

需要你出手的只有两种情况：首次建档（跑一次 python ingest.py，要向 HuggingFace 下载模型），以及彻底重建（改了 chunk_size、切块逻辑或 embedding 模型之后）：

rm -rf chroma_store .file_hashes.json bm25_index.pkl.gz   # 全是衍生产物，删了不心疼
python ingest.py                                          # 全新重建

为什么改了切块参数必须彻底重建？ 索引状态只对「文件内容」敏感，认不出切块 参数变了——不重建的话库里会同时残留新旧两种切法的分片，而且不报错。

什么时候才需要 watcher.py

只有这两个场景：

• 不聊天的时候索引也必须是新的，例如另一个程序直接读 Chroma 或倒排索引文件

• 知识库极大，想把同步开销彻底移出检索路径

它是个可选的加速器，不是必需品：

python watcher.py --verbose      # 看每个文件的处理明细
python watcher.py --debounce 5   # 批量同步大量文件时调大合并窗口
python watcher.py --poll         # 网络盘 / 虚拟共享目录上改用轮询

它和自动同步同时开着也不会损坏数据（索引状态是原子替换、分片按确定性 id 覆写）， 最多是重复劳动。真想常驻的话，Windows 用任务计划程序，macOS/Linux 写 systemd / launchd 服务。

性能参考

自动同步的成本 ≈ 一次目录遍历 + 每个文件一次 stat。几百到几千个笔记是几十毫秒量级， 基本感觉不到。如果你有十万量级的笔记，把 sync.check_interval 调大（比如 600）， 或者干脆改用 watcher.py 预建。

常见问题排查

依赖与 Python 版本

• 锁定版本见 requirements.txt（CPU 可用）、requirements-cuda.txt（GPU，需 NVIDIA 驱动 ≥ CUDA 12.6）

• 默认模型 bge-small-zh-v1.5 中英通用、只占 ~100MB 磁盘，embedding 计算纯本地

目录结构

second-brain-mcp/
├── README.md                 # 本文档
├── config.example.yaml       # 配置模板（含注释，可入仓库）
├── config.yaml               # 你的个人配置（.gitignore 已忽略，不入仓库）
│
│   ── 基础层：无副作用，所有入口共用 ──
├── kb_config.py              # 配置加载：默认值 ⇠ config.yaml ⇠ 环境变量
├── kb_scan.py                # 文件发现、忽略规则、安全路径解析（读写两侧共用同一条边界）
├── kb_text.py                # 切块与分词（入库与检索共用同一份实现）
│
│   ── 索引层 ──
├── bm25_index.py             # BM25 倒排索引：构建 / 落盘 / 加载 / 打分 / 过期签名
├── ingest.py                 # 增量引擎：sync_all（全库对账）+ apply_file_changes（按路径）
│
│   ── 入口层 ──
├── mcp_server.py             # MCP 服务：检索前自动补差 + 检索 + 对话写入（含 --search 自测）
├── watcher.py                # 【可选】常驻监听，改动后立刻重建；仅特殊场景才需要
├── register_mcp.bat          # Windows 一键注册
├── register_mcp.sh           # macOS / Linux 一键注册
├── requirements[-cuda].txt   # 依赖清单（CPU / GPU 两版）
├── LICENSE                   # MIT
└── examples/sample_kb/       # 演示知识库，跑通即懂

运行期产物（均已 gitignore）：chroma_store/、.file_hashes.json（索引状态：每个文件的 md5 + mtime/size）、bm25_index.pkl.gz。

许可证

MIT —— 随意使用、修改、分发、商用，保留版权声明即可。