内容
<p align="center">
<img src="docs/site/assets/logo.png" alt="pond" width="200">
</p>
# 工具列表
[](https://github.com/tenequm/pond/actions/workflows/ci.yml)
[](https://crates.io/crates/pond-db)
[](https://pond.locker/)
[](LICENSE)
无损存储和搜索 AI 代理会话，适用于所有 AI 客户端。
**快速入门。** 安装，运行引导设置，并导入本地会话：
```sh
brew install tenequm/tap/pond
pond init # 引导设置：存储、适配器、MCP 注册、选定调度
pond sync # 导入、嵌入、更新索引 - 每个启用的适配器
```
`pond init` 将 pond 注册为检测到的客户端的 MCP 服务器；手动添加：
```sh
claude mcp add -s user pond -- pond mcp # Claude Code
codex mcp add pond -- pond mcp # Codex
```
Pond 保留您曾经进行过的 AI 对话，并使其可搜索，让您可以继续在任何支持的工具中使用它们 - 您的历史记录、搜索和会话，与创建它们的代理供应商无关。它是一个 Rust 二进制文件，用于将注册的代理客户端适配器中的会话导入到规范的会话/消息/部分互操作语言中，将它们存储在对象存储上的 Lance 中，并通过 HTTP+JSON 和 MCP 提供搜索功能。有两种部署方式：本地笔记本电脑上的个人 pond，或用于托管代理基础设施的多租户后端。无需额外的数据库，无需围绕 Lance 的包装。
当前自动同步的代理客户端：
- Claude Code CLI
- Claude 桌面应用程序（本地代理模式）
- Codex CLI
- opencode CLI
- pi-coding-agent CLI
您还可以使用 `claude-ai-export` 适配器导入 Claude.ai 数据导出 - 需要手动下载，因此不会自动发现：`pond sync claude-ai-export --path <path>`。
状态：预 v1。架构、线路形状和配置键在 v1 之前可能会发生破坏性更改。完整文档位于 [pond.locker](https://pond.locker/)；合约位于 [`docs/spec.md`](docs/spec.md)。
## 背景
每个代理 CLI 都提供其自己的会话格式和搜索界面。切换工具意味着丢失历史记录。在另一个提供商的工具中重放 Claude Code 会话意味着手动重新转换线路形状。托管的多租户部署会从头开始重建相同的存储层。
Pond 是位于其下的存储和检索层。每个适配器都是客户端格式与规范模式之间的双向编解码器，因此任何会话都可以通过任何适配器恢复 - 不需要返回到生成它的客户端。存储、搜索（向量或 BM25 完整文本，一个臂每个查询）和提供者无关的重放都位于单个 Lance-on-object-storage 基础上。
v1 界面包括：完整的 CLI、HTTP+JSON 和 MCP 传输、三个 Lance 数据集上的搜索、`intfloat/multilingual-e5-small` 嵌入（FP16 权重，macOS 上的 Metal，CUDA 选择加入，CPU 故障转移），以及通过 Lance 的 `object_store` 集成实现本地 FS / S3 / GCS / Azure 后端。
## 安装
支持 Linux 和 macOS；Windows 不在 v1 范围内。
**包管理器（macOS 和 Linux）：**
```sh
brew install tenequm/tap/pond # Homebrew
nix profile add github:tenequm/pond-nix#pond # Nix
cargo install pond-db # crates.io（安装 `pond` 命令）
```
**从源代码构建：**
```sh
git clone https://github.com/tenequm/pond.git
cd pond
cargo install --path .
```
对于 Linux 上的 CUDA 加速：
```sh
cargo install --path . --features cuda
```
在 macOS 上，自动选择 Metal 后端；在其他系统上，CPU 故障转移在没有额外功能的情况下运行。
## 用法
在一次传递中设置存储、适配器、MCP 注册和可选的同步调度（幂等 - 随时重新运行以修复或更新）：
```sh
pond init
```
然后从本地适配器导入会话，嵌入它们，更新索引，并搜索：
```sh
pond sync
pond search "如何连接 OCC 重试循环"
```
运行服务器：
```sh
pond serve # HTTP on 127.0.0.1:9797
pond serve --transport stdio # MCP over stdio
pond mcp # stdio MCP 的别名
```
获取单个会话或消息，或移动整个语料库：
```sh
pond get --session-id <id>
pond copy --from local --to snapshot.pond
pond copy --from snapshot.pond --to local
```
使用只读 SQL 提问（与 `pond_sql_query` MCP 工具相同的界面）：
```sh
pond sql "SELECT project, count(*) FROM messages GROUP BY project ORDER BY 2 DESC"
```
按需运行维护（同步已经内联嵌入和折叠索引）：
```sh
pond optimize --only embed
pond optimize --only index
```
自动保持 pond 更新（macOS 上的 launchd，Linux 上的 systemd 用户计时器或 cron）：
```sh
pond schedule start # 默认每 5 分钟一次（--every 15m|1h|6h|1d）
pond schedule status
pond schedule logs
```
`pond status` 打印每个表的存储表，然后是 `indexes`（文本/语义准备度），`stored`（会话 + 可搜索消息）和 `adapters`（配置的适配器计数）。传递 `--adapters` 以获取每个项目表和每个意图索引的详细信息。`pond search --explain` 为每个检索臂返回 Lance 的 `analyze_plan` 输出。
### 远程存储
默认情况下，pond 将数据存储在 `$XDG_DATA_HOME/pond` 下。要使用对象存储，请添加凭证并切换目标：
```sh
pond creds add # 交互式：名称，访问密钥，隐藏秘密
pond storage use s3+https://nbg1.your-objectstorage.com/my-pond # 探测端到端，然后翻转 [storage].path
pond storage check # 验证：解析，凭证，条件放入（OCC），写入/读取/删除
```
`pond init --storage-path <url>` 在设置期间配置远程目标，并在目标为远程时内联提示凭证，因此存储桶是一个命令。`s3+https://host/bucket` 形式适用于任何 S3 兼容存储（Hetzner，R2，B2，MinIO）；`s3://`，`gs://` 和 `az://` 在没有匹配的 `[creds.*]` 集的情况下使用标准云 SDK 凭证链。`pond copy --from <local> --to <url>` 将现有本地数据带入存储桶 - 幂等，永不删除源，并在完成后重建目标索引并验证每个行着陆（如果有任何行丢失或重复，则退出 6，因此您永远不会手动协调）。`pond copy --verify-only --from <local> --to <url>` 只读运行相同的检查，无需复制。完整演练：[pond.locker](https://pond.locker/)。
### 配置
`pond init` 交互式地完成以下所有操作，并启用它找到的适配器。`pond sync` 仅导入已启用的适配器 - 启用一个适配器是一个明确的步骤（`pond adapters enable` / `pond adapters discover` / `pond init`），而不会成为同步的副作用。配置位于 `$XDG_CONFIG_HOME/pond/` 下。每个 `[adapters.<name>]` 块需要 `enabled = true` 才能激活；没有它的部分（或 `enabled = false`）将被跳过。
```toml
[adapters.claude-code]
enabled = true
path = "~/.claude/projects"
[adapters.codex-cli]
enabled = false # 保留在配置中，在 `pond sync` 上跳过
path = "~/.codex/sessions"
```
### 详细程度
根级 `-v` / `-vv` / `-vvv` 提高跟踪级别（信息 / 调试 / 跟踪）；`-q` / `-qq` 降低它。默认情况下只显示警告。`RUST_LOG` 在设置时覆盖 CLI 标志；`POND_LOG` 不再受支持。
## 设计
完整合约在 [`docs/spec.md`](docs/spec.md) 中。关键选择：
- **Lance 直接，无包装。** `lance-format/lance` 包是唯一的存储和搜索引擎。没有 `lancedb`，没有并行抽象。存储、索引、OCC、模式演化、blob 列、版本控制和时间旅行都是 Lance。只读 `pond sql` 接口是 DataFusion 在相同 Lance 数据集上的规划 - 一个查询出口，而不是第二个引擎。
- **规范会话/消息/部分互操作语言。** 由 pond 拥有，形状为 Effect v4 的 `Prompt` 端部分联合。此模式是 pond 的产品；其他一切都是围绕它的机制。
- **三个 Lance 数据集**（`sessions`，`messages`，`parts`）。`messages` 携带可为空的嵌入（`vector` + `embedding_model`）以及反归一化筛选列（`source_agent` / `project` / `role` / `timestamp`）以进行单阶段筛选下推。
- **无合成适配器缝隙。** 适配器通过提取器助手解析源记录，使“发明值”成为编译错误 - `model-no-synthesis`，`model-schema-honesty` 和 `adapter-provenance-required` 是结构性的，而不是审查规则。
- **索引生命周期与写入解耦。** 写入提交数据（包括内联计算的嵌入），而不会折叠搜索索引。`pond sync` 默认运行索引维护，`pond optimize --only index` 按需运行；Lance 将索引结果与未索引片段的平面扫描合并，因此读取保持正确。
- **单臂检索。** 每个查询运行一个检索器 - `vector`（余弦，带有轻微的最近时间打破者）或 `fts`（BM25）- 按查询选择；无服务端融合。向量臂在存储没有嵌入时回退到全文搜索，而 `--sort-by recency` 返回最新优先。结果分组到每个会话的一个摘要，按 `session_root` 键入。
- **语言中立的全文本搜索。** 带有英语词干（ascii-folding on）的字级 `simple` 分词器；词干识别失败的标记原样通过并保持精确匹配，以便 pond 索引会话的语言相同。
- **两个传输，一个处理程序集。** HTTP+JSON（axum）和 MCP（rmcp）都分派到相同的处理程序。线路操作：`pond_search`，`pond_get`，`pond_ingest`。MCP 还公开只读的 `pond_sql_query` 工具和 `schema://pond`，`schema://pond-sql` 和 `stats://pond` 资源。
- **不透明字符串多租户。** 每个租户都是集成商提供的 `namespace` 字符串；pond 不进行身份验证、授权或建模身份。对象存储的 IAM 是存储边界。
- **加密是操作性的。** 存储桶 SSE 加文件系统加密；pond 不持有密钥，不添加应用级加密。
## 参考
形成 pond 规范模型的上游模式在 [`docs/references/`](docs/references/) 中有文档记录（源 URL + 每个事项的原因；不重新分发 vendored 代码本身）。真正的会话捕获位于 `tests/fixtures/adapter/` 下。
| 源 | 原因 |
|--------|----------------|
| [Effect-TS/effect](https://github.com/Effect-TS/effect) | Effect v4 Prompt/Response 部分联合。Pond 的规范类型复制此形状。 |
| [sst/opencode](https://github.com/sst/opencode) | 效果模式规范部分联合；SDK 类型；存储模式。 |
| [kilo-org/kilocode](https://github.com/kilo-org/kilocode) | OpenCode 分叉。添加 `editorContext`，计划后续，kilocode 特定事件。 |
| [badlogic/pi-mono](https://github.com/badlogic/pi-mono) | pi-coding-agent 叶游标分支和跨提供者一致性测试矩阵。 |
| [open-telemetry/semantic-conventions-genai](https://github.com/open-telemetry/semantic-conventions) | GenAI 语义约定。为形状重叠提供灵感；pond 不源自 OTel。 |
| `tests/fixtures/adapter/` | 来自九个源工具的真实会话捕获（claude_ai_export, claude_code, claude_desktop_app, claude_managed_agents, codex_cli, nanoclaw, openclaw, opencode, pi-coding-agent）。驱动适配器设计并作为适配器测试夹具。 |
## 贡献
欢迎提出问题和拉取请求。现在最有用的贡献：
- 对 [`docs/spec.md`](docs/spec.md) 的规范反馈。
- 指向其他参考模式或值得记录的会话样本的指针，位于 `docs/references/` 下。
- 针对 v1 界面（CLI 动词、线路操作、模式不匹配、OCC 行为、对象存储后端）的错误报告。
对于较大的更改，请先打开一个问题来讨论方向。对于安全问题，请参阅 [SECURITY.md](.github/SECURITY.md)。
## 许可证
[Apache-2.0](LICENSE) (c) 2026 tenequm
