AOCI-CODE

AOCI-CODE

Eine persistente, Git-versionierte Karte deiner gesamten Codebasis — geschrieben von deinem Coding-Agenten, verwaltet von einem lokalen MCP-Server. Agenten lesen sie einmal und kennen das System, statt das Repository bei jeder Aufgabe erneut zu durchsuchen.

🇺🇸 English | 🇨🇳 简体中文

Was es leistet

Große Systeme bauen, ohne den Überblick zu verlieren. In Codex, Claude Code, Cursor, OpenCode und ähnlichen Agenten beginnt dein Agent jede Aufgabe mit dem Wissen über das gesamte System: wofür jede Datei da ist, wovon sie abhängt und was nicht kaputtgehen darf. Er hört auf, die Codebasis bei jeder Anfrage zu durchsuchen und erneut zu lesen. Menschen, die keine professionellen Entwickler sind, können ihre eigenen Systeme weiterentwickeln; professionelle Entwickler können das gesamte System an einen Agenten übergeben und ihre Aufmerksamkeit auf Architektur und Design richten.

Ein bestehendes System in einem Schritt übernehmen. Richte den Agenten auf eine bestehende Codebasis von bis zu etwa 500.000 Zeilen und bitte ihn, den Index zu erstellen. Er meldet, wie gut er jeden Bereich kennt, und setzt die Entwicklung von dort aus fort. Die praktische Grenze ist die Größe des Index, nicht die Zeilenzahl: Ein kommerzielles System mit 700.000 Zeilen wird heute auf diese Weise entwickelt, mit einem Index von etwa 300K Tokens.

Personen, Agenten oder Gespräche wechseln, ohne neu anzufangen. Der Index liegt im Repository neben dem Code und wird von Git versioniert. Wenn ein Projekt den Besitzer wechselt, den Agenten wechselt oder ein neues Gespräch beginnt, macht ein Lesen des Index dort weiter, wo es aufgehört hat.

Nach dem ersten Index ist die Pflege automatisch. Der MCP-Server erkennt Codeänderungen und gibt die Einträge aus, die aktualisiert werden müssen. Der Agent füllt sie aus, während er jede Aufgabe abschließt, sodass der Index zum aktuellen Code passt und du nie für die Pflege anhalten musst.

Wie es aussieht

Eine Zeile pro Datei, vom Modell aus dem tatsächlichen Quellcode geschrieben. Dies ist ein echter Eintrag aus dem eigenen Index dieses Repositorys:

atomic.go[CG9L]: F:Provides durable replace CAS, create CAS, atomic writes, and no-clobber recovery moves | R:code:internal/fs/atomic_exchange_linux.go,code:internal/fs/atomic_exchange_windows.go,code:internal/fs/lock.go | A:AtomicWrite,AtomicWriteCAS,AtomicCreateCAS,AtomicMoveCAS | S:Native publication never degrades to an overwriting rename; on a race, unsafe type, or unverifiable bytes, preserve third-party state

F ist, wofür die Datei verantwortlich ist, R ist, was du zusammen mit ihr lesen musst, A ist, worauf Aufrufer sich verlassen, und S ist, was du nicht aus dem Code ableiten kannst, aber nicht falsch machen darfst. Das Tag [CG9L] ordnet die Datei nach Schicht, Domäne, Wichtigkeit und Größe ein. Ein paar hundert solcher Zeilen decken ein ganzes System ab, und ein Agent kann sie in einem Durchgang lesen. Das Eintragsformat erklärt jedes Feld.

Wie unterscheidet sich das von CodeGraph?

• CodeGraph parst deinen Code in einen Graphen aus Symbolen und Aufrufen. Wenn der Agent eine Frage stellt, liefert es den exakten Quellcode und die Aufrufpfade zurück. Es ist ein präzises Nachschlagewerkzeug für die aktuelle Aufgabe.
• AOCI-CODE lässt das Modell eine Zeile pro Datei und Tabelle schreiben: wofür sie da ist, womit sie verbunden ist und was nicht kaputtgehen darf. Der Agent liest zuerst den gesamten Index, sodass er das System kennt, bevor die Aufgabe beginnt. Der Index liegt in Git und wird mit dem Code synchron gehalten.
• Nutze beides: den Index, um das System zu kennen, CodeGraph, um während der Arbeit den exakten Code abzurufen.

Der vollständige Vergleich behandelt auch RAG, LSP und Repo-Maps.

Was dich erwartet

Der erste Index dauert eine Weile. Der Agent liest jede verwaltete Datei und schreibt einen Eintrag pro Datei: etwa eine Stunde pro 200.000 Zeilen Code, abhängig vom Modell und der Geschwindigkeit des Agenten. Er läuft in Stapeln und setzt bei Unterbrechung dort fort, wo er aufgehört hat.

Hast du eine Datenbank? Indiziere sie ebenfalls. MySQL und PostgreSQL werden unterstützt, sowie openGauss 6.0.5 mit Einschränkungen. MySQL bedeutet 5.7.6 und später; MariaDB wird nicht unterstützt. Erstelle zuerst den Code-Index, dann den Datenbank-Index. Wenn Code- und Tabellenwissen gemeinsam geliefert werden, versteht der Agent das System vollständiger.

Nur lokal: schreibgeschützt auf deinem System, kein Internet, keine gespeicherten Zugangsdaten. AOCI-CODE liest deinen Quellcode und die Tabellenstrukturen der Datenbank, niemals Geschäftsdaten. Es schreibt seine Indexdateien und seinen eigenen Zustand im Projektverzeichnis sowie die Registrierung der Statusseite in deinem Benutzer-Cache-Verzeichnis. Es erreicht niemals das Internet und lädt nichts hoch: Die einzigen Verbindungen, die es öffnet, sind zu der von dir deklarierten Datenbank für Katalog-Metadaten und zu seiner eigenen Loopback-Statusseite. Datenbank-Zugangsdaten werden über den Namen einer Umgebungsvariablen referenziert und nie gespeichert. Der Indextext wird lokal von deinem eigenen Agenten über den Modellkanal geschrieben, den du bereits nutzt; AOCI-CODE fügt keinen neuen Datenabfluss hinzu.

Schnellstart

Gib deinem Agenten die folgende Anweisung, um AOCI-CODE herunterzuladen und einzurichten. Nachdem du den Agenten neu gestartet hast, sende die zweite Anweisung, um den Index zu erstellen.

AOCI-CODE project: https://github.com/aoci-spec/aoci-code

Download the latest release package for this operating system and CPU architecture from
https://github.com/aoci-spec/aoci-code/releases, and follow the installation instructions
on the Release page to verify it. If no compatible release package exists, or if I
explicitly request the latest source, build it from the official repository.

After extracting the package, place aoci (aoci.exe on Windows) at a stable absolute path.
Then use that absolute path to do the following for my project:

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

   scan takes its file inventory from Git, so do not add the cognition assets
   init writes (aoci.txt, aoci.meta.txt, aoci.code.txt, AGENTS.md) to .gitignore
   or .git/info/exclude — an ignored asset is silently skipped and the index
   cannot be built. Leave the host-config ignore init writes for itself as it is.

3. Tell me to restart the agent so the newly written MCP server takes effect

Stop after those three steps and do not build the index yet — I will tell you to continue
after the restart.

Nach dem Neustart des Agenten sende diese:

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.

Der Agent startet das Panel im Hintergrund mit aoci ui --detach --json und übergibt dir den Link. AOCI-Panel beschreibt, was es anzeigt und welche weiteren Befehle es gibt.

Warum der Neustart: Der Index wird über die MCP-Werkzeuge von AOCI geschrieben, und die Sitzung, die init ausgeführt hat, hat den MCP-Server nicht geladen, den init gerade geschrieben hat. Ein Host, der MCP-Server dynamisch lädt, benötigt möglicherweise keinen Neustart; Host-Integration erklärt, wie man das erkennt.

Wenn dein Projekt eine Datenbank hat (PostgreSQL und MySQL werden unterstützt, plus eingeschränktes openGauss 6.0.5), indiziere sie ebenfalls. Deklariere die Quelle wie unter Database Cognition beschrieben, stelle die Umgebungsvariable für die Verbindungszeichenfolge in der Host-Umgebung bereit (AOCI speichert keine Zugangsdaten) und sende dann:

Build the AOCI database index for this project.

Wenn der Kontext komprimiert wurde oder du möchtest, dass der Agent sein Bild des Systems neu aufbaut, sende dies:

Using only AOCI, establish whole-framework cognition of this project, tell me your mastery of each area as a percentage, and whether you can take over development.

Wie es funktioniert

AOCI (AI-Oriented Cognition Infrastructure) ist die Methode und das Protokoll: eine Schicht zwischen Coding-Agenten und Softwaresystemen. Modelle schlussfolgern, Agenten planen und führen aus, und AOCI hält eine aktuelle Beschreibung des Systems bereit, die Code, Konfiguration, Tests und Datenbankstruktur umfasst, damit Agenten sie vor dem Handeln lesen. AOCI-CODE ist dieses Projekt: das aoci-CLI, der MCP-Server und der Index, den sie pflegen.

AOCI-CODE destilliert das, was für das Verstehen und Ändern eines Systems wirklich zählt, in einen dichten Klartext-Index, der Symbole und Bedeutung verbindet. Wenn der Modellkontext begrenzt ist, liest ein Agent zuerst den Index, erhält die wichtigsten Informationen des Projekts in einem Durchgang und beginnt dann mit der Aufgabe. Das reduziert wiederholtes Suchen und erneutes Lernen und trägt das Verständnis über Aufgaben und Sitzungen hinweg.

• Keine einmalige Zusammenfassung. Der Index entwickelt sich mit dem System weiter und bleibt im Projekt, wo du ihn mit Git diffen, prüfen, versionieren und zurücksetzen kannst.
• Mehr als „wo die Dateien liegen". Er hält Verantwortlichkeiten, starke Beziehungen, öffentliche Verträge, Transaktionsgrenzen, Kompatibilitätsbeschränkungen und andere Dinge fest, die aus der Codestruktur schwer abzuleiten sind.
• Portabel. Der Index wird mit dem Projekt gespeichert und ist nicht an ein Modell, einen Agenten oder eine Sitzung gebunden. Solange er mit dem Code abgeglichen ist, kann jeder Agent und jede spätere Sitzung ihn wiederverwenden, ohne das Verständnis von Grund auf neu aufzubauen.
• Code und Datenbanken zusammen. Das Modell kann einen separaten Index auf Tabellenebene für Datenbanktabellen erstellen. Gemeinsam geliefert, geben beide dem Agenten ein vollständigeres Bild des Systems.

Der Index ist eine Menge verwalteter Klartextdateien, die mit dem Projekt gespeichert werden:

• Root (aoci.txt) deklariert, woraus der aktuelle Index besteht, und ist sein Aktivierungseinstiegspunkt.
• Meta (aoci.meta.txt) enthält das Tag-Wörterbuch, die FRAS-Regeln und die Autorenbeschränkungen.
• Code (aoci.code.txt) enthält die vom Modell verfassten Einträge für Code und andere Repository-Assets.
• Database (aoci.database.txt) enthält optionale Einträge auf Tabellenebene, wenn Database Cognition aktiviert ist.

Root, Meta und die beteiligten Objekt-Volumes bilden zusammen den Whole-Index. Der Workflow darauf hat drei Stufen:

1. Den Index unter Governance erstellen. Das Modell liest Quellcode und akzeptierte Belege. AOCI-CODE verwaltet den Managed Scope und die Einträge, die das Modell für jedes verwaltete Objekt mit der Rolle index schreibt.
2. Vor dem Handeln lesen. Der Agent liest die Projektregeln, den Live-Leitfaden und den aktuellen Whole-Index und prüft dann Quellcode und andere Belege für die anstehende Aufgabe.
3. Nach verifizierter Änderung pflegen. Sobald Code und Tests stabil sind, sorgen die Projektregeln und der MCP-Workflow dafür, dass der Agent die betroffenen Einträge aktualisiert und den Index wieder auf aligned bringt.

Da diese Dateien Klartext im Repository sind, versioniert Git sie. Solange der Index mit der aktuellen Systemversion abgeglichen bleibt, kann jeder Agent und jede spätere Sitzung denselben Whole-Index lesen und wiederverwenden.

Manuelle Integration

Beziehe AOCI-CODE aus der kanonischen Quelle oder verwende ein signiertes Paket von GitHub Releases. Bevor du eine vorgefertigte Binärdatei verwendest, befolge die grundlegende, empfohlene oder vollständige Verifizierungsstufe im Installationsleitfaden und melde, welche Stufe abgeschlossen wurde. Gib dieses README und den stabilen absoluten Pfad der verifizierten Binärdatei an einen Coding-Agenten, dem du vertraust, etwa Codex, Claude Code, Cursor oder OpenCode. Der Agent kann den Anweisungen im Projekt folgen, um AOCI zu initialisieren, MCP zu integrieren und den ersten Index zu erstellen.

Wie lange der erste Index dauert, hängt von der Größe des Repositorys ab. Eine normale Integration umfasst vier Schritte: die Binärdatei vorbereiten, den Agenten oder dich selbst das Ziel-Repository initialisieren lassen, den Host bitten, „den Index zu erstellen", und die Übereinstimmung überprüfen. Danach musst du nicht jede Anfrage mit „den Index pflegen" beenden. Die Projektregeln und der MCP-Workflow sorgen dafür, dass der Agent den Index inkrementell pflegt, wann immer sich verwaltete Objekte ändern.

Voraussetzungen

• Ein verifiziertes Release-Paket oder ein Checkout des kanonischen AOCI-CODE-Quell-Repositorys.
• Nur für Quellcode-Builds: die Go-Toolchain, die in go.mod, make und den anderen vom Repository benötigten Werkzeugen deklariert ist.
• Ein unterstützter MCP-Host, etwa Codex, Claude Code, Cursor oder OpenCode.
• Normaler Lese- und Schreibzugriff auf das Ziel-Repository.

AOCI-CODE integriert sich in den MCP-Host, nicht in eine Modell-Provider-API. DeepSeek und andere Modelle können AOCI-CODE nutzen, wenn der Agent oder Host, der sie ausführt, standardmäßiges stdio-MCP unterstützt und dem Werkzeugvertrag folgen kann; ein Modellname allein begründet keine Kompatibilität.

Der Weg über signierte Pakete und die Befehle zur Prüfung der ausführbaren Datei stehen im Installationsleitfaden. Der Weg über den Quellcode-Build folgt unten.

Aktueller RC: verifiziertes Paket verwenden oder aus dem Quellcode bauen

[!IMPORTANT] AOCI-CODE v0.1.0-rc22 ist der aktuelle Release Candidate. Es ist Fair-Source-/Source-Available-Software unter FSL-1.1-MIT; siehe LICENSE. Baue aus der kanonischen Quelle oder verwende ein signiertes Paket aus dem v0.1.0-rc22 GitHub Release, nachdem du das Verfahren zur Release-Verifizierung befolgt hast.

Die signierte Release-Binärdatei identifiziert sich als aoci version 0.1.0-rc22. Ein Quellcode-Build identifiziert stattdessen den exakten Checkout und meldet möglicherweise eine Entwicklungsversion wie v0.1.0-rc22-1-g<short-commit> (plus -dirty, falls zutreffend), zusammen mit seinem Git-Commit. Dies sind unterschiedliche Build-Eingaben, kein Versionskonflikt.

Um mit der GitHub CLI herunterzuladen, authentifiziere dich zuerst und lade dann die Assets des getaggten Releases herunter:

gh auth login
gh release download v0.1.0-rc22 --repo aoci-spec/aoci-code

Für einen anonymen Download öffne die v0.1.0-rc22 Release-Seite in einem Browser und lade das Archiv und die benötigten Verifizierungs-Assets herunter.

Um aus dem Quellcode zu bauen, klone das kanonische Repository, baue die Binärdatei und halte den resultierenden Pfad stabil:

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

Unter Windows baue denselben Quellcode in 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 --version

Gib dann dieses README an einen Agenten, dem du das Projekt bereits anvertraust, und frage:

Read this AOCI-CODE README and use the built aoci binary at its stable absolute path
to initialize AOCI for the current project, integrate MCP, and run scan. Stop there and
tell me to restart the agent; I will ask you to build the index afterwards.

Der Agent sollte das Projektstammverzeichnis ermitteln, einen stabilen absoluten Pfad zur gebauten Binärdatei verwenden, die Initialisierung ausführen, die zum aktuellen Host passt, und Ihnen klar mitteilen, wann ein Host-Neustart oder eine echte menschliche Genehmigung erforderlich ist. Die Binärdatei kann im AOCI-CODE-Checkout bleiben oder in ein gemeinsames Werkzeugverzeichnis verschoben werden, solange die MCP-Konfiguration auf den korrekten absoluten Pfad verweist.

Manuelle Initialisierung

Um AOCI selbst zu initialisieren, führen Sie Folgendes im Stammverzeichnis des Ziel-Repositorys aus oder übergeben Sie einen expliziten Pfad über --repo:

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

init schreibt die Locale-Konfiguration, den verwalteten AGENTS.md-Regelblock, die Git-Grenzen und ein leeres Index-Gerüst. Konfiguration und Prompting variieren je nach Host; siehe Host-Integration. Es erfindet keine fachliche Bedeutung aus Dateinamen, Verzeichnissen oder einem AST.

Für ein neues Repository etabliert der erste scan die verwaltete Baseline. Bei einem Projekt, das bereits eine verwaltete Baseline hat, erfolgt das Hinzufügen, Entfernen oder Ändern des verwalteten Umfangs über den formalen Scope-Change-Workflow; scan --force ist keine Abkürzung, um Governance-Fakten neu zu definieren. --force kann auch keine ungelösten Drift, Belege oder Wiederherstellungsgrenzen löschen.

$Aoci = (Resolve-Path "C:\path\to\aoci-code\build\aoci.exe").Path
& $Aoci --repo . init --locale en-US --agent codex
& $Aoci --repo . scan

Den Agenten den ersten Index bauen lassen (wichtig)

Sobald die Initialisierung und scan abgeschlossen sind, prüfen Sie, ob die Agentensitzung bereits die AOCI-Werkzeuge bereitstellt; aktualisieren oder starten Sie sie andernfalls neu. Geben Sie dann im Agenten für das Zielprojekt Folgendes ein:

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.

Der Agent startet das Panel im Hintergrund mit aoci ui --detach --json und übergibt Ihnen den Link. AOCI-Panel beschreibt, was es anzeigt und welche weiteren Befehle es gibt.

Der Host liest die AOCI-Regeln und den Live-Leitfaden des Projekts, untersucht Quellcode, Tests, Konfiguration und relevante Belege und schreibt dann FRAS-Kandidaten für jedes verwaltete Objekt, dessen Rolle index ist. Sie müssen Plan, Stage, Check, Diff, CAS oder Apply nicht selbst orchestrieren.

Sobald der erste Index vollständig ist, senden Sie gewöhnliche Entwicklungsanfragen wie üblich, zum Beispiel:

Add priorities to tasks, including the frontend, backend, database, and test changes.

Sie müssen nicht „den AOCI-Index am Ende pflegen" anhängen. Die Projektregeln und MCP veranlassen den Agenten, nach Indexänderungen zu suchen, sobald Code und Tests stabil sind, und dann die betroffenen Einträge über den formalen Workflow zu aktualisieren. Wenn das Projekt automation.mode=auto verwendet, unterbricht AOCI-CODE Sie nur, wenn eine echte menschliche Genehmigung erforderlich ist, eine externe Aktion ausgeführt werden muss, eine Wiederherstellung nicht nachgewiesen werden kann, eine Sicherheitsprüfung fehlschlägt oder ein Konflikt mit gleichzeitigen Änderungen durch Dritte festgestellt wird. Andere Automatisierungsmodi folgen ihren eigenen Laufzeitverträgen.

Ausrichtung überprüfen

Nach Abschluss des Onboardings führen Sie aus:

"$AOCI" --repo . verify
"$AOCI" --repo . check

Der Index und der aktuelle verwaltete Quellcode sollten wieder zu aligned konvergieren. Wenn nicht, konsultieren Sie zuerst den Live-Leitfaden; duplizieren Sie die interne Zustandsmaschine nicht in einem Wrapper-Skript:

"$AOCI" --repo . index agent guide --agent codex --json

Grundlegende Diagnose ausführen

"$AOCI" --repo . capabilities
"$AOCI" --repo . doctor

Um zu bestätigen, mit welchem AOCI der Host tatsächlich verbunden ist, lesen Sie, was der Server über sich selbst berichtet, statt was auf der Festplatte liegt. In jeder aoci_overview-check_only-Antwort oder jeder aoci_maintain-Antwort ist cognition_receipt.mcp_service_version die laufende Version und runtime_repository_root das Repository, das sie verwaltet. Der passende Binärpfad ist der command in der .mcp.json des Projekts oder in der entsprechenden Host-Konfiguration: .codex/config.toml, opencode.json oder .cursor/mcp.json. Das Ersetzen von Bytes auf der Festplatte ändert keinen laufenden MCP-Prozess, daher prüfen Sie nach einem Upgrade oder Rollback erneut anhand dieser Fakten.

Für eine einmalige Einführung verwenden Sie examples/minimal-repository im Repository.

make fast

make full
./build/aoci --version

mkdir -p build
CGO_ENABLED=0 go build -o build/aoci ./cmd/aoci

Was nach der Initialisierung erscheint

Ein typisches Repository enthält diese Indexdateien:

aoci.txt                    Root: declares the current CognitionSet and participating Volumes
aoci.meta.txt               Meta: tag dictionary, FRAS rules, and authoring constraints
aoci.code.txt               Code: model-authored entries for code and repository assets
aoci.database.txt           Database: optional table-level entries; absent by default
.aoci/
├── config.json             Team policy, Locale, Scope, and budgets
├── baseline.json           Governed Baseline for source, index, and database bindings
├── curation.json           Optional file-level include/exclude decisions
└── ...                     Drafts, Ledger, transactions, and recovery evidence; normally not committed to Git

Das Initialisieren eines neuen Projekts erzeugt das Root, Meta und ein leeres Code-Volume; Database fehlt standardmäßig. AOCI-CODE generiert keine fachliche Bedeutung für das Repository oder die Datenbank von sich aus.

aoci init --agent <name> schreibt zusätzlich die Host-Integrationskonfiguration (.mcp.json, .claude/settings.json, .codex/config.toml oder opencode.json), deren Befehls- und Repository-Pfade maschinengebundene absolute Pfade sind. Fügen Sie diese Dateien zur .gitignore des Repositorys hinzu und committen Sie sie nicht: Eine committete Kopie bricht auf jeder anderen Maschine, und da die Installer einen vorhandenen Eintrag anhand der Schlüsselpräsenz erkennen, behält ein erneutes Ausführen von init dort stillschweigend die defekten Pfade bei.

Wie eine Entwicklungsaufgabe abläuft

Die beiden folgenden Diagramme zeigen den Workflow, wie Sie ihn erleben, nicht die interne Implementierung von AOCI.

Neues Projekt: zuerst ein einfaches System bauen, dann AOCI einbringen

flowchart TD
    I["The user proposes a product idea and requirements"] --> S["Use the agent's existing capabilities to build a simple new system"]
    S --> Q["Integrate AOCI MCP"]
    Q --> V["The agent builds the Whole-Index and verifies aligned"]
    V --> N["The user continues with ordinary development requests"]
    N --> M["The agent completes code, tests, and incremental index maintenance"]
    M --> N

Ein neues System benötigt AOCI-CODE nicht ab der ersten Codezeile. Bauen Sie zuerst einen Prototyp mit den vorhandenen Fähigkeiten des Agenten; etwa 10.000–30.000 Zeilen sind ein guter Punkt, um es einzubringen (keine harte Schwelle). Teams, die früher eine sitzungsübergreifende Kontinuität wünschen, können früher integrieren.

Bestehendes Projekt: das Repository indexieren, dann iterieren

flowchart TD
    R["Existing repository, tests, configuration, and optional Schema"] --> B["Build AOCI-CODE from canonical source<br/>Request index generation"]
    B --> E["The agent inspects the existing system and writes the first index"]
    E --> V["Verify, Check, and Guide converge to aligned"]
    V --> T["The user submits an ordinary development task"]
    T --> C["The agent modifies code and runs quality checks"]
    C --> U["MCP guides the agent through index maintenance"]
    U --> G["The index and the current system return to aligned"]
    G --> T

Nach Abschluss des ersten Index funktionieren beide Abläufe im Alltag gleich: Sie beschreiben die fachliche oder technische Anforderung; der Agent kombiniert den Whole-Index mit aktuellen Belegen, führt die Entwicklung und Verifikation durch und aktualisiert die geänderten Objekte über MCP, während er die Aufgabe abschließt. Sie müssen die internen Befehle Plan, Stage, Diff, CAS oder Baseline nicht erlernen oder die Wartungsanforderung in jedem Prompt wiederholen.

Wenn ein vollständiger Batch abgelehnt wird, bevor irgendein formaler Schreibvorgang beginnt, bleibt der Index unverändert. Wenn der Workflow nach Beginn der formalen Schreibvorgänge unterbrochen wird, bewahrt das System die unveränderliche Absicht, die Schreibbelege und den Wiederherstellungszustand und setzt dann entweder von einem nachweisbaren Postimage fort oder rollt auf das exakte Preimage zurück. Ein Byte-Konflikt durch Dritte schlägt fail-closed fehl; AOCI-CODE überschreibt niemals eine externe Änderung, um „den Schreibvorgang abzuschließen".

Der Endzustand ist immer einer von applied, repair_required oder stopped. stopped ist kein Erfolg und bedeutet nicht zwangsläufig, dass nichts geschrieben wurde; prüfen Sie failed_step, die Belege für formale Schreibvorgänge und die Wiederherstellungsaktion, die der Leitfaden zurückgibt.

Wer was tut: das Modell und AOCI-CODE

Das Modell besitzt die Bedeutung

Das Host-Modell liest Quellcode, Tests, Konfiguration, Dokumentation und alle Belege, die es benötigt, und entscheidet dann:

• wofür ein Objekt tatsächlich verantwortlich ist;
• welche Dateien, Module oder Datenbankobjekte starke Beziehungen sind, die berücksichtigt werden müssen, um es sicher zu ändern;
• welche APIs, Befehle, Formate oder beobachtbaren Verträge es bereitstellt;
• welche Transaktions-, Autorisierungs-, Nebenläufigkeits-, Caching-, Deployment-, Kompatibilitäts- oder historischen Einschränkungen nicht allein aus der gewöhnlichen Struktur abgeleitet werden können.

AOCI-CODE setzt FRAS nicht aus Dateinamen, Pfaden, Erweiterungen, ASTs oder Vorlagen zusammen und schreibt nicht stillschweigend um, was das Modell geschrieben hat.

AOCI-CODE besitzt die Governance

AOCI-CODE ist verantwortlich für:

1. die Etablierung von Safe Inventory, Managed Scope und der aktuellen Baseline;
2. die Bereitstellung des aktuellen Whole-Index und die Bestätigung seiner Identität;
3. die Erzeugung eines deterministischen Plans, Zielsatzes und von Quell-SHA-256-Werten;
4. die Validierung der Kandidatenstruktur, des Tag-Wörterbuchs, der Beziehungsidentitäten, des Umfangs, der Eigentümerschaft, der Budgets und des betroffenen Bereichs;
5. die Bewahrung der Bindung zwischen Prüf-, Diff- und Review-Inhalten;
6. das Committen eines vollständigen Batches mit prozessübergreifenden Sperren, CAS und atomaren Schreibvorgängen;
7. das Vorrücken der Baseline, das Anhängen des Ledgers und die Bewahrung von Wiederherstellungsbelegen nach einem Fehler nach dem Schreiben;
8. den erneuten Nachweis des aktuellen Governance-Zustands durch Verify, Check und den Leitfaden;
9. die Ableitung von Lineage-, Relations-, Impact-, Snapshot- und Evolution-Beobachtungen aus autoritativen Assets, ohne eine zweite Quelle der Wahrheit zu erzeugen.

Alles grüne Maschinenergebnisse bedeuten nur, dass die kodierten strukturellen und Governance-Verträge gelten; sie bedeuten nicht, dass jede Aussage, die das Modell geschrieben hat, korrekt ist.

Wie der Index organisiert ist

Ein AOCI-Index hat zwei Ebenen: die Indexregeln und die Indexeinträge. Das Produkt unterstützt zwei physische Layouts, und diese sind nicht ein Dateiformat.

Volumes-v1-Layout

Ein Volumes-Projekt trennt Verantwortlichkeiten:

• aoci.txt ist nur das Root. Es deklariert die Volumes, die am aktuellen CognitionSet teilnehmen.
• aoci.meta.txt enthält Meta: das Tag-Wörterbuch, die FRAS-Regeln, Budgets und den Authoring-Vertrag.
• aoci.code.txt enthält die Einträge für Code-Objekte.
• aoci.database.txt enthält die Einträge für Datenbankobjekte, wenn Database Cognition aktiviert ist.

Code- und Database-Volumes teilen dieselbe FRAS-Zeilenstruktur, haben aber unabhängige Objektidentitäten, Belegbindungen, Eigentümerschaft und Lebenszyklen. Root, Meta und die Objekt-Volumes bilden zusammen den Whole-Index; nur das aoci.txt-Root zu lesen reicht nicht aus, um zu behaupten, das gesamte System gelesen zu haben.

Betrachten Sie es als eine Karte:

• Die Indexregeln sind die Legende und das Koordinatensystem der Karte.
• Die Indexeinträge sind die Marker, die jeden Ort beschreiben.
• Root ist der Katalog- und Versionseinstiegspunkt für den aktuellen Kartensatz.
• Ein Volume ist ein separates Blatt, das vom selben Protokoll regiert wird, aber seine eigene Belegquelle und seinen eigenen Lebenszyklus hat.

Wie der Index-Header aussieht

Root und Meta beginnen jeweils mit maschinengelesenen Header-Zeilen. Dies schreibt aoci init für ein neues en-US-Projekt namens my-service, beginnend mit dem Root, dem Aktivierungseinstiegspunkt:

#AOCI-ROOT-MANIFEST: 1
#Format-Version: cognition-volumes/v1
#Locale: en-US
#Project: my-service
#Global-Invariants: -
#Volume: id=meta kind=meta path=aoci.meta.txt format=meta-v1 depends=- state=enabled
#Volume: id=code kind=code path=aoci.code.txt format=object-fras-v2 depends=meta state=enabled

Jede #Volume:-Zeile deklariert ein teilnehmendes Volume mit seiner Identität, Art, Pfad, Format, Abhängigkeit und Aktivierungszustand. Ein Volume, das hier nicht deklariert ist, ist nicht Teil des aktuellen CognitionSet, unabhängig davon, was sonst im Arbeitsbaum enthalten ist. Das Aktivieren von Database Cognition fügt eine weitere Zeile hinzu, #Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled.

Meta beginnt dann mit den Regeln, die jeden Eintrag regieren:

#AOCI-META-VOLUME: 1
#Object-Protocol: repository-cognition-object/v2
#FRAS-Discipline: 2
#FRAS-v2-Limits-Authority: machine-contract
#S-Admission: non-inferable-and-error-preventing
#S quota: C9-8≤600 C7-4≤200 C3-1≤50
#Object-Kinds: code=file database=table

#FRAS-v2-Limits-Authority: machine-contract ist die tragende Zeile: Die Feldgrenzen gehören zur Binärdatei, nicht zu diesem Text, sodass ein Projekt sie nicht durch Bearbeiten seines eigenen Meta erweitern kann. #S-Admission und #S quota regieren speziell das S-Feld: was dort überhaupt aufgezeichnet werden darf und wie viele Zeichen jedes Wichtigkeitsband ausgeben darf. Das Tag-Wörterbuch folgt unmittelbar nach diesen Zeilen; es wird weiter unten vollständig gezeigt.

Das Code-Volume beginnt mit einer einzigen Zeile, #AOCI-CODE-VOLUME: 1, und alles danach sind Verzeichnisabschnitte und Einträge.

Dies sind die Werte, mit denen ein neues Projekt startet, keine festen Protokollkonstanten. Das eigene Root und Meta jedes Repositorys sind danach maßgeblich: Ein älteres Projekt kann ein benutzerdefiniertes Tag-Wörterbuch tragen, und ein mit --locale zh-CN initialisiertes Projekt schreibt #Locale: zh-CN und lokalisiert den Schlüssel #S quota: entsprechend.

Was die Indexregeln definieren

In Volumes v1 speichert das Meta-Volume des Projekts diese Regeln; im Legacy-Layout liegen sie im monolithischen Header. Projekte können unterschiedliche Tag-Wörterbücher verwenden, während die grundlegende FRAS-Struktur gleich bleibt.

Diese README erklärt nur, wie diese Regeln zu lesen sind. Für die konkreten, ausführbaren Regeln sind das Meta- oder Legacy-Header des aktuellen Projekts, der AOCI-Leitfaden und die formale Spezifikation maßgeblich.

Was ein Eintrag erfasst (FRAS)

Sobald die Regeln vorliegen, schreibt das Modell für jedes verwaltete Objekt mit der Rolle index einen Eintrag. Die Rolle observe nimmt nur an der Änderungsbeobachtung teil, und die Rolle exclude markiert, was bewusst ausgelassen wird; keine von beiden besitzt einen formalen Eintrag. AOCI verwendet FRAS, um die vier Informationsarten zu ordnen, die in einem Eintrag am wichtigsten sind:

• F — Function: wofür das Objekt verantwortlich ist.
• R — Relations: welche anderen Objekte ebenfalls berücksichtigt werden müssen, um es zu verstehen oder sicher zu ändern.
• A — API: welche Schnittstellen, Befehle, Formate oder beobachtbaren Verträge es bereitstellt.
• S — Non-obvious constraints: wichtige Informationen, die F, R und A nicht abdecken, die aber benötigt werden, um das Objekt sicher zu verstehen oder zu ändern, etwa zentrale Einschränkungen, Ausnahmen, Grenzen und besondere Semantiken. S sollte die ersten drei Felder nicht wiederholen.

Zum Beispiel verwendet ein Eintrag innerhalb des Verzeichnisabschnitts ===.../internal/fs/=== den Basisnamen:

atomic.go[CG9L]: F:Provides durable replace CAS, create CAS, atomic writes, and no-clobber recovery moves | R:code:internal/fs/atomic_exchange_linux.go,code:internal/fs/atomic_exchange_windows.go,code:internal/fs/lock.go | A:AtomicWrite,AtomicWriteCAS,AtomicCreateCAS,AtomicMoveCAS | S:Native publication never degrades to an overwriting rename; on a race, unsafe type, or unverifiable bytes, preserve third-party state 

Der Verzeichnisabschnitt und der Basisname ergeben zusammen eine Code-Objektidentität. Für Volume-übergreifende oder Systemprojektionen erweitert sie sich zu einer kanonischen Identität wie code:internal/fs/atomic.go. Ein Datenbankobjekt verwendet seine eigene kanonische Identität, etwa database://primary/public/orders.

Der Eintrag hat zwei Teile:

atomic.go [CG9L]
└─ object ─┘ └ tags ┘

F: Core responsibility
R: Strong relationships that must be understood together
A: External interface or contract
S: Important additional information beyond F, R, and A

Kompakte Tags geben jedem Objekt Koordinaten für Architekturschicht, funktionale Domäne, Wichtigkeit, optionale technische Merkmale und Größe. Das Tag-Wörterbuch wird durch das Meta-Volume oder den Legacy-Header des Projekts definiert. Das Programm validiert das Wörterbuch und die Struktur; es entscheidet nicht über die fachliche Bedeutung.

S ist keine Inhaltsangabe, keine gewöhnliche Zusammenfassung und keine Wiederholung von F, R und A. Es ergänzt wichtige Informationen, die die ersten drei Felder nicht abdecken und die das Verständnis oder die technische Korrektheit beeinflussen, zum Beispiel:

• ein Redis-Zugriffsfehler muss auf die Datenbank zurückfallen;
• eine bestimmte Tabelle darf nicht in AutoMigrate aufgenommen werden;
• ein Legacy-Kompatibilitätszweig darf nicht durch gewöhnliche Bereinigung entfernt werden;
• die Originaldatei muss nach einem Schreibfehler erhalten bleiben.

Das Modell schreibt dies aus tatsächlichem Quellcode und Belegen. AOCI-CODE validiert die Struktur des Eintrags, bindet ihn an die Quelldatei und regelt, wie er in den formalen Index gelangt.

Das Starter-Tag-Wörterbuch lesen

Der folgende Auszug ist wörtlich aus der aktuellen Meta-Vorlage des en-US Volume (textassets/en-US/templates/volume-meta.txt.tmpl) übernommen. Es ist ein Starter-Wörterbuch, kein universelles Vokabular: Das formale Meta jedes Repositorys bleibt maßgeblich. Der Starter deklariert kein D-Wörterbuch; D bleibt eine optionale Achse und darf nur verwendet werden, wenn das aktuelle formale Meta sie deklariert.

#Canonical-Tag-Authoring: compact A+B+C+[D]+E; dotted form is read compatibility only
#Code canonical identity example: code:path/to/file.go
#Code Entry example: file.go[EG7T]: F:Runs the example application | R:code:config/load.go | A:main | S:Exits non-zero when the config file is missing; it never falls back to built-in defaults
#[Tag dictionary: code]
#A Layer: C-SharedFoundation E-EntryBoundary A-ApplicationOrchestration D-DomainLogic K-AlgorithmComputation M-Middleware P-Persistence I-IntegrationAdapter R-RuntimeFoundation L-LibrarySDK F-DeclarativeConfiguration O-OperationsDelivery T-TestValidation S-DocumentationSpecification X-DevelopmentTooling Z-Other
#B Module: G-CrossDomain U-UserInteraction B-CoreBusiness D-DataState I-IdentityAccess N-NetworkProtocol M-MessageEvent S-SecurityPrivacy C-ConfigurationPolicy O-Observability R-ReliabilityRecovery P-PerformanceResource W-WorkflowScheduling A-AnalyticsIntelligence H-HardwareDevice L-Localization V-BuildRelease Q-QualityAssurance E-ExtensionPlugin Z-Other
#C Importance: 9-highest 8-very-high 7-high 6-above-average 5-medium 4-below-average 3-low 2-very-low 1-lowest
#E Scale: L-large>400 M-medium200-400 S-small100-200 T-tiny<100
#[Tag dictionary: database]
#A Layer: E-EntityMaster T-TransactionFact R-RelationMapping M-DetailDependent C-ReferenceDictionary S-StateStorage H-HistoryVersion L-LogAudit Q-QueueOutbox A-AggregateProjection K-KeyValueConfiguration B-DocumentLargeObject Z-Other
#B Module: G-CrossDomain B-CoreBusiness I-IdentityAccess T-OrganizationTenant U-UserExperience F-FinanceBilling K-ContentKnowledge C-ConfigurationPolicy W-WorkflowTask M-MessageEvent N-ExternalIntegration S-SecurityPrivacy O-ObservabilityAudit R-ReliabilityRecovery P-PerformanceResource A-AnalyticsIntelligence H-HardwareDevice L-Localization V-BuildRelease Q-QualityTesting E-ExtensionPlugin Z-Other
#C Importance: 9-highest 8-very-high 7-high 6-above-average 5-medium 4-below-average 3-low 2-very-low 1-lowest
#E Scale: L-large>400 M-medium200-400 S-small100-200 T-tiny<100

Unter dem Starter-Code-Wörterbuch bedeutet [CG9L] C SharedFoundation, G CrossDomain, 9 höchste Wichtigkeit und L große Größe; es ist kein D-Wert vorhanden. Dies erklärt, wie der bestehende Eintrag zu lesen ist, nicht wie das Modell Tags zuweisen sollte. Das Modell wählt Tags weiterhin aus dem aktuellen Projekt-Meta, basierend auf Quellcode und akzeptierten Belegen.

Cognition Volumes

AOCI-CODE pflegt einen logischen Whole-Index, während jede Art von Index ihre eigene Datei, Eigentümerschaft und ihren eigenen Lebenszyklus hat.

Jedes Objekt hat genau einen gültigen Eigentümer. Ein Objekt im falschen Volume zu platzieren erzeugt einen Eigentümerschaftskonflikt. AOCI-CODE behebt ihn nur, wenn die Maschine den falschen Eigentümer, den richtigen Eigentümer und die aktuellen Objektfakten beweisen kann; es rät die Eigentümerschaft nicht aus ähnlichen Namen.

Das Code-Volume, das Database-Volume und der Geltungsbereich können sich gemeinsam weiterentwickeln, teilen sich aber eine einzige verwaltete Commit-Grenze. Das Anwenden einer Domäne darf die bestehende Baseline-Projektion einer anderen Domäne nicht verwerfen. Ein Volume-Apply, die Baseline-Aktualisierung und die zugehörigen Geltungsbereichsprojektionen werden als ein konsistentes Transaktionsergebnis veröffentlicht oder gehen in eine nachweisbare Wiederherstellung über. Sie hinterlassen nie einen halbfertigen Zustand, in dem „die Datei erfolgreich war, aber ein anderes Volume keine Baseline hat“.

Host-Integration

aoci init schreibt immer verwaltete Agent-Regeln, aber die Host-Integration unterscheidet sich:

• Codex erhält eine MCP-Konfiguration auf Projektebene und, mit --hooks, einen Kontextkompaktierungs-Prompt plus SessionStart(compact). Es installiert weiterhin keinen Dateibearbeitungs-Hook.
• Claude Code kann einen PreToolUse-Hook installieren.
• OpenCode V1 erhält eine strikte opencode.json auf Projektebene.
• Cursor gibt nur einen Referenz-Konfigurationsausschnitt zurück; es wird nichts in das Projekt geschrieben.

Prüfe nach der Konfiguration, ob die aktuelle Host-Sitzung die AOCI-Tools bereits bereitstellt. Aktualisiere oder öffne diese Projektsitzung nur neu, wenn sie den neuen Server noch nicht geladen hat. Eine neue Sitzung liest die Regeln und den Whole-Index normalerweise einmal. Solange die Indexidentität gültig bleibt und keine bekannte Host-Kompaktierung stattgefunden hat, verwenden spätere Aufgaben wieder, was das Modell bereits hat; der gesamte Index wird nicht erneut mechanisch injiziert.

aoci --repo /absolute/path/to/repository init --agent codex
aoci --repo /absolute/path/to/repository init --agent codex --hooks
aoci --repo /absolute/path/to/repository init --agent claude --hooks
aoci --repo /absolute/path/to/repository init --agent opencode
aoci --repo /absolute/path/to/repository init --agent cursor

Codex --hooks beschränkt eine Kompaktierungsübergabe auf die Receipt-Identität, den unvollendeten Schreib- oder Wiederherstellungszustand und eine unmittelbare Neuladeanweisung; es darf keine Whole-Index- oder Overview/Attestation-Inhalte behalten oder zusammenfassen. Ein PreCompact-Hook kann nicht in die Host-Kompaktierungseingabe injizieren oder Verlauf daraus löschen und kann dies daher nicht allein durchsetzen. Prüfe und vertraue dem installierten Projekt-Hook über Codex /hooks, bevor du dich darauf verlässt.

Die Legacy-Ausgabe behält die Stufen 0–4 für die Kompatibilität mit bestehenden Hosts und Berichten bei. Das aktuelle cognition-state/v2 drückt aus, wie brauchbar das Bild des Modells vom System ist, als Stufen 0–3, und trennt strikte Beweis- und Governance-Fakten in unabhängige Dimensionen:

Diese Dimensionen ersetzen einander nicht. Attestation beweist nur die Auslieferungsabdeckung und Identitätskonsistenz für das aktuelle Material; es bedeutet nicht, dass der Agent jede mögliche zukünftige Aufgabe vollständig verstanden hat. Nur current_system_cognition_reliable=true erlaubt eine uneingeschränkte Behauptung vollständigen Verständnisses des aktuellen Systems.

AOCI-Panel

aoci ui stellt auf dieser Maschine ein schreibgeschütztes Panel bereit, sodass du den Zustand des Index sehen kannst, ohne einen Agenten zu fragen:

• den Index-Header und die Code-/Database-Volumes wörtlich (===-Abschnittszeilen bleiben unverändert, filterbar, als Ganzes kopierbar); der Tab „Alle“ ist der vollständige Index genau so, wie ein Agent ihn über Overview erhält
• Index-Tokens gegenüber dem Budget und den Overview-Chunk-Plan
• wie viel Code der Index abdeckt: Dateien, Zeilen, Tokens und das Kompressionsverhältnis; wie viele Datenbanktabellen
• Governance-Zustand und Drift, Managed Scope, Host-Integrationen und die laufenden aoci mcp-Prozesse
• die Befehle und Prompts, die dem Agenten als Nächstes gegeben werden sollen, mit Kopierschaltflächen

Die Seite wechselt zwischen Chinesisch und Englisch; das Aktualisierungsintervall ist wählbar (standardmäßig 30 s).

Mehrere aoci mcp-Server in einem WSL? Unter Linux und WSL entdeckt das Panel jeden aoci mcp-Prozess des aktuellen Benutzers und dessen Repository, wechselt über Tabs oben zwischen ihnen und markiert einen Server, dessen Binärdatei auf der Festplatte ersetzt wurde. Grenzen: Es bindet nur Loopback-Adressen (jede andere Bindung wird abgelehnt), beantwortet nur GET und HEAD, nimmt keine Sperre, hängt nichts an das Ledger an und ändert kein Byte des Repositorys. Es ist ein separater Prozess, der nichts mit aoci mcp zu tun hat; der MCP-Server öffnet weiterhin keinen Socket. Die Registrierung eines Hintergrundpanels liegt im Cache-Verzeichnis des Benutzers, niemals im Repository.

Häufige CLI-Befehle

Häufige Kombinationen:

# Initialization and first Baseline
aoci --repo . init --locale en-US --agent codex
aoci --repo . scan

# Verification and governance gates for Cognition Volumes
aoci --repo . verify --json
aoci --repo . check --json

# Live Guide; do not duplicate the state machine in a wrapper
aoci --repo . index agent guide --agent codex --json

# Capabilities and diagnostics
aoci --repo . capabilities
aoci --repo . doctor

# Database Evidence, Access, and Cognition lifecycle
aoci --repo . database --help
aoci --repo . database source access --source primary --json
aoci --repo . database cognition status
aoci --repo . cognition plan --help

# Derived System Cognition observations
aoci --repo . cognition system lineage
aoci --repo . cognition system relations

# MCP stdio Server
aoci --repo . mcp

Befehle für Plan, Stage, Check, Diff, Apply, Curation, Scope Change, Bootstrap, Migration und Wiederherstellung existieren weiterhin. Folgen Sie dem Leitfaden, den die laufende Binärdatei zurückgibt; kopieren Sie die interne Zustandsmaschine nicht in Skripte.

Über „schreibgeschützte" Befehle

Für verify, check, index score und index inventory bedeutet „schreibgeschützt", dass der formale Index und die Baseline nicht verändert werden; es bedeutet nicht strikt null Dateisystemschreibvorgänge. Wenn das Ledger aktiviert ist, können alle vier Befehle an das lokale Ledger anhängen, und verify versucht außerdem, den Verify-Verlauf zu schreiben. Ein Fehler beim Audit-Schreiben ändert weder bestehende Exit-Codes noch Governance-Kriterien.

Wenn ein strikt dateischreibfreier Vorgang erforderlich ist, verwenden Sie eine isolierte Kopie; die aktuelle öffentliche CLI bietet keinen pauschalen Schalter, der alle Ledger- und Verify-Verlauf-Schreibvorgänge deaktiviert. System-Cognition-Befehle erzeugen keinen zweiten formalen Zustand, aber gewöhnliche CLI-Aufrufe folgen weiterhin dem Laufzeitvertrag der aktuellen Version für Ledger- und lokale Verlaufsdatensätze.

MCP-Server

aoci mcp benötigt keinen residenten Daemon und stellt über stdio genau neun Tools bereit:

Im MCP-Modus ist stdout für JSON-RPC reserviert; Protokolle und Diagnosen gehen an stderr. Die Tool-Beschreibungen, JSON-Schemata und Maschinenzustandswerte, die die laufende Binärdatei bereitstellt, sind maßgeblich; diese README ist nur ein Ausgangspunkt.

Die aktuelle Version stellt die System-Cognition-Fähigkeiten über die bestehende CLI und den Governance-Kernel bereit. Sie fügen kein zehntes MCP-Tool hinzu und ändern weder Namen, Zwecke noch den stdio-Vertrag der bestehenden neun.

Langlaufende Sitzungen und Whole-Index-Lieferung

Zu Beginn einer neuen Konversation lädt ein Agent normalerweise eine vollständige Overview, um ein Bild des Systems zu erhalten, das dem aktuellen Repository, der Indexversion und der AOCI-Dienstidentität entspricht. Solange das Modell sich auf dieses Bild verlassen kann, muss es nicht vor jeder Aufgabe oder jedem Tool-Aufruf neu laden.

Innerhalb derselben Konversation entscheidet das Modell anhand seines eigenen Zustands, ob es erneut lädt, außer nach einer bekannten Host-Kontextkompaktierung. Eine kompaktierte Übergabe darf nur die Receipt-Identität, den unvollendeten Schreib- oder Wiederherstellungszustand und eine unmittelbare Neuladeanweisung bewahren; sie darf keine Whole-Index- oder Overview-Header-, Eintrags-, Chunk-, Challenge- oder Attestation-Inhalte behalten oder zusammenfassen. Indexinhalte oder ein in diese Übergabe kopiertes Receipt können nicht beweisen, dass das aktuelle Bild des Modells zuverlässig ist.

Bevor der Agent nach einer bekannten Kompaktierung die Geschäftsarbeit fortsetzt, lädt er die Regeln neu, falls sie nicht mehr zuverlässig vorhanden sind, deklariert context_compaction mit einer frischen Ereignis-ID und absolviert eine gewöhnliche vollständige Overview-Sequenz aus Cursor, Bestätigung und Attestation. check_only und die Cognition-Probe sind kein Ersatz. Nach frischem vollständigem Transport erlaubt die bestehende Regel für partielle oder fehlgeschlagene Attestation weiterhin eine quellengebundene Fortsetzung ohne eine zweite automatische Overview. Bei einer semantischen Änderung oder einer wichtigen Phasengrenze ohne bekannte Kompaktierung stellt AOCI Aktualisierungsschwellen, Checkpoints und Identitätsfakten bereit, und das Modell entscheidet, ob es sein systemweites Bild für die Aufgabe wiederherstellen muss.

Der Inhalt jeder vollständigen Overview besteht aus einem Startmarker, dem exakten Inhalt des aktuellen formalen Index und einem Endmarker.

Wenn eine Overview das Chunk-Budget des Projekts überschreitet:

1. beginnt die Lieferung sofort mit Chunk 1;
2. muss der Agent next_cursor automatisch bis zum letzten Chunk folgen;
3. reicht der Agent eine Attestation unter Verwendung des gelieferten Whole-Index ein;
4. dürfen lokale Suche, altes Gedächtnis, ergänzende Quellenlektüre oder direktes Dateilesen nicht als vollständige Lieferung dargestellt werden;
5. schlägt eine ausstehende Wiederherstellung oder ein inkonsistenter Snapshot ohne Vermischung von Inhalten fehlgeschlossen fehl.

overview_delivery.chunk_tokens ist die einzige Einstellung für die Liefergröße. Der Standardwert ist 7000, mit einem gültigen Bereich von 4000 bis 24000. check_only=true ist ein kompakter Checkpoint ohne Chunk-Kette.

AOCI deklariert eine Ergebnisgrößen-Zulassung pro Tool auf aoci_overview. Ein Host, der andernfalls ein großes Tool-Ergebnis auf die Festplatte schreiben würde und nur eine Vorschau in den Kontext des Modells legt (bei der Indexlieferung ein stiller Fehler), erhöht diesen Schwellenwert allein für dieses Tool. Unter Claude Code macht dies die vollständige 24000 nutzbar und liefert einen Index mit 480 Objekten in drei Chunks statt in fünf. Es wird nichts geprüft: Die Deklaration ist statisch, und ein Host, der sie nicht erkennt, ignoriert sie, wie es die MCP-Spezifikation verlangt.

Der Aktualisierungsschwellenwert beträgt standardmäßig 30 verschiedene semantische Pfade und kann auch pro Projekt konfiguriert werden. Für exakte Zählregeln halten Sie sich an die Cognition-Refresh-Dokumentation und den Laufzeitvertrag.

Database Cognition

AOCI-CODE kann die Datenbankstruktur unter denselben Index und dieselbe Governance bringen, mit einer expliziten und engen Zugriffsgrenze:

Explicit database command
  → Read-only PostgreSQL/MySQL/openGauss system catalogs
  → Canonical schema evidence
  → Human acceptance of the evidence hash
  → The host model writes table-level FRAS from complete evidence
  → Entries are bound to the evidence and enter governed apply

• Es findet kein Datenbanknetzwerkzugriff statt, wenn keine Datenbank konfiguriert ist oder kein expliziter Datenbankbefehl ausgeführt wird.
• Es werden nur Schema-Metadaten für Basistabellen gelesen, keine Geschäftszeilen; Views, Routinen und Kommentare liegen außerhalb des aktuellen Erfassungsumfangs.
• Es wird kein DDL oder DML ausgeführt.
• Hostnamen, Benutzernamen, DSNs und Anmeldedatenwerte werden niemals in die Indexdateien geschrieben.
• Database Cognition apply läuft offline und verbindet sich beim Schreiben nicht erneut mit der Datenbank.
• Das Programm bewahrt und vergleicht strukturelle Evidenz, aber das Modell schreibt weiterhin Tabellenverantwortlichkeiten, Beziehungen und hochwertige Einschränkungen.

Die MySQL-Unterstützung umfasst 5.7.6 und später. Der Collector liest die Serverversion und führt nur die Katalogabfragen aus, die diese Version beantworten kann: CHECK-Einschränkungen ab 8.0.16, Indexausdrücke ab 8.0.13, Indexsichtbarkeit ab 8.0.0. Ein 5.7-Server zeichnet eine leere Check-Liste auf, da 5.7 die CHECK-Syntax parst und nichts speichert; die Evidenz hat auf jeder unterstützten Version dieselbe Form. MariaDB wird nicht unterstützt und wird abgelehnt, statt als MySQL gelesen zu werden.

Das anfängliche openGauss-Profil ist bewusst auf openGauss 6.0.5 LTS im A/PG-Kompatibilitätsmodus und gewöhnliche nicht partitionierte Basistabellen beschränkt. Nicht unterstützte Katalogfunktionen schlagen fehlgeschlossen fehl, statt stillschweigend auf PostgreSQL-Fakten reduziert zu werden; dies erhebt keinen Anspruch auf Unterstützung für MogDB, GaussDB, Dolphin/B/MySQL-Modus, Partitionen oder Subpartitionen, Column-Store, MOT, Fremd- oder temporäre Tabellen, Views, Routinen oder Trigger.

Hier gilt die fehlgeschlossene Erkennung für ausgewählte sichtbare tabellenartige Objekte mit nicht unterstützter Semantik. Routinen und Trigger bleiben außerhalb der v1-Tabellenobjekt-Domäne und werden niemals als Tabellenfakten dargestellt.

Der openGauss-Pfad verwendet AOCIs geprüften lokalen Patch über den offiziellen Connector-v1.0.8-Quellcode. Sein strikter Parser akzeptiert nur die geprüften Verbindungsparameter und konsumiert keine umgebende PG*-, Dienst-, Passwortdatei-, Home-Verzeichnis- oder Logger-Konfiguration. Eine TCP-Verbindung außerhalb einer numerischen Loopback-Adresse muss explizit sslmode=verify-full verwenden (und einen absoluten Pfad zu einem vertrauenswürdigen Root in sslrootcert, wenn angegeben), mit TLS 1.2 als Minimum; TLS-Downgrade-Modi werden abgelehnt. sslmode=disable wird nur für einen expliziten Unix-Socket oder eine numerische Loopback-Adresse akzeptiert, die als lokale/Test-Grenze verwendet wird. Datenbankadministratoren bleiben dafür verantwortlich, diese DSN außerhalb der Konversation bereitzustellen und das Konto mit den geringsten Rechten einzurichten.

Das Database Volume ist standardmäßig nicht vorhanden. Es gelangt erst in den Whole-Index, nachdem das Projekt Database Cognition explizit aktiviert und Evidenz-, Bindungs- und Lifecycle-Governance abgeschlossen hat.

Onboarding für Datenbankzugriff: Sie müssen keine DSN-Details verstehen

Sie deklarieren nur eine nicht sensible Identität für eine Datenbankquelle. Wenn --credential-env weggelassen wird, leitet AOCI eine stabile Umgebungsvariablenreferenz aus der Quell-ID ab; zum Beispiel wird primary zu AOCI_DB_PRIMARY_DSN:

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

Verwenden Sie dann die schreibgeschützte Zugriffs-Vorabprüfung, um zu sehen, ob die externe Umgebung diese Referenz bereitgestellt hat:

aoci --repo . database source access --source primary --json

Dieser Befehl verbindet sich nicht mit der Datenbank, gibt keinen Anmeldedatenwert zurück und fordert Sie nicht auf, eine DSN in eine Konversation einzufügen. Ein Datenbank- oder Infrastrukturadministrator stellt die Umgebungsvariable außerhalb des AOCI-Prozesses bereit und gewährt schreibgeschützten Zugriff mit den geringsten Rechten auf die Systemkataloge. Die Quellkonfiguration speichert nur den Referenznamen der Anmeldedaten, nicht das Geheimnis.

Die aktuelle Release-Kandidatin stellt nur den Umgebungs-Anmeldedaten-Provider bereit. Cloud-Secret-Manager wie Vault, Kubernetes Secret und AWS/GCP/Azure können in späteren Versionen über dieselbe Provider-Grenze integriert werden; sie sind heute nicht verfügbar, und diese README impliziert nichts anderes. Diese Aufteilung hält Kontenformate, DSN-Kodierung und die Verwaltung des Geheimnis-Lebenszyklus von gewöhnlichen Nutzern fern und hält die Autorisierung dennoch explizit: AOCI entdeckt keine Anmeldedaten automatisch, scannt nicht .env, liest keine Geheimnisdateien und umgeht keine Autorisierungsgrenze eines Datenbankadministrators.

System Cognition Foundation

Aufbauend auf den Code- und Datenbankindizes stellt AOCI-CODE eine Reihe von abgeleiteten System-Cognition-Beobachtungen bereit. Sie beantworten Fragen wie „Woher stammt dieses Objekt?“, „Welche Codeobjekte könnte eine Datenbankänderung betreffen?“ und „Was hat sich zwischen einer historischen Beobachtung und jetzt geändert?“ Sie erzeugen keine neue Ebene autoritativer Fakten.

# Where an index object came from, with its evidence and receipt bindings
aoci --repo . cognition system lineage

# Volume containment and dependencies plus resolved model-authored R relationships
aoci --repo . cognition system relations

# Find code impact from a database object along formal R relationships
aoci --repo . cognition system impact \
  --object database://primary/public/orders

# Save a historical observation on the caller side
aoci --repo . cognition system snapshot --json > previous.json

# Compare a caller-supplied historical observation with the current derived projection
aoci --repo . cognition system evolution \
  --snapshot-file previous.json

Autoritätsgrenze

Jedes System-Cognition-Ergebnis meldet derived=true; die Relations-Projektion meldet zusätzlich authoritative=false. Cognition Volumes, Schema-Evidenz-Bindungen, Baseline-Fingerabdrücke und receipt-gebundene Identitäten bleiben die zugrunde liegenden Autoritäten. Nicht aufgelöste R-Beziehungen erzeugen ein unvollständiges Ergebnis oder Diagnosen; das Programm rät nicht und füllt sie nicht aus.

AOCI-CODE ist kein Knowledge-Graph-System. Die schmale Relations-Projektion ist eine praktische Beziehungsansicht, besitzt aber kein zweites Zustandsverwaltungssystem, keinen unabhängigen Schreibpfad und keinen neuen Faktenspeicher. Abgeleitete Ausgaben können gelöscht und aus den aktuellen autoritativen Assets neu berechnet werden. Wenn eine Projektion mit autoritativen Assets in Konflikt steht, gewinnen die Assets.

Ausführungsmodi, Datenschutz und Datengrenzen

• AOCI-CODE ist standardmäßig local-first, ohne Standard-Cloud-Endpoint, ohne gehosteten Quellcode-Upload-Dienst und ohne erforderlichen Hintergrundserver.
• Die Datenverarbeitung im Agent-native-Modus hängt vom gewählten Host und dessen Produktrichtlinien ab; AOCI-CODE lädt keine Daten im Namen des Hosts hoch.
• Der Datenbanknetzwerkzugriff muss explizit ausgelöst werden und ist auf schreibgeschützte Schema-Metadaten beschränkt.
• Das Ledger, Entwürfe, Transaktionen und Wiederherstellungsevidenz werden standardmäßig unter .aoci/ gespeichert und normalerweise von Git ignoriert; die Indexdateien und Team-Governance-Assets können in Git eingecheckt werden.
• System-Cognition-Projektionen werden lokal aus vorhandenen autoritativen Assets berechnet und erfordern keine Graphdatenbank, Vektordatenbank oder einen entfernten Graphdienst.

Wie es sich von einer Repo-Map, RAG, LSP oder einem Code-Graph unterscheidet

Suche, ASTs, LSP, Code-Graphen und RAG sind gut bei strukturellen und Retrieval-Fragen. AOCI-CODE erledigt eine andere Aufgabe: Es pflegt eine versionierte Beschreibung des Systems, die den verwalteten Scope abdeckt und sich inkrementell mit der Software weiterentwickelt. Was Sie erhalten:

• Einen Whole-Index. Eine Systemkarte, die den aktuellen verwalteten Scope abdeckt, nicht Fragmente, die für jede Aufgabe ad hoc zusammengestellt werden.
• FRAS-Einträge. Verantwortlichkeiten, starke Beziehungen, öffentliche Verträge und hochwertige Einschränkungen für jedes Objekt mit der Rolle index.
• Persistenz über Sitzungen hinweg. Die Indexdateien liegen beim Repository, sodass spätere Sitzungen und andere Agenten dieselbe Version wiederverwenden.
• Managed Scope. Eine explizite Aufzeichnung darüber, welche Objekte in den Index eingehen, welche nur auf Änderungen beobachtet werden und welche bewusst ausgelassen werden.
• Drift-Erkennung. Unterscheidet Missing, Orphan, Stale, Unbaselined, Zeilenendeänderungen, Kurationsunterschiede und Quellen, die vom Verfassen ausgeschlossen sind (leer, binär, übergroß).
• Gesteuerte Aktualisierungen. Kandidaten gelangen über Quellbindung, Plan, Validierung, Review, CAS, atomare Schreibvorgänge, Baseline und Wiederherstellungsworkflows in die formalen Dateien.
• Delivery-Attestierung. Chunk, Cursor, Receipt und Challenge belegen, dass der Whole-Index vollständig ausgeliefert wurde.
• Database Cognition. Einträge auf Tabellenebene, die aus explizit akzeptierter PostgreSQL/MySQL/openGauss-Schema-Evidenz erstellt und gesteuert werden.
• Systemprojektionen. Lineage, schmale Relations, Datenbank-zu-Code-Impact, Snapshot und Evolution-Beobachtungen, abgeleitet aus dem autoritativen Index und seinen Bindungen, ohne autoritativen Zustand zu duplizieren; Impact durchläuft nur explizite, vom Modell verfasste R-Beziehungen.

AOCI-CODE ergänzt bestehende Werkzeuge, statt sie zu ersetzen.

Die empfohlene Kombination: AOCI-CODE liefert den globalen semantischen Prior; Code-Graphen, LSP, Suche und Quellcode liefern präzise Evidenz; Tests und Laufzeitergebnisse liefern die endgültige Abnahme. Die Relations-Projektion von AOCI ersetzt keinen präzisen Call Graph: Sie legt strukturelles Volume-Containment und Root-Abhängigkeitskanten offen, während ihre semantischen Kanten auf starke Beziehungen beschränkt sind, die das Modell explizit verfasst hat.

Technologie-Stack

AOCI-CODE erfordert kein Neo4j, keine Vektordatenbank, keinen dauerhaft laufenden Daemon und keinen AOCI-Clouddienst. Wenn Database Cognition aktiviert ist, ist die Zieldatenbank nur eine explizite, schreibgeschützte Quelle für Schema-Evidenz, nicht AOCIs eigener Zustandsspeicher.

FAQ

Warum zeigt Legacy status --deep weiterhin Drift?

status --deep, index score und index agent plan sind nur für Legacy. Führen Sie für ein Cognition-Volumes-Repository den Live-Guide aus und lassen Sie den Host gewöhnliches argumentloses aoci_maintain verwenden, reichen Sie den vollständigen aktuellen Batch über aoci_update_entry ein und schließen Sie mit Verify, Check und dem Guide ab. Ändern Sie die Baseline nicht direkt und überspringen Sie keine Schritte zur Quellbindung und Wiederherstellung.

Das Legacy-Layout selbst ist veraltet. Volumes v1 ist der unterstützte Pfad für neue und migrierte Repositories, und die Legacy-only-Befehle sind zur Entfernung in v0.2.0 vorgesehen; migrieren Sie ein Legacy-Repository vorher mit aoci cognition migration.

aoci --repo . index agent guide --agent codex --json

Warum hat der Host das falsche AOCI gestartet?

Prüfen Sie den Pfad der ausführbaren Datei in der MCP-Konfiguration auf Projektebene und stellen Sie sicher, dass es ein stabiler absoluter Pfad ist, und führen Sie dann aus:

/absolute/path/to/aoci --version
/absolute/path/to/aoci --repo . doctor

Um den geladenen stdio-Server zu überprüfen und nicht nur die Datei auf der Festplatte, inspizieren Sie außerdem die tatsächliche ausführbare Datei des Host-Prozesses, seine Befehlszeile --repo und die Prozessidentität nach einem Neustart.

Muss ich selbst ein Datenbankkonto erstellen und einen DSN bereitstellen?

Sie müssen die DSN-Syntax nicht verstehen und sollten keine Geheimnisse im Chat senden. Nachdem Sie eine nicht sensible Quellidentität deklariert haben, stellt AOCI eine stabile Umgebungsvariablen-Referenz bereit. Ein Datenbankadministrator muss dennoch ein externes Konto mit minimalen Rechten und schreibgeschütztem Zugriff auf den Systemkatalog erstellen und diese Referenz der Laufzeitumgebung bereitstellen. Die aktuelle Version erstellt kein Datenbankkonto im Namen einer Organisation und liest keinen Geheimnisspeicher automatisch.

Kann es in CI laufen?

Ja. Scannen, Verifizierung, Governance-Gates und deterministische Prüfungen laufen, ohne neue Einträge zu schreiben. Für exakte Befehle, Audit-Schreibvorgänge und Exit-Codes halten Sie sich an --help der aktuellen Binärdatei, die JSON-Schemas und die CI-Dokumentation des Projekts.

Beweist ein rundum grünes AOCI-Ergebnis, dass die Semantik korrekt ist?

Nein. Ein grünes Ergebnis beweist, dass die kodierten strukturellen und Governance-Bedingungen erfüllt sind. Was das Modell geschrieben hat, muss weiterhin gegen Quellcode, Schema, Tests, Laufzeitergebnisse und menschliche Prüfung abgeglichen werden.

Ist der System-Cognition-Graph eine neue Quelle der Wahrheit?

Nein. Die aktuelle Fähigkeit ist eine schmale Relations-Projektion, keine unabhängige Graphplattform. Sie berechnet Ergebnisse nur aus dem formalen Index, der Evidenz, den Receipts und der Baseline und persistiert keine neuen autoritativen Fakten. Das Programm erzeugt auch keine semantischen Beziehungen automatisch aus Importen, SQL, Dateinamen oder Ähnlichkeit.

Dokumentation

Dokumentations- und öffentliche Vertragslinks sind an v0.1.0-rc22 gebunden, damit sie gültig bleiben, wenn diese README aus einem binären Release-Archiv gelesen wird, das die Verzeichnisse docs/ oder spec/public/ des Repositorys nicht enthält.

Black-Box-Verifikationssuiten

Das Repository enthält vier eigenständige Black-Box-Suiten unter scripts/blackbox/, die ein gebautes aoci-Binary strikt von außerhalb des Prozesses testen, ausschließlich über das öffentliche stdio-MCP-Protokoll und die CLI:

• Protokollkonformität — 53 schreibgeschützte Prüfungen der MCP-Wire-Oberfläche, wobei die lokalisierungsabhängigen Sätze unter zh-CN wiederholt werden;
• Fehlerinjektionsszenarien — 75 Szenarien zu Cursor-Manipulation, Absturzwiederherstellung, konkurrierenden Schreibern und dem Pre-Write-Hook auf Wegwerf-Fixture-Repositorys;
• Lebenszyklus über eingefrorene reale Projekte — drei eingecheckte Fixture-Projekte: repo-a (TypeScript) und repo-b (Python + MySQL) durchlaufen den vollständigen Lebenszyklus von init bis zur Neuausrichtung, und repo-c (ein geschichteter Dienst mit 453 Dateien) treibt zusätzlich das Authoring in mehreren Batches am Batch-Limit der Maschine voran. Eine optionale Modellspur führt einen echten KI-Agenten — jedes Modell, das Ihre OpenCode- Installation bereitstellt — durch die beiden kleinen Repositorys und bewertet den End- zustand anhand öffentlicher Oberflächen.
• Upgrade-Achse — 80 Prüfungen pro veröffentlichter Version über zehn Repository- Formen: Jede veröffentlichte Version baut und erstellt ein Repository mit ihrem eigenen Binary, dann muss das zu testende Binary dieses verwalten, ohne eine Identität zu verschieben, eine Scope-Änderung zu verlangen oder ein formales Asset umzuschreiben, und was es dann erstellt, muss einen Checkout an einem anderen Pfad ausgerichtet halten; in der zehnten Form kehren sich die Rollen um, und jede veröffentlichte Version muss ein Repository lesen, das das zu testende Binary geschrieben hat, ohne abzustürzen oder es umzuschreiben. Die anderen drei Suiten erzeugen jedes Fixture mit dem zu testenden Binary, sodass ein zwischen Versionen geändertes Preimage für sie konstruktionsbedingt unsichtbar ist.

Sie benötigen nur Python 3 und git zusätzlich zu einem gebauten Binary (Docker für die MySQL- Suite; OpenCode plus Ihr eigenes Modellabonnement für die Modellspur), sodass ein Repository-Klon seinen eigenen Build, einen Plattform-Port oder einen Fork verifizieren kann — und AOCI_BIN kann die Konformitäts- und Szenario-Suiten auf jedes alternative Binary richten, das die öffentlichen Verträge in spec/public/ beansprucht. Diese Suiten befinden sich im Repository-Klon; binäre Release-Archive enthalten sie nicht. Siehe scripts/blackbox/README.md für Befehle und Ergebnisinterpretation.

Forschung, geistiges Eigentum und Lizenz

AOCI-CODE-Forschungspapiere und -Artefakte dürfen veröffentlichte Methoden, experimentelle Protokolle und Ergebnisse öffentlich beschreiben. Patentanmeldungen, erteilter Schutzbereich, Rechtsstatus, Inhaber und territoriale Wirkung sind rechtliche Tatsachen und sollten nicht auf Grundlage einer internen README, einer historischen Versionsnummer oder einer unbestätigten Nacherzählung in Produktbeschreibungen aufgenommen werden.

Wenn künftig eine bestimmte Patentnummer, ein Erteilungsdatum oder ein Schutzbereich offengelegt werden muss, sollten der Rechteinhaber und die Rechtsberatung dies anhand offizieller öffentlicher Register verifizieren und in einem dedizierten IP-, NOTICE- oder Rechtsdokument ablegen. Diese README sollte nur auf diese maßgebliche Datei verlinken; sie sollte weder selbst den Patentschutz erweitern noch den Patentstatus als Softwarelizenz darstellen.

Community

Scannen Sie den Code mit WeChat oder WeCom (企业微信), um der AOCI-Projektgruppe beizutreten und mit den Maintainern und anderen Nutzern zu sprechen. Reichen Sie Fehlerberichte und Funktionswünsche als GitHub-Issues ein, damit sie durchsuchbar bleiben, und melden Sie vermutete Schwachstellen privat, wie in SECURITY.md beschrieben, niemals in der Gruppe.

Bei AOCI-CODE geht es nicht darum, einem Agenten mehr Code sehen zu lassen. Es gibt dem Agenten vor jeder Aktion ein aktuelles, strukturiertes, nachvollziehbares und verwaltetes Verständnis des Systems. Git versioniert Ihren Code, Datenbankmigrationen versionieren Ihre Datenstrukturen, und AOCI-CODE versioniert, was Agenten über das System wissen, zusammen mit der Nachvollziehbarkeit, der Governance-Konsistenz und den Wiederherstellungsgrenzen der Entwicklung dieses Wissens.