tacitus-mcp-server

Tacitus

为 AI Agent 提供长期记忆——本地优先，且具备来源追溯能力。

Tacitus 是一个 MCP 服务，可将任意文件夹中的 Markdown 笔记 转变为原生适用于 Agent 的知识库。它为 AI Agent （Claude Code、Claude Desktop 和任何 MCP 客户端）提供了它们真正需要的三项功能：

1. 可追溯来源的记忆——类型化、可查询的长期记忆。每条事实 都附带来源，并在令牌预算内返回；矛盾会被明确指出，而不会被悄悄化解。
2. 适配上下文窗口的检索——搜索会在令牌预算内返回排序后的片段 （而非整篇笔记）；get_note 会逐步披露内容（大纲 → frontmatter → 全文）；维基链接图是可查询的 API。 混合词法与语义搜索，并支持可选的神经嵌入器。
3. 安全写回——提出变更集、预览差异、原子提交，并可按版本回滚。 只读范围禁止修改；每次写入都会记录审计日志。

笔记仍以纯 .md 文件形式保存在你的文件夹中。无云端依赖，无供应商锁定。

录制于真实会话——上方显示的 memory id、changeset id、version id 和审计 日志行均为二进制程序实际返回的内容（详情）。

快速开始

npx -y @dashiro/tacitus-mcp-server /path/to/your/vault

Claude Code

claude mcp add tacitus -- npx -y @dashiro/tacitus-mcp-server /path/to/your/vault

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "tacitus": {
      "command": "npx",
      "args": ["-y", "@dashiro/tacitus-mcp-server", "/path/to/your/vault"]
    }
  }
}

原生二进制程序（无需 Node）

更喜欢单个零依赖的二进制程序？Rust 服务会在每次发布时提供适用于 macOS、Linux 和 Windows 的预构建版本。

# macOS / Linux — installs `tacitus-mcp` into your Cargo bin dir
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/ionasrobert/tacitus-mcp-server/releases/latest/download/tacitus-mcp-installer.sh | sh

# Windows (PowerShell)
irm https://github.com/ionasrobert/tacitus-mcp-server/releases/latest/download/tacitus-mcp-installer.ps1 | iex

或者，从最新版本下载适用于你平台的 .tar.xz / .zip。然后将任意 MCP 客户端指向该二进制程序，而不是 npx：

claude mcp add tacitus -- tacitus-mcp /path/to/your/vault

原生二进制程序是旗舰服务（25 个工具；npm 服务包含核心的 16 个——见下表）。两者共用相同的磁盘格式，因此同一个 vault 可与任一版本配合使用。设置 TACITUS_SCOPE=read-only 可在无写入权限的情况下运行原生 服务。

工具

分组	工具
记忆	remember、recall、forget
检索	search、get_note、graph_query、list_notes、properties_query*
回写	propose_changes、commit_changes、revert、rename_note、delete_note、get_version*
便捷工具	create_note、update_note、link、tag、audit_log
模板	list_templates、create_from_template
任务	list_tasks、toggle_task
元数据	capabilities

* 优先支持原生 Rust 服务（npm 服务将随后跟进）： properties_query — 针对 YAML frontmatter 执行类似 Bases 的结构化查询 （筛选条件为 eq|ne|contains|exists|not_exists|gt|lt|gte|lte，支持排序、选择、 token_budget）。模板 — .tacitus/templates/ 中的 Markdown 文件，其 {{var}} 占位符构成一个架构；替换会在 YAML 解析前进行，因此数值变量会保留类型，{{date}}/{{time}}/{{datetime}} 会自动填充，创建操作会像任何 Agent 写入一样进行版本控制并记录审计。 任务 — 每一条清单行（- [ ]）都会作为一个有类型的实体（完成状态、来自 due:YYYY-MM-DD 或 📅 的截止日期、#标签），可供查询和切换；切换时会将 任务文本用作并发保护条件，因此过期的调用方会收到 CONFLICT， 而不是误切换错误的任务。rename_note 会在一个原子变更集中，将所有指向该笔记的 wikilink 重定向至新位置（保留别名/标题）——一次撤销即可还原整个重命名操作； delete_note 也会进行版本控制。

每个工具都会使用架构验证输入，并返回结构化、可操作的 错误（{ code, reason, suggestion }），而非堆栈跟踪。

面向开发者：插件与集成

在 Tacitus 中，插件就是一个 MCP 客户端——上述工具契约是 公开 API，内置权限范围控制、版本控制和审计功能。

• docs/PLUGINS.md — 集成指南：连接 Agent、 使用 Python/TypeScript 编写插件、嵌入 Rust 引擎、插件模式
• TypeScript SDK — @dashiro/tacitus-sdk：每个工具都作为 类型化方法提供，{code, reason, suggestion} 错误会以 TacitusToolError 的形式抛出：

  const tacitus = await TacitusClient.spawn({ vault: '/path/to/vault' });
  const hits = await tacitus.search({ query: 'client X', token_budget: 500 });
  

• 沙盒化 WASM 插件（实验性） — tacitus-plugins crate 使用 Wasmtime 运行 guest wasm，并根据清单声明的权限（工具允许列表
  • 范围）执行，同时设有燃料和内存限制，且不提供 WASI：tacitus.call 就是 tools/call。 原生二进制内嵌了运行时：tacitus-mcp plugin list|run 可用于 cron Agent 和脚本。 参见 docs/PLUGINS.md §5
• docs/MCP_API.md — 全部 25 个工具的完整参考 （参数、返回值、错误代码）
• 神经搜索（可选启用）：TACITUS_EMBEDDER=ollama 使用本地 Ollama 守护进程 生成嵌入向量（TACITUS_OLLAMA_EMBED_MODEL，默认为 nomic-embed-text； 需要支持嵌入的 Ollama）。向量缓存在 .tacitus/vectors/ 中； 若不可用，则回退到确定性哈希嵌入器。
• docs/SYNC.md — 同步（测试版）：设备之间进行端到端加密的 CRDT 同步 （tacitus-mcp sync init；sync status 会显示知识库占用的中继配额）
• docs/DATA_FORMAT.md — 磁盘上的数据格式 （.tacitus/ 内部结构、稳定 ID、笔记约定）
• examples/ — 三个完整插件（Python 只读分析器、 Node 每日日记 cron Agent、沙盒化 WASM guest），均已通过二进制程序测试

同步中继能看到什么

左侧：两台设备，内容为纯 Markdown。右侧：中继为该知识库存储的全部内容。录制结束后， 这些数据块是从真实的 log.jsonl 中读取出来的——没有笔记标题、没有路径、没有明文。知识库代码就是密钥，永远不会离开你的设备；如果丢失，保存在中继上的副本将永远无法解密。

语义搜索（可选神经嵌入）

search 默认采用 混合 模式（词法搜索 + 确定性离线嵌入器，可识别词形变化）。如需匹配同义词或释义，可选择神经嵌入器：

npm i @huggingface/transformers
TACITUS_EMBEDDER=transformers npx @dashiro/tacitus-mcp-server /path/to/vault

向量缓存于 .tacitus/vectors/ 下。如果可选依赖或模型不可用，则回退到确定性嵌入器。

存储方式

your-vault/
├── notes...             ← your Markdown files (untouched format)
└── .tacitus/
    ├── memory/*.md      ← agent memories (Markdown + YAML frontmatter)
    ├── vectors/*.json   ← cached embeddings
    ├── history/*.json   ← version snapshots (for revert)
    └── audit.log        ← JSONL log of every agent write

开发

多语言单体仓库。参考服务（通过 npm 发布）使用 TypeScript 编写，位于 packages/mcp-server。crates/ 中的 原生 Rust 服务 提供单二进制、零运行时依赖的构建（crates/tacitus-core 引擎 + crates/tacitus-mcp rmcp 服务）——功能集包含 TS 服务的全部功能，并有所扩展（25 个工具，对比 16 个）。其 stable_id 与 TS 引擎逐字节匹配，因此两个引擎生成的记忆 ID 完全相同。

# TypeScript server
npm ci
npm test          # vitest
npm run typecheck
npm run lint
npm run build     # tsup → packages/mcp-server/dist
npm run eval      # retrieval quality report

# Rust server (native, single binary)
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --check
cargo run -p tacitus-mcp -- /path/to/vault   # runs the MCP server on stdio
cargo build --release                         # → target/release/tacitus-mcp

每当推送 v* 标签时，cargo-dist 会通过 dist-workspace.toml + .github/workflows/release.yml 构建跨平台发布二进制文件，并将其发布到 GitHub Releases。

许可证

MIT——详见 LICENSE。