Skip to main content
Glama

secondbrain-mcp

Local-first personal knowledge base as MCP: Markdown vault + hybrid RAG retrieval + a safety-first gateway with hash locks, audit trail, privacy zones and rollback — so that AI agents can use your knowledge base without being able to wreck it.

状态:✅ v0.2 —— 14 个工具 · 单元+e2e 门禁全绿(含真实 stdio 协议端到端)· CI 门禁全过(semantic 门在 CI 口径外,见评测) | License: MIT

为什么做这个

2026 年的 AI agent 已经很会「读」,但很少被允许「写」用户的长期知识库——因为写没有安全边界。

本项目把一套在个人生产环境真实运行的知识库网关重写为单一 Python 核心,核心是四件事:

  1. 哈希锁写入:所有更新必须携带 expected_hash,且在锁内复验;冲突即拒绝并给出恢复指令。

  2. 无删除设计:归档 = 移动到 Archive 区并生成可回滚清单,清单在移动之前写入。

  3. 隐私分区:95_Private 在读取、写入、索引、检索四层拒绝,分区判定大小写无关。

  4. 全量审计:intent 与 outcome 分开记录,每条带前一条的哈希,形成可校验的链。

Related MCP server: brain-mcp

功能

  • MCP server:14 个窄工具(read / list / search / index / review / create / append / patch / meta / move / archive / restore / archive_list_batches)

  • 混合检索:BM25 倒排 + 向量余弦 + RRF 融合,两道防噪门禁

  • 增量索引:embed_state 显式跟踪,失败在下一轮自动重试

  • 模型指纹:换模型强制重建向量,杜绝向量空间混用

  • 正文编辑:note_patch 两阶段确认,先出 diff 再落盘

  • 隐私分区与待确认队列

  • 合成演示知识库(demo vault,无任何真实个人内容)

  • 单元测试 + 对抗性测试 + MCP stdio 端到端 + 可失败的检索门禁

  • 部署健康检查(暂存库跑全契约 + live 索引只读快照探针)

文档

快速开始

要求 Python 3.10+。两档安装:

git clone https://github.com/stone1524/secondbrain-mcp
cd secondbrain-mcp
pip install -e ".[semantic]"   # 完整混合检索(含 numpy + fastembed,推荐)
pip install -e .               # 纯词法模式(无需 numpy,mode=hybrid 自动降级并在返回中说明原因)

试用合成 demo vault(不接你自己的数据,仓库自带、全部为合成内容):

secondbrain-mcp          # 不设 SB_VAULT_ROOT 时默认服务仓库内 demo-vault/

接入自己的知识库 / MCP 客户端(Claude Code、Cursor 等任何支持 MCP 的客户端):

{
  "mcpServers": {
    "secondbrain": {
      "command": "python",
      "args": ["-m", "secondbrain_mcp.adapters.mcp_stdio"],
      "env": {
        "SB_VAULT_ROOT": "C:/path/to/your/markdown-vault",
        "SB_STATE_ROOT": "C:/path/to/state",
        "SB_AGENT_LABEL": "claude"
      }
    }
  }
}

环境变量:

变量

默认

说明

SB_VAULT_ROOT

仓库内 demo-vault/(按安装位置解析;wheel 安装找不到捆绑目录时回退 ./demo-vault)

vault 目录

SB_STATE_ROOT

<vault>/.secondbrain

索引、审计、锁的根目录

SB_RAG_DB

<state>/index.db

索引库路径

SB_AGENT_LABEL

无

审计归因标签,多客户端共用时区分写入者

SB_RAG_SEMANTIC

1

设为 0 走纯词法(纯词法模式无需 numpy)

SB_RAG_MODEL

BAAI/bge-small-zh-v1.5

嵌入模型

SB_RAG_MODEL_CACHE

无

模型缓存目录(离线场景必填,直通 fastembed)

SB_RAG_EMBED_BATCH

0(后端默认)

嵌入批大小,直通 fastembed

SB_SEMANTIC_FLOOR

0.55

语义命中相似度下限(查询与笔记同语言时)

SB_SEMANTIC_FLOOR_CROSS

0.42

跨中英语言对的语义命中下限(zh 调优模型跨语言余弦偏低,按语言对单独校准)

SB_SEMANTIC_MIN_TOKENS

20

语义命中最小 token 数,按整篇笔记计量(命中分块或全篇分块合计过线均可)

索引在首次 search 时按需自动构建或修复(大库首次调用会慢);index_rebuild 用于手动/强制重建(换嵌入模型后加 force=true)。note_read 才是取证。

安全模型

  • 写:note_create 默认只进 inbox 且重名加后缀(不覆盖);overwrite=true 提供带 expected_hash 哈希锁的受控覆盖(锁内复验);note_append / note_patch / note_meta / note_move 全部要求 expected_hash,并在文件锁内复验

  • 删:不存在。唯一移除路径是带批次回滚清单的归档,restore 可整批或按条恢复

  • 隐私:私有前缀在读、写目的地、索引、搜索四层拒绝,且大小写无关;泄漏探针在单元与线上两层测试

  • 审计:每次写落 intent 与 outcome 两条,带哈希链;AuditLog.verify() 可校验

  • 内容即数据:所有读取与检索结果带 trust: untrusted_note,提示调用方不得把笔记内容当作指令

评测

python -m secondbrain_mcp.eval.run --cases eval/cases-dev.json --semantic

五道门禁,每一道都能真的失败:recall@5 ≥ 0.85(标题派生用例口径;零重叠探针 no_shared_term 由下述 semantic 门与 by_category 读数单独承担,headline recall 仍计全量)、semantic rank-1 wins ≥ 1(仅在 --semantic 下生效,词法模式报告为 not-applicable 而不是静默通过;CI 无模型缓存、从不跑 --semantic,向量通道在 CI 口径中为 uncovered)、null vectors == 0、privacy leakage == 0(读侧四种拼写探测)、index_side_leak == 0(直接读库,抓读侧门禁看不见的入库泄漏)。CI 会先建 demo 索引,再跑门禁与部署契约检查,并再生成 eval/cases-dev.json 与提交版本比对(用例文件不得滞后 policy 变更)。 当前结果与旧系统的对照见 docs/evaluation.md。

开发方式:AI 结对 + 测试门禁

本仓库以「AI agent 结对 + 人工把关」的方式开发:agent 负责起草与重构,人负责审查与取舍,所有提交前必须通过同一组门禁——

  • pytest -q:357 条用例(单元 + 对抗 + MCP stdio 端到端),本地实跑通过才允许提交

  • ruff 静态检查

  • GitHub Actions:双平台 × 双版本矩阵,main 分支保留全矩阵通过记录(2026.10.20 Run 5 可查)

38 次提交均由本人逐个确认——AI 提升的是速度,边界与取舍仍由人决定。这也是本项目主题(让 AI 安全地参与真实工作)在开发过程本身上的实践。

License

MIT

Available Tools

13 tools
append_noteB

Append to a note under a per-file lock with optimistic-concurrency check on expected_hash.

Inputs: note (required), content (required), expected_hash.

archive_notesA

Archive notes by (note, hash, category) entries into the review area with a batch rollback manifest. Run dry_run first.

Inputs: entries (required), dry_run.

create_inbox_noteA

Create a note in an inbox directory (Web/Conversations/Files). Never overwrites an existing file.

Inputs: folder (required), content (required), filename (required).

list_archivesB

List archive batches with their restore accounting.

Inputs: limit.

list_notesA

List note paths (private notes excluded), newest first; optional folder prefix and substring pattern.

Inputs: limit, folder, pattern.

move_noteA

Move a note within the vault (never into a private area); destination must not exist.

Inputs: note (required), destination (required), expected_hash.

rag_reindexC

Incrementally re-index the vault into a rebuildable derived index.

Inputs: force.

rag_statusA

Index health metadata (document/chunk counts, schema version) without exposing note contents.

Inputs: no named parameters.

read_noteA

Read a standard note by vault-relative path; returns the full-content hash. Private notes are never readable.

Inputs: note (required), offset, max_length.

restore_archiveB

Restore an archived batch back to its original paths; skips already-restored, missing, altered or occupied entries.

Inputs: only, dry_run, batch_id.

search_notesA

Keyword search over indexed notes; falls back to a linear vault scan when the index is empty.

Inputs: query (required), limit, paths.

update_metadataA

Update an allowlisted set of frontmatter fields (status/tags/agent_generated/...); other keys are dropped.

Inputs: note (required), fields (required), expected_hash.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools are clearly separated by action and resource, and the archive/restore group is unambiguous. However, search_notes and rag_search both offer retrieval over notes, and list_notes' substring filter partially overlaps with search_notes, so an agent could occasionally pick the wrong one.

    Naming Consistency5/5

    Tool names follow a consistent snake_case verb_noun pattern: read_note, list_notes, move_note, append_note, update_metadata, archive_notes, restore_archive. The rag_* tools use a domain prefix but still read predictably, so the naming convention is coherent throughout.

    Tool Count5/5

    Thirteen tools is a well-scoped count for a note-management server covering capture, retrieval, organization, metadata, and archiving. Each tool has a clear role and none feel redundant or extraneous.

    Completeness4/5

    The core note lifecycle is well covered: create via inbox, read, list, search, move, append, metadata update, archive, and restore. The main gaps are the lack of a direct content-replacement operation and a permanent delete/purge, though append and archive/restore mitigate most practical needs.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers