swadhin / contexa public

docs: add root README with project overview and paper reference

Swadhin Biswas committed 7 months ago
4625e4e
1 parent 8c7bdcc
commit 4625e4e
1 file changed
+273 -0
Showing 1 changed file+273-0
README.md
▼README.md
+273-0
@@ -0,0 +1,273 @@
1
+# contexa
2
+
3
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
4
+[![arXiv](https://img.shields.io/badge/arXiv-2508.00031-b31b1b.svg)](https://arxiv.org/abs/2508.00031)
5
+[![PyPI](https://img.shields.io/pypi/v/contexa.svg)](https://pypi.org/project/contexa/)
6
+[![npm](https://img.shields.io/npm/v/contexa.svg)](https://www.npmjs.com/package/contexa)
7
+[![crates.io](https://img.shields.io/crates/v/contexa.svg)](https://crates.io/crates/contexa)
8
+[![Go Reference](https://pkg.go.dev/badge/github.com/swadhinbiswas/contexa.svg)](https://pkg.go.dev/github.com/swadhinbiswas/contexa)
9
+[![Hex.pm](https://img.shields.io/hexpm/v/contexa.svg)](https://hex.pm/packages/contexa)
10
+
11
+**Git-inspired context management for LLM agents.** COMMIT, BRANCH, MERGE, and CONTEXT operations over a persistent versioned memory workspace.
12
+
13
+Based on the research paper:
14
+
15
+> *"Git Context Controller: Manage the Context of LLM-based Agents like Git"*
16
+> Junde Wu et al., [arXiv:2508.00031](https://arxiv.org/abs/2508.00031), 2025
17
+
18
+Available in **Python**, **TypeScript/JavaScript**, **Rust**, **Go**, **Zig**, **Lua**, and **Elixir**.
19
+
20
+---
21
+
22
+## Why contexa?
23
+
24
+LLM-based agents accumulate observations, thoughts, and actions over time. Context windows are finite. As conversations grow, agents lose track of earlier reasoning, repeat mistakes, or forget prior decisions.
25
+
26
+**contexa** borrows Git's branching model to give agents structured, versioned memory:
27
+
28
+```
29
+ main
30
+ |
31
+ init --> log OTA --> COMMIT --> COMMIT --> MERGE <--+
32
+ | |
33
+ BRANCH --> COMMIT --+
34
+ (experiment)
35
+```
36
+
37
+| Command | Git Equivalent | What It Does |
38
+|---------|---------------|--------------|
39
+| **OTA Log** | Working directory | Continuous Observation-Thought-Action trace |
40
+| **COMMIT** | `git commit` | Milestone summary, compresses older OTA steps |
41
+| **BRANCH** | `git branch` | Isolated workspace for alternative reasoning |
42
+| **MERGE** | `git merge` | Integrates a successful branch back into main |
43
+| **CONTEXT** | `git log` | Retrieves history at K-commit resolution |
44
+
45
+The paper shows **K=1 performs best** in most benchmarks -- agents do better with compressed recent context than full history dumps.
46
+
47
+---
48
+
49
+## Install
50
+
51
+| Language | Package | Install |
52
+|----------|---------|---------|
53
+| Python | [`contexa`](https://pypi.org/project/contexa/) | `pip install contexa` |
54
+| TypeScript/JS | [`contexa`](https://www.npmjs.com/package/contexa) | `npm install contexa` |
55
+| Rust | [`contexa`](https://crates.io/crates/contexa) | `cargo add contexa` |
56
+| Go | [`contexa`](https://pkg.go.dev/github.com/swadhinbiswas/contexa) | `go get github.com/swadhinbiswas/contexa/cortexa` |
57
+| Lua | [`contexa`](https://luarocks.org/modules/swadhinbiswas/contexa) | `luarocks install contexa` |
58
+| Elixir | [`contexa`](https://hex.pm/packages/contexa) | `{:contexa, "~> 0.1.1"}` in mix.exs |
59
+| Zig | `contexa` | See [Zig README](ZIG/README.md) |
60
+
61
+All packages implement the same API and produce the same `.GCC/` file system layout. Workspaces created by one language can be read by another.
62
+
63
+---
64
+
65
+## Quick Start
66
+
67
+### Python
68
+
69
+```python
70
+from contexa import GCCWorkspace
71
+
72
+ws = GCCWorkspace("/path/to/project")
73
+ws.init("Build a REST API")
74
+ws.log_ota("saw empty dir", "scaffold first", "create_files()")
75
+ws.commit("Project scaffold done")
76
+ws.branch("auth-jwt", "Explore JWT authentication")
77
+ws.commit("JWT middleware implemented")
78
+ws.merge("auth-jwt")
79
+ctx = ws.context(k=1)
80
+print(ctx.summary())
81
+```
82
+
83
+### TypeScript
84
+
85
+```typescript
86
+import { GCCWorkspace } from "contexa";
87
+
88
+const ws = new GCCWorkspace("/path/to/project");
89
+ws.init("Build a REST API");
90
+ws.logOTA("saw empty dir", "scaffold first", "createFiles()");
91
+ws.commit("Project scaffold done");
92
+ws.branch("auth-jwt", "Explore JWT authentication");
93
+ws.commit("JWT middleware implemented");
94
+ws.merge("auth-jwt");
95
+const ctx = ws.context(undefined, 1);
96
+console.log(ctx.summary());
97
+```
98
+
99
+### Rust
100
+
101
+```rust
102
+use contexa::GCCWorkspace;
103
+
104
+let mut ws = GCCWorkspace::new("/path/to/project");
105
+ws.init("Build a REST API")?;
106
+ws.log_ota("saw empty dir", "scaffold first", "create_files()")?;
107
+ws.commit("Project scaffold done", None, None)?;
108
+ws.branch("auth-jwt", "Explore JWT authentication")?;
109
+ws.commit("JWT middleware implemented", None, None)?;
110
+ws.merge("auth-jwt", None, "main")?;
111
+let ctx = ws.context(None, 1)?;
112
+println!("{}", ctx.summary());
113
+```
114
+
115
+### Go
116
+
117
+```go
118
+import "github.com/swadhinbiswas/contexa/cortexa"
119
+
120
+ws := cortexa.New("/path/to/project")
121
+ws.Init("Build a REST API")
122
+ws.LogOTA("saw empty dir", "scaffold first", "createFiles()")
123
+ws.Commit("Project scaffold done", nil, nil)
124
+ws.Branch("auth-jwt", "Explore JWT authentication")
125
+ws.Commit("JWT middleware implemented", nil, nil)
126
+ws.Merge("auth-jwt", nil, "main")
127
+ctx, _ := ws.Context(nil, 1)
128
+fmt.Println(ctx.Summary())
129
+```
130
+
131
+### Zig
132
+
133
+```zig
134
+const contexa = @import("contexa");
135
+
136
+var ws = contexa.Workspace.init(allocator, "/path/to/project");
137
+try ws.create("Build a REST API");
138
+_ = try ws.logOTA("saw empty dir", "scaffold first", "createFiles()");
139
+const c = try ws.commit("Project scaffold done", null);
140
+defer allocator.free(c.commit_id);
141
+try ws.branch("auth-jwt", "Explore JWT authentication");
142
+const c2 = try ws.commit("JWT middleware implemented", null);
143
+defer allocator.free(c2.commit_id);
144
+const mc = try ws.merge("auth-jwt", "main");
145
+defer allocator.free(mc.commit_id);
146
+const ctx = try ws.context(null, 1);
147
+defer ctx.deinit(allocator);
148
+```
149
+
150
+### Lua
151
+
152
+```lua
153
+local contexa = require("contexa")
154
+
155
+local ws = contexa.GCCWorkspace.new("/path/to/project")
156
+ws:init("Build a REST API")
157
+ws:log_ota("saw empty dir", "scaffold first", "create_files()")
158
+ws:commit("Project scaffold done")
159
+ws:branch("auth-jwt", "Explore JWT authentication")
160
+ws:commit("JWT middleware implemented")
161
+ws:merge("auth-jwt", nil, "main")
162
+local ctx = ws:context("main", 1)
163
+print(contexa.context_summary(ctx))
164
+```
165
+
166
+### Elixir
167
+
168
+```elixir
169
+alias Contexa.{Workspace, Models}
170
+
171
+ws = Workspace.new("/path/to/project")
172
+ws = Workspace.init(ws, "Build a REST API")
173
+{ws, _} = Workspace.log_ota(ws, "saw empty dir", "scaffold first", "create_files()")
174
+{ws, _} = Workspace.commit(ws, "Project scaffold done")
175
+ws = Workspace.branch(ws, "auth-jwt", "Explore JWT authentication")
176
+{ws, _} = Workspace.commit(ws, "JWT middleware implemented")
177
+{ws, _} = Workspace.merge(ws, "auth-jwt", nil, "main")
178
+ctx = Workspace.context(ws, "main", 1)
179
+IO.puts(Models.context_summary(ctx))
180
+```
181
+
182
+---
183
+
184
+## File System Layout
185
+
186
+All implementations produce the same on-disk structure:
187
+
188
+```
189
+your-project/
190
+ .GCC/
191
+ main.md # Global roadmap
192
+ branches/
193
+ main/
194
+ log.md # Continuous OTA trace
195
+ commit.md # Milestone-level summaries
196
+ metadata.yaml # Branch intent & status
197
+ feature-branch/
198
+ log.md
199
+ commit.md
200
+ metadata.yaml
201
+```
202
+
203
+All data is stored as **human-readable Markdown and YAML** -- inspect and debug agent memory directly in your editor.
204
+
205
+---
206
+
207
+## Repository Structure
208
+
209
+```
210
+contexa/
211
+ PYTHON/ # PyPI: contexa
212
+ JS/ # npm: contexa
213
+ RUST/ # crates.io: contexa
214
+ GO/ # pkg.go.dev: github.com/swadhinbiswas/contexa
215
+ ZIG/ # Zig package: contexa
216
+ LUA/ # LuaRocks: contexa
217
+ ELIXIR/ # Hex.pm: contexa
218
+```
219
+
220
+Each directory is an independent package with its own build tooling, tests, and README.
221
+
222
+---
223
+
224
+## Data Models
225
+
226
+| Model | Description | Key Fields |
227
+|-------|-------------|------------|
228
+| **OTARecord** | Single Observation-Thought-Action cycle | `step`, `timestamp`, `observation`, `thought`, `action` |
229
+| **CommitRecord** | Milestone checkpoint | `commit_id`, `branch_name`, `branch_purpose`, `previous_progress_summary`, `this_commit_contribution`, `timestamp` |
230
+| **BranchMetadata** | Branch intent and status | `name`, `purpose`, `created_from`, `created_at`, `status`, `merged_into`, `merged_at` |
231
+| **ContextResult** | CONTEXT retrieval result | `branch_name`, `k`, `commits`, `ota_records`, `main_roadmap`, `metadata` |
232
+
233
+---
234
+
235
+## Contributing
236
+
237
+1. Fork the repository
238
+2. Create a feature branch: `git checkout -b feature/my-feature`
239
+3. Make your changes and add tests
240
+4. Run the test suite for your language
241
+5. Submit a pull request
242
+
243
+---
244
+
245
+## License
246
+
247
+MIT License. See [LICENSE](LICENSE) for details.
248
+
249
+---
250
+
251
+## Citation
252
+
253
+```bibtex
254
+@article{wu2025gcc,
255
+ title={Git Context Controller: Manage the Context of LLM-based Agents like Git},
256
+ author={Wu, Junde and others},
257
+ journal={arXiv preprint arXiv:2508.00031},
258
+ year={2025}
259
+}
260
+```
261
+
262
+---
263
+
264
+## Links
265
+
266
+- [Original Paper](https://arxiv.org/abs/2508.00031) -- arXiv:2508.00031
267
+- [Python (PyPI)](https://pypi.org/project/contexa/)
268
+- [TypeScript (npm)](https://www.npmjs.com/package/contexa)
269
+- [Rust (crates.io)](https://crates.io/crates/contexa)
270
+- [Go (pkg.go.dev)](https://pkg.go.dev/github.com/swadhinbiswas/contexa)
271
+- [Lua (LuaRocks)](https://luarocks.org/modules/swadhinbiswas/contexa)
272
+- [Elixir (Hex.pm)](https://hex.pm/packages/contexa)
273
+- [Author: Swadhin Biswas](https://github.com/swadhinbiswas)
0
274