state-trace

Graph-native working memory for coding agents: typed memories, causal retrieval, bounded capacity, and compact briefs for small models.

state-trace is a bounded working-memory layer for coding and debugging agents that need the right file, failure, and next action under tight token budgets. It is not a replacement for a general-purpose temporal knowledge graph like Graphiti — see ARCHITECTURE.md for the honest comparison.

What it is optimized for:

• artifact-first retrieval for coding agents
• current-vs-stale task state (engine.current_state(), engine.failed_hypotheses())
• compact harness-facing briefs for smaller models
• online agent loops and post-hoc trajectory ingestion
• bounded memory with decay, compression, and lifecycle retention
• MCP-mountable, local-first deployment

Headline: SWE-bench-Verified localization — n=500

The credibility benchmark. Cold-start artifact localization on the full SWE-bench-Verified test split: given only the GitHub issue text and hints (no trajectory), rank the correct patch file at 1 and at 5.

pip install -e ".[bench]"
python3 examples/swebench_verified_eval.py --limit 500 --backends no_memory bm25 state_trace graphiti

What this says, plainly:

• state_trace leads on both Artifact@1 and Artifact@5 against every baseline, with non-overlapping 95% CIs across the board.
• vs. Graphiti: a wide, definitive gap (A@1 0.254 vs 0.098; A@5 0.376 vs 0.216). Non-overlapping CIs on both metrics. On the same input with the same deterministic embedder/reranker stub, the typed coding-agent ontology + cold-start lexical fallback localizes the right file and puts it in the top 5 meaningfully more often.
• vs. BM25: a consistent win with non-overlapping CIs on both A@1 (lower bound 0.218 > BM25 upper bound 0.208) and A@5 (lower bound 0.336 > BM25 upper bound 0.338). BM25's pure file-token lexical search is a strong baseline; state_trace's coding-agent ontology + module-to-path translation + GitHub-URL extraction beats it decisively on cold-start localization.
• Latency: state_trace retrieves in ~15ms vs BM25's ~0.1ms vs Graphiti's ~4,850ms. For per-action memory lookups in an agent loop, the ~320× delta over Graphiti compounds meaningfully over a long session.

v0.3.0 landed a module-to-path translator in retrieve_brief's lexical fallback: dotted Python module references in issue text (astropy.modeling.separable_matrix) now resolve to file path candidates (astropy/modeling/separable.py), which pushed A@1 from 0.216 → 0.254 on n=500.

Caveats

• Graphiti is run with a deterministic hash-embedder and BM25 + cosine + BFS → RRF reranker (no LLM entity extraction). That's the same simplification graphiti_head_to_head_eval.py uses for reproducibility without API keys. A full Graphiti pipeline with GPT-4-class extraction might close some of the gap, at materially higher cost per ingest.
• Cold-start localization from issue text is only one axis. Trajectory-informed retrieval (BENCHMARKS.md) is where state_trace's larger advantage lives.

Live solve-rate — n=20 with Codex CLI + swebench docker harness

Localization leads need to be converted into downstream solve wins to matter. Running the actual swebench test suite on patches Codex CLI produces with vs. without a state-trace brief:

| arm | resolved | unresolved | errored | solve-rate | | ---

... View full README on GitHub