Skip to content
tapes

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

Section titled “Before you start”

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

Terminal window
tapes local up
tapes serve
tapesctl config set tapes-url http://localhost:8081

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.

Section titled “Search”
Terminal window
tapesctl search "how was authentication fixed?"
tapesctl search "logging configuration" --top 10

An empty result set is not an error: non-quiet output says No results found. and exits 0.

Compose it

Section titled “Compose it”

Quiet output is a pipe format rather than a verbosity setting: it prints one bare session id per line, which is the shape skill generation takes as positionals, so the two compose:

Terminal window
tapesctl skill generate $(tapesctl search "Charm CLI" --quiet --top 1) \
  --name charm-patterns

The skills guide picks up from here.

Over HTTP

Section titled “Over HTTP”

The equivalent read endpoint is:

Terminal window
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

Section titled “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.