AOCI-CODE: a Git-versioned cognition map for AI coding agents

The problem AOCI-CODE targets: agents that re-read the codebase

A coding agent that has no persistent model of a repository spends its context re-discovering the same files. The README frames AOCI-CODE as an indexing method that gives an agent what it calls whole-system cognition, so the agent works from an index rather than searching and re-reading the codebase for every task. The stated audience is two groups: non-professional developers iterating on their own systems, and professional developers who want to hand a system to an agent and keep their attention on architecture.

The README also makes a claim about scale that is worth reading carefully. It says the supported scale is set by the index size, not by line count, and that a 700,000-line commercial system is developed this way with an index of about 300K tokens. That is a statement about one system, not a benchmark. The one-step setup section separately describes systems of up to 500,000 lines. Those two numbers are not the same measurement, and the README does not reconcile them, so treat the index size as the real constraint and the line count as an illustration.

The other problem it addresses is handover. The index lives in the repository next to the code and is versioned by Git, so a change of project manager, developer, agent, or conversation is meant to be recoverable by reading the index. That is a design decision with a cost: the index becomes an artifact your team must keep in sync with the code, and the README's answer is that the MCP detects code changes and issues the entries that need updating, which the agent fills in as it finishes each task.

How the index is built and kept current

The mechanism has three moving parts visible in the repository: a CLI binary called aoci, an MCP server that exposes nine tools, and a set of index files written into the project directory.

Building the index is an agent task, not a command that reads your code by itself. The agent reads every managed file and writes one entry per file, which is why the README says a larger system takes longer, roughly an hour for 200,000 lines depending on the model and the agent's speed. The build runs in batches and an interrupted build resumes where it stopped. The index text is written locally by your own agent through the model channel you already use.

scan takes its file inventory from Git. That single detail explains the sharpest constraint in the README: the cognition assets init writes (aoci.txt, aoci.meta.txt, aoci.code.txt, AGENTS.md) must not be added to .gitignore or .git/info/exclude, because an ignored asset is silently skipped and the index cannot be built. Silent skipping is the failure mode to watch for, since nothing in the described flow raises an error when it happens.

On the data side, the README states that AOCI-CODE only reads source code and database table structures, never business data. It writes its index files and its own state inside the project directory, plus the status page's registration in your user cache directory. It does not reach the Internet and uploads nothing; the only connections it opens are to the database you declare, for catalog metadata, and its own loopback status page. Database credentials are referenced by environment-variable name and never stored.

Installing AOCI-CODE and building a first index

The README does not give a package-manager install. It tells you to download the latest release package for your operating system and CPU architecture from the GitHub releases page and follow the installation instructions on that page, or build from the official repository if no compatible package exists. After extracting, place aoci (aoci.exe on Windows) at a stable absolute path.

Initialization and host integration are then driven by instructions you paste into your agent. The README's first instruction tells the agent to run init to initialize AOCI and integrate MCP for the current host, then run scan, then stop and ask you to restart the agent. Some hosts, Cursor for example, do not write project configuration, so init gives you the configuration to paste yourself.

1. Run init to initialize AOCI and integrate MCP for the current host; if this host does
   not write project configuration (Cursor, for example), give me the configuration I
   need to paste myself
2. Run scan
3. Tell me to restart the Agent so the newly written MCP server takes effect

The restart is not optional in the described flow. The index is authored through AOCI's MCP tools, and the MCP server that init just wrote was not loaded in the session that wrote it. A host that loads MCP servers dynamically may not need the restart, and the README points to its Host integration section for how to tell.

After restarting, the second instruction asks the agent to confirm the MCP server is connected, build the index, and hand back the panel link. The agent starts the panel in the background:

aoci ui --detach --json

If your project has a database, the README recommends building a database index as well. PostgreSQL and MySQL are supported, plus openGauss 6.0.5 with constraints. You declare the source, provide the connection-string environment variable in the host environment, and send an instruction to build it. Build the code index first, then the database index.

Where AOCI-CODE is the wrong tool

The first index is the obvious cost. One entry per managed file, written by a model, means the initial build is measured in hours on a large repository, and the quality of every entry depends on the model doing the writing. If you need an index today and cannot spend that time, this is not the tool for the job.

The second limitation is the Git inventory rule. Because scan reads its file inventory from Git, any project that keeps generated or vendored code out of version control will have those files absent from the index. That is a defensible default, but it means the index describes your repository as Git sees it, not as your build sees it.

The third is that AOCI-CODE is not a code search engine or a static analysis tool. It does not answer queries by itself; it produces cognition material for an agent to read. If your goal is a queryable graph of symbols and references with no model in the loop, a language server or a code intelligence index is the better fit, and it will be faster and deterministic in ways this is not.

Finally, the release line is at v0.1.0-rc12, and the license field on the repository is NOASSERTION while the README badge says FSL-1.1-MIT. Those two signals do not agree, and the README does not explain the split. Anyone adopting this for a commercial system should resolve that before depending on it.

AOCI-CODE compared with a plain language server index

The nearest thing most teams already run is a language server or a code intelligence index such as the one behind an editor's go-to-definition. The difference in approach is where the knowledge lives and who writes it.

A language server derives facts from the compiler or parser. It is deterministic, it updates as files change, and it answers structured queries about symbols, types, and references. It does not summarize intent, and it has no notion of a database schema sitting beside the code.

AOCI-CODE derives its entries from a model reading files and writing prose entries, one per file, plus table-level cognition for MySQL, PostgreSQL, or constrained openGauss 6.0.5. The output is an artifact a human can read and a Git history can version. That is the trade: you get summarization and cross-file narrative that a language server will never produce, and you give up determinism and speed on the first build.

The two are not mutually exclusive, and the README does not present them as competitors. The practical question is whether your agent's bottleneck is finding symbols or holding the shape of the system. AOCI-CODE is aimed at the second.

Maintenance, licensing, and what the release line tells you

The repository is not archived, and the last push was on 2026-09-14. Releases have moved quickly through the 0.1.0 line: v0.1.0-rc9 on 2026-09-08, v0.1.0-rc11 on 2026-09-12, and v0.1.0-rc12 on 2026-09-14. That cadence means you should expect the interface to move, and it means pinning a release rather than tracking main is the safer default for a team.

Upgrade cost is partly bounded by the design. The index is versioned by Git alongside the code, so an upgrade does not require rebuilding cognition from scratch in principle. The README does not document rollback, and it does not describe what happens to existing index files when the entry format changes between release candidates. That is the gap to probe before you commit a large repository to this.

On licensing, the README badge reads FSL-1.1-MIT while the repository's license metadata is NOASSERTION. FSL is a source-available license family with terms that differ from a standard open source license, and the MIT portion of the label suggests a conversion over time. The repository also carries NOTICE, PATENTS, TRADEMARKS, and THIRD-PARTY-NOTICES files, and the go.mod replaces the openGauss connector with a vendored copy under third_party. Read those files yourself and get your own legal read before shipping this inside a commercial product. Nothing here is legal advice.

Editorial conclusion

AOCI-CODE is aimed at teams who already drive development through a code agent and want that agent to hold whole-system context instead of re-reading files. It is the wrong tool if you want a queryable code graph with no model in the loop, or if your repository is far past the scale the README describes. Before adopting it, verify three things: that your host loads the MCP server after a restart, that the four cognition assets init writes are not in .gitignore or .git/info/exclude, and that a batch build resumes after you interrupt it.

Frequently asked questions

Official sources

1. aoci-spec/aoci-code on GitHub
2. Issues
3. README
4. Releases