tracecc

name	tracecc
description	Search and analyze past agent sessions using compiled trace bundles. Use when asked to recall previous conversations, find past sessions, search agent history, or answer questions like 'what did I say about X' or 'find the session where'.
version	1.0.0
author	Larry Ludlow
license	MIT
platforms	["macos","linux"]
metadata	{"hermes":{"tags":["Memory","Search","Sessions","Traces","History"],"related_skills":[],"requires_tools":["terminal"]}}

TraceCC - Agent Trace Search & Analysis

Search, render, and analyze compiled agent session traces via the tracecc CLI. TraceCC compiles raw JSONL session traces into an indexed SQLite bundle, then provides structured search and multiple view projections over that bundle.

When to Use

• User asks about past conversations ("what did I say about X", "when did we discuss Y")
• User wants to find a previous session or recall something from history
• Debugging past agent behavior or reviewing tool call patterns
• Searching for errors, decisions, or topics across session history

Quick Reference

Task	Command
Compile traces	tracecc compile --bundle traces.tcc --redact default --json
BM25 search	tracecc search traces.tcc --query "topic" --mode bm25 --limit 10
Regex search	tracecc search traces.tcc --query "exact_match" --mode regex
UI view	tracecc render traces.tcc --view ui --session latest
Full transcript	tracecc render traces.tcc --view full --session <id>
List sessions	tracecc inspect traces.tcc --sessions
Dereference lines	tracecc inspect traces.tcc --lines 120:160

Setup

TraceCC must be configured to know where Hermes session traces live. Run once:

tracecc setup --hermes --yes

This registers ~/.hermes/sessions as a trace root in ~/.TraceCC/config.toml. No project association is needed since Hermes is an agent, not a project-scoped tool.

Procedure

Compile the Bundle

Only recompile when the bundle is stale or missing. Compilation walks all configured trace roots and produces a single .tcc file.

tracecc compile --bundle traces.tcc --redact default --json

Always use --redact default to strip API keys, tokens, and credentials from compiled output.

Search

Two modes depending on the query type:

BM25 (ranked relevance) for natural-language queries:

tracecc search traces.tcc --query "scheduling API discussion" --mode bm25 --limit 10

Regex (exact patterns) for function names, error messages, specific strings:

tracecc search traces.tcc --query "summarize_diff" --mode regex --limit 10

Filters narrow results:

• --roles user,assistant,tool_call,tool_result,tool_error - filter by message role
• --since 2026-04-01 / --until 2026-04-11 - date range
• --runtime hermes - restrict to Hermes sessions only
• --limit N - max results (default 20)

Render

View a session's content in different projections:

# Human-readable summary
tracecc render traces.tcc --view ui --session latest

# Full lossless transcript
tracecc render traces.tcc --view full --session <session-id>

# Query-driven projection (only relevant blocks)
tracecc render traces.tcc --view adaptive --query "topic" --session all

Inspect

Examine bundle internals and dereference pointers from search results:

# List all sessions with metadata
tracecc inspect traces.tcc --sessions

# Dereference a line range from a search result (e.g. "session:L71-L72")
tracecc inspect traces.tcc --lines 71:72

Workflows

"What did I say about X?"

1. BM25 search with a broad query, limit 10
2. If results are noisy, add --roles or --since filters
3. Use session IDs from results to render --view ui for context
4. If exact text is needed, use inspect --lines with the line range from search

"What errors have we been hitting?"

1. search --roles tool_error --mode bm25 --query "error" --limit 20
2. Group by session ID in the output
3. Render UI view for sessions with interesting errors

"Show me recent sessions"

1. inspect --sessions to list all compiled sessions
2. For a date range: search --since YYYY-MM-DD --until YYYY-MM-DD --roles user --query "." --mode regex

Pitfalls

• The bundle is read-only after compile. Search and render never modify it.
• Recompile only when asked or when the bundle is clearly stale.
• If search returns nothing, try alternate query phrasings or broader filters before reporting "not found".
• Line numbers in all rendered output refer to the canonical full view. UI and adaptive views are projections over the same coordinate system.

Verification

After compiling, check session counts in the JSON output. After searching, confirm result pointers can be dereferenced with inspect --lines.