AOCI-CODE — a Git-versioned cognition index for coding agents
Distills your whole codebase and database schema into one Git-versioned index your coding agent reads before it touches anything.
- Source repo
- aoci-spec/aoci-code
- Stars
- ★ 1.4k
- Last updated
- today
- License
- NOASSERTION
- Primary language
- Go
- FA score
- 52/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeClaude.ai (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Taking over an undocumented legacy system: point your agent at a codebase of up to roughly 500K lines, have it build the index and report per-area mastery, then continue development.
- Not a fit if
- Codebases far beyond roughly 500K lines that cannot absorb the first-index build time
- Users who want a one-click hosted service instead of wiring up a binary and MCP config
- Source review
- 52/100 · Major gaps
What does this agent do, and when should you use it?
AOCI-CODE (AI-Oriented Cognition Infrastructure) is a local-first Go project consisting of the aoci CLI and a stdio MCP server that gives coding agents durable context about a repository. The host model writes one FRAS line per managed object — F for responsibility, R for strong relations, A for exposed contracts, S for non-obvious constraints — tagged by layer, domain, importance and size. Those lines live as plain text in aoci.txt (Root), aoci.meta.txt (rules), aoci.code.txt and optional aoci.database.txt, so Git versions, diffs and rolls them back with the code. The MCP server exposes exactly nine tools and governs writes with deterministic plans, source SHA-256 binding, cross-process locks, CAS and atomic writes, so a batch either lands completely or recovers provably. AOCI-CODE never reaches the Internet, never uploads source, and stores only environment-variable references to database credentials. It remains a release candidate (v0.1.0-rc19) under an FSL-1.1-MIT source-available license.
aoci init writes the Root/Meta skeleton, a managed AGENTS.md rules block, Git boundaries and host MCP configuration; aoci scan takes its inventory from Git and establishes the managed Baseline; the host model then authors FRAS entries per object through MCP. The running aoci mcp server offers nine tools: reads (aoci_rules, aoci_overview, aoci_get_entries, aoci_search), maintenance (aoci_maintain, aoci_update_entry, aoci_remove_entry) and supporting evidence (aoci_header, aoci_report). For large indexes, aoci_overview delivers the Whole-Index in chunks the agent must follow via next_cursor, ending in one attestation. aoci verify reports Missing/Orphan/Stale/Unbaselined facts, aoci check runs the aggregated governance gate, and aoci index agent guide walks the deterministic host workflow. On the database side, aoci database source add declares a source, aoci database source access performs a read-only credential preflight, and aoci database cognition bootstrap adds table-level entries, reading only PostgreSQL/MySQL/openGauss system catalogs. aoci cognition system lineage/relations/impact/snapshot/evolution derive observation views over authoritative assets, all marked derived=true. aoci ui --detach --json starts a loopback-only read-only panel showing the index verbatim, covered lines, compression ratio, chunk plan and drift.
- Taking over an undocumented legacy system: point your agent at a codebase of up to roughly 500K lines, have it build the index and report per-area mastery, then continue development.
- Working across sessions in Codex, Claude Code, Cursor or OpenCode: because the index ships with the repository, a new person, a different agent or a fresh conversation resumes by reading it once.
- Non-professional developers iterating on their own projects, so the agent starts each task already knowing the system instead of re-searching the repo.
- Teams that need code and database context together: build the code index first, then enable Database Cognition with
aoci database cognition bootstrapfor table-level entries. - Assessing database change blast radius with
aoci cognition system impact --object database://primary/public/ordersto walk the model-authored R relationships. - Auditing and rolling back: the index is plain text under Git, so it can be reviewed, diffed and reverted, with a local panel showing coverage and governance state.
How do you install or deploy this agent?
The recommended route is a signed release package. Download the v0.1.0-rc19 assets with GitHub CLI and follow the verification level documented on the release page:
gh auth login
gh release download v0.1.0-rc19 --repo aoci-spec/aoci-codeOr build from the canonical repository (this needs the Go toolchain and make):
git clone https://github.com/aoci-spec/aoci-code.git
cd aoci-code
mkdir -p build
make build
./build/aoci --versionThe equivalent on Windows PowerShell:
git clone https://github.com/aoci-spec/aoci-code.git
Set-Location .\aoci-code
New-Item -ItemType Directory -Force .\build | Out-Null
make build
.\build\aoci.exe --versionEither way, keep the resulting binary at a stable absolute path, because the MCP configuration points at that path. Note that the license is FSL-1.1-MIT and the repository describes the project as source-available (Fair Source).
How do you use this agent?
Initialize in the target repository root and establish the Baseline:
AOCI=/absolute/path/to/aoci-code/build/aoci
"$AOCI" --repo . init --locale en-US --agent codex
"$AOCI" --repo . scaninit also writes host MCP configuration (.mcp.json, .claude/settings.json, .codex/config.toml or opencode.json) containing machine-bound absolute paths and should be gitignored. Do not add aoci.txt, aoci.meta.txt, aoci.code.txt or AGENTS.md to .gitignore — an ignored asset is silently skipped.
Then restart or refresh the host session so the newly written MCP server takes effect, and ask the agent to build the index:
First confirm the AOCI MCP server is connected, then build the AOCI index for this project. When it is complete, give me the AOCI panel link.Once the index is complete, verify alignment and open the panel:
"$AOCI" --repo . verify
"$AOCI" --repo . check
"$AOCI" --repo . ui --detach --jsonIf the project has a database, declare a source (the credential is referenced only by environment variable name; primary maps to AOCI_DB_PRIMARY_DSN) and run the read-only preflight:
aoci --repo . database source add \
--source-id primary \
--engine postgresql \
--database-name app \
--namespace public
aoci --repo . database source access --source primary --jsonWhat are this agent's strengths and limitations?
- Plain-text index files live inside the repository and are versioned by Git, so they can be diffed, reviewed, rolled back and reused by any agent or later session without binding to a model or conversation.
- Local-first by design: no Internet access, no uploads, and database credentials stored only as environment-variable reference names.
- Governed writes: deterministic plans with source SHA-256 values, cross-process locks, CAS and atomic writes that either land as one consistent batch or recover provably.
- A loopback-only read-only panel (default 30 s refresh) shows the index verbatim, covered files and lines, compression ratio, chunk plan and drift for human auditing.
- Documented host integration for several agents: Codex, Claude Code, OpenCode V1 and Qoder write project config, while Cursor returns a reference snippet.
- The first index is slow — the README estimates about an hour per 200,000 lines — and there is no shortcut to skip it.
- Index quality depends on the host model: all-green machine results prove structural and governance contracts only, not that every model-written statement is correct.
- The license is reported as NOASSERTION and the README describes it as FSL-1.1-MIT (Fair Source/source-available), so commercial terms need separate review before adoption.
- The software is free, but you must already have an MCP host and pay for your own model usage; no vendor-hosted service is offered.
- Database Cognition covers PostgreSQL, MySQL and a deliberately limited openGauss 6.0.5 LTS profile; other engines and partition/column-store objects are out of scope.
- It is still a release candidate (v0.1.0-rc19), so CLI behavior and interfaces may change before a stable release.
How does this agent compare with similar options?
The README explicitly contrasts AOCI-CODE with CodeGraph: CodeGraph parses code into a graph of symbols and calls and returns exact source and call paths when the agent asks a question, making it a precise lookup tool for the task at hand. AOCI-CODE instead has the model write one FRAS line per file so the agent reads the whole index first and knows the system before the task starts. The README recommends using both — the index to know the system, CodeGraph to fetch exact code while working — and states that a full comparison covering RAG, LSP and repo maps also exists.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AOCI-CODE — a Git-versioned cognition index for coding agents This agent | 52 · Major gaps | CLIFree + model costs | ★ 1.4k | today | Go | Codex · Claude Code |
| Headroom: The Context Compression Layer for AI Agents | 59 · Major gaps | CLIFree + model costs | ★ 75k | today | Python | Codex · Claude Code · OpenAI API · Claude API |
| Piia Engram | 88 · Good | CLIFree | ★ 163 | 1d ago | Python | Codex · Claude Code |
| Remnic Agent Memory | 85 · Good | CLIFree + model costs | ★ 218 | 2d ago | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
README and SECURITY.md state local-first operation, read-only source and database catalog metadata, no Internet, credentials referenced only by environment-variable name, MCP stdout reserved for JSON-RPC, and formal asset updates using validation, locking, CAS, atomic writes and recovery. least_privilege, data_flow_transparency, sensitive_data_handling, external_effects and rollback are each backed by identifiable text, so 2. user_confirmation is only gestured at via automation.mode=auto with no default mode or concrete confirmation points, deducted to 1. source_attribution shows only FSL-1.1-MIT and Copyright 2026 Liu JinShi; publisher identity is unverified and no signing/provenance chain is described, deducted to 1.
CI workflows cover go mod verify, go mod tidy with diff check, unit tests, staticcheck, govulncheck, cross-platform builds and black-box protocol suites, giving real evidence for self_consistency and dependency_availability, so 2. failure_messages only mentions verify/check converging to aligned without showing concrete error text or diagnostics, deducted to 1.
README clearly supports Codex, Claude Code, Cursor and OpenCode MCP hosts and notes DeepSeek-class models need a host supporting stdio MCP, so audience_and_scenarios and capability_boundaries are 2; environment_fit covers Linux/macOS/Windows and CGO-free builds, so 2. trigger_precision relies on the agent deciding when to maintain the index, with no deterministic trigger conditions, deducted to 1.
information_architecture and install_notes are complete, with quick start, manual integration, verification steps and Windows PowerShell examples, so 2; license is the full FSL-1.1-MIT text, so 2. naming_stability is deducted to 1 for the rc19 version string and hard-coded paths/versions across the README; examples_and_faq is deducted to 1 as only examples/minimal-repository is mentioned; known_limitations is deducted to 1 as only first-index duration and scale limits are noted; versioning_changelog is deducted to 1 for the absence of a CHANGELOG; maintenance_responsibility is deducted to 1 as maintainers and response timelines are not stated.
output_usability is 2 given the concrete FRAS entry example and field explanations; marginal_value is deducted to 1 because the CodeGraph/RAG/LSP comparison is self-asserted without independent corroboration; cost_benefit is deducted to 1 because the README admits roughly one hour per 200,000 lines for the first index but gives no quantified benefit versus alternatives.
claim_traceability is deducted to 1 because most performance and scale claims (700,000 lines, ~300K-token index) have no in-repo verifiable data; cross_source_corroboration is deducted to 1 as only README and CI partially corroborate each other; fact_inference_separation is deducted to 1 as the material does not clearly separate fact from inference.
- Publisher identity is unverified; README performance and scale claims (700,000 lines, ~300K-token index) lack in-repo verifiable data and must not be used to infer reliability.
- First-index cost is high (roughly one hour per 200,000 lines) and index maintenance timing depends on agent judgment with no deterministic trigger.
- License is FSL-1.1-MIT (Fair Source) with competing-use restrictions; confirm compliance before commercial use.
- This is a static source review; no build, test or runtime verification was executed, so confidence is low.
FAQ
Does it send my code or database anywhere?
How long does the first index take, and can it be interrupted?
Which MCP hosts are supported, and why does Cursor need manual work?
init; Cursor only receives a reference snippet, so you paste the configuration yourself. Other standard stdio MCP hosts need manual configuration and host-specific validation.Who guarantees the correctness of what the model writes into the index?
Should the index files and host config be committed to Git?
init such as .mcp.json, .codex/config.toml and opencode.json contains machine-bound absolute paths and should be gitignored instead.