pond

[pond]

pond

[CI] [crates.io] [docs] [License]

"I know we discussed that before. Why can't I find that damn conversation?"

Pond makes every AI agent session you've ever run - Claude Code, Codex, any tool, any machine - searchable in one place.

Your agent history is already on your disk: thousands of sessions full of decisions, fixes, and dead ends - scattered across tools that can't search them. Pond ingests them all automatically and losslessly into storage you own (a local dir or your own S3 bucket), makes the whole corpus searchable and SQL-queryable, and hands that recall back to your agents over MCP - so "how did we fix this before?" is a query, not an archaeology dig. Sessions stop being locked to the tool that created them: any session can be restored into any supported client and continued there.

brew install tenequm/tap/pond   # macOS / Linux
scoop bucket add tenequm https://github.com/tenequm/scoop-bucket   # Windowsscoop install tenequm/pond

Or prompt your agent: "Please install and set up pond (see github.com/tenequm/pond)" - the full, failure-proofed version of that prompt is in Connect your agents.

[A live pond corpus, then Claude Code answering a three-month-old debugging question from it]

_{A live 12k-session corpus, then a three-month-old fix found and verified against the current code (crisper MP4)}

[Bar chart: tokens into context for one recall answer. pond_search returns a complete ranked answer in 1.5-3k tokens; grep plus reading one matching transcript costs 90-255k tokens, chosen from 23-3,270 unranked matching files]

_{Five real recall questions, one corpus, one machine - method, raw numbers, and a rerunnable script in docs/benchmarks}

Status: pre-v1. Schemas, wire shapes, and config keys are subject to breaking change until v1. Full documentation lives at pond.locker; the contract is docs/spec.md.

Quickstart

Install, run guided setup, and ingest your local sessions:

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

pond init registers pond as an MCP server for Claude Code and installs the bundled pond skill; for Codex it prints the command to run instead - restart the client afterwards so the tools load. By hand: claude mcp add -s user pond -- pond mcp, codex mcp add pond -- pond mcp; skill: mkdir -p ~/.claude/skills/pond && pond skill > ~/.claude/skills/pond/SKILL.md (that whole line is POSIX-only - mkdir -p, &&, and > all break or corrupt in Windows PowerShell 5.1; use the PowerShell block in Connect your agents). Then ask your agent - real prompts from daily use:

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

Sessions are picked up automatically from Claude Code, the Claude desktop app (local agent mode), Codex CLI, opencode, pi-coding-agent, oh-my-pi, OpenClaw, NanoClaw, Hermes Agent, letta-code, grok-build, Antigravity CLI (agy, including its ACP server), and Devin CLI (devin). A Claude.ai data export imports with pond sync claude-ai-export --path <path> (manual download, so not auto-discovered).

Isn't this another memory tool?

No - it's the layer underneath one. Memory tools store what they decided you'd need - facts, summaries, filed chunks; the sessions themselves are gone. Pond keeps the sessions: every message, tool call, and result, value-complete, cross-client, in storage you own, never pruned - searchable over MCP and restorable into any client. Memory is a derived view you can always rebuild from an archive; an archive can never be rebuilt from memories.

Three kinds of tool get called "memory". Side by side:

¹ cass also mirrors the raw files, so they outlive the source. ² deja-vu copies records between machines over ssh; cass pulls other hosts' session files over ssh/rsync into its local index; ctx is single-machine. ³ cass has no MCP server.

Pick session search for fast local recall. Pick a memory layer when the agent should carry distilled facts, not the record. Pick pond when you want the sessions themselves, in storage you own, from every machine you run.

Full comparison, with receipts per tool: pond.locker/compare. Every cell is a claim about a specific version of someone else's project. If one has gone stale, open an issue and it gets fixed the same day.

Background

Every agentic CLI ships its own session format and its own search surface. Switching tools means losing history. Replaying a Claude Code session in another provider's tooling means re-translating the wire shape by hand. Hosted multi-tenant deployments rebuild the same storage layer from scratch.

Pond is the storage and retrieval layer that sits underneath. Every adapter is a bidirectional codec between a client format and one canonical schema, so any session can be restored by any adapter - it need not return to the client that produced it. Storage, search (BM25 full-text by default, with optional semantic search, one arm per query), and provider-agnostic replay all sit on a single Lance-on-object-storage foundation.

The v1 surface includes: full CLI, HTTP+JSON and MCP transports, search over three Lance datasets, opt-in intfloat/multilingual-e5-small embeddings at FP16 weights (Metal on macOS, CUDA opt-in, CPU fallback), and local-FS / S3 / GCS / Azure backends through Lance's object_store integration.

Install

Linux, macOS, and Windows are supported.

macOS and Linux:

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

Windows (Scoop, the primary channel - it also ships pondw.exe, the windowless launcher that scheduled sync runs through):

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

Buckets are git clones, so the first line needs git on PATH - if it fails with "Git is required for buckets", run scoop install git and retry.

No Scoop yet? Bootstrap it first, from a normal (non-admin) PowerShell (its installer refuses an elevated shell):

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

Then open a new terminal - PATH changes reach only processes started after the install. See the Windows notes for Defender, long paths, scheduling, and WSL.

No package manager (any platform): every release attaches prebuilt binaries (pond-x86_64-pc-windows-msvc.zip on Windows, ~223 MB unpacked) - unpack one and add its directory to PATH (on Windows: Settings > System > About > Advanced system settings > Environment Variables, under your user variables), nothing else to install.

Via cargo (any platform, needs the Rust toolchain):

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

Both install pond.exe only, so scheduled sync on Windows - which runs through pondw.exe - wants the Scoop or zip install instead (or --features windows-launcher on a source build). cargo install also needs the protoc and NASM prerequisites below.

Build from source:

git clone https://github.com/tenequm/pond.gitcd pondcargo install --path packages/pond

On Windows that clone needs git config --global core.longpaths true first (test-fixture paths exceed 260 characters), and the build needs an explicit --target x86_64-pc-windows-msvc - without it cargo applies the repo's +crt-static flag to build scripts and proc-macros too, which then fail to load.

For CUDA acceleration on Linux:

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

On macOS the Metal backend is selected automatically; on other systems the CPU fallback runs without extra features. Building from source on Windows additionally needs protoc (winget install Google.Protobuf) and NASM (winget install NASM.NASM, then add C:\Program Files\NASM to PATH yourself - its installer doesn't) on PATH.

If any install path fails, the Troubleshooting guide covers the common stalls.

Usage

Sync and search

Set up storage, adapters, MCP registration, and an optional sync schedule in one pass (idempotent - re-run it any time to repair or update):

pond init

Then import sessions from local adapters, update indexes, and search:

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

Run a server

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

Fetch and copy

Fetch a single session or message, or move a whole corpus:

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

Read-only SQL

Ask structured questions with read-only SQL (the same surface as the pond_sql MCP tool):

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

Maintenance

Run maintenance on demand (sync folds indexes on every run):

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

Scheduled sync

Keep pond current automatically (launchd on macOS, systemd user timers or cron on Linux, Task Scheduler on Windows - there, run it from a normal shell, not an elevated one, or the task ends up owned by Administrators):

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

Status and introspection

pond status prints a per-table storage table, then indexes (text readiness, plus the semantic half only when embeddings are enabled), stored (sessions + messages), agents (source agents in the store), and this host's view of it: per-adapter sessions pending sync, the last sync's outcome (including a surfaced failure from a scheduled run), and the next scheduled run. pond status --hosts breaks a shared store down by ingest host; --include-subagents counts each subagent as its own agent. pond sync --dry-run previews what the next sync would read. pond search --explain returns Lance's analyze_plan output for each retrieval arm.

Remote storage

By default pond stores data locally under ~/.local/share/pond (%LOCALAPPDATA%\pond\data on Windows). To use an object store, add credentials and switch the destination:

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

pond init --storage-path <url> configures a remote destination during setup and prompts for credentials inline when the destination is remote, so a bucket is one command. The s3+https://host/bucket form works for any S3-compatible store (Hetzner, R2, B2, MinIO); s3://, gs://, and az:// use the standard cloud SDK credential chain when no [creds.*] set matches. pond copy --from <local> --to <url> carries existing local data into the bucket - idempotent, never deletes the source, and on completion it rebuilds the destination indexes and verifies every row landed (exit 6 if any are missing or duplicated, so you never reconcile by hand). pond copy --verify-only --from <local> --to <url> runs that same check read-only, without copying. Full walkthrough: pond.locker.

Configuration

pond init walks through everything below interactively and enables the adapters it finds. pond sync only ingests already-enabled adapters - enabling one is an explicit step (pond adapters enable / pond adapters discover / pond init), never a side effect of sync. Config lives at ~/.config/pond/config.toml on macOS and Linux, %APPDATA%\pond\config.toml on Windows (pond config path prints it). Every [adapters.<name>] block needs enabled = true to be active; sections without it (or with enabled = false) are skipped. ~ in paths expands on every platform (%USERPROFILE% on Windows).

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

Search is BM25 full-text by default. Semantic search is opt-in and off unless you ask for it: with it off no pond process downloads or loads an embedding model, new messages get no vectors, and --mode vector is refused. Turn it on in config or with POND_EMBEDDINGS_ENABLED=true, then run pond optimize --only embed once to fill the backlog:

[embeddings]enabled = true

Full detail, including what it costs and how mixed fleets behave, is in the configuration reference.

Supported harnesses

One adapter per harness, in pond adapters discovery order; Reads is the path pond init discovers and writes to [adapters.<name>].path - shown POSIX-style, with the same home-relative layout on Windows (~/.claude/projects is %USERPROFILE%\.claude\projects). Last verified is the most recent capture or refresh date of the adapter's committed fixture (packages/pond/tests/fixtures/adapter/), the corpus its mapping is tested against. Adapters are maintained best-effort, and format drift is safe by design: unknown record shapes still ingest losslessly, malformed input surfaces as a typed error naming the file. Adding a harness is routine work - see Contributing.

Verbosity

Root-level -v / -vv / -vvv raise the tracing level (info / debug / trace); -q / -qq lower it. The default surfaces warnings only. RUST_LOG overrides the CLI flag when set; POND_LOG is no longer honored.

Design

The full contract is in docs/spec.md. Key choices:

• Lance direct, no wrapper. The lance-format/lance crates are the only storage and search engine. No lancedb, no parallel abstraction. Storage, indexing, OCC, schema evolution, blob columns, versioning, and time-travel are all Lance. The read-only pond sql surface is DataFusion planning over the same Lance datasets - a query escape hatch, not a second engine.
• Canonical Session / Message / Part interlingua. Owned in pond, in the shape of Effect v4's Prompt-side Part union. This schema is pond's product; everything else is machinery around it.
• Three Lance datasets (sessions, messages, parts). messages carries the nullable embedding (vector + embedding_model) alongside denormalized filter columns (source_agent / project / role / timestamp) for single-stage filter pushdown.
• No-synthesis adapter seam. Adapters parse source records through extractor helpers that make "invent a value" a compile error - model-no-synthesis, model-schema-honesty, and adapter-provenance-required are structural, not review rules.
• Index lifecycle decoupled from writes. Writes commit data (including embeddings, computed inline at ingest when embeddings are enabled) without folding the search indexes. pond sync runs index maintenance by default, and pond optimize --only index runs it on demand; Lance merges index results with a flat scan over unindexed fragments, so reads stay correct.
• Single-arm retrieval. Each query runs one retriever - fts (BM25, the default) or vector (cosine, with a gentle recency tiebreaker, offered only when embeddings are enabled) - chosen per query; no server-side fusion. --sort-by recency returns newest-first. Results group to one summary per session, keyed on session_root.
• Language-neutral full-text. Word-level simple tokenizer with English stemming (ascii-folding on); tokens the stemmer does not recognize pass through unchanged and stay exact-matchable, so pond indexes sessions in any language alike.
• Two transports, one handler set. HTTP+JSON (axum) and MCP (rmcp) both dispatch into the same handlers. Wire ops: pond_search, pond_get_session, pond_get_message, pond_ingest. MCP additionally exposes the read-only pond_sql tool and the schema://pond, schema://pond-sql, and stats://pond resources.
• Opaque-string multi-tenancy. Each tenant is a namespace string the integrator supplies; pond does not authenticate, authorize, or model identity. The object store's IAM is the storage boundary.
• Encryption is operational. Bucket SSE plus filesystem encryption; pond holds no keys and adds no application-level crypto.

Roadmap

pond ships in small steps. This table lists the steps in order. Done steps stay in the table. The roadmap board holds the same items with their issues. React or comment on an issue to influence the order.

Step 7 was based on data. Over 63 days, agents ran 1,126 searches against this archive. BM25 found the answer 61% of the time. Vector found it 37% of the time. Read the measurement.

This is a direction, not a contract. The order changes when the data changes.

References

The upstream schemas that shaped pond's canonical model are documented in docs/references/ (source URLs + why each matters; the vendored code itself is not redistributed). Real session captures live under packages/pond/tests/fixtures/adapter/.

Contributing

Issues and pull requests are welcome. The most useful contributions right now:

• An adapter for a harness pond does not read yet. The playbook is the pond-add-adapter skill; the PR expectations are in CONTRIBUTING.md.
• Spec feedback on docs/spec.md.
• Pointers to additional reference schemas or session samples worth documenting under docs/references/.
• Bug reports against the v1 surface (CLI verbs, wire ops, schema mismatches, OCC behavior, object-store backends).

For something bigger, the roadmap is the list. Comment on the issue before you start, so we agree on the scope. For other larger changes, open an issue first to discuss the direction. For security issues, see SECURITY.md.

Questions or feedback? Start a GitHub Discussion, or DM me on Telegram or X - I answer personally.

Links

• Docs: pond.locker
• Crate: pond-db on crates.io
• MCP Registry name: mcp-name: io.github.tenequm/pond

License

Apache-2.0 (c) 2026 tenequm