# Tapes Documentation

> Operator and integrator reference for the tapes server: capture, derive, query, search, cassettes, and the private ingest write path. Use this set to install, run, configure, and extend the Go binary in this repository. Client capture and read commands live in tapesctl and are cited only where this server requires them.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750)
- [GitHub repository](https://github.com/papercomputeco/tapes)

## Repository

- Repository: papercomputeco/tapes

- Generated: 2026-08-18T20:20:03.787Z
- Updated: 2026-08-19T01:07:53.887Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 23

## Pages

- [Overview](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/01-overview.md): What tapes captures, which binary owns the database, default listen ports, and the first docs routes after install.
- [Installation](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/02-installation.md): Install the tapes server and tapesctl client, bootstrap local PostgreSQL and Ollama, and verify with tapes version and tapes local status.
- [Quickstart](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/03-quickstart.md): Start tapes serve, point tapesctl at :8081, seed demo data, list sessions, and capture one real agent against :8082.
- [Capture and derive](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/04-capture-and-derive.md): Append-only raw_turns, the lossy reduction stored beside raw_response, and the idempotent deriver that projects sessions, traces, and spans.
- [Sessions, traces, and spans](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/05-sessions-traces-and-spans.md): Deterministic derived IDs, session rollups, trace-as-turn, span kinds, and how subagent threads rejoin through transcript anchors.
- [Read API vs ingest](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/06-read-api-vs-ingest.md): Two sealed contracts, two ports, and the trust boundary: :8081 is the public read surface and :8082 is a private in-cluster write path.
- [Cassettes](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/07-cassettes.md): cassette/v1alpha1 admission: OpenAPI plus x-tapes-cassette, path rewrite under /v1/cassettes/{name}, and operator-owned process lifecycle.
- [Capture an agent](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/08-capture-an-agent.md): Point 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.
- [Search spans](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/09-search-spans.md): Semantic search over embedded main-conversation LLM spans via GET /v1/search/spans, tapesctl search, and the MCP search tool.
- [Inspect and export](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/10-inspect-and-export.md): List sessions, browse traces and raw_turns, enable the optional API web UI, and stream GET /v1/sessions/{id}/export as JSONL.
- [Generate skills](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/11-generate-skills.md): Server skill store and /v1/skills routes, transcript spine used for generation, and how tapesctl generate/list/sync talk to this API.
- [Run a cassette locally](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/12-run-a-cassette-locally.md): Admit the bundled hello-world cassette with Compose, --cassettes, and tapesctl against the republished /v1/cassettes surface.
- [Configure embeddings](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/13-configure-embeddings.md): Switch embedding.provider between ollama and openai, set model and dimensions, store keys with tapes auth, and run or disable the embed worker.
- [CLI reference](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/14-cli-reference.md): tapes commands and flags: init, local, serve, status, auth, config, backfill, raw equivalence, dev, and version. tapesctl is the client, not this binary.
- [Configuration reference](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/15-configuration-reference.md): Dotdir resolution, flag then TAPES_ then config.toml precedence, dotted keys, defaults, credentials.toml, and the cassettes array.
- [Read API](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/16-read-api.md): Compiled GET /openapi for :8081: sessions, traces, spans, stats, search, skills, admin, MCP, cassette proxy, and CONTRACT seal rules.
- [Ingest API](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/17-ingest-api.md): Private write contract on :8082: POST /v1/ingest, POST /v1/ingest/transcript, body cap, JSON error envelope, and 413 reject_oversize.
- [MCP](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/18-mcp.md): Streamable HTTP MCP at /v1/mcp: cassette tools marked x-tapes-mcp, the legacy search tool, and stateless transport limits.
- [Split the stack](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/19-split-the-stack.md): Run proxy, api, ingest, derive-worker, and embed-worker as separate processes, including flags, DSNs, and independent failure domains.
- [Gateway capture](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/20-gateway-capture.md): tapes-extproc Envoy adapter: env config, gRPC recv limits, ingest POST of completed turns, and RawResponseMode for the capture ratchet.
- [Prove the capture ratchet](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/21-prove-the-capture-ratchet.md): off, dual, and raw reducer modes, plus tapes raw equivalence classes, excluded fields, and the read-only comparison against stored reductions.
- [Troubleshooting](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/22-troubleshooting.md): Wrong-port capture, missing OpenAI embed keys, ingest 413, attribution-repair 200 vs 202, --wipe data loss, and GOEXPERIMENT=jsonv2 build failures.
- [Contribute](https://grok-wiki.com/public/docs/papercomputeco-tapes-020596f21750/pages/23-contribute.md): Nix or Make build, make test through Dagger, OpenAPI CONTRACT seals, sqlc generate, PR title labels, and tapes vs tapesctl ownership.

## Source Files

- `AGENTS.md`
- `api/admin_handlers.go`
- `api/cassetterunner/mcp.go`
- `api/cassettes.go`
- `api/CONTRACT`
- `api/mcp/cassette.go`
- `api/mcp/mcp.go`
- `api/mcp/search.go`
- `api/openapi_routes.go`
- `api/openapi.go`
- `api/search_spans_handler.go`
- `api/sessions_handlers.go`
- `api/skills_handlers.go`
- `api/trace_browse_handlers.go`
- `api/v1_handlers.go`
- `api/web_ui.go`
- `cli/tapes-extproc/main.go`
- `cmd/tapes/auth/auth.go`
- `cmd/tapes/backfill/backfill.go`
- `cmd/tapes/config/config.go`
- `cmd/tapes/config/set.go`
- `cmd/tapes/dev/checkopenapi.go`
- `cmd/tapes/dev/dev.go`
- `cmd/tapes/init/init.go`
- `cmd/tapes/local/local.go`
- `cmd/tapes/raw/equivalence.go`
- `cmd/tapes/serve/api/api.go`
- `cmd/tapes/serve/cassettes.go`
- `cmd/tapes/serve/deriveworker/deriveworker.go`
- `cmd/tapes/serve/embedworker/embedworker.go`
- `cmd/tapes/serve/ingest/ingest.go`
- `cmd/tapes/serve/proxy/proxy.go`
- `cmd/tapes/serve/serve.go`
- `cmd/tapes/serve/stack.go`
- `cmd/tapes/status/status.go`
- `cmd/tapes/tapes.go`
- `cmd/tapes/version/version.go`
- `CONTRIBUTING.md`
- `Dockerfile.extproc`
- `docs/apis.md`
- `docs/architecture.md`
- `docs/cassette-walkthrough.md`
- `docs/cassettes.md`
- `docs/cli.md`
- `docs/configuration.md`
- `docs/data.md`
- `docs/development.md`
- `docs/installation.md`
- `docs/integrations.md`
- `docs/introduction.md`
- `docs/mcp.md`
- `docs/search.md`
- `docs/skills.md`
- `e2e/hurls/ingest/ingest.hurl`
- `extproc/config.go`
- `extproc/dispatcher.go`
- `extproc/processor.go`
- `extproc/rawlane.go`
- `fixtures/thread/README.md`
- `flake.nix`
- `go.mod`
- `ingest/config.go`
- `ingest/CONTRACT`
- `ingest/errorhandler.go`
- `ingest/ingest.go`
- `ingest/openapi.go`
- `ingest/rawreduce.go`
- `ingest/responses.go`
- `install.sh`
- `makefile`
- `migrations/1781049035_raw_turns.up.sql`
- `migrations/1781230000_span_model.up.sql`
- `pkg/capture/reducer.go`
- `pkg/cassette/examples/hello-world/cassette.toml`
- `pkg/cassette/examples/hello-world/compose.yaml`
- `pkg/cassette/examples/hello-world/main.go`
- `pkg/cassette/examples/mcp-tool/main.go`
- `pkg/cassette/v1alpha1/manifest.go`
- `pkg/cassette/v1alpha1/validate.go`
- `pkg/config/cassettes.go`
- `pkg/config/defaults.go`
- `pkg/config/flags.go`
- `pkg/config/types.go`
- `pkg/config/viper.go`
- `pkg/derive/deriver.go`
- `pkg/derive/fold.go`
- `pkg/derive/reconcile.go`
- `pkg/derive/spans.go`
- `pkg/derive/worker/worker.go`
- `pkg/dotdir/manager.go`
- `pkg/embeddings/embedder.go`
- `pkg/embeddings/ollama/ollama.go`
- `pkg/embeddings/openai/openai.go`
- `pkg/embeddings/utils/new.go`
- `pkg/embedworker/worker.go`
- `pkg/rawequiv/rawequiv.go`
- `pkg/rawequiv/report.go`
- `pkg/skill/generator.go`
- `pkg/skill/transcript.go`
- `pkg/skill/types.go`
- `pkg/skill/writer.go`
- `pkg/spanembed/spanembed.go`
- `proxy/proxy.go`
- `README.md`