Tapes Documentation

Pages

1. OverviewWhat tapes captures, which binary owns the database, default listen ports, and the first docs routes after install.
2. InstallationInstall the tapes server and tapesctl client, bootstrap local PostgreSQL and Ollama, and verify with tapes version and tapes local status.
3. QuickstartStart tapes serve, point tapesctl at :8081, seed demo data, list sessions, and capture one real agent against :8082.
4. Capture and deriveAppend-only raw_turns, the lossy reduction stored beside raw_response, and the idempotent deriver that projects sessions, traces, and spans.
5. Sessions, traces, and spansDeterministic derived IDs, session rollups, trace-as-turn, span kinds, and how subagent threads rejoin through transcript anchors.
6. Read API vs ingestTwo sealed contracts, two ports, and the trust boundary: :8081 is the public read surface and :8082 is a private in-cluster write path.
7. Cassettescassette/v1alpha1 admission: OpenAPI plus x-tapes-cassette, path rewrite under /v1/cassettes/{name}, and operator-owned process lifecycle.
8. Capture an agentPoint Claude, Codex, pi, or a generic provider client at capture: tapesctl start/capture vs a fixed-port proxy on :8080, always writing ingest on :8082.
9. Search spansSemantic search over embedded main-conversation LLM spans via GET /v1/search/spans, tapesctl search, and the MCP search tool.
10. Inspect and exportList sessions, browse traces and raw_turns, enable the optional API web UI, and stream GET /v1/sessions/{id}/export as JSONL.
11. Generate skillsServer skill store and /v1/skills routes, transcript spine used for generation, and how tapesctl generate/list/sync talk to this API.
12. Run a cassette locallyAdmit the bundled hello-world cassette with Compose, --cassettes, and tapesctl against the republished /v1/cassettes surface.
13. Configure embeddingsSwitch embedding.provider between ollama and openai, set model and dimensions, store keys with tapes auth, and run or disable the embed worker.
14. CLI referencetapes commands and flags: init, local, serve, status, auth, config, backfill, raw equivalence, dev, and version. tapesctl is the client, not this binary.
15. Configuration referenceDotdir resolution, flag then TAPES_ then config.toml precedence, dotted keys, defaults, credentials.toml, and the cassettes array.
16. Read APICompiled GET /openapi for :8081: sessions, traces, spans, stats, search, skills, admin, MCP, cassette proxy, and CONTRACT seal rules.
17. Ingest APIPrivate write contract on :8082: POST /v1/ingest, POST /v1/ingest/transcript, body cap, JSON error envelope, and 413 reject_oversize.
18. MCPStreamable HTTP MCP at /v1/mcp: cassette tools marked x-tapes-mcp, the legacy search tool, and stateless transport limits.
19. Split the stackRun proxy, api, ingest, derive-worker, and embed-worker as separate processes, including flags, DSNs, and independent failure domains.
20. Gateway capturetapes-extproc Envoy adapter: env config, gRPC recv limits, ingest POST of completed turns, and RawResponseMode for the capture ratchet.
21. Prove the capture ratchetoff, dual, and raw reducer modes, plus tapes raw equivalence classes, excluded fields, and the read-only comparison against stored reductions.
22. TroubleshootingWrong-port capture, missing OpenAI embed keys, ingest 413, attribution-repair 200 vs 202, --wipe data loss, and GOEXPERIMENT=jsonv2 build failures.
23. ContributeNix or Make build, make test through Dagger, OpenAPI CONTRACT seals, sqlc generate, PR title labels, and tapes vs tapesctl ownership.