OPEN SOURCE • Apache 2.0 • ZERO DEPENDENCIES

Compress Everything, Forget Nothing

TraceGC prunes obsolete updates, aborted pipelines, and duplicate tool logs from your agent's execution history — deterministically, locally, with zero extra LLM calls. Original steps remain recoverable.

$pip install tracegc

—GitHub Stars

—GitHub Forks

Apache 2.0License

Python3.9+ Compatible

ZeroExternal Packages

Clean Dependency Profile

The core library requires no external third-party imports. Drop it cleanly into any stateful Python workflow layout.

Strict Determinism

Compaction executes locally without stochastic loops. The same input trace always compiles to the exact same prompt prefix.

Full Trace Integrity

Obsolete events scale down into receipt stubs inline. Retain original parameters inside a lightweight local data store.

The Scaling Problem

Agent Traces Grow Forever

As LLM agents loop to solve complex tasks, tool outputs, aborted logs, and temporary state mutations accumulate. Prompts hit context limits, prompts trigger high latency, and LLM confusion increases.

Interactive Compaction Sandbox

Raw Appended Trace (Chaotic Log)

e001 [decision]Start config

e002 [set_var]key="x", value=10

e003 [set_var]key="x", value=20

e004 [tool_call]run_calculator

e005 [tool_result]ans = 42

e006 [abandon]ref_to=["e007"]

e007 [set_var]key="y", value=99

Raw linear event lists are unsorted, causing redundant prompt processing overhead.

Core Engine

One Compaction Pass
Nothing Lost

TraceGC executes 5 deterministic stages locally, transforming execution graphs into clean, compacted prompt output.

Stage Trace DiffStage 1

Before Compaction

# raw events
e001 [decision] "Try search"
e002 [tool_call] "google_search"
e003 [abandon] ref_to=["e002"]

After Compaction

# pruned output
[RECEIPT e002] # Swept dead branch

Stage operations execute locally with a correctness guarantee.

Capabilities

Engineered for Precision

TraceGC bypasses lossy summaries. Every pruned byte remains retrievable.

Dynamic receipts

Receipt-Based Recovery

Pruned execution logs scale down inline into lightweight token placeholders ([RECEIPT ID]). Hover over the stubs below to simulate recovery calls:

[RECEIPT e002]

client.get_receipt("e002"){"id": "e002", "type": "set_var", "key": "x", "value": 10, "pruned": true}

→ Hover to expand get_receipt()

[RECEIPT e009]

client.get_receipt("e009"){"id": "e009", "type": "set_var", "key": "y", "value": 100, "pruned": true}

→ Hover to expand get_receipt()

Zero cost overhead

No Extra LLM Calls

Unlike LLM-based recaps that cost tokens and add latency, compaction logic executes fully locally. Free up LLM workloads and save prompt budgets.

Local DevOffline

API entry points

Incremental or Single-Shot

Initialize the TraceGC client wrapper to append logs step-by-step during live agent execution loops, or compile list payloads in batch calls.

TraceGC()compact_events()

Provider integrations

Lazy-Loaded Middlewares

Connect context compaction easily. Import optional OpenAI and Anthropic adapters (call_openai_with_compaction) that load dependencies on-demand.

openaianthropic

Data validation

Typed Event Schema

Robust validation for 18 structured event schemas, from state updates to file edits, test runs, and git operations.

Validated on append

Usage

Zero Complexity Integration

Drop context compaction directly into python loops. Code is 100% Python.

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()
print(result["prompt"])
# Output: [RECEIPT e002]
x = 20
decision: Start config

Pipeline Workflow

A Linear, Deterministic Pipeline

Hover over each element below to inspect the stages of compilation.

← Hover over pipeline blocks above for detail →

Performance

Real Data, No Hype

TraceGC does not compete with hosted vector DBs or lose content. Below are literal benchmark statistics across different trace sizes.

Trace Size	Compaction Method	Tokens	Recall	Artifact	Continuation	Decision	Deterministic
Short	full_history	121.0	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	truncate_by_event_count	133.3	0.0%	100%	0.0%	0.0%	n/a
Medium	tracegc_pipeline	299.0	100%	100%	100%	100%	Yes
Long	ai_summarize_recursive	219.2	100%	0.0%	100%	0.0%	No
Long	tracegc_pipeline	1028.3	100%	100%	100%	100%	Yes

"TraceGC's token reduction is more conservative than truncation or AI summarization. The tradeoff is deliberate — nothing is ever discarded, and every pruned event is recoverable via get_receipt(). It is the only method in this benchmark that scored 100% on all four correctness probes at every trace length."

Worked Examples

Real Case Studies

42% context reduction

Conversational Reasoning Loop

During multi-step reasoning, agents accumulate deep tree loops and trial runs. TraceGC sweeps aborted paths and redundant thoughts automatically, preserving the final clean sequence.

Compacted Log

Accumulated loops: 4,200 tokens

Post-compaction: 2,436 tokens

Correctness: 100% decision probe recall

Comparison Matrix

How TraceGC Compares

Detailed, honest comparisons with alternate agentic memory architectures.

Project Paradigm	Focus	Strength	Limitation vs. TraceGC
MemGPT / Letta	OS-style virtual context memory paging to disk	Broad framework tooling, mature agent systems	Heavier architecture. Not a zero-dependency local utility library.
Vector DB / RAG Memory	Semantic text search query over raw memories	Excellent semantic recall accuracy at scale	Requires hosted databases. Non-deterministic and lack receipts.
AI Summarization	LLM recaps that summarize linear logs periodically	Flexible summaries for natural language prose	Stochastic, adds API cost/latency, zero decision-probe score.
Knowledge Graph systems	Structuring experience as entity-relation networks	Extremely rich semantic database indexing	Typically requires LLM parsing. Heavy runtime compared to local events.

Developer Experience

Simple Execution Loop

No complex setup scripts. Just pip install and import client modules inside Python.

python3 - REPL terminal

$ pip install tracegc

Downloading tracegc-0.5.0-py3-none-any.whl (24 kB) Installing collected packages: tracegc Successfully installed tracegc-0.5.0

$ python3

Knowledgebase

Reference Documentation

Get instant answers regarding schemas, validation rules, and configuration parameters.

Core Concept

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.

FAQ

Frequently Asked Questions

Maintainers

Built in the Open

TraceGC is maintained on GitHub by the developers below.

Athish M

@athishio • Main Maintainer

View GitHub Profile →

Kamalesh T

@kamaleshio • Maintainer

View GitHub Profile →

Rohinth K V

@Rohinth-hq • Maintainer

View GitHub Profile →

Bavithiran V

@bavithiranv • Maintainer

View GitHub Profile →

Available at no charge

Integrate TraceGC

Compact event timelines deterministically. Save LLM window space and costs.

pip install tracegc[ Copy ]

Open Source

Contribute on GitHub

Read codebase sources, check test coverages, and download benchmarks.

View GitHub

Compress Everything, Forget Nothing

Clean Dependency Profile

Strict Determinism

Full Trace Integrity

Agent Traces Grow Forever

Raw Appended Trace (Chaotic Log)

One Compaction PassNothing Lost

Engineered for Precision

Receipt-Based Recovery

No Extra LLM Calls

Incremental or Single-Shot

Lazy-Loaded Middlewares

Typed Event Schema

Zero Complexity Integration

A Linear, Deterministic Pipeline

Real Data, No Hype

Real Case Studies

Conversational Reasoning Loop

How TraceGC Compares

Simple Execution Loop

Reference Documentation

Core Concept

Frequently Asked Questions

Built in the Open

Athish M

Kamalesh T

Rohinth K V

Bavithiran V

Integrate TraceGC

Contribute on GitHub

One Compaction Pass
Nothing Lost