内容
# 乌龟 🐢
**忘记不相关的信息并协调一组代理** — 本地优先，基于 SQLite，无运行时依赖。
大多数内存层 **积累平面**：所有信息都具有相同的权重，并且随着时间的推移，会返回旧的和不相关的上下文。乌龟解决了另一个问题：**老化的记忆**（热 → 温 → 冷，修剪短暂信息，标记旧信息以供审查）**+ 多个代理之间的协调**。它是一个 **MCP 服务器** + 一个 **CLI**，用于编码 CLI（Claude Code、Cursor、Codex、Gemini CLI 等），基于本地 **SQLite**。单个二进制文件：无需 Node、无服务、无 API 密钥。您的数据不会离开您的机器。
---
## 使它与众不同
- 🧠 **老化记忆（几乎没有人这样做）**。记忆根据访问时间从 **热 → 温 → 冷** 转变；短暂信息被修剪；旧信息被标记为“在信任前需要验证”。与其积累所有信息，活动范围保持 **相关且小**。如果您的痛点是 *"我的记忆返回旧的和不相关的信息"*，乌龟从设计上解决了这个问题。
- 🤝 **协作平台，而不仅仅是一个笔记柜**。代理之间的消息总线/中继、活动订阅源和 **9 个代理**，具有 **可配置的任务模型**。记忆 **+ 团队**。
- 🪶 **本地优先且节省令牌**。两阶段恢复（廉价索引 → 按需内容；〜-66%，参见 *令牌节省*），令牌预算和快速 FTS5。无云，无密钥。
### 此外
- **具有历史的演化主题**（`topic_key` 带有 upsert + 版本：“我们对该主题的了解以及何时了解”）。
- **辅助合并** 重复项（乌龟建议，代理决定）。
- **上下文压缩生存**（专用检查点）。
- **技能层 + 人员** 内置二进制文件。
- **可移植性**：JSON 导出/导入和通过 git 片段同步（无合并冲突）。
- **可选语义搜索** 通过 Ollama 本地（`turtle semantic on`）；默认为 FTS，无依赖。
**多 CLI 设计**。乌龟是一个与 MCP 提供商无关的提供商：使用的 CLI 决定了模型（Claude Code → Claude，Codex → OpenAI，...）；乌龟不管理密钥或提供商。
---
## 令牌节省
这是乌龟的核心。 大多数内存层中“记住”的成本很高，因为它们会返回每次搜索中每个匹配项的 **完整内容**。 乌龟通过三个杠杆避免了这种情况：
**1. 两阶段恢复（主要）**。 `memory_search` 返回一个 **廉价的索引** — id、标题、摘要，无内容 — 并且您只使用 `memory_get` 检索少量内存的完整正文。
以实际数据为准（12 个结果，每个 ~580 个字符；`estimate_tokens = chars/4`）：
| 阶段 | 令牌（12 个结果） | 每个结果 |
| --- | ---: | ---: |
| **索引** （默认） | **600** | ~50 |
| 紧凑 （带摘录） | 1,452 | ~121 |
| 完整 （全文内容） | 1,767 | ~147 |
→ **-66%** 在第一击中。 在典型的回忆中（您搜索 12 个，打开 2 个）：`600 + 2×147 ≈ 894` tok vs `~1,767` 在单阶段内存层中 → **~50% 减少**，并且随着语料库的增长，差距越来越大。
**2. 工具配置文件**。 每个 MCP 服务器都将其工具模式注入上下文 **按次序**。 `turtle mcp --profile minimo` 仅暴露核心（6 个工具）而不是 30 个 → **~70% 减少** 每回合定义税。（默认设置为 `complete` 因为协议从协调开始。）
**3. 令牌预算和分级**。 记忆根据访问时间从热 → 温 → 冷转变，保持活动范围小；搜索 **根据令牌预算进行裁剪**，永远不会用完您的上下文。
---
## 可选语义搜索
默认情况下，乌龟使用 **FTS5** （快速、本地、零依赖）进行搜索，这足以满足大多数情况。 如果您还想要 **语义召回** （根据含义查找记忆，而不仅仅是单词），请运行以下命令：
```sh
turtle semantic on
```
这会检查 **[Ollama](https://ollama.com)** 是否正在运行，下载嵌入模型（`nomic-embed-text`，~270 MB，一次性）并生成您的记忆嵌入。 从那时起，搜索 **结合 FTS + 语义相似性** （RRF 融合）。 二进制文件 **不会** 增长：模型位于 Ollama 中，不在乌龟中。
```sh
turtle semantic status # 打开/关闭，模型，Ollama 是否响应，嵌入记忆
turtle semantic off # 返回 FTS（不删除已计算的嵌入）
```
**优雅降级**：如果 Ollama 未运行，搜索仍将使用 FTS 继续 - 永远不会中断。 而且，不启用语义功能的人不需要 Ollama 或任何额外的依赖。
---
## 安装
乌龟是一个 **单一二进制文件**。 您不需要 Rust 或编译器即可使用它。
### Homebrew（macOS / Linux）
```sh
brew install contactandrewchl-wq/tap/turtle
```
### Linux / macOS（单命令安装程序）
```sh
curl -fsSL https://raw.githubusercontent.com/contactandrewchl-wq/turtle-mcp/main/install.sh | sh
```
### Windows（PowerShell）
```powershell
irm https://raw.githubusercontent.com/contactandrewchl-wq/turtle-mcp/main/install.ps1 | iex
```
涵盖 Linux（x86-64 和 ARM64，静态编译的 musl）、macOS（Apple Silicon 和 Intel）和 Windows x86-64。安装程序下载最新 [Release](https://github.com/contactandrewchl-wq/turtle-mcp/releases) （v0.1.0）的二进制文件并将其放入您的 `PATH` 中。
### 从源代码编译（任何操作系统）
需要 Rust 工具链（[rustup](https://rustup.rs)）：
```sh
git clone https://github.com/contactandrewchl-wq/turtle-mcp
cd turtle-mcp
cargo install --path crates/turtle-cli --locked
```
**平台 C 编译器**：macOS → Xcode 命令行工具；Linux → `build-essential`；Windows → `stable-x86_64-pc-windows-gnu`（mingw，无 Visual Studio） **或** `-msvc`（带有 C++ 工作负载的 VS 构建工具）。
验证：在新终端中，`turtle --version`。
---
## 逐步启动
1. **安装**（上文）并检查：`turtle --version`。
2. **一次性安装所有 CLI** （注册 MCP，注入协议，安装人员和 **将捆绑的技能 + 9 名人员嵌入数据库**）：
```sh
turtle install # 菜单：检测已安装的客户端并选择
turtle install claude-code # 或直接按名称
```
支持 `claude-code`、`claude-desktop`、`cursor`、`windsurf`、`gemini-cli`、`codex` 和 `opencode`。
> `turtle install` = 播种捆绑包 **+** `turtle setup`。 如果您只使用 `turtle setup`（不播种），而 `turtle stats` 显示 **0 技能**，请运行 `turtle skills seed`。
3. **重启 CLI** 以启动 MCP 服务器。
4. **测试记忆**:
```sh
turtle guardar "我们使用 rmcp 作为 MCP" "乌龟通过 MCP 和 CLI 公开服务。" -t decision
turtle buscar rmcp
```
5. **诊断** （可选）：`turtle doctor`.
---
## 在您的客户端中注册并审查设置
`turtle install <客户端>` 播种技能/人员包，然后运行 `turtle setup`。
`turtle setup <客户端>` （无播种）执行三个操作，均 **幂等** （合并，不覆盖他人）：
- 在客户端配置中写入 MCP 服务器条目，带有二进制文件的 **绝对路径**。 相当于：
```json
{ "command": "turtle", "args": ["mcp"] }
```
- 将乌龟的使用协议注入客户端指令（在 Claude Code 中为 `~/.claude/CLAUDE.md`；在 Codex 中为 `~/.codex/AGENTS.md`；在 OpenCode 中为 `~/.config/opencode/AGENTS.md`），在一个标记和可替换的块中。
- 在 Claude Code 中，还安装 **9 名人员** 作为子代理（`~/.claude/agents/`）并连接会话钩子。
**事物存储位置：**
| 事物 | 存储位置 |
| --- | --- |
| 数据库（您的记忆） | 用户数据目录，或 `--db` / `$TURTLE_DB` |
| Claude Code 的 MCP 配置 | `~/.claude.json` |
| Codex 的 MCP 配置 | `~/.codex/config.toml` （表格 `[mcp_servers.turtle]`） |
| OpenCode 的 MCP 配置 | `~/.config/opencode/opencode.json` （对象 `mcp`，条目 `type: "local"`） |
| 人员模型覆盖 | `~/.turtle/models.conf` |
**审查/验证：**
```sh
turtle --version # PATH 中的二进制文件
turtle doctor # 模式、完整性、FTS 索引、重复项
turtle stats # 项目和类型计数
cat ~/.claude.json | grep -A2 turtle # 查看注册的 MCP 条目（Claude Code）
```
**从客户端卸载乌龟** （不删除您的记忆）：`turtle uninstall <客户端>`。
---
## 用法（CLI）
主要数据作为参数传递，**项目根据当前仓库/文件夹自动检测** （使用 `-p` 或 `$TURTLE_PROJECT` 覆盖）：
**记忆**
```sh
turtle guardar "MCP 服务器与 rmcp" "乌龟通过 MCP 和 CLI 公开服务。" -s "MCP + CLI"
turtle guardar "合同模式" "演化版本 2" --topic api/contract # 演化主题（upsert）
turtle buscar rmcp # 廉价索引； -g 在所有项目中搜索
turtle buscar rmcp -v 紧凑 # 詳細度：索引（默认）· 紧凑 · 完整
turtle ver <id> # 完整内容
turtle ctx 在 MCP 上工作 # 当前项目上下文
turtle guardar "规则" "..." -i pinned # 重要性：固定 / 正常 / 短暂
git log -1 | turtle guardar "最后提交" # 内容也通过 stdin 输入
```
**时间线和合并**
```sh
turtle 历史 <id> # 主题的较早版本（最新优先）
turtle 重复 # 建议重复的记忆进行合并（无 AI）
turtle 相关 <id_b> <id_a> duplicate # 替换 · 冲突 · 相关 · 重复
turtle 比较 <id_a> <id_b> # 内容对比，帮助决策
```
**会话和协调**
```sh
turtle 会话 启动 实现会话 -a 开发 # 显示初始上下文（增量）
turtle 会话 关闭 <id> # 自动总结已完成的内容
turtle 消息 "检查端点" -a 后端 --de 前端 # 有方向的转发
turtle 收件箱 后端 # 角色收件箱（待处理）
turtle 检查点 "我正在执行步骤 3/5" # 在压缩后生存
turtle 活动 # 代理活动订阅源
```
**人员模型** （Claude Code，根据您的订阅）：
```sh
turtle 模型 # 交互式菜单：选择人员和模型
turtle 模型 设置 donatello=opus brunelleschi=haiku # 直接设置
turtle 模型 重置 # 恢复默认模型
```
**技能、健康状况和可移植性**
```sh
turtle 技能 导入 # 导入技能/和人员/（项目 + ~/.claude）
turtle 技能 种子 # 加载嵌入包（21 技能 + 9 名人员）
turtle 医生 --修复 # 修复不同步的 FTS 索引
turtle 导出 --输出 backup.json # 开放的 JSON 备份；导入不会重复
turtle 同步 导出 .turtle/mem # 每个 <id>.json 的内存（在 git 中版本控制，无冲突）
```
---
## MCP 服务器
`turtle mcp` 通过 stdio 进行 MCP 通信；任何兼容的客户端都可以连接。公开 **30 种工具**，包括 `memory_save`、`memory_search`、`memory_get`、`memory_history`、`memory_duplicates`、`context_get`、`session_start`/`session_close`、`message_send`/`inbox`、`relation_add`、`skills_search`/`skill_get` 等等。具有项目的工具在省略时 **自动检测** 目录（或 `$TURTLE_PROJECT`）：
为了减少每回合的定义令牌消耗：`turtle mcp --profile minimo` （或 `TURTLE_MCP_PROFILE=minimo`）仅保留 6 个核心工具（~70% 减少）；`complete` （默认）公开 30 个工具。
### 状态栏（Claude Code）
`turtle statusline` 打印 git 分支 + 模型 + 预估令牌消耗。在 `~/.claude/settings.json` 中：
```json
{ "statusLine": { "type": "command", "command": "turtle statusline" } }
```
```
🐢 功能/旅行 · Sonnet 4.6 · 5 小时 15.3M tok · 语义 17.0M tok
```
### 会话钩子（自动存在）
`turtle setup claude-code` 连接两个钩子，以便乌龟无需请求即可存在：
- `turtle hook session-start` — 启动时，注入项目的最近记忆。
- `turtle hook prompt-submit` — 在响应之前，将相关记忆注入请求。
手动，在 `~/.claude/settings.json` 中：
```json
{
"hooks": {
"SessionStart": [{ "hooks": [{ "type": "command", "command": "turtle hook session-start" }] }],
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "turtle hook prompt-submit" }] }]
}
}
```
---
## 开发
需要 [rustup](https://rustup.rs)。本地验证：
```sh
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
```
结构：
```
crates/
turtle-core/ 域类型
turtle-data/ SQLite、迁移、FTS5
turtle-embed/ （可选存根）
turtle-usage/ 令牌消耗测量
turtle-service/ 用例（2 阶段恢复、合并）
turtle-mcp/ MCP 服务器
turtle-cli/ `turtle` 二进制文件
```
---
## 许可证
MIT - 见 [`LICENSE`](LICENSE)。
