TraceGC

Deterministic, receipt-preserving context compaction library for AI agents with no extra LLM calls.

• Reduces token cost by pruning obsolete event paths and redundant actions.
• Avoids stale-context confusion by removing overridden variables and dead-end attempts.
• Zero added latency from AI calls using a fully local, deterministic compaction engine.
• Retention Policy Control through optional metadata (importance, tags, retain_until) to protect critical events from being pruned.
• CLI Auditing & Inspection (tracegc command) to compact, dry-run, explain pruning decisions, diff prompts, and restore receipts.
• Composable with provider-native compaction (Anthropic's compact API, OpenAI's trained-in Codex pruning, Google ADK) — run TraceGC as a deterministic pre-filter upstream instead of choosing one or the other. See Provider-Native Compaction vs. TraceGC.

Interactive Demos

• Google Colab: Try out the library and run code examples directly in the Colab Notebook.
• Web App: Visualize the compaction behavior interactively in your browser at the TraceGC Web Playground.

Description

TraceGC is a framework-agnostic, installable library combining deterministic graph-based pruning with recoverable receipts. While existing tools (such as Self-GC, ClawVM, Cognee, ContextNest, Headroom, and MemGPT/Letta) split these approaches across research papers, hosted SaaS products, client-side compressors, or LLM-based summarization routines, TraceGC ships as a simple, drop-in, zero-dependency Python library designed for developers building stateful agent workflows.

By modeling the agent's interaction history (execution traces) as a directed multigraph, TraceGC identifies and removes obsolete or superseded steps, dead execution branches, and cycles. When elements are pruned, TraceGC leaves behind lightweight, deterministic receipt stubs inline, allowing agents to preserve awareness of their history. Furthermore, the complete original content of any pruned step remains fully recoverable on-demand.

---

Architecture

TraceGC processes execution traces through a linear compilation pipeline, transforming a raw timeline of structured events into a clean, compacted prompt prefix.

Compaction Pipeline Flow

┌───────┐      ┌───────┐      ┌─────────────────────────┐      ┌──────────────┐      ┌───────────────────┐
│ Trace │ ───► │ Graph │ ───► │    Override Engine +    │ ───► │ Topo Sampler │ ───► │ Compacted Prompt  │
└───────┘      └───────┘      │   Dead-Branch Sweeper   │      └──────────────┘      │  + Receipt Store  │
                              └─────────────────────────┘                            └───────────────────┘

Entry Points

• TraceGC (Recommended for Agent Loops): An incremental-friendly wrapper class. It allows you to append events one by one as they happen (add_event()) and call compact() on demand. This is the recommended entry point for long-running agent loops where history grows step-by-step.
• compact_events() (Single-Shot): A low-level function that accepts a static list of event dictionaries and returns the compacted output in a single call. Best for post-mortem processing or batch compaction pipelines.

The Receipts Model

To prevent context-compaction from causing permanent "memory loss," TraceGC employs a deterministic receipt recovery model. Pruned events are never discarded from memory; they are converted into lightweight inline receipt stubs (e.g., [RECEIPT node_id]). Callers can recover the complete, original event dictionary (including arguments, tool names, and return values) at any time by calling get_receipt(graph, node_id).

---

Installation

For Local Development / From Source

Clone this repository and run an editable installation from the root directory:

pip install -e .

From PyPI

Once published to PyPI, you can install the package directly:

pip install tracegc

---

Quick Start (Incremental API)

The recommended interface for managing agent context is the TraceGC client. It allows you to append events step-by-step as they occur and run compaction on-demand:

from tracegc import TraceGC

# 1. Initialize the client
client = TraceGC()

# 2. Append events incrementally as they occur
client.add_event({
    "id": "e001", 
    "type": "decision", 
    "timestamp": 1000, 
    "parent_id": None, 
    "content": "Start config"
})
client.add_event({
    "id": "e002", 
    "type": "set_var", 
    "timestamp": 1010, 
    "parent_id": "e001", 
    "key": "x", 
    "value": 10
})
client.add_event({
    "id": "e003", 
    "type": "set_var", 
    "timestamp": 1020, 
    "parent_id": "e002", 
    "key": "x", 
    "value": 20  # Supersedes x=10
})

# 3. Compact the context history on-demand
result = client.compact()

# The result dictionary contains:
# - 'prompt': The rendered prompt string with receipts (e.g. '[RECEIPT e002]\nx = 20')
# - 'tokens_before' / 'tokens_after': Token metrics before and after compaction
# - 'receipts': List of receipt node IDs generated
# - 'pruned_ids': List of all event IDs that were pruned
# - 'compact_events': List of surviving event dictionaries
# - 'graph': The internal StateGraph state
print(result["prompt"])

Storage Backends (In-Memory & SQLite)

TraceGC supports customizable storage backends via tracegc-storage. By default, TraceGC() uses in-memory storage (MemoryStore()). To persist session events and receipts across restarts, pass a SQLiteStore:

from tracegc import TraceGC
from tracegc_storage import MemoryStore, SQLiteStore

# 1. Default in-memory usage
client_mem = TraceGC()  # uses MemoryStore()

# 2. SQLite-backed usage (persists to file)
store = SQLiteStore("agent_history.db")
client_db = TraceGC(store=store, context_id="session_123")

client_db.add_event({
    "id": "e001", "type": "set_var", "timestamp": 1000, "key": "model", "value": "v1"
})
client_db.add_event({
    "id": "e002", "type": "set_var", "timestamp": 2000, "key": "model", "value": "v2"
})
res = client_db.compact()

# Re-opening a new client instance with the same DB file and context_id restores trace history
client_reloaded = TraceGC(store=SQLiteStore("agent_history.db"), context_id="session_123")
res_reloaded = client_reloaded.compact()
print(res_reloaded["prompt"])

Low-Level API (Single-Shot Compaction)

If you already have a full, pre-collected list of events upfront, you can use the lower-level single-shot function compact_events() directly:

from tracegc import compact_events

events = [
    {"id": "e001", "type": "decision", "timestamp": 1000, "parent_id": None, "content": "Hello"},
    # ... other events ...
]
result = compact_events(events)

---

LLM Middleware Adapters

TraceGC provides concrete integration helper functions for popular LLM provider libraries. These helper functions are optional (lazy-loaded inside the functions), so the core tracegc package remains completely dependency-free.

To use these adapters, ensure you install the corresponding package first:

# To use the Anthropic adapter
pip install anthropic

# To use the OpenAI adapter
pip install openai

Usage Example

from tracegc import TraceGC
from tracegc.middleware import call_openai_with_compaction

# Build and populate your context
client = TraceGC()
client.add_event({"id": "e1", "type": "set_var", "timestamp": 1000, "parent_id": None, "key": "x", "value": 10})
client.add_event({"id": "e2", "type": "set_var", "timestamp": 1010, "parent_id": "e1", "key": "x", "value": 20})

# Call the model; the adapter automatically handles compaction of history 
# and sends the compacted prompt as the system prefix.
res = call_openai_with_compaction(
    tracegc=client,
    model="gpt-4o-mini",
    user_message="Explain what value x holds.",
    api_key="your-openai-api-key"  # Optional, falls back to env var
)

print(res["response_text"])
print(res["metrics"]) # {input_tokens, output_tokens, tokens_before, tokens_after}

---

Pruning Stages

TraceGC executes five deterministic stages to prune context:

1. Dead-Branch Sweeper (DFS): Recursively traverses sequence edges starting from explicit abandon events to prune unsuccessful or aborted attempts. For example, if a sub-branch of tool calls and decisions is created but later abandoned, the sweeper marks the entire sub-branch as pruned.
2. Override Engine (supersedes edges): Finds superseded state variables (like set_var events) and retains only the most recent update per key among surviving nodes. For example, if a state variable is set multiple times, intermediate values are pruned in favor of the latest value.
3. Deduplication Engine: Identifies duplicate tool call results (identical tool name, inputs, and outputs/results) and prunes redundant later identical executions, leaving a receipt pointing to the earliest surviving call.
4. Topological Sampler (Cycle Collapse): A defensive/structural optimization stage. It identifies cycles and strongly connected components (SCCs) via Tarjan's algorithm and collapses them into single deterministic receipt nodes (e.g., collapsing repeating execution loops to leave a single receipt stub). Since the standard add_event() event-stream API enforces sequential dependency parent checks, cycles can never form in normal client usage. This stage exists as defensive infrastructure to safely handle graphs constructed by other means (e.g. direct StateGraph population from out-of-order logs or non-chronological sources).
5. Semantic Pruning Engine: Processes semantic duplicates, superseded technology decisions, and resolved errors while preserving provenance. It also prunes obsolete file reads (obsolete once edited) and redundant successful verification command executions.

---

Receipts & Event Recovery

Pruned events are never permanently deleted from memory. Instead, they are flagged as pruned (pruned=True) on the StateGraph and represented by inline stubs ([RECEIPT <node_id>]).

Callers can recover the complete original event payload at any time using get_receipt(graph, node_id). For example, recovering e002 returns the original superseded variable assignment dict:

# Call get_receipt from the TraceGC client instance:
print(client.get_receipt("e002"))
# Returns:
# {'id': 'e002', 'type': 'set_var', 'timestamp': 1010, 'parent_id': 'e001', 'key': 'x', 'value': 10, 'pruned': True}

---

Event Schema

TraceGC validates incoming events according to five structured types defined in tracegc/events.py:

• set_var: Used to update state variables.
  • Required fields: id, type, timestamp, key, value
• tool_call: Represents a tool execution request.
  • Required fields: id, type, timestamp, tool_name, arguments
• tool_result: Captures the execution result of a tool.
  • Required fields: id, type, timestamp, call_id, result
• abandon: Denotes abandoning a path.
  • Required fields: id, type, timestamp, ref_to (list of target node IDs to prune)
• decision: Describes a transition logic or agent choice.
  • Required fields: id, type, timestamp, content

All events support an optional parent_id (string) field to map the sequential execution path.

Coding Agent Event Types (Schema v0.3.0+)

• file_read: Reads a file payload.
  • Required fields: id, type, timestamp, path (non-empty string)
• file_edit: Edits a file.
  • Required fields: id, type, timestamp, path (non-empty string), diff_hash (non-empty string hash of the change)
• command_run: Runs a terminal command.
  • Required fields: id, type, timestamp, command (non-empty string), exit_code (integer)
• test_run: Runs test cases.
  • Required fields: id, type, timestamp, test_names (list of strings), exit_code (integer), passed_count (integer), failed_count (integer)
• build_run: Runs a build task.
  • Required fields: id, type, timestamp, exit_code (integer)
• git_diff: Shows repository diff.
  • Required fields: id, type, timestamp, diff_hash (non-empty string), files_changed (list of strings)
• git_commit: Creates a git commit.
  • Required fields: id, type, timestamp, commit_hash (non-empty string), message (non-empty string)
• error: Signals an error execution.
  • Required fields: id, type, timestamp, message (non-empty string)
  • Optional field: related_to (non-empty string ID of the causing event, or None)
• artifact_created: Generates a file artifact.
  • Required fields: id, type, timestamp, artifact_type (non-empty string), path (non-empty string)
• requirement: Defines a system requirement.
  • Required fields: id, type, timestamp, content (non-empty string)
• constraint: Defines a system constraint.
  • Required fields: id, type, timestamp, content (non-empty string)
• verification: Asserts a verification check.
  • Required fields: id, type, timestamp, content (non-empty string), passed (boolean)

---

Prior Art / Related Work

The problem of managing long-context window limits and cost in agentic systems is an active area of research and engineering. Related approaches include:

• Provider-Native Compaction (Anthropic, OpenAI, Google): Compaction built directly into the model provider's API or agent framework — e.g. Anthropic's compact API (configurable thresholds, custom summarization prompts, available across Claude API/Bedrock/Vertex/Foundry), OpenAI's Codex-Max/Codex models trained to prune their own history as a native model objective, and Google ADK's compaction architecture. These require no separate library, but compact by having a model summarize or rewrite history — the same class of approach as "AI-Driven Summarization" below, just integrated at the provider layer instead of bolted on by the developer.
• Content-Level Compression (Headroom): Compresses the content of individual messages or tool outputs as they arrive (routing JSON, logs, or text to specialized per-type compressors, including the trained ML-based compressor Kompress) while leaving the historical conversation structure untouched to maximize provider KV-cache hits.
• Graph-based Memory Systems & Knowledge Graphs: Tools (like Cognee) that structure agent experiences as entity-relation networks rather than linear logs.
• OS-Inspired Memory Architectures: Frameworks (such as MemGPT/Letta) that treat context management analogously to operating system paging, moving data between virtual memory and disk.
• Hosted Memory & Vector Databases: SaaS platforms and databases that offer retrieval-augmented generation (RAG) and search workflows over raw text memories.
• AI-Driven Summarization: Naive LLM calls that periodically summarize history logs into shorter paragraphs.

Provider-Native Compaction vs. TraceGC

As of 2026, model providers increasingly ship compaction as a built-in feature rather than something developers bolt on themselves. This is a meaningfully different animal from TraceGC, not a competing implementation of the same idea:

• Provider-native compaction is model-driven. Whether it's an explicit summarization call (Anthropic's compact API) or a pruning behavior trained directly into the model (OpenAI's Codex-Max), the decision about what to keep is made by a model reading the history and rewriting or dropping parts of it. That is a more sophisticated version of the same "AI-Driven Summarization" category above, with the same fundamental tradeoff: it is not deterministic, output differs run to run, and (per TraceGC's own benchmark) this class of approach has historically scored well on recall but near-zero on preserving the rationale behind a decision — the exact failure mode now widely referred to in the industry as "context rot."
• TraceGC is structure-driven. It doesn't ask a model what to keep; it computes what is already provably dead — a state variable that's been overwritten, a tool call that's an exact duplicate, a branch that was explicitly abandoned — and removes only that, leaving a recoverable receipt behind. Nothing is ever summarized or paraphrased.
• These are not mutually exclusive. TraceGC is not positioned as a replacement for provider-native compaction — it's a deterministic pre-filter that can run before it. Pruning the provably-dead branches and superseded state out of a trace first means a provider's compact call (or a trained-in pruning pass) has less redundant, already-obsolete material to summarize, and fewer opportunities to accidentally summarize away something that mattered. Teams already using a provider's native compaction don't need to rip it out to adopt TraceGC — TraceGC can sit upstream of it in the pipeline.

Headroom vs. TraceGC

A primary architectural distinction exists between Headroom and TraceGC:

• Headroom compresses the content of individual messages/tool-outputs as they arrive—routing JSON/code/logs/text to per-type compressors (one of which, Kompress, uses a trained ML model, not pure determinism), and explicitly leaves prior conversation history untouched to preserve provider KV-cache hits. Headroom decides what to keep small on the way in.
• TraceGC solves a different layer: given an agent's already-accumulated structured event history, it identifies which parts are now dead (superseded, abandoned, or cyclical) and structurally removes them. TraceGC decides what should still exist at all once it is already there.

The two approaches are complementary rather than competing: Headroom shrinks new incoming tool outputs, while TraceGC prunes stale state from history. Furthermore, TraceGC's entire pipeline has zero ML/AI models anywhere, including in the pruning logic itself, whereas Headroom's is deterministic for some content types but uses a trained model for general text. Additionally, Headroom's memory-layer deduplication explicitly relies on an LLM call to judge whether two facts should be merged ('LLM-Mediated Dedup'), whereas TraceGC's deduplication is exact-match on tool name, arguments, and result — fully deterministic, with no model call anywhere in the decision.

TraceGC's Niche

TraceGC does not compete with hosted retrieval systems, general-purpose cognitive architectures, or provider-native compaction. Its niche is defined by:

1. Lightweight & Dependency-Free: It is an offline, installable Python library with zero external package dependencies.
2. Deterministic Core & Semantic Cache: It operates on structured schemas (set_var, tool_call, etc.), and optionally extracts and normalizes unstructured natural language logs into validated semantic events via a cached, incremental semantic pipeline.
3. Receipt-Based Guarantee: Unlike lossy summarization or truncation — including model-driven compaction, whether called explicitly or trained into the model — pruned elements are replaced with inline receipt stubs that guarantee the original metadata remains fully recoverable on-demand.
4. Composable Pre-Filter: Because it's deterministic and framework-agnostic, TraceGC can run upstream of a provider's own compaction step rather than requiring a choice between the two.

Benchmark Results

TraceGC was benchmarked against three alternative context-management strategies — no compaction (full_history), naive truncation (by event count and by token count), and AI-driven summarization (Gemini 3.6 Flash, single-pass and recursive) — across 9 fixtures spanning three agent types (coding, research, customer-support) and three trace lengths (short, medium, long). Each method was scored on token output, latency, determinism, and four semantic probes (recall, artifact-tracking, continuation, decision) that check whether compaction silently lost anything that mattered.

Trace Size	Method	Tokens	Recall	Artifact	Continuation	Decision	Deterministic
Short	full_history	121.0	100%	100%	100%	100%	n/a
Short	truncate_by_event_count	116.3	100%	100%	100%	100%	n/a
Short	ai_summarize_single	90.7	100%	33.3%	55.6%	0.0%	No
Short	tracegc_pipeline	75.3	100%	100%	100%	100%	Yes
Medium	full_history	379.7	100%	100%	100%	100%	n/a
Medium	truncate_by_event_count	133.3	0.0%	100%	0.0%	0.0%	n/a
Medium	ai_summarize_single	146.7	66.7%	88.9%	100%	0.0%	No
Medium	ai_summarize_recursive	131.0	0.0%	66.7%	100%	0.0%	No
Medium	tracegc_pipeline	299.0	100%	100%	100%	100%	Yes
Long	full_history	1301.0	100%	100%	100%	100%	n/a
Long	truncate_by_event_count	104.3	0.0%	0.0%	0.0%	0.0%	n/a
Long	ai_summarize_single	243.4	100%	0.0%	100%	0.0%	No
Long	ai_summarize_recursive	219.2	100%	0.0%	100%	0.0%	No
Long	tracegc_pipeline	1028.3	100%	100%	100%	100%	Yes

(Truncated for brevity above — see Comparative Benchmark Report for the full table including token-count truncation, average latencies, and per-tier breakdowns.)

Methodology Note: Exact Substring Matching

[!NOTE] The decision probe checks for exact substring survival against the original event text. This structurally favors methods that preserve verbatim text (truncate_by_event_count, truncate_by_token_count, tracegc_pipeline) over methods that paraphrase (ai_summarize_single, ai_summarize_recursive) — a correctly-summarized, semantically accurate paraphrase can score 0% on this probe even when it retains the right information in different words. We report probe scores as-is because they're deterministic and reproducible, but this benchmark measures literal information survival, not downstream answer correctness. For a test of actual downstream answer correctness (an LLM answering a real question from compacted vs. full context), see the Scenario 5 stress-test result in the Supplementary Finding: Live Answer-Quality Check section of WRITEUP.md. We have not separately investigated the low artifact-accuracy scores for AI summarization on long traces, so this caveat does not extend to that metric either — it may reflect a genuine limitation of summarization, a different measurement artifact, or something else; it is simply unexamined.

What this actually shows

Naive truncation produces the smallest output by far, but it does so by simply discarding whatever falls outside its window — recall and decision accuracy collapse to 0% on medium and long traces. It compresses by destroying information, not by understanding it.

Reproducing the Benchmark

You can reproduce the free, deterministic benchmark results locally against the exact 9 bundled trace fixtures using the CLI:

tracegc benchmark --sample

To run the benchmark against your own custom trace file (in JSON or JSONL format):

tracegc benchmark /path/to/trace.json

Add --output json to produce machine-readable JSON output instead of the default table.

AI-summarization compresses more aggressively than TraceGC on longer traces and preserves recall reasonably well, but decision accuracy is 0% across every single trace length — the rationale behind an agent's pivot from one approach to another is consistently lost in summarization. It also costs real money (~$0.0046 total across 99 calls in this benchmark), takes 4-50 seconds of added latency per call, and produces different output on every run.

TraceGC is the only method that scored 100% across all four probes on every trace length tested. Its token reduction is more conservative than the alternatives — the tradeoff is deliberate: nothing is ever truly discarded, and every pruned event remains recoverable via get_receipt(). The pitch isn't "smallest possible output" — it's "reduction with a correctness guarantee nothing else in this table has."

Known limitations of this benchmark

• Pro-tier comparison not run. Gemini Pro was unavailable (0 req/day quota) in this environment; all AI-summarization figures are Flash-tier only.
• Small sample size. 3 runs per fixture/method combination — this reflects behavior on these specific trace structures, not a broad statistical distribution.
• Unresolved anomaly: ai_summarize_recursive scored 0% recall on medium traces but recovered to 100% on long traces. No clear architectural explanation was found; this is reported as-is rather than smoothed over.
• Cycle Collapse Verification: Cycle-collapsing behavior (defensive graph loop collapsing) is verified separately under synthetic cyclic traces in tests/test_topo_sampler.py. All comparative benchmark numbers are scored against natural, un-injected event traces.

---

Limitations

• Structured Events Only: Compaction operates purely on typed, structured event inputs. TraceGC does not parse freeform natural-language prose or try to semantic-check contradictions in plain text.
• DAG Assumption: The state graph must resolve to a Directed Acyclic Graph (DAG) after the cycle collapsing stage has executed to allow topological rendering.
• API Compaction Performance: Incremental compaction is not fully incremental under the hood; it re-runs the full compaction pipeline on each .compact() call. For very long traces, this means repeated execution overhead.
• Retain Until Expiration: The retain_until event metadata field currently has no dynamic expiration mechanism (e.g. tracking when a task or session actually ends). In Phase 1, it behaves identically to permanent protection.
• Deduplication Scope: Deduplication is intentionally scoped to tool_call/tool_result pairs only. Repeated file_read, test_run, build_run, or similar coding-agent events are NOT deduplicated, even if identical — re-reading a file or re-running tests after a change represents meaningful re-verification, not redundancy, and collapsing them would remove genuine reasoning-trace context.

---

Development Setup

For local development across the package monorepo, you must install the packages in editable mode to allow correct module resolution (e.g. without manually managing PYTHONPATH).

1. Install the core tracegc package:

   pip install -e .
   

2. Install the tracegc-storage package:

   pip install -e ./tracegc-storage
   

3. Once functional implementations are added for tracegc-mcp and tracegc-langgraph, install them similarly:

   pip install -e ./tracegc-mcp
   

   pip install -e ./tracegc-langgraph