cortexa

Git-inspired context management for LLM agents. COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.

Rust implementation of the cortexa framework.

Based on: arXiv:2508.00031 -- "Git Context Controller: Manage the Context of LLM-based Agents like Git" (Junde Wu et al., 2025)

Installation

[dependencies]
cortexa = "0.1"

Quick Start

use cortexa::GCCWorkspace;

fn main() -> cortexa::Result<()> {
    let mut ws = GCCWorkspace::new("/path/to/project");
    ws.init("Build a REST API service with user auth")?;

    ws.log_ota(
        "Project directory is empty",
        "Need to scaffold the project structure first",
        "create_files(['main.rs', 'Cargo.toml', 'models.rs'])",
    )?;

    ws.commit("Project scaffold and User model complete", None, None)?;

    ws.branch("auth-jwt", "Explore JWT-based authentication")?;
    ws.log_ota("Reading JWT docs", "JWT is stateless", "implement_jwt()")?;
    ws.commit("JWT auth middleware implemented", None, None)?;

    ws.merge("auth-jwt", None, "main")?;

    let ctx = ws.context(None, 1)?; // K=1: paper default
    println!("{}", ctx.summary());

    Ok(())
}

Core Concepts

OTA Logging (Observation-Thought-Action)

let rec = ws.log_ota(
    "API returns 500 error on /users endpoint",
    "The database connection might not be initialized",
    "check_db_connection()",
)?;
println!("Step: {}", rec.step);           // 1 (auto-incremented)
println!("Timestamp: {}", rec.timestamp); // RFC3339

COMMIT -- Save Milestones

let commit = ws.commit(
    "Fixed database connection, /users now returns 200",
    None,                                        // previous summary auto-populated
    Some("Database layer stable, move to auth"), // optional roadmap update
)?;
assert_eq!(commit.commit_id.len(), 8);
assert_eq!(commit.branch_name, "main");

BRANCH -- Explore Alternatives

ws.branch("redis-cache", "Try Redis caching instead of in-memory")?;
ws.log_ota("Redis docs reviewed", "Need redis crate", "cargo add redis")?;
ws.commit("Redis caching layer implemented", None, None)?;

assert_eq!(ws.current_branch(), "redis-cache");
println!("{:?}", ws.list_branches()); // ["main", "redis-cache"]

MERGE -- Integrate Results

let merge_commit = ws.merge("redis-cache", None, "main")?;
// Appends branch OTA trace to main's log
// Creates a merge commit on main
// Marks branch as "merged" in metadata
assert_eq!(ws.current_branch(), "main");

CONTEXT -- Retrieve History

let ctx = ws.context(None, 1)?; // K=1: paper default

println!("{}", ctx.branch_name);  // "main"
println!("{}", ctx.main_roadmap); // Global project roadmap
println!("{:?}", ctx.commits);    // Last K CommitRecords
println!("{:?}", ctx.ota_records); // All OTA records
println!("{:?}", ctx.metadata);   // BranchMetadata

// Formatted markdown summary for LLM prompt injection
println!("{}", ctx.summary());

API Overview

GCCWorkspace

Data Models

Directory Structure

your-project/
  .GCC/
    main.md                          # Global roadmap
    branches/
      main/
        log.md                       # Continuous OTA trace
        commit.md                    # Milestone-level summaries
        metadata.yaml                # Branch intent & status
      feature-branch/
        log.md
        commit.md
        metadata.yaml

All data is stored as human-readable Markdown and YAML.

Running Tests

git clone https://github.com/swadhinbiswas/Cortexa.git
cd cortexa/RUST
cargo test

8 tests + 1 doc-test cover all GCC commands.

Dependencies

• serde + serde_yaml -- YAML serialization for branch metadata
• chrono -- UTC timestamps (RFC3339)
• uuid -- Commit ID generation (v4 UUIDs, first 8 chars)
• thiserror -- Ergonomic error types

License

MIT License. See LICENSE for details.

Citation

@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.00031},
  year={2025}
}

Links

• GitHub Repository
• crates.io
• docs.rs
• Original Paper
• Author: Swadhin Biswas