aoci-spec/aoci-code

What it claims

AOCI-CODE is a Go CLI and stdio MCP server that has the coding agent write one FRAS line per file and per database table. The README reports a 700,000-line commercial system developed this way with an index of about 300K tokens. It says the practical limit is index size, not line count, and that onboarding existing codebases works up to about 500,000 lines. The first index takes roughly an hour per 200,000 lines, runs in batches and resumes if interrupted. For new projects the README suggests adopting it at around 10,000 to 30,000 lines, not from the first commit.

How it works

The index is split into four plain-text files: aoci.txt (Root, the activation manifest, published last), aoci.meta.txt (tag dictionary and FRAS rules), aoci.code.txt, and an optional aoci.database.txt. Each entry carries a tag such as [CG9L] (layer, domain, importance 1-9, size band) and the F, R, A and S fields. The model writes all meaning. AOCI-CODE does not generate entries from filenames, ASTs or templates, and it does not rewrite what the model wrote. The binary validates structure, binds entries to source SHA-256, and commits batches with cross-process locks, CAS and atomic writes. Field limits are enforced by the binary, so a project cannot widen them by editing its Meta file.

A write ends in one of applied, repair_required or stopped. An interrupted write resumes or rolls back to the exact preimage. A conflict with an external edit fails closed.

flowchart TD
    T[Dev task] --> C[Agent edits code, runs tests]
    C --> D[MCP detects drifted entries]
    D --> W[Agent writes FRAS candidates]
    W --> V{Validation and CAS}
    V -->|ok| A[applied, Baseline advances]
    V -->|third-party conflict| S[stopped or repair_required]
    A --> T

The MCP server exposes exactly nine tools: aoci_rules, aoci_overview, aoci_get_entries, aoci_search, aoci_maintain, aoci_update_entry, aoci_remove_entry, aoci_header and aoci_report. Overview is delivered in chunks. overview_delivery.chunk_tokens defaults to 7000 (range 4000 to 24000). The agent must follow next_cursor to the end and submit an attestation. On Claude Code a per-tool result-size declaration makes 24000 usable, so a 480-object index arrives in three chunks instead of five.

How to use it

Install from the signed v0.1.0-rc23 release or build from source. The build is CGO-free:

git clone https://github.com/aoci-spec/aoci-code.git
cd aoci-code
mkdir -p build
make build
./build/aoci --version

Initialize and baseline the target repository, then restart the agent so it loads the new MCP server:

AOCI=/absolute/path/to/aoci-code/build/aoci
"$AOCI" --repo . init --locale en-US --agent codex
"$AOCI" --repo . scan

After the restart, ask the agent to build the index. Check alignment with verify, check and doctor. aoci ui --detach --json starts a read-only loopback panel that shows token use, coverage and drift.

Host support varies. Codex gets project MCP config and an optional --hooks compaction prompt. Claude Code can install a PreToolUse guard. OpenCode V1 gets opencode.json. Qoder writes .mcp.json. Cursor gets only a snippet to paste by hand.

For a database, declare a source. The credential is read from an environment variable such as AOCI_DB_PRIMARY_DSN:

aoci --repo . database source add \
  --source-id primary \
  --engine postgresql \
  --database-name app \
  --namespace public

Only base-table schema metadata is read. A human accepts the evidence hash before the model writes table entries. aoci cognition system impact --object database://primary/public/orders lists code objects reachable from a table through model-authored R links.

Limits

• Licence. The licence is FSL-1.1-MIT, which is source-available rather than open source. The current version is a release candidate.
• Correctness. The README states that all-green checks prove only structural and governance contracts, not that the model's statements are correct.
• Ignore rules. Do not gitignore aoci.txt, aoci.meta.txt, aoci.code.txt or AGENTS.md. Scan takes its file list from Git and silently skips ignored assets.
• Host config files. Do gitignore the host config files init writes (.mcp.json, .codex/config.toml and similar). They contain machine-bound absolute paths, and re-running init keeps a broken committed copy.
• Read-only is not zero-write. verify and check do not change the index, but they may append to the local Ledger. There is no switch to disable these writes.
• MySQL. Support covers 5.7.6 and later. MariaDB is refused.
• openGauss. Only 6.0.5 LTS in A/PG mode with non-partitioned base tables is supported. Remote connections require sslmode=verify-full.
• Not collected. Views, routines, triggers and comments are not read.
• Credentials. Only environment-variable credentials work. Vault and cloud secret managers are not available.
• Truncated page. The fetched page was cut at 60,000 of 70,155 characters. The comparison table with CodeGraph, RAG, LSP and repo maps, and any later sections, were not seen.