pond

pond

“我们之前明明讨论过。为什么我找不到那段该死的对话？”

Pond 会将你运行过的所有 AI Agent 会话——Claude Code、Codex、任何工具、任何机器上的会话——汇集到一处，供你搜索。

你的 Agent 历史记录已经在磁盘上：数千个会话，包含各种决策、修复和走过的弯路，却散落在无法搜索的各类工具中。Pond 会自动、无损地将它们全部导入你拥有的存储空间（本地目录或你自己的 S3 存储桶），让整个语料库都可搜索并支持 SQL 查询，再通过 MCP 将这些回忆交还给你的 Agent——于是，“以前是怎么修复这个问题的？”变成了一个查询，而不是一场考古挖掘。会话不再被锁定在创建它的工具中：任何会话都可以恢复到任意受支持的客户端中，并在那里继续使用。

brew install tenequm/tap/pond   # macOS / Linux

scoop bucket add tenequm https://github.com/tenequm/scoop-bucket   # Windows
scoop install tenequm/pond

或者向你的 Agent 提示：“请安装并设置 pond（参见 github.com/tenequm/pond）”——这条提示词的完整防错版本见连接你的 Agent。

_{包含 1.2 万个会话的实时语料库，随后找出一项三个月前的修复，并根据当前代码验证（更清晰的 MP4）}

_{五个真实的回忆查询、一个语料库、一台机器——方法、原始数据和可重新运行的脚本见 docs/benchmarks}

状态：v1 前版本。在 v1 发布前，架构、线缆格式和配置键都可能发生不兼容变更。完整文档见 pond.locker；规范见 docs/spec.md。

快速入门

安装、运行引导式设置，并导入本地会话：

brew install tenequm/tap/pond   # macOS / Linux; Windows: Scoop or a release zip - see Install below
pond init   # guided setup: storage, adapters, MCP + agent skill, optional schedule
pond sync   # ingest and index - every enabled adapter

pond init 会将 pond 注册为 Claude Code 的 MCP 服务，并安装内置的 pond 技能；对于 Codex，它会改为打印需要运行的命令——之后请重启客户端，让工具加载。手动操作：claude mcp add -s user pond -- pond mcp、codex mcp add pond -- pond mcp；技能：mkdir -p ~/.claude/skills/pond && pond skill > ~/.claude/skills/pond/SKILL.md（整行命令仅适用于 POSIX——mkdir -p、&& 和 > 在 Windows PowerShell 5.1 中都会失效或造成损坏；请使用连接你的 Agent中的 PowerShell 代码块）。然后向你的 Agent 提问——以下是日常使用中的真实提示词：

check in pond how we solved this before, then apply the same fix here

where we left off yesterday - check pond, then continue

are you sure that won't break X? check in pond how we struggled with exactly this

会话会自动从 Claude Code、Claude 桌面应用（本地 Agent 模式）、Codex CLI、opencode、pi-coding-agent、oh-my-pi、OpenClaw、NanoClaw、Hermes Agent、letta-code、grok-build、Antigravity CLI（agy，包括其 ACP 服务）和 Devin CLI（devin）中获取。Claude.ai 数据导出可通过 pond sync claude-ai-export --path <path> 导入（需手动下载，因此不会自动发现）。

这不又是一个记忆工具吗？

不是——它是记忆工具底层的一层。记忆工具会存储它们认为你需要的内容——事实、摘要、归档的片段；会话本身则不复存在。Pond 会保留会话：每条消息、工具调用和结果，完整无缺，跨客户端存储在你拥有的存储空间中，永不清理——可通过 MCP 搜索，也可恢复到任意客户端。记忆是一个可随时从档案重建的衍生视图；档案则永远无法从记忆重建。

有三类工具会被称为“记忆”工具。并列对比如下：

	pond	会话搜索（ctx、deja-vu、cass）	记忆层（Mem0、Letta）
安装前的历史记录	有	有	无
保留的内容	整个会话	搜索索引 ¹	提取出的事实
存储位置	本地目录或 S3 存储桶	本地索引	工具的数据库
框架删除文件后	仍然存在	下次刷新时消失 ¹	仅保留提取内容
多台机器	一个共享存储桶	拉取到一台机器 ²	共享服务或云端
Agent 访问方式	CLI、MCP、HTTP、SQL	CLI、MCP ³	HTTP、SDK、MCP

¹ cass 也会镜像原始文件，因此这些文件会在源文件之后继续保留。² deja-vu 会通过 ssh 在机器间复制记录；cass 会通过 ssh/rsync 将其他主机的会话文件拉取到本地索引中；ctx 仅支持单机。³ cass 没有 MCP 服务。

想要快速进行本地回忆，请选择会话搜索。当你希望 Agent 保存提炼出的事实，而不是记录本身时，请选择记忆层。当你希望保留会话本身，存储在你拥有的空间中，并涵盖你使用的每台机器时，请选择 pond。

完整对比以及各工具的依据：pond.locker/compare。每个单元格的内容都是针对其他项目特定版本的声明。如果某项内容已经过时，提交 issue，当天就会修正。

背景

每种 Agent CLI 都有自己的会话格式和搜索界面。切换工具意味着丢失历史记录。在其他提供商的工具中重放 Claude Code 会话，则意味着要手动重新转换线缆格式。托管式多租户部署还得从头重建相同的存储层。

Pond 是底层的存储和检索层。每个适配器都是客户端格式与某个规范模式之间的双向编解码器，因此任何适配器都能还原任意会话——不必回到生成该会话的客户端。存储、搜索（默认采用 BM25 全文搜索，可选语义搜索，每次查询使用一个搜索分支）以及与提供商无关的重放，都基于单一的 Lance 对象存储基础设施。

v1 的功能包括：完整 CLI、HTTP+JSON 和 MCP 传输协议、基于三个 Lance 数据集的搜索、可选择启用的 intfloat/multilingual-e5-small FP16 权重嵌入（macOS 上使用 Metal，可选择启用 CUDA，并提供 CPU 回退），以及通过 Lance 的 object_store 集成支持本地文件系统、S3、GCS 和 Azure 后端。

安装

支持 Linux、macOS 和 Windows。

macOS 和 Linux：

brew install tenequm/tap/pond              # Homebrew
nix profile add github:tenequm/pond#pond   # Nix

Windows（Scoop 是主要安装渠道，也会提供 pondw.exe，这是供计划同步任务运行的无窗口启动器）：

scoop bucket add tenequm https://github.com/tenequm/scoop-bucket
scoop install tenequm/pond

存储桶是 git 克隆，因此第一行命令需要在 PATH 中找到 git——如果失败并提示 “Git is required for buckets”，请运行 scoop install git，然后重试。

还没有 Scoop？请先在普通（非管理员）PowerShell 中安装（其安装程序会拒绝在提升权限的 shell 中运行）：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
irm get.scoop.sh | iex

然后打开一个新终端——PATH 的更改只会影响安装后启动的进程。关于 Defender、长路径、计划任务和 WSL，请参阅 Windows 说明。

**没有包管理器（适用于任何平台）：**每个发行版都会附带预构建二进制文件（Windows 上为 pond-x86_64-pc-windows-msvc.zip，解压后约 223 MB）——解压并将其目录添加到 PATH 即可（Windows 上：设置 > 系统 > 关于 > 高级系统设置 > 环境变量，在用户变量下添加），无需安装其他内容。

通过 cargo 安装（适用于任何平台，需要 Rust 工具链）：

cargo binstall pond-db   # downloads the prebuilt binary (needs cargo-binstall)
cargo install pond-db    # builds from crates.io (installs the `pond` command)

这两种方式都只会安装 pond.exe，因此 Windows 上的计划同步任务（通过 pondw.exe 运行）应使用 Scoop 或 zip 安装方式（或者在源码构建时添加 --features windows-launcher）。cargo install 还需要下文列出的 protoc 和 NASM 先决条件。

从源码构建：

git clone https://github.com/tenequm/pond.git
cd pond
cargo install --path packages/pond

在 Windows 上，克隆仓库前需要先运行 git config --global core.longpaths true（测试夹具路径超过 260 个字符），并且构建时需要明确指定 --target x86_64-pc-windows-msvc——否则 cargo 会将仓库的 +crt-static 标志也应用到构建脚本和过程宏，导致它们无法加载。

在 Linux 上启用 CUDA 加速：

cargo install --path packages/pond --features cuda

在 macOS 上会自动选择 Metal 后端；其他系统无需额外功能即可使用 CPU 回退。若在 Windows 上从源码构建，还需要在 PATH 中安装 protoc（winget install Google.Protobuf）和 NASM（winget install NASM.NASM，然后自行将 C:\Program Files\NASM 添加到 PATH——其安装程序不会自动添加）。

如果任何安装方式失败，请参阅故障排除指南，了解常见问题的解决方法。

用法

同步和搜索

一次性设置存储、适配器、MCP 注册和可选的同步计划（操作幂等——可随时重新运行以修复或更新）：

pond init

然后从本地适配器导入会话、更新索引并进行搜索：

pond sync
pond search "how did we wire up the OCC retry loop"

运行服务

pond serve                         # HTTP on 127.0.0.1:9797
pond serve --transport stdio       # MCP over stdio
pond mcp                           # alias for stdio MCP

获取和复制

获取单个会话或消息，或迁移整个语料库：

pond get-session <id>
pond get-message <id>
pond copy --from local --to snapshot.pond
pond copy --from snapshot.pond --to local

只读 SQL

使用只读 SQL 查询结构化信息（与 pond_sql MCP 工具提供的接口相同）：

pond sql "SELECT project, count(*) FROM messages GROUP BY project ORDER BY 2 DESC"

维护

按需执行维护（每次同步都会合并索引）：

pond optimize --only embed   # only when [embeddings].enabled = true
pond optimize --only index

定时同步

自动保持 pond 更新（macOS 上使用 launchd，Linux 上使用 systemd 用户定时器或 cron，Windows 上使用任务计划程序——在 Windows 上，请从普通 shell 运行，而不是以提升的权限运行，否则任务会归 Administrators 所有）：

pond schedule start                # every 5m by default (--every 15m|1h|6h|1d)
pond schedule status
pond schedule logs

状态与内省

pond status 会打印每个表的存储情况表格，接着显示 indexes（文本索引就绪状态；仅在启用嵌入时显示语义索引部分）、stored（会话 + 消息）、agents（存储中的源 Agent），以及此主机对存储的视图：每个适配器待同步的会话数、上次同步的结果（包括定时运行中出现并报告的故障），以及下次定时运行的时间。pond status --hosts 会按摄取主机拆分共享存储；--include-subagents 会将每个子 Agent 计为独立 Agent。pond sync --dry-run 可预览下次同步将读取的内容。pond search --explain 会为每个检索分支返回 Lance 的 analyze_plan 输出。

远程存储

默认情况下，pond 会将数据存储在本地的 ~/.local/share/pond（Windows 上为 %LOCALAPPDATA%\pond\data）。要使用对象存储，请添加凭据并切换目标位置：

pond creds add                                                    # interactive: name, access key, hidden secret
pond storage use s3+https://nbg1.your-objectstorage.com/my-pond   # probe end-to-end, then flip [storage].path
pond storage check                                                # verify: parse, creds, conditional-put (OCC), write/read/delete

pond init --storage-path <url> 可在设置期间配置远程目标位置；如果目标位置是远程存储，还会提示你直接输入凭据，因此只需一条命令即可配置存储桶。s3+https://host/bucket 形式适用于任何兼容 S3 的存储（Hetzner、R2、B2、MinIO）；如果没有匹配的 [creds.*] 配置，s3://、gs:// 和 az:// 会使用标准云 SDK 凭据链。pond copy --from <local> --to <url> 可将现有本地数据迁移到存储桶——此操作具备幂等性，不会删除源数据，并会在完成后重建目标索引并验证每一行都已写入（如果有任何数据缺失或重复，则退出码为 6，因此无需手动协调）。pond copy --verify-only --from <local> --to <url> 会执行相同的检查，但以只读方式运行，不进行复制。完整操作指南：pond.locker。

配置

pond init 会以交互方式引导你完成以下所有配置，并启用它找到的适配器。pond sync 只会摄取已启用的适配器——启用适配器需要明确执行此步骤（pond adapters enable / pond adapters discover / pond init），绝不会作为同步的副作用。macOS 和 Linux 上的配置位于 ~/.config/pond/config.toml，Windows 上则位于 %APPDATA%\pond\config.toml（运行 pond config path 可查看路径）。每个 [adapters.<name>] 配置块都必须包含 enabled = true 才会生效；没有此项（或设置为 enabled = false）的配置段会被跳过。所有平台上的路径都会展开 ~（Windows 上为 %USERPROFILE%）。

[adapters.claude-code]
enabled = true
path = "~/.claude/projects"

[adapters.codex-cli]
enabled = false                    # kept in config, skipped on `pond sync`
path = "~/.codex/sessions"

默认使用 BM25 全文搜索。语义搜索为可选功能，除非你主动启用，否则默认关闭：关闭时，任何 pond 进程都不会下载或加载嵌入模型，新消息不会生成向量，并且会拒绝 --mode vector。在配置中启用，或设置 POND_EMBEDDINGS_ENABLED=true，然后运行一次 pond optimize --only embed 来处理积压内容：

[embeddings]
enabled = true

完整说明（包括相关成本以及混合部署环境的运行方式）请参阅配置参考。

支持的运行环境

每种运行环境对应一个适配器，顺序与 pond adapters 的发现顺序一致；Reads 是 pond init 发现并写入 [adapters.<name>].path 的路径——此处以 POSIX 格式显示，Windows 上的主目录相对布局相同（~/.claude/projects 对应 %USERPROFILE%\.claude\projects）。Last verified 是该适配器已提交测试样例（packages/pond/tests/fixtures/adapter/）最近一次采集或刷新的日期；映射会针对这套测试语料进行测试。适配器按尽力原则维护，格式变更在设计上不会造成问题：未知记录形状仍会无损导入，格式错误的输入则会抛出注明文件名的类型化错误。添加运行环境是常规工作——请参阅贡献。

适配器	读取内容	最近验证日期
claude-code	Claude Code CLI，~/.claude/projects	2026-08-14
claude-desktop-app	Claude Desktop / Cowork 本地 Agent 会话	2026-05-13
claude-ai-export	claude.ai 数据导出存档（手动指定 --path）	2026-06-04
codex-cli	OpenAI Codex CLI，~/.codex/sessions	2026-09-01
opencode	opencode，~/.local/share/opencode（opencode.db：1.x 表和 OpenCode 2 的 session_v2 存储，以及旧版 JSON 目录树）	2026-10-12
openclaw	openclaw，~/.openclaw	2026-05-13
nanoclaw	nanoclaw，~/nanoclaw（包含 data/v2-sessions 的安装根目录）	2026-05-14
hermes	Hermes Agent，~/.hermes（每个配置文件对应一个 state.db）	2026-07-23
pi-coding-agent	pi，~/.pi/agent/sessions	2026-08-06
oh-my-pi	oh-my-pi，~/.omp/agent/sessions（仅导入）	2026-08-14
letta-code	letta-code，~/.letta/transcripts（通过 LETTA_TRANSCRIPT_ROOT 重定位的根目录会配置为显式的 path）	2026-08-24
grok-build	grok-build（xAI 的 grok CLI），~/.grok/sessions（通过 GROK_HOME 重定位的目录会配置为显式的 path）	2026-08-24
agy	Antigravity CLI 及其 ACP 服务，~/.gemini（包含 antigravity-cli/ 和 antigravity-acp/；通过 GEMINI_HOME 重定位的目录会配置为显式的 path；仅导入）	2026-09-10
devin	Devin CLI（Cognition 的 devin），~/.local/share/devin/cli（sessions.db；Windows 上为 %APPDATA%\devin\cli；通过 XDG_DATA_HOME 重定位的目录会配置为显式的 path；仅导入）	2026-09-26

详细程度

根级 -v / -vv / -vvv 会提高跟踪级别（info / debug / trace）；-q / -qq 会降低级别。默认情况下只显示警告。设置 RUST_LOG 后，它会覆盖 CLI 标志；不再支持 POND_LOG。

设计

完整约定见 docs/spec.md。主要设计选择：

• 直接使用 Lance，不加包装层。 lance-format/lance crate 是唯一的存储和搜索引擎。不使用 lancedb，也不引入并行抽象。存储、索引、OCC、模式演进、Blob 列、版本控制和时间旅行都由 Lance 实现。只读的 pond sql 接口是在相同 Lance 数据集上进行 DataFusion 规划的查询出口，而不是第二套引擎。
• 规范的 Session / Message / Part 中间表示。 由 pond 持有，结构采用 Effect v4 的 Prompt 侧 Part 联合类型。此模式是 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 会将索引结果与未建立索引片段的全表扫描结果合并，因此读取仍然正确。
• 单路检索。 每次查询只运行一种检索器——fts（BM25，默认选项）或 vector（余弦相似度，并辅以温和的近期性次级排序；仅在启用嵌入时提供）——按查询选择；服务端不做结果融合。--sort-by recency 按时间倒序返回结果。结果按 session_root 分组，每个会话返回一条摘要。
• 语言无关的全文检索。 使用词级别的 simple 分词器，并启用英语词干提取（ASCII 折叠）；词干提取器无法识别的词会原样保留，仍可精确匹配，因此 pond 对所有语言的会话一视同仁地建立索引。
• 两种传输方式，共用一组处理器。 HTTP+JSON（axum）和 MCP（rmcp）都会分发到相同的处理器。传输操作包括：pond_search、pond_get_session、pond_get_message、pond_ingest。MCP 还会额外提供只读的 pond_sql 工具，以及 schema://pond、schema://pond-sql 和 stats://pond 资源。
• 不透明字符串多租户。 每个租户由集成方提供的 namespace 字符串标识；pond 不负责身份验证、授权或身份建模。对象存储的 IAM 构成存储边界。
• 加密属于运维范畴。 使用存储桶 SSE 和文件系统加密；pond 不持有密钥，也不添加应用层加密。

路线图

pond 分步小步发布。下表按顺序列出了各步骤。已完成的步骤仍会保留在表中。路线图看板列出了相同事项及其 issue。在 issue 上点赞或评论，可以影响排序。

#	步骤	状态
1	将 Claude Code 和 Codex 的数据无损导入 Lance，支持本地或 S3	✅ v0.5
2	单路搜索：BM25 或向量，每次查询使用一路	✅ v0.10
3	在一分钟内完成远程同步；热搜索在一秒内完成	✅ v0.11-v0.12
4	工具调用列，以及针对语料库的只读 SQL	✅ v0.13
5	崩溃安全的本地存储，打开时可自我修复	✅ v0.14.0
6	十一种运行环境、pond resume 可接入任意客户端、MCP 注册表、Windows	✅ v0.14.11
7	BM25 成为默认搜索路。嵌入改为可选。#164	✅ v0.15.0
8	新适配器成为常规项目：pond-add-adapter 操作手册 + 一致性测试框架 #172、letta-code #170、grok CLI #171——十二种运行环境	✅ v0.15.1
9	Lance 10，然后是 11：计数下推、日期筛选 zonemap、词干提取器自我修复。#145	✅ v0.16.0-v0.17.0
10	pond erase：唯一获准的删除方式。#45	⏭ 下一步
11	远程读取速度与本地读取一样快。#165	⏳ 之后
12	命名空间：将工作会话和个人会话分开。#166	🔧 进行中（设计）
13	在复制、导出和恢复会话时进行脱敏。导入时绝不脱敏。#167	⏳ 之后
14	herdr 插件：在任意机器上，将所有会话（无论是否在线）显示在一个列表中。恢复、分叉、交接。#219	⏳ 之后
	将规范模型作为已发布的契约：ATIF 导出与导入、/format 页面、稳定性承诺。由投票决定是否推进，不纳入编号顺序。#180	🔧 进行中
	社区适配器：需要支持九种运行环境，由操作手册驱动——Qwen Code、Crush、Cline、OpenHands、Copilot CLI、Cursor CLI、Droid、Kiro CLI、Roo/Zoo Code。adapter issues	🙋 期待贡献
	捕获守护进程。pond 读取运行环境已写入的内容。	❌ 暂无计划
	由服务托管你的存储桶的托管服务。你的存储仍归你所有。	❌ 暂无计划
	对已存储会话进行摘要或裁剪。pond 会保留会话。	❌ 暂无计划

步骤 7 基于数据得出。在 63 天内，Agent 对该存档进行了 1,126 次搜索。BM25 有 61% 的几率找到答案，向量搜索则为 37%。请阅读测量结果。

这只是发展方向，并非承诺。数据变化时，顺序也会随之调整。

参考资料

塑造 pond 规范模型的上游架构记录在 docs/references/ 中（源 URL + 各自的重要性；不会重新分发引入的代码）。真实会话记录位于 packages/pond/tests/fixtures/adapter/ 下。

来源	重要性
Effect-TS/effect	Effect v4 Prompt/Response Part 联合类型。Pond 的规范类型采用了这一结构。
sst/opencode	Effect Schema 规范 Part 联合类型；SDK 类型；存储架构。
kilo-org/kilocode	OpenCode 分支。新增 editorContext、计划后续跟进和 kilocode 专属事件。
badlogic/pi-mono	pi-coding-agent 的叶子游标分支，以及跨提供商一致性测试矩阵。
open-telemetry/semantic-conventions-genai	GenAI 语义约定。为结构重叠提供灵感；pond 并非基于 OTel 衍生而来。
packages/pond/tests/fixtures/adapter/	十五种源运行环境的会话样本（agy、claude_ai_export、claude_code、claude_desktop_app、claude_managed_agents、codex_cli、devin、grok-build、hermes、letta-code、nanoclaw、oh-my-pi、openclaw、opencode、pi-coding-agent；除合成的 hermes state.db 和生成的 oh-my-pi 语料外，均为真实记录）。这些样本用于指导适配器设计，并作为适配器测试夹具。

贡献

欢迎提交问题和拉取请求。目前最有帮助的贡献包括：

• 为 pond 尚未支持的运行环境编写适配器。操作指南见 pond-add-adapter skill；PR 要求见 CONTRIBUTING.md。
• 对 docs/spec.md 提供规范反馈。
• 提供值得记录在 docs/references/ 下的其他参考架构或会话样本。
• 针对 v1 接口的问题报告（CLI 动词、线协议操作、架构不匹配、OCC 行为、对象存储后端）。

如需进行更大型的工作，请查看路线图。开始前请先在问题中留言，以便我们就范围达成一致。其他较大的改动，请先提出问题讨论方向。安全问题请参阅 SECURITY.md。

有问题或反馈？请发起 GitHub Discussion，或通过 Telegram 或 X 私信我——我会亲自回复。

链接

• 文档：pond.locker
• Crate：pond-db on crates.io
• MCP Registry 名称：mcp-name: io.github.tenequm/pond

许可证

Apache-2.0 (c) 2026 tenequm