cortexa

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

Go 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

go get github.com/swadhinbiswas/Cortexa/GO/cortexa

Quick Start

package main

import (
    "fmt"
    "github.com/swadhinbiswas/Cortexa/GO/cortexa"
)

func main() {
    ws := cortexa.New("/path/to/project")
    if err := ws.Init("Build a REST API service with user auth"); err != nil {
        panic(err)
    }

    ws.LogOTA(
        "Project directory is empty",
        "Need to scaffold the project structure first",
        "create_files(['main.go', 'go.mod', 'models.go'])",
    )

    ws.Commit("Project scaffold and User model complete", nil, nil)

    ws.Branch("auth-jwt", "Explore JWT-based authentication")
    ws.LogOTA("Reading JWT docs", "JWT is stateless", "implementJWT()")
    ws.Commit("JWT auth middleware implemented", nil, nil)

    ws.Merge("auth-jwt", nil, "main")

    ctx, _ := ws.Context(nil, 1) // K=1: paper default
    fmt.Println(ctx.Summary())
}

Core Concepts

OTA Logging (Observation-Thought-Action)

rec, err := ws.LogOTA(
    "API returns 500 error on /users endpoint",
    "The database connection might not be initialized",
    "checkDbConnection()",
)
fmt.Println(rec.Step)      // 1 (auto-incremented)
fmt.Println(rec.Timestamp) // RFC3339 timestamp

COMMIT -- Save Milestones

commit, err := ws.Commit(
    "Fixed database connection, /users returns 200",
    nil, // previous summary auto-populated from last commit
    nil, // optional roadmap update
)
fmt.Println(commit.CommitID)   // "a3f2b1c4" (8-char hex)
fmt.Println(commit.BranchName) // "main"

BRANCH -- Explore Alternatives

ws.Branch("redis-cache", "Try Redis caching instead of in-memory")
ws.LogOTA("Redis docs reviewed", "Need redis package", "goGet('redis')")
ws.Commit("Redis caching layer implemented", nil, nil)

fmt.Println(ws.CurrentBranch()) // "redis-cache"
branches, _ := ws.ListBranches()
fmt.Println(branches) // ["main", "redis-cache"]

MERGE -- Integrate Results

mergeCommit, err := ws.Merge("redis-cache", nil, "main")
// Appends branch OTA trace to main's log
// Creates a merge commit on main
// Marks branch as "merged" in metadata
fmt.Println(ws.CurrentBranch()) // "main"

CONTEXT -- Retrieve History

ctx, err := ws.Context(nil, 1) // K=1: paper default

fmt.Println(ctx.BranchName)  // "main"
fmt.Println(ctx.MainRoadmap) // Global project roadmap
fmt.Println(ctx.Commits)     // Last K CommitRecords
fmt.Println(ctx.OTARecords)  // All OTA records
fmt.Println(ctx.Metadata)    // *BranchMetadata

// Formatted markdown summary for LLM prompt injection
fmt.Println(ctx.Summary())

API Overview

Workspace

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/GO
go test -v ./cortexa/

20 tests cover all GCC commands: init, OTA logging, commit, branch, merge, context, switch, list, and model serialization.

Requirements

• Go >= 1.21
• gopkg.in/yaml.v3 -- YAML serialization for branch metadata

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
• pkg.go.dev
• Original Paper
• Author: Swadhin Biswas