tapes-search - SKILL.md Agent Skill

name: tapes-search description: Search over stored LLM sessions using semantic search. Use when you need to find relevant conversations, recall previous session context, or search through historical LLM interactions stored in the tapes system.

Tapes Search Skill

Search over stored LLM sessions using semantic search via the tapes search CLI command.

When to Use

Use this skill when you need to:

Find relevant past conversations or sessions
Recall context from previous LLM interactions
Search through historical data stored in the tapes telemetry system
Locate specific discussions or topics from past sessions

Prerequisites

The tapes search command requires:

A Postgres-backed tapes API or local tapes runtime
A pgvector-backed vector index in the same Postgres database
An embedding provider, either Ollama or OpenAI, to convert queries to vectors

Quick Start

Start the API with Ollama embeddings:

ollama pull embeddinggemma
ollama serve
tapes serve

Or start the API with OpenAI embeddings:

tapes auth openai
tapes config set embedding.provider openai
tapes serve

Then search through the API:

tapes search "<your query>"

Command Reference

Basic Usage

tapes search <query> [flags]

API Flag

Flag	Description	Example
`--api-target`	Tapes API server URL	`http://localhost:8081`

Optional Flags

Flag	Description	Default
`--top`, `-k`	Number of results to return	`5`
`--debug`	Enable debug logging	`false`

Examples

Search for Configuration Discussions

tapes search "how to configure logging" \
  --api-target http://localhost:8081

Get More Results

tapes search "error handling patterns" \
  --top 10 \
  --api-target http://localhost:8081

Debug Mode

tapes search "authentication flow" \
  --debug \
  --api-target http://localhost:8081

Output Format

The search results display:

Rank and Score: Position and similarity score (higher = more relevant)
Hash: The unique content-addressable hash of the matched message
Role: Whether the match is from a user or assistant message
Preview: A snippet of the matched content
Session History: The full conversation context from root to matched message

Example output:

Search Results for: "how to configure logging"
============================================================

[1] Score: 0.8542
    Hash: abc123
    Role: assistant
    Preview: To configure logging in your application ...

    Session (3 turns):
    |-- [user] How do I set up logging?
    |-- [assistant] You can configure logging by ...
    `-> [user] What about debug mode?

Tips

Be specific: More detailed queries yield more relevant results
Use natural language: The semantic search understands context and meaning
Adjust top-k: Increase -k if you need more results to find what you're looking for
Check the session context: The full ancestry helps understand the conversation flow