内容
# Tremula
[](https://pypi.org/project/tremula-mcp/)
[](https://pypi.org/project/tremula-mcp/)
[](LICENSE)
> *Populus tremuloides* — 颤抖的白杨树。Pando 群落有数千根树干共享一个生存的根系。Tremula 为您的代码库提供相同的内存形状：每个项目一个知识图谱，在项目实际相交的地方相连。
**Tremula 是用于 AI 辅助开发的自我维护内存。** 它在您的代码库中维护一个与 Obsidian 兼容的 markdown 知识图谱 — 模块、关键函数、架构决策、约定、跨服务合约 — 并在您工作时自动维护。
## 为什么
AI 编码代理每次会话都开始时没有任何记忆，而手写的文档也会腐烂。Tremula 通过两个协作循环来弥补这两个空白：
- **反应循环 — 一个 MCP 服务器** ，向任何 MCP 客户端公开六种工具：`search`、`get_context`（一个主题 *加上* 其图邻居）、`read_note`、`write_note`、`link_notes`、`split_note`。
- **环境循环 — 生命周期钩子** ，无需请求即可工作：捕获会话事件到一个廉价的本地日志，在会话开始时注入保险库的索引，在不引人注意的情况下将与正在触摸的文件相关的少数笔记附加，并在一个防抖动后台进程中将持久知识（决策、约定、合约）蒸馏成笔记。
检索是一个漏斗，而不是一个倾倒：会话开始时大约 2k 个令牌索引，按需扩展图形上下文，每个提示的小工作上下文附件。上下文开销保持不变，无论保险库增长多大。
## 保险库的建立和维护方式
| 机制 | 何时 | 成本 |
|---|---|---|
| `tremula bootstrap --brief` | 一次，立即 | 零 LLM — 文档字符串 + 树探针 AST |
| `tremula bootstrap [target ...]` | 任意选择深入 | 约一个小型 LLM 调用每个模块 |
| 背景蒸馏器 | 工作时（防抖动，≥10 分钟间隔） | 每个运行一个小型 LLM 调用 |
| 修订看护人 | 每 5 次蒸馏运行或 `tremula revise` | 分割超大笔记，合并重复项，存档过时项 |
| `tremula verify` | 当您声明检出为规范时 | 列出（或 `--prune`）代码真正消失的笔记 — 唯一删除或降低信任的命令 |
模块依赖链接来自树探针导入图 — 计算的，从不虚构。蒸馏器是 **代理无关的** ：默认情况下，它自动检测您已经在 `PATH` 上的哪个代理 CLI（`claude`、`gemini`、`codex`，...），并外壳到它 — 无需 API 密钥，无供应商锁定。指向特定 CLI、显式命令或 Anthropic API 在一个配置文件行中（参见[选择模型提供者](#choosing-the-model-provider))。
### 内存跟随您的检出，而不是您的分支
您跨多个分支工作；您的内存不应在它们之间出血。一个笔记由蒸馏器写入，当您构建一个功能时，笔记是 **临时的** ，并绑定到它描述的代码（它触摸的文件和它命名的符号）。当该代码实际出现在您的工作树中时，它会被主动注入 — 因此，关于半成品功能分支的笔记永远不会在 `main` 上的会话中出现。每次蒸馏器重新观察到存在的代码时，笔记就会累积一个确认；经过几个确认后，它就变成 **批准的** ，并且始终有资格，排名在证据较少的笔记之前。
这以 **您当前检出的内容** 为基准，因此它不需要分支跟踪，无需提交 SHA，也无需 PR — Tremula 保持一个内存图谱，而不是一个版本控制工具。它也能干净地降级：没有 git，或者没有树探针语法的语言，一切仍然像以前一样有资格。抑制是 **仅注入** 的 — 被抑制的笔记永远不会被删除，并且通过 `search`/`get_context` 仍然可以搜索。可以在 `~/.tremula/config.yaml` 中调整它（`confirmation_threshold`，默认为 3；`confirmation_batch_size`；或 `lifecycle_enabled: false` 以关闭整个行为）。
## 安全模型
- **Markdown 是真相的来源。** SQLite/FTS5 是一个可重建的缓存。 在 Obsidian 或任何编辑器中编辑笔记；更改会自动被拾取。
- **手写的笔记受到保护。** 机器编写的笔记被标记为 `source: distilled`。 蒸馏器可以自由更新自己的笔记，但只能 **丰富** 您自己的笔记 — 通过 LLM 判定器加上确定性无内容丢失的备份。
- **项目在构造时是隔离的。** 会话解析自己的保险库加上明确声明的共享保险库（`roots`）— 任何其他地址都无法解析，而不是简单地过滤。
- **没有任何内容被删除。** 清理归档到保险库内的 `attic/`，git 历史记录作为更深的墓碑。 分支/工作树状态仅影响 **主动注入** （参见[内存跟随您的检出](#memory-follows-your-checkout-not-your-branch)) — 永远不会存储的内容。 信任仅自动上升；降低或修剪信任是显式且需选择的 `tremula verify`。
## 联邦
在实际相交的仓库中连接它们：
```bash
tremula root add webapp-api --members webapp,api
```
共享合约生活在桥梁保险库中，每个端点一个笔记，每个侧面一个部分（`## 提供者（api）` / `## 消费者（webapp）`）。每个项目的工具只能编辑自己的部分 — 因此当两侧意见不一致时，差异在一个文件中可见，而不是在两个仓库中隐藏。
## 安装和设置
### 手动
#### 快速入门
四个命令即可使用保险库 — 无需 API 密钥，无需其他要求：
```bash
uv tool install tremula-mcp # 安装（pip install tremula-mcp 也有效）
cd ~/code/your-project # 您的仓库
tremula registry init # 创建 + 注册 tremula-vault/
tremula bootstrap --brief # 从您的代码中播种（即时，无需 API 密钥）
```
然后在仓库根目录中保存一个 `.mcp.json`，并重启您的会话：
```json
{ "mcpServers": { "tremula": { "command": "tremula", "args": ["serve"] } } }
```
这就是反应循环 — 您的代理现在拥有六种内存工具。对于更丰富的种子、稳定的项目名称、构建目录过滤或环境自动蒸馏循环，请按照下面的完整设置进行。
#### 完整设置
**1 · 安装**
```bash
uv tool install tremula-mcp # 或：pip install tremula-mcp
# 零安装：uvx tremula-mcp <cmd>
```
**2 · 注册项目**
```bash
cd ~/code/your-project
tremula registry init
```
创建 `tremula-vault/`（及其 `_index.md`）并注册仓库。项目密钥默认为目录名称 — 要固定一个稳定的密钥（例如 `webapp_frontend` 而不是 `frontend`）：
```bash
tremula registry init --name webapp_frontend
```
您也可以通过 `.mcp.json` 中的 `env` 块中的 `TREMULA_PROJECT` 环境变量设置密钥，并使用 `registry init --name <new> --force` 重命名。
**3 · 保持构建输出** *(大型或 JS/TS 仓库)*
`bootstrap` 已经跳过 `node_modules`、`.venv`、构建目录和 Tremula 自己的状态。对于框架构建输出，请在仓库根目录中添加一个 `.tremulaignore` — 每行一个目录名称 — **在** 播种之前，以便工件不会将真实源代码排除在保险库之外：
```
.next
.sst
.open-next
```
（机器范围的默认值也可通过 `bootstrap_skip_dirs` 在 `~/.tremula/config.yaml` 中获得。）
**4 · 播种保险库 — 简要、完整或部分**
选择前期生成的数量：
| 模式 | 命令 | 您得到的内容 |
|---|---|---|
| **简要** — *推荐* | `tremula bootstrap --brief` | 整个仓库作为从文档字符串 + 树探针 AST 的存根笔记。**即时，零 LLM 调用，无需 API 密钥。** 环境蒸馏器在您工作时填充笔记。 |
| **完整** | `tremula bootstrap` | 整个仓库，每个模块一个 LLM 调用，生成更丰富的摘要。会消耗调用和时间 — 运行 `tremula bootstrap --dry-run` 先预览计数。 |
| **部分** | `tremula bootstrap src/ app/` | 只有您命名的目录（添加 `--brief` 获取存根）。大型仓库和多模块仓库的最佳选择。 |
使用 `tremula bootstrap src/core/` 深度丰富任何目标。完整和部分运行需要模型提供者 — Tremula 自动检测您的代理 CLI，参见[选择模型提供者](#choosing-the-model-provider)；简要不需要。
**5 · 连接 MCP 服务器**
将以下内容保存为 `.mcp.json` 在仓库根目录 — 它向您的代理公开了六种内存工具：
```json
{ "mcpServers": { "tremula": { "command": "tremula", "args": ["serve"] } } }
```
**6 · 添加环境循环** *(可选，推荐)*
将 `examples/claude-settings.json` 复制到 `.claude/settings.json`。每个钩子都运行 `tremula hook <Event>`；它们一起捕获会话，注入索引，附加相关笔记，并在后台蒸馏持久知识。
重启会话，并在提示时批准服务器 + 钩子。（使用 `TREMULA_HOOKS_DISABLED=1` 静音环境循环。）
### 或者询问您的代理
将以下内容粘贴到 Claude Code（或任何具有 shell 访问权限的代理）中，进入您的项目：
> 在此处设置 Tremula 代码内存。 使用 `uv tool install tremula-mcp` 安装它。 **在运行任何写入操作之前，请向我询问三个问题并等待我的答案：**
> 1. **项目密钥** — 默认是此目录的名称（`<dir>`）。如果目录名称通用，建议一个稳定的、明确的密钥（例如 `webapp_frontend` 而不是 `frontend`）。
> 2. **引导模式** — 我应该如何播种保险库？提供这三个并根据仓库大小推荐一个：
> - **简要** — 整个仓库，零 LLM 存根（文档字符串 + AST），即时，无需 API 密钥。默认最佳；蒸馏器在工作时丰富笔记。
> - **完整** — 整个仓库，每个模块一个 LLM 调用（更丰富，消耗调用和时间）。我会先显示调用计数并在运行前确认。
> - **部分** — 仅特定目录（例如 `src/`、`app/`），简要或完整。建议用于大型仓库或多模块仓库。
> 3. **忽略** — 通过两种方式收集构建输出目录候选：读取已声明的忽略文件（`.gitignore`、`.dockerignore`、`.npmignore`、`.eslintignore`，...）以获取已声明的目录，并扫描树以获取通用目录（`.next`、`.sst`、`.open-next`、`dist`、`build`、`coverage`）。删除那些已经被默认覆盖的目录，显示其余的并在写入仓库根目录的 `.tremulaignore`（每行一个目录名称）之前确认。这会将生成的档案排除在保险库之外。
>
> 然后，使用我的答案：运行 `tremula registry init`（如果我选择自定义密钥，请添加 `--name <key>`），然后在选择的模式下引导 — `tremula bootstrap --brief`（简要），`tremula bootstrap`（完整，在我确认调用计数后），或 `tremula bootstrap [--brief] <dirs>`（部分）。创建 `.mcp.json` 注册一个名为 `tremula` 的 MCP 服务器，stdio 命令为 `tremula serve`（添加一个 `env.TREMULA_PROJECT` 设置为我的密钥，如果它与目录名称不同）。在 `.claude/settings.json` 中添加钩子，运行 `tremula hook <Event>` 以获取 SessionStart、UserPromptSubmit、PostToolUse、Stop、PreCompact 和 SessionEnd。最后，显示生成的保险库笔记计数，并要求我重启会话。
在 Obsidian 中打开 `tremula-vault/` 以获取图形视图。机器编写的笔记在 `_index.md` 的自动部分排队；将链接移动到您的精选标题中会支持它。
如果您使用的是源代码检出？`git clone … && uv sync`，然后使用 `uv run tremula …` 并将 `.mcp.json`/钩子命令指向 `.venv/bin/tremula`（此仓库的 `.mcp.json` 显示模式）。
## 选择模型提供者
引导（完整模式）和后台蒸馏器需要一个 LLM。Tremula 是 **代理无关的** ，并且带有 no 供应商默认值 — 在 `~/.tremula/config.yaml` 中设置 `provider`:
```yaml
# 默认：自动检测 PATH 上的代理 CLI（claude / gemini / codex / ...）并外壳到它。无需 API 密钥。如果安装了多个，请使用 `agent` 固定一个。
provider:
kind: auto
# agent: claude # 可选：固定多个 CLI 存在时
```
`auto` 不需要密钥 — 它使用您的已安装 CLI 已经认证的内容。只有 `kind: anthropic` 读取 `auth_env`。`bootstrap --brief` **零** LLM 调用，因此它根本不需要提供者。
## 客户端支持
服务器通过 stdio 讲标准 MCP — Claude Code、Cursor、Codex、Gemini CLI 或任何其他讲 MCP 的客户端。环境循环为 Claude Code 的钩子生命周期提供服务；任何可以通过生命周期事件运行命令的主机都可以驱动相同的 `tremula hook <event>` CLI。
## 状态
核心完整且自我维持：此仓库的保险库由 Tremula 维持，大约四分之三的笔记由系统编写，系统正在编写。
路线图：混合语义搜索（sqlite-vec）· 长寿命 HTTP 守护进程 · 本机文件监视器。
## 开发
```bash
uv sync --extra dev
uv run pytest # TREMULA_LIVE_TESTS=1 uv run pytest -m live 进行真实 LLM 测试
uv run ruff check src tests
```
MIT.
