the-truth-mcp

# the-truth-mcp [](LICENSE) [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](https://docs.astral.sh/uv/) > **你的第二大脑作为仓库.** 你将信息扔到MCP。Gemini负责组织。你的MCP客户端查询并引用它。 一个本地MCP，它将一个markdown文件夹转换为一个**自我组织的知识库**，基于[Andrej Karpathy的LLM Wiki模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)。与其在矢量数据库中对原始块进行RAG，不如维护一个相互连接的`.md`文件图，该图由代理主动重新组织。 MCP是**客户端无关的**：它与任何MCP兼容的工具一起运行（Claude Code、Codex CLI、Gemini CLI、Cursor、Claude Desktop、ChatGPT等）。服务器内部只有Gemini - 重新组织知识库的图书管理员。 --- ## 快速入门（单个命令） 您需要[`uv`](https://docs.astral.sh/uv/getting-started/installation/)，MCP客户端和[Gemini API密钥](https://aistudio.google.com/apikey)（免费层足够）。 根据您使用的客户端选择命令： ```bash # Claude Code（Anthropic） uvx --from git+https://github.com/guilleheizen/the-truth-mcp \ the-truth-mcp install-claude \ --vault ~/Documents/my-vault \ --key AIza...your-gemini-key... # Codex CLI（OpenAI）- 在~/.codex/config.toml中注册 uvx --from git+https://github.com/guilleheizen/the-truth-mcp \ the-truth-mcp install-codex --vault ~/Documents/my-vault --key AIza... # Gemini CLI（Google）- 在~/.gemini/settings.json中注册 uvx --from git+https://github.com/guilleheizen/the-truth-mcp \ the-truth-mcp install-gemini --vault ~/Documents/my-vault --key AIza... ``` 每个`install*`执行相同的操作： 1. 如果指定的路径不存在，则创建知识库。 2. 在客户端的本机配置文件中注册MCP。 3. 在`~/.config/the-truth-mcp/.env`中以`600`权限保存API密钥和模型 - **绝不**在客户端配置文件中。密钥存储在一个位置，并在所有客户端之间共享。 > **奖励 - 附加`--with-skills`**，命令除了注册MCP外，还安装[`Ar9av/obsidian-wiki`](https://github.com/Ar9av/obsidian-wiki)技能框架到同一个知识库。这为您提供了Karpathy的LLM Wiki模式的过程操作（`wiki-query`，`wiki-lint`，`wiki-update`，`wiki-research`等），可从任何代理执行。参见下面的[Obsidian Wiki技能（可选）](#obsidian-wiki技能可选)部分。 ### 你需要看到的内容 ```text → 在/Users/.../my-vault中检测到现有知识库 → 使用shell的API密钥（$GEMINI_APIKEY）。模型保存在~/.config/the-truth-mcp/.env中。 → 在Claude Code中注册MCP `the-truth`（用户范围） ✓ MCP `the-truth`已安装在claude-code上。 知识库： /Users/.../my-vault 模型： gemini-2.5-flash 范围： 用户 配置： ~/.config/the-truth-mcp/.env（图书管理员的密钥 + 模型） ``` 如果您在任何步骤看到`✗`，请运行`the-truth-mcp doctor /Users/.../my-vault`进行诊断。 > **如果您已经在shell中导出了`GEMINI_API_KEY`**（zshrc/bashrc），您可以省略`--key`。服务器首先从环境中读取，如果找不到，则仅查看全局`.env`文件 - shell始终优先。 然后，您打开客户端，指向知识库并使用MCP工具（`save_info`，`vault_search`，`vault_read_page`，`vault_list_pages`）。 --- ## 它是如何工作的 ``` 您的MCP客户端 │ ├── save_info(...) ──▶ MCP ──▶ raw/<slug>.md （纯文本，不可变） │ │ │ └── Gemini API ──▶ wiki/ （Gemini决定结构） │ └── vault_search / vault_read_page ──▶ MCP ──▶ wiki/ （只读） ``` **三个角色，无重叠**: | 角色 | 谁 | 做什么 | |---|---|---| | 客户端 | 任何MCP工具（您） | **查询**和**保存原始信息**。绝不写入`wiki/`。 | | 服务器 | MCP `the-truth` | 文件系统上的I/O。只有一个写入工具：`save_info`。 | | 图书管理员 | Gemini（在MCP内） | `wiki/`的唯一所有者。读取整个知识库并重新组织。 | --- ## 您获得的内容 一个像这样的文件夹，**自动维护**，当您扔来源时： ``` my-vault/ ├── AGENTS.md ← 游戏规则（您编辑，Gemini读取） ├── raw/ ← 不变：每个来源 │ ├── software-2-0.md │ ├── attention-paper.md │ └── … ├── wiki/ ← Gemini自行组织 │ ├── index.md │ ├── concepts/ ← （或papers/，或people/，或Gemini决定） │ │ ├── software-2-0.md │ │ └── attention.md │ └── … └── log.md ← 仅追加操作日志 ``` **`wiki/`页面**使用`[[wikilinks]]`相互引用 - 与[Obsidian](https://obsidian.md)，Logseq或任何理解该格式的编辑器开箱即用。 --- ## 从头开始，适应您的领域 知识库**不强加类别**。Gemini观察您存储的内容并决定组织结构。如果您想指导结构，请在知识库的`AGENTS.md`中编写约定（有一个保留部分）。 一些配置示例（参见存储库中的[`examples/`](examples/)）： - **技术研究**（默认适合）：`concepts/`，`people/`，`papers/` - **产品/团队**：`features/`，`decisions/`，`incidents/`，带有front-matter中的`severity` - **咨询**：`clients/`，`projects/`，`lessons-learned/` - **个人学习**：`topics/`，`resources/`，`doubts/` - **烹饪**：`recipes/`，`techniques/`，`ingredients/` 您编辑`AGENTS.md`，存储一些新内容，Gemini开始尊重约定。无需触摸代码。 --- ## MCP工具和资源 **工具**（6）： | 工具 | 描述 | |---|---| | `vault_search(query, limit?)` | 在`wiki/`中grep。返回文件+行。 | | `vault_read_page(slug_or_path)` | 页面的完整内容。 | | `vault_list_pages(category?)` | 页面列表。`category`是`wiki/`的子文件夹（自由）。 | | `vault_status()` | 快照：页面，待处理原始文件，最后一次整理。使用它来决定是否运行`vault_groom`。 | | `save_info(content, …, defer_groom?)` | 在`raw/`中保存原始内容。默认情况下触发Gemini；使用`defer_groom=true`仅写入文件（快速，适用于批处理）。 | | `vault_groom()` | 要求Gemini立即重新组织`wiki/`。在批量`save_info(defer_groom=true)`后调用，或编辑`AGENTS.md`时。 | **资源**（通过`@`提及阅读）： - `vault://index` - 目录 - `vault://log` - 完整日志 - `vault://agents` - `AGENTS.md`（实时模式） - `vault://page/{category}/{slug}` - 任意页面 ### 高效模式：快速导入+延迟整理 如果您要连续保存多个文档，请不要在每次`save_info`时触发Gemini。推荐的流程： ``` save_info(doc1, defer_groom=true) ← ~100ms save_info(doc2, defer_groom=true) ← ~100ms save_info(doc3, defer_groom=true) ← ~100ms … vault_groom() ← 单次Gemini运行，吸收三个原始文件 ``` 成本：1次Gemini调用而不是N。时间：~30s最终，而不是3×30s间隔。知识库保持同样有组织。 要自动执行周期性整理，请使用CLI `the-truth-mcp groom <vault>`（见下文）在cron / launchd / GitHub Action中。 --- ## Obsidian Wiki技能（可选） MCP**工具**（上面的6个）是基元：读取、写入、组织。对于更具流程的流程 - “ ingest此URL”，“审计wiki”，“将项目同步到知识库” - 生态系统有一个优秀的基于技能的框架，[`Ar9av/obsidian-wiki`](https://github.com/Ar9av/obsidian-wiki），它忠实地实现了Karpathy的[LLM Wiki模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)。 优点：Ar9av的技能是markdown文件，任何代理都可以读取和执行它们 - Claude Code、Cursor、Codex CLI、Gemini CLI、Windsurf、Copilot等。不需要额外的服务器。并且它们**在同一个知识库**上运行，由`the-truth-mcp`管理 - 它们是互补的层，而不是排斥的。 ### 一行安装 ```bash the-truth-mcp install-skills --vault ~/Documents/my-vault ``` 这会将`Ar9av/obsidian-wiki`克隆到`~/.local/share/obsidian-wiki`（或您使用`--repo-dir`指定的位置），预先编写其`.env`文件，并运行`setup.sh` - 它将24个技能链接到您安装的所有代理中。 如果您刚刚开始，您可以将所有内容合并到一次运行中： ```bash the-truth-mcp install-claude --vault ~/Documents/my-vault --with-skills # （install-codex、install-gemini也是如此） ``` 这会将MCP注册到您的客户端+ Ar9av的技能 - 准备好一起使用两者。 ### 何时使用什么 | 任务 | MCP工具 | Ar9av技能 | |---|---|---| | 保存原始文本/markdown | `save_info` ✓ | `wiki-ingest` ✓ | | 保存URL并获取它 | - | `ingest-url` ✓ | | 读取页面 | `vault_read_page` ✓ | （技能直接从文件系统读取） | | 搜索文本 | `vault_search` ✓ | `wiki-query`（带合成）✓ | | 重新组织wiki | `vault_groom` ✓（内部Gemini） | `wiki-update`（使用客户端LLM） | | 健康检查 | - | `wiki-lint` ✓ | | 将项目同步到知识库 | - | `wiki-update` ✓ | | 主题研究 | - | `wiki-research` ✓ | | 导出图 - | `wiki-export` ✓ | 总结： **`the-truth-mcp`为您提供使用内部Gemini的自动重新组织**（需要API密钥但不消耗客户端令牌，一次1M上下文请求）。 **Ar9av为您提供模式的完整操作集**在客户端代理令牌上运行。试试两者，选择适合您使用的。 --- ## 配置 服务器按此顺序解析变量（具有值时优先）： 1. **进程环境** - 您的shell导出（`~/.zshrc`，`~/.bashrc`）。 2. **当前工作目录的`.env`** - 从存储库运行服务器时很有用。 3. **`<vault>/.env`** - 知识库特定配置。 4. **`~/.config/the-truth-mcp/.env`** - 用户全局配置（安装程序写入）。 | 变量 | 必需 | 默认值 | 描述 | |---|---|---|---| | `VAULT_PATH` | 是 | - | 知识库的绝对路径。每个`install*`都将其记录在客户端的配置中。别名：`LLM_WIKI_PATH`。 | | `GEMINI_API_KEY` | 是（用于`save_info`） | - | [Google AI Studio](https://aistudio.google.com/apikey)的API密钥。 | | `GEMINI_MODEL` | 否 | `gemini-2.5-flash` | 图书管理员的模型。 `gemini-2.5-pro`提供更好的质量。 | 接受的密钥别名：`GOOGLE_API_KEY`，`GEMINI_APIKEY`，`GOOGLE_GENAI_API_KEY`。 ### Gemini免费层 - 您期望什么 [Google AI Studio免费层](https://aistudio.google.com/apikey)有中等的速率限制（大约15次/分钟的`gemini-2.5-flash`，每日配额）。正常使用 - 每分钟保存1-2个文档 - 足够。如果您进行快速`save_info`爆发，您将收到429s；服务器会自动重试并退回到`gemini-2.5-pro`作为后备。如果您进行大量导入，请考虑支付Google AI Studio的层或切换到Vertex AI。 ### 为什么密钥存储在`~/.config/the-truth-mcp/.env`而不是客户端配置 ### 密钥为何存储在`~/.config/the-truth-mcp/.env`而不是客户端配置文件中 客户端MCP配置文件（`~/.claude.json`，`~/.codex/config.toml`，`~/.gemini/settings.json`）是被GUI应用程序打开的文件，不会经过shell；人们可能会不小心分享或上传它们到存储库中，在那里它们可能会被公开。如果将API密钥以纯文本形式存储在那里，它是一个footgun。MCP的全局配置存在于其自己的文件中，具有`chmod 600`权限，仅由服务器加载，并在所有客户端之间共享 - 将其安装到三个不同的工具中，密钥仍然存储在一个位置。 --- ## CLI ```bash the-truth-mcp # 启动MCP服务器（stdio）- 客户端调用此命令 the-truth-mcp init <path> # 创建新的知识库（不注册） the-truth-mcp install-claude --vault <p> # 注册到Claude Code（~/.claude.json） the-truth-mcp install-codex --vault <p> # 注册到Codex CLI（~/.codex/config.toml） the-truth-mcp install-gemini --vault <p> # 注册到Gemini CLI（~/.gemini/settings.json） the-truth-mcp install-skills --vault <p> # 安装Ar9av/obsidian-wiki技能（克隆+设置） the-truth-mcp doctor [<path>] # 验证设置（环境变量，密钥，知识库，Gemini健康状况） the-truth-mcp groom <path> # 运行Gemini以整理知识库（cron友好） the-truth-mcp --version ``` 共享的标志由三个`install-*`使用：`--vault`，`--key`（如果已经在shell中），`--model`，`--name`，`--local`，`--with-skills`（还安装Ar9av/obsidian-wiki）。`install-claude`命令还接受`--scope {user,local,project}`以选择在Claude Code中注册MCP的位置。 您可以对同一知识库运行多个`install*`命令 - 每个客户端都有自己的配置文件，密钥通过`~/.config/the-truth-mcp/.env`共享。 ### 编程定期整理 `the-truth-mcp groom <vault>`是在客户端MCP之外运行的包装器 - 在您将文档以`defer_groom=true`模式保存了一整天后很有用。示例： ```bash # launchd（macOS）：~/Library/LaunchAgents/com.the-truth.groom.plist指向： the-truth-mcp groom ~/Documents/my-vault # cron（Linux）：crontab -e - 每天凌晨3点运行 0 3 * * * /usr/local/bin/the-truth-mcp groom $HOME/Documents/my-vault >> $HOME/.the-truth-groom.log 2>&1 # GitHub Action：知识库的存储库有一个工作流，每次提交时都会进行整理 # （查看示例中的yaml）。 ``` 该命令读取shell中的API密钥，知识库中的`.env`文件，或`~/.config/the-truth-mcp/.env`文件 - 与服务器相同的顺序。退出代码：`0` ok，`1` 知识库不存在，`2` Gemini失败，`3` lock timeout，`4` 整理运行但有单个操作错误。 --- ## 为什么选择Gemini进行重新组织 - **1M令牌上下文**：一次性读取整个知识库。其他模型将不得不分页。 - **经济高效**：Gemini Flash非常便宜 - 可以连续调用`save_info`而无需担心费用。 - **角色分离**：MCP客户端读取并引用；Gemini是整理知识库的图书管理员。人类是仲裁者。 如果您想更改它（另一个模型，本机模型），请在`src/the_truth_mcp/gemini_agent.py`中隔离。 --- ## 开发 参见[CONTRIBUTING.md](CONTRIBUTING.md)获取完整流程。快速游览： ```bash git clone https://github.com/guilleheizen/the-truth-mcp.git cd the-truth-mcp uv sync uv run the-truth-mcp run # 本地运行服务器 ``` 结构： ``` src/the_truth_mcp/ ├── server.py ← FastMCP：工具+资源 ├── vault.py ← 文件系统上的I/O（无LLM，可测试） ├── gemini_agent.py ← 图书管理员Gemini（一次，结构化JSON） ├── schemas.py ← Pydantic：计划+ 7种操作类型 ├── cli.py ← init，doctor，run，install* ├── vault_starter/ ← 无客户端模板，`init`复制 └── client_extras/ ← 每个`install-<client>`添加到知识库的文件 └── claude-code/ ← .claude/（斜杠命令，权限，钩子） ``` --- ## 已知限制 - **重试有限**：服务器重试Gemini的暂时性错误（429/5xx）并使用退后（2s，8s，30s）并回退到`gemini-2.5-pro`。如果仍然失败 - 无网络，密钥过期 - 原始内容存储在`raw/`中，`wiki/`不会更新，直到下一次`save_info`。信息不会丢失。 - **一次，不循环代理**：Gemini发出每个调用的单个计划。对于非常大的知识库（> 500k令牌内容），这可能有限制。 - **`log.md`不会压缩**：仅追加，增长不受限制。 欢迎提交PR以解决任何问题。 --- ## 故障排除 ### Gemini响应503或429 速率限制或上游过载。服务器会自动重试并延迟。如果仍然失败，请尝试一分钟后重试`save_info`。如果持续，请尝试`GEMINI_MODEL=gemini-2.5-pro`以降低负载。 ### 找不到Gemini API密钥 服务器检查了四个环境别名（`GEMINI_API_KEY`，`GOOGLE_API_KEY`，`GEMINI_APIKEY`，`GOOGLE_GENAI_API_KEY`），但没有找到任何一个。修复：重新运行`the-truth-mcp install-claude --vault <path> --key <key>`，或在shell rc中导出`GEMINI_API_KEY=...`。 ### 知识库路径指向不存在的目录 `VAULT_PATH`指向一个不存在的文件夹。修复：您要么纠正注册（重新运行`install-*`），要么手动创建路径。运行`the-truth-mcp doctor <path>`进行诊断。 ### `<path>`中未找到`AGENTS.md` 知识库缺少其模式文件。或者，您指向的`VAULT_PATH`是一个没有创建`AGENTS.md`的目录，或者您手动复制了一个`AGENTS.md`模板（参见`src/the_truth_mcp/vault_starter/AGENTS.md`）。 ### MCP出现，但工具无响应 服务器启动了，但某些内容在启动时静默失败了（典型情况：macOS上从Spotlight/Dock启动客户端时环境变量加载不正确）。关闭客户端并从加载了shell rc的终端启动它。或者，确保密钥位于`~/.config/the-truth-mcp/.env`中 - 服务器加载密钥，不依赖客户端环境。 --- ## License MIT. 参见[LICENSE](LICENSE).