Search captured sessions by meaning

A month of captured sessions is only useful if you can find the one where the agent fixed the thing. Tapes searches semantically over the embedded span projection: each hit is an individual main-conversation LLM span with its session id, similarity score, and a text snippet.

Before you start

The quickstart setup provides everything search needs — PostgreSQL with pgvector, and Ollama with the embeddinggemma model:

tapes local up
tapes serve

tapes serve derives captures and embeds eligible spans in the background by default. You also need something to search: capture a session (the Claude Code guide is the shortest path) or seed representative data with tapesctl seed.

Search

tapesctl search "how was authentication fixed?"
tapesctl search "logging configuration" --top 10

Each hit is a turn: its score, the prompt that started it, and when it ran, with the span that matched on the » line and the session, trace, and span ids under it, whole, so a hit leads straight to sessions get, traces get, or spans get. An empty result set is not an error: non-quiet output says No results found. and exits 0. --json prints the search cassette’s document.

Compose it

Quiet output is a pipe format rather than a verbosity setting: it prints one bare session id per line, deduplicated in score order, which is what skill generation takes as selectedSessionIds:

tapesctl search "Charm CLI" --quiet --top 3 | jq -R . | jq -s '{selectedSessionIds: .}'

The skills guide picks up from here.

Over HTTP

The equivalent read endpoint is:

curl --get http://localhost:8081/v1/search/spans \
  --data-urlencode 'query=how was authentication fixed?' \
  --data-urlencode 'top_k=5'

There is no /v1/search endpoint. See HTTP APIs for tenant headers and contracts.

When results are empty

Walk the chain in order — each step depends on the one before:

1. The API is reachable: tapes status.
2. Sessions exist: tapesctl sessions list, and a session has derived spans: tapesctl sessions traces <session-id>.
3. The embedding service is running; for Ollama, curl http://localhost:11434/api/tags.
4. embedding.model and embedding.dimensions match the pgvector table.

A configured but uninitialized search surface returns HTTP 503, and the response body names the cause. The search reference covers split deployments with separate derive and embed workers.