Versioned memory for AI agents
A brain-inspired context management system based on Git's branching model
Contexa implements the Git Context Controller (GCC) -- a structured, versioned memory system for LLM-based agents. A play on "context" and "cortex", it gives agents a persistent brain that survives across sessions, branches for parallel exploration, and compressed recall at any resolution.
Available in Python, TypeScript/JavaScript, Rust, Go, Zig, Lua, and Elixir. All 7 implementations produce the same .GCC/ on-disk format (Markdown + YAML) and are fully interoperable.
LLM agents lose track of earlier reasoning as context windows fill up. Current workarounds -- full history dumps, naive summarization, or ad-hoc memory stores -- are expensive, lossy, or unstructured.
GCC applies Git's proven branching model to agent memory:
| GCC Command | Git Analogy | What It Does |
|---|---|---|
| OTA Log | Working directory | Continuous Observation-Thought-Action trace |
| COMMIT | git commit |
Milestone summary that compresses older OTA steps |
| BRANCH | git branch |
Isolated workspace for alternative reasoning paths |
| MERGE | git merge |
Integrates a successful branch back into the main trajectory |
| CONTEXT | git log |
Retrieves history at K-commit resolution |
The GCC framework achieves state-of-the-art results:
| Benchmark | Score | Model |
|---|---|---|
| SWE-Bench Verified | 80.2% | Claude 4 Sonnet |
| BrowseComp-Plus | 83.4% | GPT-5 |
Outperforms 26 existing open and commercial agent systems. Key findings:
- K=1 (most recent commit only) performs best in most benchmarks
- Each component contributes: RoadMap+COMMIT (69.1%) -> +Logs+CONTEXT (75.3%) -> +Metadata (77.8%) -> +BRANCH&MERGE (80.2%)
- Agents with GCC allocate more computation (more tool calls) but achieve better cost-efficiency
.GCC/
main.md # Tier 1: Global roadmap / planning artifact
branches/
main/
commit.md # Tier 2: Commit-level milestone summaries
log.md # Tier 3: Fine-grained OTA traces
metadata.yaml # Branch intent, status, provenance
experiment/
commit.md
log.md
metadata.yaml
| Language | Package | Install |
|---|---|---|
| Python | contexa |
pip install contexa |
| TypeScript/JS | contexa |
npm install contexa |
| Rust | contexa |
cargo add contexa |
| Go | contexa |
go get github.com/swadhinbiswas/contexa/GO/contexa |
| Lua | contexa |
luarocks install contexa |
| Elixir | contexa |
{:contexa, "~> 0.1.1"} in mix.exs |
| Zig | contexa |
See Zig README |
All 7 packages produce the same .GCC/ file system layout. A workspace created by one language can be read or extended by any other.
from contexa import GCCWorkspace
ws = GCCWorkspace("/path/to/project")
ws.init("Build a REST API with user auth")
# Agent logs its reasoning
ws.log_ota("saw empty dir", "scaffold first", "create_files()")
ws.log_ota("files created", "implement user model", "write_code('models.py')")
ws.commit("Project scaffold and User model complete")
# Branch to explore alternatives
ws.branch("auth-jwt", "Explore JWT authentication")
ws.log_ota("JWT docs reviewed", "stateless, good for APIs", "implement_jwt()")
ws.commit("JWT auth middleware implemented")
# Merge and retrieve context
ws.merge("auth-jwt")
ctx = ws.context(k=1) # K=1: paper's recommended default
print(ctx.summary()) # Formatted markdown ready for LLM prompt injectionimport { GCCWorkspace } from "contexa";
const ws = new GCCWorkspace("/path/to/project");
ws.init("Build a REST API");
ws.logOTA("saw empty dir", "scaffold first", "createFiles()");
ws.commit("Project scaffold done");
ws.branch("auth-jwt", "Explore JWT authentication");
ws.commit("JWT middleware implemented");
ws.merge("auth-jwt");
const ctx = ws.context(undefined, 1);
console.log(ctx.summary());use contexa::GCCWorkspace;
let mut ws = GCCWorkspace::new("/path/to/project");
ws.init("Build a REST API")?;
ws.log_ota("saw empty dir", "scaffold first", "create_files()")?;
ws.commit("Project scaffold done", None, None)?;
ws.branch("auth-jwt", "Explore JWT authentication")?;
ws.commit("JWT middleware implemented", None, None)?;
ws.merge("auth-jwt", None, "main")?;
let ctx = ws.context(None, 1)?;
println!("{}", ctx.summary());import "github.com/swadhinbiswas/contexa/GO/contexa"
ws := contexa.New("/path/to/project")
ws.Init("Build a REST API")
ws.LogOTA("saw empty dir", "scaffold first", "createFiles()")
ws.Commit("Project scaffold done", nil, nil)
ws.Branch("auth-jwt", "Explore JWT authentication")
ws.Commit("JWT middleware implemented", nil, nil)
ws.Merge("auth-jwt", nil, "main")
ctx, _ := ws.Context(nil, 1)
fmt.Println(ctx.Summary())const contexa = @import("contexa");
var ws = contexa.Workspace.init(allocator, "/path/to/project");
try ws.create("Build a REST API");
_ = try ws.logOTA("saw empty dir", "scaffold first", "createFiles()");
const c = try ws.commit("Project scaffold done", null);
defer allocator.free(c.commit_id);
try ws.branch("auth-jwt", "Explore JWT authentication");
const c2 = try ws.commit("JWT middleware implemented", null);
defer allocator.free(c2.commit_id);
const mc = try ws.merge("auth-jwt", "main");
defer allocator.free(mc.commit_id);
const ctx = try ws.context(null, 1);
defer ctx.deinit(allocator);local contexa = require("contexa")
local ws = contexa.GCCWorkspace.new("/path/to/project")
ws:init("Build a REST API")
ws:log_ota("saw empty dir", "scaffold first", "create_files()")
ws:commit("Project scaffold done")
ws:branch("auth-jwt", "Explore JWT authentication")
ws:commit("JWT middleware implemented")
ws:merge("auth-jwt", nil, "main")
local ctx = ws:context("main", 1)
print(contexa.context_summary(ctx))alias Contexa.{Workspace, Models}
ws = Workspace.new("/path/to/project")
ws = Workspace.init(ws, "Build a REST API")
{ws, _} = Workspace.log_ota(ws, "saw empty dir", "scaffold first", "create_files()")
{ws, _} = Workspace.commit(ws, "Project scaffold done")
ws = Workspace.branch(ws, "auth-jwt", "Explore JWT authentication")
{ws, _} = Workspace.commit(ws, "JWT middleware implemented")
{ws, _} = Workspace.merge(ws, "auth-jwt", nil, "main")
ctx = Workspace.context(ws, "main", 1)
IO.puts(Models.context_summary(ctx)) main
|
init --> OTA --> COMMIT --> COMMIT ---------> MERGE <--+
| |
BRANCH --> OTA --> COMMIT --+
(experiment)
CONTEXT(k=1) returns: roadmap + last commit + current OTA log
The CONTEXT command controls how much history the agent sees. The paper's experiments show K=1 (most recent commit only) is optimal -- agents perform better with compressed recent context than with full history dumps.
| Model | Description | Key Fields |
|---|---|---|
| OTARecord | Single Observation-Thought-Action cycle | step, timestamp, observation, thought, action |
| CommitRecord | Milestone checkpoint | commit_id, branch_name, branch_purpose, previous_progress_summary, this_commit_contribution, timestamp |
| BranchMetadata | Branch intent and status | name, purpose, created_from, created_at, status, merged_into, merged_at |
| ContextResult | CONTEXT retrieval result | branch_name, k, commits, ota_records, main_roadmap, metadata |
All data is stored as human-readable Markdown and YAML -- inspect and debug agent memory directly in your editor.
Contexa/
PYTHON/ # PyPI: contexa (Python 3.10+)
JS/ # npm: contexa (Node.js 18+)
RUST/ # crates.io: contexa (Rust stable)
GO/ # pkg.go.dev (Go 1.21+)
ZIG/ # Zig package (Zig 0.14+)
LUA/ # LuaRocks: contexa (Lua 5.1+)
ELIXIR/ # Hex.pm: contexa (Elixir 1.15+)
assets/ # Logo and visual assets
Each directory is an independent package with its own build tooling, tests, and README.
See CONTRIBUTING.md for development setup, testing instructions, and guidelines.
- Fork the repository
- Create a feature branch:
git checkout -b feat/my-change - Make your changes and add tests
- Run the test suite for your language
- Submit a pull request
MIT License. See LICENSE for details.
If you use Contexa in research, please cite the original paper:
@article{wu2025gcc,
title={Git Context Controller: Manage the Context of LLM-based Agents like Git},
author={Wu, Junde and others},
journal={arXiv preprint arXiv:2508.00031v2},
year={2025}
}