Search

Search your stored conversations using semantic similarity. Find relevant sessions by meaning, not just exact keywords.

Prerequisites

PostgreSQL with pgvector For storing both conversation sessions and vector embeddings. Use tapes local up to bootstrap locally.

Embedding Provider Ollama (embeddinggemma) or OpenAI for generating embeddings from conversations

Search Guide

Step 1: Bootstrap local Postgres + Ollama

Pull the Postgres image (with pg_duckdb + pgvector preinstalled) and the Ollama container in one command. tapes local up also pulls embeddinggemma automatically.

tapes local up

Already have your own Postgres and Ollama running? Skip this step and supply your own DSN below.

Step 2: Run tapes with embeddings enabled

Start the tapes proxy and API against the local Postgres:

tapes serve \
  --postgres "postgres://tapes:tapes@localhost:5432/tapes?sslmode=disable" \
  --embedding-provider ollama \
  --embedding-target "http://localhost:11434" \
  --embedding-model embeddinggemma

Embeddings are written to the same Postgres database via pgvector. Override with --vector-store-target only if you want embeddings in a different database.

Step 3: Use your LLM through the proxy

Embeddings are generated automatically when an embedding provider is configured:

curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3", "messages": [{"role": "user", "content": "How do I configure logging?"}]}'

Step 4: Search your sessions

Query your conversation history using natural language. Search talks to the running API server — embeddings are configured on the server, not the client:

tapes search "logging configuration"

# Point at a non-default API, return more hits
tapes search "logging configuration" --api-target http://localhost:8081 --top 10

Understanding Results

Each hit is an individual LLM span with its trace and turn context:

Score Similarity score (higher = more relevant)

Trace / span id Where the hit lives in the derived projection

Turn The user prompt of the turn the span belongs to

Snippet Matched content from the span

Session · model The owning session id and the model that produced the span

Once you've found a relevant session, export it with tapes export, or turn it into a reusable skill with tapes skill generate $(tapes search "your query" --quiet --top 1) --name my-skill. See the History guide for browsing sessions.