second-brain MCP

second-brain MCP Server

面向 AI Agent 的自维护个人知识库——一个由 MCP 驱动的纯 Markdown 知识库。

📖 英文 · 繁體中文

---

本地知识库，AI Agent 可以读取、写入并自主维护。只需一条命令即可保存论文或笔记——second-brain 会将其转换为 Markdown、对所有图表进行 OCR、生成嵌入以支持语义搜索，并自动关联相关笔记。随着时间推移，长期未阅读的笔记会自动压缩，让知识库不断扩大的同时，回忆成本依然低廉。

所有内容都是纯 Markdown——可通过 Google Drive / iCloud / git 同步，随时切换 Agent，零绑定。

亮点

• 一条命令保存任何内容——save_article(url_or_pdf) 会获取内容、转换为 Markdown、对图表进行 OCR（Claude Vision）、生成嵌入并自动关联相关笔记。
• 图表级搜索——search_figures("UMAP melanocyte") 可在整个资料库中返回精确匹配的图表面板。
• 自组织——新笔记会自动关联相关笔记；经常阅读的笔记会提取可复用的规则。
• 像大脑一样遗忘的记忆——使用艾宾浩斯排序；过时的笔记会自动压缩（减少 60–90% 的令牌数）。
• 只读整理审计——检查文章元数据、链接、精确重复候选项、收件箱存放时长和来源新鲜度，不会更改知识库。
• 会话连续性——每次会话开始时，get_context() 会重新加载目标 + 排名靠前的笔记 + 规则。
• 可插拔后端——DuckDB（默认，离线）或 Postgres + pgvector（集中式、多机器）。可选自托管嵌入；离线时回退到 BM25。

快速开始（Claude Code）

pip install mcp-second-brain
playwright install chromium

claude mcp add --scope user second-brain \
  --env SECOND_BRAIN_PATH=~/second-brain \
  -- python -m mcp_second_brain

首次运行时会创建知识库目录和模板。然后告诉 Agent 执行 init_vault 进行验证。

⚠️ PyPI 版本目前落后于源代码树。要获取最新版本，以及了解 Claude Desktop、Windows 和多机器 / 中央服务配置，请参阅 NEW_MACHINE_SETUP.md。

核心工具

工具	功能
auth_context	读取已通过身份验证的调用方的规范 UUID、角色和 RBAC 状态
get_context	会话开始时获取目标 + 排名靠前的笔记 + 自动规则
save_article	URL / PDF → Markdown + 图表 + 嵌入
search_notes / search_figures	混合 BM25 + 语义搜索（笔记文本 / 图表内容）
search_articles	按作者、ORCID、DOI/PMID/PMCID 和年份结构化搜索论文
audit_article_records	有界、只读的文章整理和社交来源新鲜度报告
new_note / update_note / append_to_note	创建和编辑笔记（自动归档、自动索引、自动关联）
vault_sleep	压缩陈旧、低活跃度的笔记
get_agent_instructions	向远程 Agent 提供完整的归档 SOP（AGENTS.md）

完整工具参考（46 个工具）见 AGENTS.md。

需要查找内容时使用 search_notes；服务器或索引可能不健康时使用 health_check； 需要整理报告时使用 audit_article_records。审计结果不会自动合并、归档或删除笔记。

工作原理

Any source (paper · PDF · web · note)
        │   save_article · new_note
        ▼
Markdown vault  ──►  index  (DuckDB, or Postgres + pgvector)
  00-inbox/            • BM25 + semantic search
  10-projects/         • figure OCR + vision descriptions
  20-areas/            • auto-wikilinks between related notes
  30-resources/        • Ebbinghaus ranking → weekly auto-compression
  decisions/ memory/
        │
        ▼
Your AI agent queries it — search_notes · search_figures · get_context

知识库是事实来源；索引可随时重建（sync_index）。归档规范集中在一份操作手册 AGENTS.md 中，并通过 get_agent_instructions() 提供给任何 Agent，确保每个 Agent 都以相同方式归档，无需重新培训。

知识库结构

vault/
├── 00-inbox/       Unprocessed captures
├── 10-projects/    Active projects
├── 20-areas/       Ongoing research / coding domains
├── 30-resources/   Papers & articles (save_article writes here)
├── 40-archive/     Auto-compressed originals
├── decisions/      Architecture Decision Records
├── memory/         goals.md · rules.md  (injected every session)
└── templates/      Note templates

旧版作者元数据

search_articles 会读取结构化的 frontmatter，因此不会从正文或参考文献中推测较早的文章笔记中缺失的 authors。一个有界的两阶段 CLI 可以安全地为这些笔记补充信息：先创建并审核清单，再单独应用。

python -m mcp_second_brain.author_backfill \
  --vault "<vault>" --limit 20 --out /tmp/author-backfill.json
python -m mcp_second_brain.author_backfill \
  --vault "<vault>" --apply --manifest /tmp/author-backfill.json

仅在中央写入主机上应用。每个条目都必须与 DOI/PMID/PMCID 或标题完全匹配，且内容和正文哈希保持不变；成功写入后会重新建立索引。

文档

• AGENTS.md — 归档 SOP、命名规范、完整工具参考（唯一事实来源）
• NEW_MACHINE_SETUP.md — 源码安装、自托管、多机器中央服务、API 密钥
• CONTEXT.md — 领域模型 / 通用语言

设计说明

灵感来自生物记忆：采用艾宾浩斯遗忘曲线（access_count / ln(age_days)）进行排序，并采用依赖睡眠的巩固机制（每周使用大模型压缩低访问量笔记）。基于 MarkItDown · DuckDB · pgvector · FastMCP · Playwright · Claude API 构建。

许可证

MIT © 2026 Chan Chi Ru。参见 LICENSE。