contexa
Versioned memory for LLM agents, built on Git's branching model: observation-thought-action logs, commits, branches and merges for an agent's context, implemented in seven languages that share one .GCC/ on-disk format.
- implementations
- 7 languages
- shared format
- .GCC/ (Markdown + YAML)
- memory tiers
- 3
- context resolution
- K (default 1)
- paper
- arXiv:2508.00031
contexa implements the Git Context Controller, a structured memory system for LLM-based agents described in arXiv:2508.00031. It gives an agent a memory that survives across sessions, branches for parallel exploration, and compressed recall at any resolution. The name is a play on context and cortex.
The problem it addresses is that agents lose earlier reasoning as the context window fills. Dumping the full history, naive summarization and ad-hoc memory stores are expensive, lossy or unstructured. GCC applies Git's branching model instead.
The Git model for memory
- OTA Log is the working directory: a continuous observation, thought and action trace.
- COMMIT is a git commit: a milestone summary that compresses older OTA steps.
- BRANCH is a git branch: an isolated workspace for an alternative reasoning path.
- MERGE integrates a successful branch back into the main trajectory.
- CONTEXT is a git log: history retrieved at K-commit resolution.
The memory hierarchy
A workspace holds three tiers under a .GCC/ directory: a global roadmap in main.md, commit-level milestone summaries per branch, and fine-grained OTA traces beneath them, all as human-readable Markdown and YAML with branch metadata alongside. Because the storage is plain text, agent memory can be inspected and debugged in an editor.
Seven implementations, one format
contexa ships as a package in Python, TypeScript/JavaScript, Rust, Go, Zig, Lua and Elixir, published on PyPI, npm, crates.io, pkg.go.dev, LuaRocks and Hex. All seven read and write the same .GCC/ layout, so a workspace created in one language can be read or extended by any other. The CONTEXT call returns a formatted context block ready to inject into a prompt, and the source paper's experiments find that K=1, the most recent commit only, performs best in most benchmarks.
What the original paper reports
The GCC framework is evaluated in arXiv:2508.00031 by its authors, not in this repository. It reports 80.2% on SWE-Bench Verified with Claude 4 Sonnet and 83.4% on BrowseComp-Plus with GPT-5, with each component contributing incrementally. Those numbers belong to the paper; the contribution here is the open, cross-language implementation of the format.
The branch model
The hard part
- Seven languages, one byte-compatible format. Every implementation has to produce the same .GCC/ filesystem layout so a workspace written in one language can be read by another, which means the data model has to be pinned in each language's own idioms.
- Keeping memory human-readable. Markdown and YAML storage costs some compactness, but it makes agent memory directly inspectable, which matters more for a debugging surface.
- Deciding how much history to retrieve. The paper's finding that K=1 is optimal is counter-intuitive; making it the documented default meant trusting the evaluation over intuition.
Outcome
- Seven interoperable packages published across PyPI, npm, crates.io, pkg.go.dev, LuaRocks and Hex.
- A single .GCC/ on-disk format shared by all implementations.
- A documented command model (OTA Log, COMMIT, BRANCH, MERGE, CONTEXT) mapped onto the original paper.
- Human-readable Markdown and YAML storage that can be debugged in any editor.
- MIT-licensed and open to contributions, with a citation back to the source paper.
What I'd do differently
- Cross-language format parity is the real work. The algorithms are small; keeping seven implementations honest about one on-disk contract is what takes the effort.
- Prefer the inspectable format. Human-readable storage makes an agent's memory a debugging surface rather than a black box.
- Attribute research to its authors. The benchmark results belong to the paper, so the repository presents them as the paper's findings and keeps its own claims to the implementation.
Architecture & screenshots
More in AI / ML
OpenGrammar
Privacy-first, self-hosted writing assistant: a browser extension with a 156,000-word offline engine and more than 40 rule patterns, an AI router that only sees what local rules miss, and a Hono backend that deploys to five runtimes.
AegisVision
A multi-camera surveillance and behavioral monitoring platform that runs on ordinary hardware. It does real-time face recognition with anti-spoofing liveness checks, tracks occupancy and gate traffic, remembers where tracked assets were last seen, sends alerts, and includes an AI copilot that answers questions about the live database in plain English.