Copied to clipboard

tapes

Reference

Technical reference for tapes providers, storage backends, and data model.

Config File

Configuration is stored in .tapes/config.toml. tapes looks for config in this order:

  1. ./.tapes/config.toml — local project directory
  2. ~/.tapes/config.toml — user home directory
# .tapes/config.toml
version = 0

[storage]
postgres_dsn = "postgres://tapes:tapes@localhost:5432/tapes?sslmode=disable"

[proxy]
provider = "anthropic"
upstream = "https://api.anthropic.com"
listen = ":8080"
project = "my-app"

[api]
listen = ":8081"
# web_ui = true

[ingest]
listen = ":8082"

[client]
proxy_target = "http://localhost:8080"
api_target = "http://localhost:8081"

[vector_store]
# target defaults to storage.postgres_dsn
target = ""

[embedding]
provider = "ollama"
target = "http://localhost:11434"
model = "embeddinggemma"
dimensions = 768

[opencode]
provider = "anthropic"
model = "claude-sonnet-4-5"

[telemetry]
disabled = false

[update]
# disabled = true

Precedence

Configuration values are resolved in this order (highest to lowest priority):

  1. CLI flags — Always override everything
  2. Environment variables — TAPES_* prefixed variables (see env var reference)
  3. Config file — Values set in config.toml
  4. Defaults — Built-in default values

Use tapes config list to see all current values. See CLI config for management commands.

Providers

tapes works with any LLM provider. Configure using --provider and --upstream flags.

Provider Upstream URL
Ollama (default) http://localhost:11434
Anthropic https://api.anthropic.com
OpenAI https://api.openai.com

The --provider flag tells tapes how to parse the API format. The -u flag specifies where to forward requests.

Storage

tapes uses PostgreSQL for all storage. The same database holds the append-only raw turn log, the derived sessions / traces / spans, and vector embeddings.

PostgreSQL (required) Pass --postgres "postgres://user:pass@host:5432/tapes" to enable. The database must have the pg_duckdb and pgvector extensions installed. Schema migrations run automatically on startup. See the PostgreSQL Storage guide.
Local bootstrap Run tapes local up to start a Postgres container with pg_duckdb + pgvector preinstalled and an Ollama container alongside it.

Vector Storage

Semantic search for stored conversations. When an embedding provider is configured, the deriver embeds the derived spans and stores the vectors in the same Postgres database via pgvector. Search then runs over the span projection (see tapes search).

pgvector (built-in) Embeddings live in the same Postgres database as the derived sessions, traces, and spans. No separate vector service to run. Defaults to the --postgres DSN; override with --vector-store-target if you keep embeddings in a different database.
Ollama Embeddings Default embedding model is embeddinggemma. tapes local up pulls it automatically; otherwise install with ollama pull embeddinggemma.
OpenAI Embeddings Run tapes auth openai (or set OPENAI_API_KEY) and tapes config set embedding.provider openai. 
tapes serve \
  --postgres "postgres://tapes:tapes@localhost:5432/tapes?sslmode=disable" \
  --embedding-provider ollama \
  --embedding-target http://localhost:11434 \
  --embedding-model embeddinggemma

/v1/stats response

The GET /v1/stats endpoint returns aggregate counts and rollups across the matching window. The numbers are span-grain rollups summed from the derived model (delta-only usage, so re-sent history is not double-counted), and agree with the session and trace views.

{
  "session_count": 142,
  "turn_count": 3870,
  "completed_count": 119,
  "total_cost": 12.4538,
  "input_tokens": 1842301,
  "output_tokens": 412057,
  "total_duration_ns": 9381240000000,
  "tool_calls": 2841
}
Field Description
session_count Distinct sessions in the matched window.
turn_count Total traces (user-visible turns) matching the filter.
completed_count Sessions whose derived status is completed.
total_cost USD cost folded from per-model token rollups using the configured pricing table.
input_tokens / output_tokens Delta-only token sums across the matched spans — re-sent history is not re-billed.
total_duration_ns Sum of trace durations across the matched window, in nanoseconds.
tool_calls Count of tool invocations across the matched spans.

Filter the window with since and until (RFC3339). Totals are always computed from span-grain trace rollups (delta-only token usage), so they agree with the session and trace views.

Data Model

The deriver projects the raw turn log into three nested constructs. This is the model the API, CLI, and Deck all read. See the architecture overview for the capture-to-derive flow.

session One agent run. Carries folded model, token, cost, turn-count, and per-model usage rollups.
trace One user-visible turn within a session.
span A nested operation within a turn. kind is one of llm, tool, agent (subagent), or event (injected context). Spans nest via parent_span_id.
span link Dataflow between spans, including cross-turn compaction seams.

Internally the deriver content-addresses raw turns with a merkle structure to dedup re-sent history and preserve provenance. That layer is not exposed by the API — you query sessions, traces, and spans.

Last updated: