Aoci Code

What aoci-code does

aoci-code maintains a repository-local map of a software system for coding agents. The map covers source files, configuration, tests, and database structure, with one compact entry for each managed file or database table. Entries describe a component's responsibility, related material, depended-on interfaces, and constraints that should not be violated.

The index is stored beside the project and versioned with Git. That makes the agent's accumulated system knowledge portable across branches, developers, agent products, and new conversations. The approach is intended to let an agent read a broad system description before acting instead of repeatedly rediscovering the repository during every task.

How it works

The aoci Go executable initializes the project and integrates the MCP server with the active host. scan builds the initial inventory from Git-managed files. The agent then creates the index through MCP, with the initial pass running in batches and resuming after interruption. A background panel can be started with aoci ui --detach --json to provide a link to project status.

After indexing, the MCP server detects relevant code changes and identifies entries that need attention. The agent updates those entries as it completes work. AOCI also reports mastery by area when asked to reconstruct its understanding of the project.

Database indexing is a separate step after the code index. PostgreSQL and MySQL are supported, along with openGauss 6.0.5 under stated constraints. The server reads catalog metadata and table structure rather than business records.

Setup and configuration

Download the release package matching the operating system and CPU architecture, verify it using the release instructions, and place aoci (or aoci.exe on Windows) at a stable absolute path. Run init for the current project, then run scan. Restart the coding agent so it loads the MCP configuration; hosts that load MCP servers dynamically may not require this restart.

Do not ignore the cognition files created by initialization, including aoci.txt, aoci.meta.txt, aoci.code.txt, and AGENTS.md, because the scan uses Git's file inventory. Host-specific configuration ignores can remain managed by initialization.

For database indexing, declare the database source and expose its connection-string environment variable in the host environment. Credentials are referenced by environment-variable name and are not saved by AOCI.

Tools and capabilities

• Maintain a persistent, Git-versioned code index.
• Describe file responsibilities, relationships, interfaces, and critical constraints.
• Build an initial index in resumable batches.
• Detect code changes that require index updates.
• Index PostgreSQL, MySQL, and constrained openGauss table structures.
• Serve the project knowledge through nine MCP tools.
• Launch a local status panel in the background.

Limitations and notes

The first indexing pass can take significant time: the project describes roughly an hour per 200,000 lines, depending on the model and agent. The practical constraint is the index context size rather than line count; an approximately 300,000-token index has been used for a 700,000-line commercial system.

AOCI is local-first. It reads source code and database structures, writes its index and state locally, and opens database connections only to the declared database for catalog metadata. It does not use the Internet or upload project data. MariaDB is not supported, and MySQL support starts at version 5.7.6.