chore: rename cortexa to contexa globally

Swadhin Biswas committed 7 months ago
6f0cfba
1 parent d4819a8
commit 6f0cfba
55 files changed
+282 -268
▼.github/ISSUE_TEMPLATE/bug_report.yml
+3-3
1
1
name: Bug Report
2
-description: Report a bug in cortexa
2
+description: Report a bug in contexa
3
3
title: "[Bug]: "
4
4
labels: ["bug"]
5
5
body:
29
29
id: version
30
30
attributes:
31
31
label: Package Version
32
- description: "Which version of cortexa are you using? (e.g. 0.1.1)"
32
+ description: "Which version of contexa are you using? (e.g. 0.1.1)"
33
33
placeholder: "0.1.1"
34
34
validations:
35
35
required: true
106
106
options:
107
107
- label: I have searched existing issues and this hasn't been reported before
108
108
required: true
109
- - label: I am using the latest version of cortexa
109
+ - label: I am using the latest version of contexa
110
110
required: false
111
111
▼.github/ISSUE_TEMPLATE/config.yml
+1-1
1
1
blank_issues_enabled: false
2
2
contact_links:
3
3
- name: Documentation
4
- url: https://github.com/swadhinbiswas/Cortexa#readme
4
+ url: https://github.com/swadhinbiswas/Contexa#readme
5
5
about: Read the documentation before opening an issue
6
6
- name: Paper (arXiv)
7
7
url: https://arxiv.org/abs/2508.00031
8
8
▼.github/ISSUE_TEMPLATE/feature_request.yml
+1-1
1
1
name: Feature Request
2
-description: Suggest a new feature or enhancement for cortexa
2
+description: Suggest a new feature or enhancement for contexa
3
3
title: "[Feature]: "
4
4
labels: ["enhancement"]
5
5
body:
6
6
▼.github/ISSUE_TEMPLATE/question.yml
+2-2
1
1
name: Question
2
-description: Ask a question about using cortexa
2
+description: Ask a question about using contexa
3
3
title: "[Question]: "
4
4
labels: ["question"]
5
5
body:
6
6
- type: markdown
7
7
attributes:
8
8
value: |
9
- Have a question about using cortexa? Ask below. For bugs, please use the Bug Report template instead.
9
+ Have a question about using contexa? Ask below. For bugs, please use the Bug Report template instead.
10
10
11
11
- type: dropdown
12
12
id: language
13
13
▼.github/workflows/ci.yml
+1-1
117
117
run: go build ./...
118
118
119
119
- name: Run tests
120
- run: go test -v ./cortexa/
120
+ run: go test -v ./contexa/
121
121
122
122
# ── Zig ─────────────────────────────────────────────────────────────
123
123
test-zig:
124
124
▼.github/workflows/publish.yml
+10-10
81
81
cache-dependency-path: GO/go.sum
82
82
- run: go mod download
83
83
- run: go build ./...
84
- - run: go test -v ./cortexa/
84
+ - run: go test -v ./contexa/
85
85
86
86
test-zig:
87
87
name: Test Zig
227
227
- name: Publish to LuaRocks
228
228
env:
229
229
LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}
230
- run: luarocks upload cortexa-1.1.2-1.rockspec
230
+ run: luarocks upload contexa-1.1.2-1.rockspec
231
231
--api-key="$LUAROCKS_API_KEY" --force
232
232
233
233
# ── Publish Elixir to Hex.pm ────────────────────────────────────────
285
285
TAG="${{ steps.version.outputs.version }}"
286
286
{
287
287
echo "notes<<EOF"
288
- echo "## cortexa $TAG"
288
+ echo "## contexa $TAG"
289
289
echo ""
290
290
echo "Git-inspired context management for LLM agents — COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace."
291
291
echo ""
293
293
echo ""
294
294
echo "| Language | Command |"
295
295
echo "|----------|---------|"
296
- echo "| Python | \`pip install cortexa\` |"
297
- echo "| JS/TS | \`npm install cortexa\` |"
298
- echo "| Rust | \`cargo add cortexa\` |"
299
- echo "| Go | \`go get github.com/swadhinbiswas/cortexa/GO/cortexa@v$TAG\` |"
300
- echo "| Lua | \`luarocks install cortexa\` |"
301
- echo "| Elixir | \`{:cortexa, \"~> 1.1.3\"}\` in mix.exs |"
296
+ echo "| Python | \`pip install contexa\` |"
297
+ echo "| JS/TS | \`npm install contexa\` |"
298
+ echo "| Rust | \`cargo add contexa\` |"
299
+ echo "| Go | \`go get github.com/swadhinbiswas/contexa/GO/contexa@v$TAG\` |"
300
+ echo "| Lua | \`luarocks install contexa\` |"
301
+ echo "| Elixir | \`{:contexa, \"~> 1.1.3\"}\` in mix.exs |"
302
302
echo "| Zig | Add dependency via \`build.zig.zon\` (see README) |"
303
303
echo ""
304
304
echo "### Changes"
312
312
uses: softprops/action-gh-release@v2
313
313
with:
314
314
tag_name: ${{ steps.version.outputs.version }}
315
- name: "cortexa ${{ steps.version.outputs.version }}"
315
+ name: "contexa ${{ steps.version.outputs.version }}"
316
316
body: ${{ steps.notes.outputs.notes }}
317
317
draft: false
318
318
prerelease: ${{ contains(steps.version.outputs.version, '-') }}
319
319
▼CONTRIBUTING.md
+7-7
1
-# Contributing to cortexa
1
+# Contributing to contexa
2
2
3
-Thank you for your interest in contributing to **cortexa** — git-inspired context management for LLM agents.
3
+Thank you for your interest in contributing to **contexa** — git-inspired context management for LLM agents.
4
4
5
5
This is a polyglot monorepo with implementations in **Python, JavaScript/TypeScript, Rust, Go, Zig, Lua, and Elixir**. Contributions to any language are welcome.
6
6
20
20
21
21
## Getting Started
22
22
23
-1. Fork the repository: <https://github.com/swadhinbiswas/cortexa>
23
+1. Fork the repository: <https://github.com/swadhinbiswas/contexa>
24
24
2. Clone your fork:
25
25
```bash
26
- git clone https://github.com/<your-username>/cortexa.git
27
- cd cortexa
26
+ git clone https://github.com/<your-username>/contexa.git
27
+ cd contexa
28
28
```
29
29
3. Create a feature branch:
30
30
```bash
131
131
- **Rust**: Run `cargo fmt` and `cargo clippy` before committing.
132
132
- **Go**: Run `gofmt` and `go vet`.
133
133
- **Zig**: Follow the [Zig style guide](https://ziglang.org/documentation/master/#Style-Guide).
134
-- **Lua**: Follow the existing style in `LUA/cortexa/`.
134
+- **Lua**: Follow the existing style in `LUA/contexa/`.
135
135
- **Elixir**: Run `mix format` before committing.
136
136
137
137
## Labels
164
164
165
165
---
166
166
167
-If you have questions, feel free to [open a discussion](https://github.com/swadhinbiswas/cortexa/issues/new?template=question.yml) or reach out to [@swadhinbiswas](https://github.com/swadhinbiswas).
167
+If you have questions, feel free to [open a discussion](https://github.com/swadhinbiswas/contexa/issues/new?template=question.yml) or reach out to [@swadhinbiswas](https://github.com/swadhinbiswas).
168
168
▼DOCS/README.md
+3-3
1
-# Cortexa Documentation
1
+# Contexa Documentation
2
2
3
-This folder contains the web-based documentation for Cortexa.
3
+This folder contains the web-based documentation for Contexa.
4
4
5
5
## Viewing the Documentation
6
6
16
16
Or directly open the file in your browser:
17
17
18
18
```
19
-file:///path/to/cortexa/DOCS/index.html
19
+file:///path/to/contexa/DOCS/index.html
20
20
```
21
21
22
22
## Features
23
23
▼DOCS/index.html
+18-18
3
3
<head>
4
4
<meta charset="UTF-8">
5
5
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6
- <title>Cortexa - Git-Inspired Context Management for LLM Agents</title>
6
+ <title>Contexa - Git-Inspired Context Management for LLM Agents</title>
7
7
<link rel="preconnect" href="https://fonts.googleapis.com">
8
8
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
9
9
<link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
483
483
<nav>
484
484
<div class="logo">
485
485
<div class="logo-icon">🧠</div>
486
- <span>Cortexa</span>
486
+ <span>Contexa</span>
487
487
</div>
488
488
<ul class="nav-links">
489
489
<li><a href="#features">Features</a></li>
498
498
499
499
<section class="hero">
500
500
<div class="container">
501
- <h1 class="animate-in">Cortexa</h1>
501
+ <h1 class="animate-in">Contexa</h1>
502
502
<p class="tagline animate-in delay-1">Versioned Memory for AI Agents</p>
503
503
<p class="description animate-in delay-2">
504
504
Git-inspired context management for LLM agents. COMMIT, BRANCH, MERGE, and CONTEXT
509
509
<a href="#install" class="btn btn-primary">
510
510
📦 Install Now
511
511
</a>
512
- <a href="https://github.com/swadhinbiswas/cortexa" class="btn btn-secondary">
512
+ <a href="https://github.com/swadhinbiswas/contexa" class="btn btn-secondary">
513
513
⭐ GitHub
514
514
</a>
515
515
</div>
516
516
517
517
<div class="code-block animate-in delay-4">
518
518
<span class="comment"># Python example - Give your agent memory</span><br>
519
- <span class="keyword">from</span> cortexa <span class="keyword">import</span> GCCWorkspace<br><br>
519
+ <span class="keyword">from</span> contexa <span class="keyword">import</span> GCCWorkspace<br><br>
520
520
ws = GCCWorkspace(<span class="string">"/project"</span>)<br>
521
521
ws.init(<span class="string">"Build a REST API"</span>)<br>
522
522
ws.log_ota(<span class="string">"Empty dir"</span>, <span class="string">"Scaffold first"</span>, <span class="string">"create files"</span>)<br>
646
646
647
647
<section class="install" id="install">
648
648
<div class="container">
649
- <h2 class="section-title">Install Cortexa</h2>
649
+ <h2 class="section-title">Install Contexa</h2>
650
650
<p class="section-subtitle">Choose your language</p>
651
651
652
652
<div class="install-tabs">
660
660
</div>
661
661
662
662
<div id="install-python" class="install-code">
663
- <span class="prompt">$</span> <span class="command">pip install cortexa</span>
663
+ <span class="prompt">$</span> <span class="command">pip install contexa</span>
664
664
</div>
665
665
<div id="install-js" class="install-code" style="display: none;">
666
- <span class="prompt">$</span> <span class="command">npm install cortexa</span>
666
+ <span class="prompt">$</span> <span class="command">npm install contexa</span>
667
667
</div>
668
668
<div id="install-rust" class="install-code" style="display: none;">
669
- <span class="prompt">$</span> <span class="command">cargo add cortexa</span>
669
+ <span class="prompt">$</span> <span class="command">cargo add contexa</span>
670
670
</div>
671
671
<div id="install-go" class="install-code" style="display: none;">
672
- <span class="prompt">$</span> <span class="command">go get github.com/swadhinbiswas/cortexa/GO/cortexa</span>
672
+ <span class="prompt">$</span> <span class="command">go get github.com/swadhinbiswas/contexa/GO/contexa</span>
673
673
</div>
674
674
<div id="install-lua" class="install-code" style="display: none;">
675
- <span class="prompt">$</span> <span class="command">luarocks install cortexa</span>
675
+ <span class="prompt">$</span> <span class="command">luarocks install contexa</span>
676
676
</div>
677
677
<div id="install-elixir" class="install-code" style="display: none;">
678
678
<span class="prompt"># Add to mix.exs:</span><br>
679
- <span class="command">{:cortexa, "~> 1.1.3"}</span>
679
+ <span class="command">{:contexa, "~> 1.1.3"}</span>
680
680
</div>
681
681
<div id="install-zig" class="install-code" style="display: none;">
682
682
<span class="prompt"># Add to build.zig.zon:</span><br>
683
683
<span class="command">.dependencies = .{</span><br>
684
- <span class="command"> .cortexa = .{.path = "../cortexa"},</span><br>
684
+ <span class="command"> .contexa = .{.path = "../contexa"},</span><br>
685
685
<span class="command">}</span>
686
686
</div>
687
687
</div>
742
742
<footer>
743
743
<div class="container">
744
744
<div class="footer-links">
745
- <a href="https://github.com/swadhinbiswas/cortexa">GitHub</a>
745
+ <a href="https://github.com/swadhinbiswas/contexa">GitHub</a>
746
746
<a href="https://arxiv.org/abs/2508.00031">Paper</a>
747
- <a href="https://pypi.org/project/cortexa/">PyPI</a>
748
- <a href="https://www.npmjs.com/package/cortexa">npm</a>
749
- <a href="https://crates.io/crates/cortexa">crates.io</a>
747
+ <a href="https://pypi.org/project/contexa/">PyPI</a>
748
+ <a href="https://www.npmjs.com/package/contexa">npm</a>
749
+ <a href="https://crates.io/crates/contexa">crates.io</a>
750
750
</div>
751
- <p>© 2025 Cortexa. MIT License.</p>
751
+ <p>© 2025 Contexa. MIT License.</p>
752
752
<p style="margin-top: 0.5rem; font-size: 0.875rem;">
753
753
Based on <a href="https://arxiv.org/abs/2508.00031">Git Context Controller</a> by Junde Wu et al.
754
754
</p>
755
755
▼ELIXIR/README.md
+6-4
1
-# cortexa — Elixir
1
+# contexa — Elixir
2
2
3
3
Git-inspired context management for LLM agents — **COMMIT**, **BRANCH**, **MERGE**, and **CONTEXT** operations over a persistent versioned memory workspace.
4
4
5
5
Based on the paper *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* ([arXiv:2508.00031](https://arxiv.org/abs/2508.00031)).
6
6
7
+> **Note:** For full usage examples, cross-language interoperability, and the complete architecture, please see the [main Contexa repository README](https://github.com/swadhinbiswas/contexa).
8
+
7
9
## Install
8
10
9
11
Add to your `mix.exs`:
11
13
```elixir
12
14
def deps do
13
15
[
14
- {:cortexa, "~> 0.1.1"}
16
+ {:contexa, "~> 0.1.1"}
15
17
]
16
18
end
17
19
```
19
21
## Quick Start
20
22
21
23
```elixir
22
-alias Cortexa.{Workspace, Models}
24
+alias Contexa.{Workspace, Models}
23
25
24
26
# Create workspace
25
27
ws = Workspace.new("/tmp/my-project")
46
48
47
49
## API
48
50
49
-### `Cortexa.Workspace`
51
+### `Contexa.Workspace`
50
52
51
53
| Function | Description |
52
54
|----------|-------------|
53
55
▼ELIXIR/lib/contexa.ex
+22-0
1
+defmodule Contexa do
2
+ @moduledoc """
3
+ contexa — Git-inspired context management for LLM agents.
4
+
5
+ COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent
6
+ versioned memory workspace. Based on arXiv:2508.00031.
7
+
8
+ ## Quick Start
9
+
10
+ ws = Contexa.Workspace.new("/tmp/my-project")
11
+ ws = Contexa.Workspace.init(ws, "Build an AI agent")
12
+
13
+ {ws, _ota} = Contexa.Workspace.log_ota(ws, "Observed X", "Thinking Y", "Did Z")
14
+ {ws, _commit} = Contexa.Workspace.commit(ws, "Implemented feature")
15
+
16
+ ws = Contexa.Workspace.branch(ws, "explore", "Try alternative approach")
17
+ {ws, _commit} = Contexa.Workspace.merge(ws, "explore")
18
+
19
+ ctx = Contexa.Workspace.context(ws, "main", 3)
20
+ IO.puts(Contexa.Models.context_summary(ctx))
21
+ """
22
+end
0
23
▼ELIXIR/lib/cortexa/models.ex → ELIXIR/lib/contexa/models.ex
+3-3
1
-defmodule Cortexa.Models do
1
+defmodule Contexa.Models do
2
2
@moduledoc """
3
- Data structures for the cortexa GCC workspace.
3
+ Data structures for the contexa GCC workspace.
4
4
5
- cortexa — Git-inspired context management for LLM agents.
5
+ contexa — Git-inspired context management for LLM agents.
6
6
Based on arXiv:2508.00031.
7
7
"""
8
8
9
9
▼ELIXIR/lib/cortexa/workspace.ex → ELIXIR/lib/contexa/workspace.ex
+4-4
1
-defmodule Cortexa.Workspace do
1
+defmodule Contexa.Workspace do
2
2
@moduledoc """
3
3
GCCWorkspace — persistent versioned memory workspace for LLM agents.
4
4
5
- cortexa — Git-inspired context management.
5
+ contexa — Git-inspired context management.
6
6
Based on arXiv:2508.00031.
7
7
"""
8
8
9
- alias Cortexa.Models
10
- alias Cortexa.Models.{OTARecord, CommitRecord, ContextResult}
9
+ alias Contexa.Models
10
+ alias Contexa.Models.{OTARecord, CommitRecord, ContextResult}
11
11
12
12
@main_branch "main"
13
13
@gcc_dir ".GCC"
14
14
▼ELIXIR/lib/cortexa.ex
+0-22
1
-defmodule Cortexa do
2
- @moduledoc """
3
- cortexa — Git-inspired context management for LLM agents.
4
-
5
- COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent
6
- versioned memory workspace. Based on arXiv:2508.00031.
7
-
8
- ## Quick Start
9
-
10
- ws = Cortexa.Workspace.new("/tmp/my-project")
11
- ws = Cortexa.Workspace.init(ws, "Build an AI agent")
12
-
13
- {ws, _ota} = Cortexa.Workspace.log_ota(ws, "Observed X", "Thinking Y", "Did Z")
14
- {ws, _commit} = Cortexa.Workspace.commit(ws, "Implemented feature")
15
-
16
- ws = Cortexa.Workspace.branch(ws, "explore", "Try alternative approach")
17
- {ws, _commit} = Cortexa.Workspace.merge(ws, "explore")
18
-
19
- ctx = Cortexa.Workspace.context(ws, "main", 3)
20
- IO.puts(Cortexa.Models.context_summary(ctx))
21
- """
22
-end
23
0
▼ELIXIR/mix.exs
+4-4
1
-defmodule Cortexa.MixProject do
1
+defmodule Contexa.MixProject do
2
2
use Mix.Project
3
3
4
4
@version "1.1.2"
5
- @source_url "https://github.com/swadhinbiswas/Cortexa"
5
+ @source_url "https://github.com/swadhinbiswas/contexa"
6
6
7
7
def project do
8
8
[
9
- app: :cortexa,
9
+ app: :contexa,
10
10
version: @version,
11
11
elixir: "~> 1.14",
12
12
start_permanent: Mix.env() == :prod,
45
45
46
46
defp package do
47
47
[
48
- name: "cortexa",
48
+ name: "contexa",
49
49
licenses: ["MIT"],
50
50
links: %{
51
51
"GitHub" => @source_url,
52
52
▼ELIXIR/test/models_test.exs
+3-3
1
-defmodule Cortexa.ModelsTest do
1
+defmodule Contexa.ModelsTest do
2
2
use ExUnit.Case, async: true
3
3
4
- alias Cortexa.Models
5
- alias Cortexa.Models.{OTARecord, CommitRecord, BranchMetadata}
4
+ alias Contexa.Models
5
+ alias Contexa.Models.{OTARecord, CommitRecord, BranchMetadata}
6
6
7
7
test "generate_id returns 8 hex chars" do
8
8
id = Models.generate_id()
9
9
▼ELIXIR/test/workspace_test.exs
+4-4
1
-defmodule Cortexa.WorkspaceTest do
1
+defmodule Contexa.WorkspaceTest do
2
2
use ExUnit.Case, async: true
3
3
4
- alias Cortexa.Workspace
5
- alias Cortexa.Models
4
+ alias Contexa.Workspace
5
+ alias Contexa.Models
6
6
7
7
defp make_tmp do
8
- dir = Path.join(System.tmp_dir!(), "cortexa_ex_test_#{System.unique_integer([:positive])}")
8
+ dir = Path.join(System.tmp_dir!(), "contexa_ex_test_#{System.unique_integer([:positive])}")
9
9
File.rm_rf!(dir)
10
10
File.mkdir_p!(dir)
11
11
dir
12
12
▼GO/README.md
+14-12
1
-# cortexa
1
+# contexa
2
2
3
-[![Go Reference](https://pkg.go.dev/badge/github.com/swadhinbiswas/Cortexa/GO.svg)](https://pkg.go.dev/github.com/swadhinbiswas/Cortexa/GO)
3
+[![Go Reference](https://pkg.go.dev/badge/github.com/swadhinbiswas/contexa/GO.svg)](https://pkg.go.dev/github.com/swadhinbiswas/contexa/GO)
4
4
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
5
-[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FCortexa-black.svg?logo=github)](https://github.com/swadhinbiswas/Cortexa)
5
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FContexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
6
6
7
7
**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
8
8
9
-Go implementation of the **cortexa** framework.
9
+Go implementation of the **contexa** framework.
10
10
11
11
Based on: [arXiv:2508.00031](https://arxiv.org/abs/2508.00031) -- *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* (Junde Wu et al., 2025)
12
12
13
+> **Note:** For full usage examples, cross-language interoperability, and the complete architecture, please see the [main Contexa repository README](https://github.com/swadhinbiswas/contexa).
14
+
13
15
---
14
16
15
17
## Installation
16
18
17
19
```bash
18
-go get github.com/swadhinbiswas/Cortexa/GO/cortexa
20
+go get github.com/swadhinbiswas/contexa/GO/contexa
19
21
```
20
22
21
23
---
27
29
28
30
import (
29
31
"fmt"
30
- "github.com/swadhinbiswas/Cortexa/GO/cortexa"
32
+ "github.com/swadhinbiswas/contexa/GO/contexa"
31
33
)
32
34
33
35
func main() {
34
- ws := cortexa.New("/path/to/project")
36
+ ws := contexa.New("/path/to/project")
35
37
if err := ws.Init("Build a REST API service with user auth"); err != nil {
36
38
panic(err)
37
39
}
175
177
## Running Tests
176
178
177
179
```bash
178
-git clone https://github.com/swadhinbiswas/Cortexa.git
179
-cd cortexa/GO
180
-go test -v ./cortexa/
180
+git clone https://github.com/swadhinbiswas/contexa.git
181
+cd contexa/GO
182
+go test -v ./contexa/
181
183
```
182
184
183
185
20 tests cover all GCC commands: init, OTA logging, commit, branch, merge, context, switch, list, and model serialization.
212
214
213
215
## Links
214
216
215
-- [GitHub Repository](https://github.com/swadhinbiswas/Cortexa)
216
-- [pkg.go.dev](https://pkg.go.dev/github.com/swadhinbiswas/Cortexa/GO)
217
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
218
+- [pkg.go.dev](https://pkg.go.dev/github.com/swadhinbiswas/contexa/GO)
217
219
- [Original Paper](https://arxiv.org/abs/2508.00031)
218
220
- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
219
221
▼GO/cortexa/interop_test.go → GO/contexa/interop_test.go
+1-1
1
-package cortexa
1
+package contexa
2
2
3
3
// interop_test.go — Cross-language interoperability tests.
4
4
//
5
5
▼GO/cortexa/models.go → GO/contexa/models.go
+2-2
1
-// Package cortexa implements cortexa — Git-inspired context management
1
+// Package contexa implements contexa — Git-inspired context management
2
2
// for LLM agents. COMMIT, BRANCH, MERGE, and CONTEXT over versioned memory.
3
3
//
4
4
// Paper: "Git Context Controller: Manage the Context of LLM-based Agents like Git"
6
6
//
7
7
// Author: Swadhin Biswas (@swadhinbiswas)
8
8
9
-package cortexa
9
+package contexa
10
10
11
11
import (
12
12
"fmt"
13
13
▼GO/cortexa/workspace.go → GO/contexa/workspace.go
+1-1
1
-package cortexa
1
+package contexa
2
2
3
3
import (
4
4
"crypto/rand"
5
5
▼GO/cortexa/workspace_test.go → GO/contexa/workspace_test.go
+1-1
1
-package cortexa
1
+package contexa
2
2
3
3
import (
4
4
"os"
5
5
▼GO/go.mod
+1-1
1
-module github.com/swadhinbiswas/cortexa/GO
1
+module github.com/swadhinbiswas/contexa/GO
2
2
3
3
go 1.21
4
4
5
5
▼JS/README.md
+14-12
1
-# cortexa
1
+# contexa
2
2
3
-[![npm version](https://img.shields.io/npm/v/cortexa.svg)](https://www.npmjs.com/package/cortexa)
3
+[![npm version](https://img.shields.io/npm/v/contexa.svg)](https://www.npmjs.com/package/contexa)
4
4
[![Node.js 18+](https://img.shields.io/badge/node-18%2B-blue.svg)](https://nodejs.org/)
5
5
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
6
-[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FCortexa-black.svg?logo=github)](https://github.com/swadhinbiswas/Cortexa)
6
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FContexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
7
7
8
8
**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
9
9
10
-TypeScript/JavaScript implementation of the **cortexa** framework.
10
+TypeScript/JavaScript implementation of the **contexa** framework.
11
11
12
12
Based on: [arXiv:2508.00031](https://arxiv.org/abs/2508.00031) -- *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* (Junde Wu et al., 2025)
13
13
14
+> **Note:** For full usage examples, cross-language interoperability, and the complete architecture, please see the [main Contexa repository README](https://github.com/swadhinbiswas/contexa).
15
+
14
16
---
15
17
16
18
## Installation
17
19
18
20
```bash
19
-npm install cortexa
21
+npm install contexa
20
22
```
21
23
22
24
Or with yarn/pnpm:
23
25
24
26
```bash
25
-yarn add cortexa
26
-pnpm add cortexa
27
+yarn add contexa
28
+pnpm add contexa
27
29
```
28
30
29
31
---
31
33
## Quick Start
32
34
33
35
```typescript
34
-import { GCCWorkspace } from "cortexa";
36
+import { GCCWorkspace } from "contexa";
35
37
36
38
// 1. Initialize a workspace
37
39
const ws = new GCCWorkspace("/path/to/project");
216
218
## Running Tests
217
219
218
220
```bash
219
-git clone https://github.com/swadhinbiswas/Cortexa.git
220
-cd cortexa/JS
221
+git clone https://github.com/swadhinbiswas/contexa.git
222
+cd contexa/JS
221
223
npm install
222
224
npm test
223
225
```
261
263
262
264
## Links
263
265
264
-- [GitHub Repository](https://github.com/swadhinbiswas/Cortexa)
265
-- [npm Package](https://www.npmjs.com/package/cortexa)
266
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
267
+- [npm Package](https://www.npmjs.com/package/contexa)
266
268
- [Original Paper](https://arxiv.org/abs/2508.00031)
267
269
- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
268
270
▼JS/package-lock.json
+4-4
1
1
{
2
- "name": "cortexa",
3
- "version": "0.1.1",
2
+ "name": "contexa",
3
+ "version": "1.1.2",
4
4
"lockfileVersion": 3,
5
5
"requires": true,
6
6
"packages": {
7
7
"": {
8
- "name": "cortexa",
9
- "version": "0.1.1",
8
+ "name": "contexa",
9
+ "version": "1.1.2",
10
10
"license": "MIT",
11
11
"dependencies": {
12
12
"js-yaml": "^4.1.0"
13
13
▼JS/package.json
+5-5
1
1
{
2
- "name": "cortexa",
2
+ "name": "contexa",
3
3
"version": "1.1.2",
4
4
"description": "Git-inspired context management for LLM agents -- COMMIT, BRANCH, MERGE, and CONTEXT over versioned memory (arXiv:2508.00031)",
5
5
"author": "Swadhin Biswas <[email protected]>",
23
23
"test": "tsx --test test.ts",
24
24
"lint": "eslint src"
25
25
},
26
- "keywords": ["llm", "agent", "context-management", "git", "memory", "gcc", "cortexa"],
26
+ "keywords": ["llm", "agent", "context-management", "git", "memory", "gcc", "contexa"],
27
27
"license": "MIT",
28
28
"repository": {
29
29
"type": "git",
30
- "url": "https://github.com/swadhinbiswas/Cortexa"
30
+ "url": "https://github.com/swadhinbiswas/contexa"
31
31
},
32
- "homepage": "https://github.com/swadhinbiswas/Cortexa",
32
+ "homepage": "https://github.com/swadhinbiswas/contexa",
33
33
"bugs": {
34
- "url": "https://github.com/swadhinbiswas/Cortexa/issues"
34
+ "url": "https://github.com/swadhinbiswas/contexa/issues"
35
35
},
36
36
"dependencies": {
37
37
"js-yaml": "^4.1.0"
38
38
▼JS/src/index.ts
+1-1
1
1
/**
2
- * cortexa — Git-inspired context management for LLM agents.
2
+ * contexa — Git-inspired context management for LLM agents.
3
3
* COMMIT, BRANCH, MERGE, and CONTEXT over versioned memory.
4
4
*
5
5
* Paper: "Git Context Controller: Manage the Context of LLM-based Agents like Git"
6
6
▼JS/src/workspace.ts
+1-1
178
178
// simplest portable approach: open with 'wx+' in a retry loop.
179
179
// On success we hold the exclusive create lock; on EEXIST we
180
180
// wait briefly and retry. This is a cooperative lock: all
181
- // cortexa JS instances follow the same protocol.
181
+ // contexa JS instances follow the same protocol.
182
182
const maxWait = 10_000; // 10 seconds
183
183
const interval = 50; // ms between retries
184
184
let waited = 0;
185
185
▼JS/test.ts
+1-1
1
1
/**
2
- * Tests for cortexa TypeScript package.
2
+ * Tests for contexa TypeScript package.
3
3
* Run with: tsx --test test.ts
4
4
*/
5
5
6
6
▼LUA/README.md
+7-5
1
-# cortexa — Lua
1
+# contexa — Lua
2
2
3
3
Git-inspired context management for LLM agents — **COMMIT**, **BRANCH**, **MERGE**, and **CONTEXT** operations over a persistent versioned memory workspace.
4
4
5
5
Based on the paper *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* ([arXiv:2508.00031](https://arxiv.org/abs/2508.00031)).
6
6
7
+> **Note:** For full usage examples, cross-language interoperability, and the complete architecture, please see the [main Contexa repository README](https://github.com/swadhinbiswas/contexa).
8
+
7
9
## Install
8
10
9
11
```bash
10
-luarocks install cortexa
12
+luarocks install contexa
11
13
```
12
14
13
15
## Quick Start
14
16
15
17
```lua
16
-local cortexa = require("cortexa")
18
+local contexa = require("contexa")
17
19
18
20
-- Create workspace
19
-local ws = cortexa.GCCWorkspace.new("/tmp/my-project")
21
+local ws = contexa.GCCWorkspace.new("/tmp/my-project")
20
22
ws:init("Build an AI agent")
21
23
22
24
-- Log observations
35
37
36
38
-- Retrieve context
37
39
local ctx = ws:context("main", 3)
38
-print(cortexa.context_summary(ctx))
40
+print(contexa.context_summary(ctx))
39
41
```
40
42
41
43
## API
42
44
▼LUA/cortexa-1.1.2-1.rockspec → LUA/contexa-1.1.2-1.rockspec
+6-6
1
1
rockspec_format = "3.0"
2
-package = "cortexa"
2
+package = "contexa"
3
3
version = "1.1.2-1"
4
4
5
5
source = {
6
- url = "git+https://github.com/swadhinbiswas/Cortexa.git",
6
+ url = "git+https://github.com/swadhinbiswas/contexa.git",
7
7
tag = "v1.1.2",
8
8
dir = "LUA",
9
9
}
15
15
over a persistent versioned memory workspace for LLM agents.
16
16
Based on the paper "Git Context Controller" (arXiv:2508.00031).
17
17
]],
18
- homepage = "https://github.com/swadhinbiswas/Cortexa",
18
+ homepage = "https://github.com/swadhinbiswas/contexa",
19
19
license = "MIT",
20
20
maintainer = "Swadhin Biswas <[email protected]>",
21
21
labels = { "llm", "agent", "context-management", "git", "memory" },
29
29
build = {
30
30
type = "builtin",
31
31
modules = {
32
- ["cortexa"] = "cortexa/init.lua",
33
- ["cortexa.models"] = "cortexa/models.lua",
34
- ["cortexa.workspace"] = "cortexa/workspace.lua",
32
+ ["contexa"] = "contexa/init.lua",
33
+ ["contexa.models"] = "contexa/models.lua",
34
+ ["contexa.workspace"] = "contexa/workspace.lua",
35
35
},
36
36
}
37
37
▼LUA/cortexa/init.lua → LUA/contexa/init.lua
+4-2
1
+--- contexa — package entry point.
2
+--- @module contexa
1
3
2
-local models = require("cortexa.models")
3
-local workspace = require("cortexa.workspace")
4
+local models = require("contexa.models")
5
+local workspace = require("contexa.workspace")
4
6
5
7
return {
6
8
-- Workspace
7
9
▼LUA/cortexa/models.lua → LUA/contexa/models.lua
+2-0
1
+--- contexa — Git-inspired context management for LLM agents
1
2
--- COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent
2
3
--- versioned memory workspace. Based on arXiv:2508.00031.
3
4
---
5
+--- @module contexa.models
4
6
5
7
local M = {}
6
8
7
9
▼LUA/cortexa/workspace.lua → LUA/contexa/workspace.lua
+3-1
1
+--- contexa — Git-inspired context management for LLM agents
1
2
--- GCCWorkspace: persistent versioned memory workspace.
2
3
--- Based on arXiv:2508.00031.
3
4
---
5
+--- @module contexa.workspace
4
6
5
-local models = require("cortexa.models")
7
+local models = require("contexa.models")
6
8
local lfs_ok, lfs = pcall(require, "lfs")
7
9
8
10
local W = {}
9
11
▼LUA/test.lua
+6-4
1
+--- contexa test suite
1
2
--- Run with: lua test.lua (requires luafilesystem)
2
3
4
+-- Adjust package path to find the local contexa module
3
5
package.path = "./?.lua;./?/init.lua;" .. package.path
4
6
5
-local workspace = require("cortexa.workspace")
6
-local models = require("cortexa.models")
7
+local workspace = require("contexa.workspace")
8
+local models = require("contexa.models")
7
9
8
10
local test_count = 0
9
11
local pass_count = 0
42
42
local tmp_counter = 0
43
43
local function make_tmp()
44
44
tmp_counter = tmp_counter + 1
45
- local dir = "/tmp/cortexa_lua_test_" .. os.time() .. "_" .. tmp_counter
45
+ local dir = "/tmp/contexa_lua_test_" .. os.time() .. "_" .. tmp_counter
46
46
os.execute('rm -rf "' .. dir .. '"')
47
47
os.execute('mkdir -p "' .. dir .. '"')
48
48
return dir
53
53
end
54
54
55
55
------------------------------------------------------------------------
56
-print("cortexa Lua test suite")
56
+print("contexa Lua test suite")
57
57
print(string.rep("=", 50))
58
58
59
59
------------------------------------------------------------------------
60
60
▼PYTHON/README.md
+21-19
1
-# cortexa
1
+# contexa
2
2
3
-[![PyPI version](https://img.shields.io/pypi/v/cortexa.svg)](https://pypi.org/project/cortexa/)
3
+[![PyPI version](https://img.shields.io/pypi/v/contexa.svg)](https://pypi.org/project/contexa/)
4
4
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
5
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/swadhinbiswas/Cortexa/blob/main/LICENSE)
6
-[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FCortexa-black.svg?logo=github)](https://github.com/swadhinbiswas/Cortexa)
5
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/swadhinbiswas/contexa/blob/main/LICENSE)
6
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FContexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
7
7
8
-A Python implementation of the **cortexa** framework -- Git-inspired context management for LLM agents.
8
+A Python implementation of the **contexa** framework -- Git-inspired context management for LLM agents.
9
9
10
10
Based on: [arXiv:2508.00031](https://arxiv.org/abs/2508.00031) -- *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* (Junde Wu et al., 2025)
11
11
12
+> **Note:** For full usage examples, cross-language interoperability, and the complete architecture, please see the [main Contexa repository README](https://github.com/swadhinbiswas/contexa).
13
+
12
14
---
13
15
14
16
## Table of Contents
73
75
## Installation
74
76
75
77
```bash
76
-pip install cortexa
78
+pip install contexa
77
79
```
78
80
79
81
Or with [uv](https://docs.astral.sh/uv/):
80
82
81
83
```bash
82
-uv add cortexa
84
+uv add contexa
83
85
```
84
86
85
87
---
87
89
## Quick Start
88
90
89
91
```python
90
-from cortexa import GCCWorkspace
92
+from contexa import GCCWorkspace
91
93
92
94
# 1. Initialize a workspace
93
95
ws = GCCWorkspace("/path/to/project")
284
286
All models support serialization:
285
287
286
288
```python
287
-from cortexa import OTARecord, BranchMetadata
289
+from contexa import OTARecord, BranchMetadata
288
290
289
291
# OTARecord <-> dict
290
292
record = OTARecord.from_dict({"timestamp": "...", "observation": "...", ...})
302
304
303
305
## Real-World Example
304
306
305
-Here's how an autonomous coding agent might use cortexa to manage its memory while building a web application:
307
+Here's how an autonomous coding agent might use contexa to manage its memory while building a web application:
306
308
307
309
```python
308
-from cortexa import GCCWorkspace
310
+from contexa import GCCWorkspace
309
311
310
312
ws = GCCWorkspace("./my-webapp")
311
313
ws.init("Build a Flask web app with user auth, blog posts, and admin panel")
348
350
349
351
```bash
350
352
# Clone the repository
351
-git clone https://github.com/swadhinbiswas/Cortexa.git
352
-cd cortexa
353
+git clone https://github.com/swadhinbiswas/contexa.git
354
+cd contexa
353
355
354
356
# Install dev dependencies and run tests
355
357
uv sync
380
382
381
383
Contributions are welcome! Here's how to get started:
382
384
383
-1. Fork the repository: [https://github.com/swadhinbiswas/Cortexa](https://github.com/swadhinbiswas/Cortexa)
385
+1. Fork the repository: [https://github.com/swadhinbiswas/contexa](https://github.com/swadhinbiswas/contexa)
384
386
2. Create a feature branch: `git checkout -b feature/my-feature`
385
387
3. Make your changes and add tests
386
388
4. Run the test suite: `uv run pytest -v`
387
389
5. Submit a pull request
388
390
389
-Please open an [issue](https://github.com/swadhinbiswas/Cortexa/issues) first for major changes to discuss the approach.
391
+Please open an [issue](https://github.com/swadhinbiswas/contexa/issues) first for major changes to discuss the approach.
390
392
391
393
---
392
394
401
403
402
404
## License
403
405
404
-This project is licensed under the MIT License. See the [LICENSE](https://github.com/swadhinbiswas/Cortexa/blob/main/LICENSE) file for details.
406
+This project is licensed under the MIT License. See the [LICENSE](https://github.com/swadhinbiswas/contexa/blob/main/LICENSE) file for details.
405
407
406
408
---
407
409
422
424
423
425
## Links
424
426
425
-- **GitHub Repository**: [https://github.com/swadhinbiswas/Cortexa](https://github.com/swadhinbiswas/Cortexa)
426
-- **PyPI Package**: [https://pypi.org/project/cortexa/](https://pypi.org/project/cortexa/)
427
-- **Issue Tracker**: [https://github.com/swadhinbiswas/Cortexa/issues](https://github.com/swadhinbiswas/Cortexa/issues)
427
+- **GitHub Repository**: [https://github.com/swadhinbiswas/contexa](https://github.com/swadhinbiswas/contexa)
428
+- **PyPI Package**: [https://pypi.org/project/contexa/](https://pypi.org/project/contexa/)
429
+- **Issue Tracker**: [https://github.com/swadhinbiswas/contexa/issues](https://github.com/swadhinbiswas/contexa/issues)
428
430
- **Original Paper**: [arXiv:2508.00031v2](https://arxiv.org/abs/2508.00031v2)
429
431
- **Author**: [Swadhin Biswas](https://github.com/swadhinbiswas)
430
432
▼PYTHON/cortexa/.gitignore → PYTHON/contexa/.gitignore
+0-0
0
0
▼PYTHON/cortexa/.python-version → PYTHON/contexa/.python-version
+0-0
0
0
▼PYTHON/cortexa/README.md → PYTHON/contexa/README.md
+0-0
0
0
▼PYTHON/cortexa/__init__.py → PYTHON/contexa/__init__.py
+1-1
1
1
"""
2
-cortexa — Python implementation of Git-Context-Controller (GCC)
2
+contexa — Python implementation of Git-Context-Controller (GCC)
3
3
4
4
Paper: "Git Context Controller: Manage the Context of LLM-based Agents like Git"
5
5
arXiv:2508.00031v2, Junde Wu et al., 2025
6
6
▼PYTHON/cortexa/models.py → PYTHON/contexa/models.py
+0-0
0
0
▼PYTHON/cortexa/workspace.py → PYTHON/contexa/workspace.py
+0-0
0
0
▼PYTHON/pyproject.toml
+5-5
1
1
[project]
2
-name = "cortexa"
2
+name = "contexa"
3
3
version = "1.1.2"
4
4
description = "Python implementation of Git-Context-Controller (GCC)"
5
5
readme = "README.md"
25
25
]
26
26
27
27
[project.urls]
28
-Homepage = "https://github.com/swadhinbiswas/Cortexa"
29
-Repository = "https://github.com/swadhinbiswas/Cortexa"
30
-Issues = "https://github.com/swadhinbiswas/Cortexa/issues"
28
+Homepage = "https://github.com/swadhinbiswas/contexa"
29
+Repository = "https://github.com/swadhinbiswas/contexa"
30
+Issues = "https://github.com/swadhinbiswas/contexa/issues"
31
31
32
32
[build-system]
33
33
requires = ["hatchling>=1.21"]
34
34
build-backend = "hatchling.build"
35
35
36
36
[tool.hatch.build.targets.wheel]
37
-packages = ["cortexa"]
37
+packages = ["contexa"]
38
38
39
39
[dependency-groups]
40
40
dev = [
41
41
▼PYTHON/test/test.py
+4-4
1
-"""Tests for Cortexa Python package."""
1
+"""Tests for Contexa Python package."""
2
2
3
3
import pytest
4
-from cortexa import GCCWorkspace
4
+from contexa import GCCWorkspace
5
5
6
6
7
7
@pytest.fixture
84
84
85
85
def test_branch_metadata_records_purpose(ws):
86
86
ws.branch("jwt-branch", "Test JWT auth approach")
87
- from cortexa.models import BranchMetadata
87
+ from contexa.models import BranchMetadata
88
88
89
89
meta_text = ws._read(ws._meta_path("jwt-branch"))
90
90
meta = BranchMetadata.from_yaml(meta_text)
97
97
ws.branch("to-merge", "Will be merged")
98
98
ws.commit("Branch work done")
99
99
ws.merge("to-merge", target="main")
100
- from cortexa.models import BranchMetadata
100
+ from contexa.models import BranchMetadata
101
101
102
102
meta_text = ws._read(ws._meta_path("to-merge"))
103
103
meta = BranchMetadata.from_yaml(meta_text)
104
104
▼PYTHON/uv.lock
+1-1
12
12
]
13
13
14
14
[[package]]
15
-name = "cortexa"
15
+name = "contexa"
16
16
version = "1.1.2"
17
17
source = { editable = "." }
18
18
dependencies = [
19
19
▼README.md
+39-39
1
1
<p align="center">
2
- <img src="assets/logo.svg" alt="Cortexa" width="500" />
2
+ <img src="assets/logo.svg" alt="Contexa" width="500" />
3
3
</p>
4
4
5
5
<p align="center">
12
12
<p align="center">
13
13
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
14
14
<a href="https://arxiv.org/abs/2508.00031"><img src="https://img.shields.io/badge/arXiv-2508.00031-b31b1b.svg" alt="arXiv" /></a>
15
- <a href="https://pypi.org/project/cortexa/"><img src="https://img.shields.io/pypi/v/cortexa.svg" alt="PyPI" /></a>
16
- <a href="https://www.npmjs.com/package/cortexa"><img src="https://img.shields.io/npm/v/cortexa.svg" alt="npm" /></a>
17
- <a href="https://crates.io/crates/cortexa"><img src="https://img.shields.io/crates/v/cortexa.svg" alt="crates.io" /></a>
18
- <a href="https://pkg.go.dev/github.com/swadhinbiswas/cortexa/GO"><img src="https://pkg.go.dev/badge/github.com/swadhinbiswas/cortexa/GO.svg" alt="Go Reference" /></a>
19
- <a href="https://hex.pm/packages/cortexa"><img src="https://img.shields.io/hexpm/v/cortexa.svg" alt="Hex.pm" /></a>
15
+ <a href="https://pypi.org/project/contexa/"><img src="https://img.shields.io/pypi/v/contexa.svg" alt="PyPI" /></a>
16
+ <a href="https://www.npmjs.com/package/contexa"><img src="https://img.shields.io/npm/v/contexa.svg" alt="npm" /></a>
17
+ <a href="https://crates.io/crates/contexa"><img src="https://img.shields.io/crates/v/contexa.svg" alt="crates.io" /></a>
18
+ <a href="https://pkg.go.dev/github.com/swadhinbiswas/contexa/GO"><img src="https://pkg.go.dev/badge/github.com/swadhinbiswas/contexa/GO.svg" alt="Go Reference" /></a>
19
+ <a href="https://hex.pm/packages/contexa"><img src="https://img.shields.io/hexpm/v/contexa.svg" alt="Hex.pm" /></a>
20
20
</p>
21
21
22
22
---
23
23
24
-**Cortexa** implements the [Git Context Controller (GCC)](https://arxiv.org/abs/2508.00031) -- a structured, versioned memory system for LLM-based agents. Named after the cerebral cortex, it gives agents a persistent brain that survives across sessions, branches for parallel exploration, and compressed recall at any resolution.
24
+**Contexa** implements the [Git Context Controller (GCC)](https://arxiv.org/abs/2508.00031) -- 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.
25
25
26
26
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.
27
27
28
-## Why Cortexa?
28
+## Why Contexa?
29
29
30
30
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.
31
31
76
76
77
77
| Language | Package | Install |
78
78
|----------|---------|---------|
79
-| Python | [`cortexa`](https://pypi.org/project/cortexa/) | `pip install cortexa` |
80
-| TypeScript/JS | [`cortexa`](https://www.npmjs.com/package/cortexa) | `npm install cortexa` |
81
-| Rust | [`cortexa-gcc`](https://crates.io/crates/cortexa-gcc) | `cargo add cortexa-gcc` |
82
-| Go | [`cortexa`](https://pkg.go.dev/github.com/swadhinbiswas/cortexa/GO) | `go get github.com/swadhinbiswas/cortexa/GO/cortexa` |
83
-| Lua | [`cortexa`](https://luarocks.org/modules/swadhinbiswas/cortexa) | `luarocks install cortexa` |
84
-| Elixir | [`cortexa`](https://hex.pm/packages/cortexa) | `{:cortexa, "~> 0.1.1"}` in mix.exs |
85
-| Zig | `cortexa` | See [Zig README](ZIG/README.md) |
79
+| Python | [`contexa`](https://pypi.org/project/contexa/) | `pip install contexa` |
80
+| TypeScript/JS | [`contexa`](https://www.npmjs.com/package/contexa) | `npm install contexa` |
81
+| Rust | [`contexa`](https://crates.io/crates/contexa) | `cargo add contexa` |
82
+| Go | [`contexa`](https://pkg.go.dev/github.com/swadhinbiswas/contexa/GO) | `go get github.com/swadhinbiswas/contexa/GO/contexa` |
83
+| Lua | [`contexa`](https://luarocks.org/modules/swadhinbiswas/contexa) | `luarocks install contexa` |
84
+| Elixir | [`contexa`](https://hex.pm/packages/contexa) | `{:contexa, "~> 0.1.1"}` in mix.exs |
85
+| Zig | `contexa` | See [Zig README](ZIG/README.md) |
86
86
87
87
All 7 packages produce the same `.GCC/` file system layout. A workspace created by one language can be read or extended by any other.
88
88
93
93
### Python
94
94
95
95
```python
96
-from cortexa import GCCWorkspace
96
+from contexa import GCCWorkspace
97
97
98
98
ws = GCCWorkspace("/path/to/project")
99
99
ws.init("Build a REST API with user auth")
117
117
### TypeScript
118
118
119
119
```typescript
120
-import { GCCWorkspace } from "cortexa";
120
+import { GCCWorkspace } from "contexa";
121
121
122
122
const ws = new GCCWorkspace("/path/to/project");
123
123
ws.init("Build a REST API");
133
133
### Rust
134
134
135
135
```rust
136
-use cortexa::GCCWorkspace;
136
+use contexa::GCCWorkspace;
137
137
138
138
let mut ws = GCCWorkspace::new("/path/to/project");
139
139
ws.init("Build a REST API")?;
149
149
### Go
150
150
151
151
```go
152
-import "github.com/swadhinbiswas/cortexa/GO/cortexa"
152
+import "github.com/swadhinbiswas/contexa/GO/contexa"
153
153
154
-ws := cortexa.New("/path/to/project")
154
+ws := contexa.New("/path/to/project")
155
155
ws.Init("Build a REST API")
156
156
ws.LogOTA("saw empty dir", "scaffold first", "createFiles()")
157
157
ws.Commit("Project scaffold done", nil, nil)
165
165
### Zig
166
166
167
167
```zig
168
-const cortexa = @import("cortexa");
168
+const contexa = @import("contexa");
169
169
170
-var ws = cortexa.Workspace.init(allocator, "/path/to/project");
170
+var ws = contexa.Workspace.init(allocator, "/path/to/project");
171
171
try ws.create("Build a REST API");
172
172
_ = try ws.logOTA("saw empty dir", "scaffold first", "createFiles()");
173
173
const c = try ws.commit("Project scaffold done", null);
184
184
### Lua
185
185
186
186
```lua
187
-local cortexa = require("cortexa")
187
+local contexa = require("contexa")
188
188
189
-local ws = cortexa.GCCWorkspace.new("/path/to/project")
189
+local ws = contexa.GCCWorkspace.new("/path/to/project")
190
190
ws:init("Build a REST API")
191
191
ws:log_ota("saw empty dir", "scaffold first", "create_files()")
192
192
ws:commit("Project scaffold done")
194
194
ws:commit("JWT middleware implemented")
195
195
ws:merge("auth-jwt", nil, "main")
196
196
local ctx = ws:context("main", 1)
197
-print(cortexa.context_summary(ctx))
197
+print(contexa.context_summary(ctx))
198
198
```
199
199
200
200
### Elixir
201
201
202
202
```elixir
203
-alias Cortexa.{Workspace, Models}
203
+alias Contexa.{Workspace, Models}
204
204
205
205
ws = Workspace.new("/path/to/project")
206
206
ws = Workspace.init(ws, "Build a REST API")
248
248
## Repository Structure
249
249
250
250
```
251
-Cortexa/
252
- PYTHON/ # PyPI: cortexa (Python 3.10+)
253
- JS/ # npm: cortexa (Node.js 18+)
254
- RUST/ # crates.io: cortexa (Rust stable)
251
+Contexa/
252
+ PYTHON/ # PyPI: contexa (Python 3.10+)
253
+ JS/ # npm: contexa (Node.js 18+)
254
+ RUST/ # crates.io: contexa (Rust stable)
255
255
GO/ # pkg.go.dev (Go 1.21+)
256
256
ZIG/ # Zig package (Zig 0.14+)
257
- LUA/ # LuaRocks: cortexa (Lua 5.1+)
258
- ELIXIR/ # Hex.pm: cortexa (Elixir 1.15+)
257
+ LUA/ # LuaRocks: contexa (Lua 5.1+)
258
+ ELIXIR/ # Hex.pm: contexa (Elixir 1.15+)
259
259
assets/ # Logo and visual assets
260
260
```
261
261
283
283
284
284
## Citation
285
285
286
-If you use Cortexa in research, please cite the original paper:
286
+If you use Contexa in research, please cite the original paper:
287
287
288
288
```bibtex
289
289
@article{wu2025gcc,
299
299
## Links
300
300
301
301
- [Original Paper](https://arxiv.org/abs/2508.00031) -- arXiv:2508.00031v2
302
-- [Python (PyPI)](https://pypi.org/project/cortexa/)
303
-- [TypeScript (npm)](https://www.npmjs.com/package/cortexa)
304
-- [Rust (crates.io)](https://crates.io/crates/cortexa)
305
-- [Go (pkg.go.dev)](https://pkg.go.dev/github.com/swadhinbiswas/cortexa/GO)
306
-- [Lua (LuaRocks)](https://luarocks.org/modules/swadhinbiswas/cortexa)
307
-- [Elixir (Hex.pm)](https://hex.pm/packages/cortexa)
302
+- [Python (PyPI)](https://pypi.org/project/contexa/)
303
+- [TypeScript (npm)](https://www.npmjs.com/package/contexa)
304
+- [Rust (crates.io)](https://crates.io/crates/contexa)
305
+- [Go (pkg.go.dev)](https://pkg.go.dev/github.com/swadhinbiswas/contexa/GO)
306
+- [Lua (LuaRocks)](https://luarocks.org/modules/swadhinbiswas/contexa)
307
+- [Elixir (Hex.pm)](https://hex.pm/packages/contexa)
308
308
- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
309
309
▼RUST/Cargo.lock
+7-7
66
66
]
67
67
68
68
[[package]]
69
-name = "core-foundation-sys"
70
-version = "0.8.7"
71
-source = "registry+https://github.com/rust-lang/crates.io-index"
72
-checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
73
-
74
-[[package]]
75
-name = "cortexa"
69
+name = "contexa"
76
70
version = "1.1.2"
77
71
dependencies = [
78
72
"chrono",
84
78
"uuid",
85
79
]
86
80
81
+[[package]]
82
+name = "core-foundation-sys"
83
+version = "0.8.7"
84
+source = "registry+https://github.com/rust-lang/crates.io-index"
85
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
86
+
87
87
[[package]]
88
88
name = "equivalent"
89
89
version = "1.0.2"
90
90
▼RUST/Cargo.toml
+3-3
1
1
[package]
2
-name = "cortexa"
2
+name = "contexa"
3
3
version = "1.1.2"
4
4
edition = "2021"
5
5
description = "Git-inspired context management for LLM agents -- COMMIT, BRANCH, MERGE, and CONTEXT over versioned memory (arXiv:2508.00031)"
8
8
keywords = ["llm", "agent", "context-management", "git", "memory"]
9
9
categories = ["data-structures", "filesystem"]
10
10
readme = "README.md"
11
-repository = "https://github.com/swadhinbiswas/Cortexa"
12
-homepage = "https://github.com/swadhinbiswas/Cortexa"
11
+repository = "https://github.com/swadhinbiswas/contexa"
12
+homepage = "https://github.com/swadhinbiswas/contexa"
13
13
14
14
[dependencies]
15
15
serde = { version = "1", features = ["derive"] }
16
16
▼RUST/README.md
+15-13
1
-# cortexa
1
+# contexa
2
2
3
-[![Crates.io](https://img.shields.io/crates/v/cortexa.svg)](https://crates.io/crates/cortexa)
4
-[![docs.rs](https://docs.rs/cortexa/badge.svg)](https://docs.rs/cortexa)
3
+[![Crates.io](https://img.shields.io/crates/v/contexa.svg)](https://crates.io/crates/contexa)
4
+[![docs.rs](https://docs.rs/contexa/badge.svg)](https://docs.rs/contexa)
5
5
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
6
-[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FCortexa-black.svg?logo=github)](https://github.com/swadhinbiswas/Cortexa)
6
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FContexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
7
7
8
8
**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
9
9
10
-Rust implementation of the **cortexa** framework.
10
+Rust implementation of the **contexa** framework.
11
11
12
12
Based on: [arXiv:2508.00031](https://arxiv.org/abs/2508.00031) -- *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* (Junde Wu et al., 2025)
13
13
14
+> **Note:** For full usage examples, cross-language interoperability, and the complete architecture, please see the [main Contexa repository README](https://github.com/swadhinbiswas/contexa).
15
+
14
16
---
15
17
16
18
## Installation
17
19
18
20
```toml
19
21
[dependencies]
20
-cortexa = "0.1"
22
+contexa = "0.1"
21
23
```
22
24
23
25
---
25
27
## Quick Start
26
28
27
29
```rust
28
-use cortexa::GCCWorkspace;
30
+use contexa::GCCWorkspace;
29
31
30
-fn main() -> cortexa::Result<()> {
32
+fn main() -> contexa::Result<()> {
31
33
let mut ws = GCCWorkspace::new("/path/to/project");
32
34
ws.init("Build a REST API service with user auth")?;
33
35
172
174
## Running Tests
173
175
174
176
```bash
175
-git clone https://github.com/swadhinbiswas/Cortexa.git
176
-cd cortexa/RUST
177
+git clone https://github.com/swadhinbiswas/contexa.git
178
+cd contexa/RUST
177
179
cargo test
178
180
```
179
181
211
213
212
214
## Links
213
215
214
-- [GitHub Repository](https://github.com/swadhinbiswas/Cortexa)
215
-- [crates.io](https://crates.io/crates/cortexa)
216
-- [docs.rs](https://docs.rs/cortexa)
216
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
217
+- [crates.io](https://crates.io/crates/contexa)
218
+- [docs.rs](https://docs.rs/contexa)
217
219
- [Original Paper](https://arxiv.org/abs/2508.00031)
218
220
- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
219
221
▼RUST/src/lib.rs
+2-2
1
-//! # cortexa
1
+//! # contexa
2
2
//!
3
3
//! Git-inspired context management for LLM agents. COMMIT, BRANCH, MERGE, and
4
4
//! CONTEXT operations over a persistent versioned memory workspace.
5
5
//!
6
6
//! ## Example
7
7
//! ```rust,no_run
8
-//! use cortexa::GCCWorkspace;
8
+//! use contexa::GCCWorkspace;
9
9
//!
10
10
//! let mut ws = GCCWorkspace::new("/path/to/project");
11
11
//! ws.init("Build a production REST API").unwrap();
12
12
▼SECURITY.md
+2-2
9
9
10
10
## Reporting a Vulnerability
11
11
12
-If you discover a security vulnerability in cortexa, please report it responsibly by emailing **[email protected]** with the following information:
12
+If you discover a security vulnerability in contexa, please report it responsibly by emailing **[email protected]** with the following information:
13
13
14
14
- Description of the vulnerability
15
15
- Steps to reproduce
26
26
27
27
## Scope
28
28
29
-This security policy covers all 7 language implementations of cortexa:
29
+This security policy covers all 7 language implementations of contexa:
30
30
31
31
- Python
32
32
- JavaScript
33
33
▼ZIG/README.md
+12-10
1
-# cortexa
1
+# contexa
2
2
3
3
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
4
-[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FCortexa-black.svg?logo=github)](https://github.com/swadhinbiswas/Cortexa)
4
+[![GitHub](https://img.shields.io/badge/GitHub-swadhinbiswas%2FContexa-black.svg?logo=github)](https://github.com/swadhinbiswas/contexa)
5
5
6
6
**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
7
7
8
-Zig implementation of the **cortexa** framework.
8
+Zig implementation of the **contexa** framework.
9
9
10
10
Based on: [arXiv:2508.00031](https://arxiv.org/abs/2508.00031) -- *"Git Context Controller: Manage the Context of LLM-based Agents like Git"* (Junde Wu et al., 2025)
11
11
12
+> **Note:** For full usage examples, cross-language interoperability, and the complete architecture, please see the [main Contexa repository README](https://github.com/swadhinbiswas/contexa).
13
+
12
14
---
13
15
14
16
## Installation
19
21
20
22
```zig
21
23
.dependencies = .{
22
- .cortexa = .{
23
- .url = "https://github.com/swadhinbiswas/Cortexa/archive/refs/tags/v0.1.1.tar.gz",
24
+ .contexa = .{
25
+ .url = "https://github.com/swadhinbiswas/contexa/archive/refs/tags/v0.1.1.tar.gz",
24
26
.hash = "...", // zig build will tell you the correct hash
25
27
},
26
28
},
29
31
Then in your `build.zig`:
30
32
31
33
```zig
32
-const cortexa = b.dependency("cortexa", .{
34
+const contexa = b.dependency("contexa", .{
33
35
.target = target,
34
36
.optimize = optimize,
35
37
});
36
-exe.root_module.addImport("cortexa", cortexa.module("cortexa"));
38
+exe.root_module.addImport("contexa", contexa.module("contexa"));
37
39
```
38
40
39
41
---
42
44
43
45
```zig
44
46
const std = @import("std");
45
-const cortexa = @import("cortexa");
47
+const contexa = @import("contexa");
46
48
47
49
pub fn main() !void {
48
50
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
50
52
const allocator = gpa.allocator();
51
53
52
54
// 1. Initialize a workspace
53
- var ws = cortexa.Workspace.init(allocator, "/path/to/project");
55
+ var ws = contexa.Workspace.init(allocator, "/path/to/project");
54
56
try ws.create("Build a REST API service with user auth");
55
57
56
58
// 2. Agent logs its reasoning as it works
186
188
187
189
## Links
188
190
189
-- [GitHub Repository](https://github.com/swadhinbiswas/Cortexa)
191
+- [GitHub Repository](https://github.com/swadhinbiswas/contexa)
190
192
- [Original Paper](https://arxiv.org/abs/2508.00031)
191
193
- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
192
194
▼ZIG/build.zig
+2-2
5
5
const optimize = b.standardOptimizeOption(.{});
6
6
7
7
// Module (for use as a dependency by consumers)
8
- const mod = b.addModule("cortexa", .{
8
+ const mod = b.addModule("contexa", .{
9
9
.root_source_file = b.path("src/main.zig"),
10
10
.target = target,
11
11
.optimize = optimize,
13
13
14
14
// Static library artifact
15
15
const lib = b.addLibrary(.{
16
- .name = "cortexa",
16
+ .name = "contexa",
17
17
.root_module = mod,
18
18
});
19
19
b.installArtifact(lib);
20
20
▼ZIG/build.zig.zon
+1-1
1
1
.{
2
- .name = .cortexa,
2
+ .name = .contexa,
3
3
.version = "1.1.3",
4
4
.fingerprint = 0x2a901b16c3e1b691,
5
5
.minimum_zig_version = "0.14.0",
6
6
▼ZIG/src/main.zig
+1-1
1
-//! cortexa — Git-inspired context management for LLM agents.
1
+//! contexa — Git-inspired context management for LLM agents.
2
2
//! COMMIT, BRANCH, MERGE, and CONTEXT over versioned memory.
3
3
//!
4
4
//! Paper: "Git Context Controller: Manage the Context of LLM-based Agents like Git"
5
5