AOCI-CODE

AOCI-CODE

Une carte persistante, versionnée par Git, de l'ensemble de votre base de code — rédigée par votre agent de codage, gouvernée par un serveur MCP local. Les agents la lisent une fois et connaissent le système, au lieu de relire le dépôt à chaque tâche.

🇺🇸 English | 🇨🇳 简体中文

Ce qu'il fait

Construisez de grands systèmes sans perdre le fil. Dans Codex, Claude Code, Cursor, OpenCode et agents similaires, votre agent commence chaque tâche en connaissant déjà l'ensemble du système : à quoi sert chaque fichier, de quoi il dépend et ce qui ne doit pas casser. Il cesse de chercher et de relire la base de code à chaque requête. Les personnes qui ne sont pas développeurs professionnels peuvent continuer à faire évoluer leurs propres systèmes ; les développeurs professionnels peuvent confier tout le système à un agent et garder leur attention sur l'architecture et la conception.

Reprenez un système existant en une seule étape. Pointez l'agent vers une base de code existante pouvant atteindre environ 500 000 lignes et demandez-lui de construire l'index. Il indique à quel point il connaît chaque zone, puis reprend le développement à partir de là. La limite pratique est la taille de l'index, pas le nombre de lignes : un système commercial de 700 000 lignes est développé ainsi aujourd'hui, avec un index d'environ 300K tokens.

Changez de personne, d'agent ou de conversation sans repartir de zéro. L'index vit dans le dépôt, à côté du code, et est versionné par Git. Lorsqu'un projet change de mains, change d'agent ou ouvre une nouvelle conversation, une seule lecture de l'index permet de reprendre là où les choses s'étaient arrêtées.

Après le premier index, la maintenance est automatique. Le serveur MCP détecte les changements de code et émet les entrées à mettre à jour. L'agent les complète à la fin de chaque tâche, de sorte que l'index corresponde au code actuel et que vous n'ayez jamais à vous arrêter pour le maintenir.

À quoi cela ressemble

Une ligne par fichier, rédigée par le modèle à partir du code source réel. Voici une entrée réelle issue de l'index de ce dépôt :

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 est ce dont le fichier est responsable, R est ce que vous devez lire en même temps, A est ce sur quoi les appelants s'appuient, et S est ce que vous ne pouvez pas déduire du code mais qu'il ne faut pas se tromper. Le tag [CG9L] situe le fichier par couche, domaine, importance et taille. Quelques centaines de lignes comme celle-ci couvrent tout un système, et un agent peut les lire en une seule passe. Le format des entrées explique chaque champ.

En quoi est-ce différent de CodeGraph ?

• CodeGraph analyse votre code en un graphe de symboles et d'appels. Lorsque l'agent pose une question, il renvoie le code source exact et les chemins d'appel. C'est un outil de recherche précis pour la tâche en cours.
• AOCI-CODE fait rédiger par le modèle une ligne par fichier et par table : à quoi cela sert, à quoi cela se connecte et ce qui ne doit pas casser. L'agent lit d'abord l'index entier, il connaît donc le système avant même que la tâche ne commence. L'index vit dans Git et reste synchronisé avec le code.
• Utilisez les deux : l'index pour connaître le système, CodeGraph pour récupérer le code exact pendant le travail.

La comparaison complète couvre aussi le RAG, le LSP et les cartes de dépôt.

À quoi s'attendre

Le premier index prend du temps. L'agent lit chaque fichier géré et rédige une entrée par fichier : environ une heure pour 200 000 lignes de code, selon le modèle et la vitesse de l'agent. Il fonctionne par lots et reprend là où il s'est arrêté en cas d'interruption.

Vous avez une base de données ? Indexez-la aussi. MySQL et PostgreSQL sont pris en charge, ainsi qu'openGauss 6.0.5 avec contraintes. MySQL signifie 5.7.6 et versions ultérieures ; MariaDB n'est pas pris en charge. Construisez d'abord l'index du code, puis celui de la base de données. Avec les connaissances du code et des tables livrées ensemble, l'agent comprend le système plus complètement.

Local uniquement : lecture seule sur votre système, pas d'Internet, aucun identifiant stocké. AOCI-CODE lit votre code source et les structures de tables de la base de données, jamais les données métier. Il écrit ses fichiers d'index et son propre état dans le répertoire du projet, ainsi que l'enregistrement de la page de statut dans le répertoire de cache de votre utilisateur. Il n'accède jamais à Internet et ne téléverse rien : les seules connexions qu'il ouvre sont vers la base de données que vous déclarez, pour les métadonnées de catalogue, et vers sa propre page de statut en boucle locale. Les identifiants de base de données sont référencés par nom de variable d'environnement et jamais stockés. Le texte de l'index est écrit localement par votre propre agent via le canal de modèle que vous utilisez déjà ; AOCI-CODE n'ajoute aucune nouvelle sortie de données.

Démarrage rapide

Donnez à votre agent l'instruction suivante pour télécharger AOCI-CODE et le configurer. Après avoir redémarré l'agent, envoyez la seconde instruction pour construire l'index.

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.

Après avoir redémarré l'agent, envoyez celle-ci :

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.

L'agent démarre le panneau en arrière-plan avec aoci ui --detach --json et vous transmet le lien. Panneau AOCI décrit ce qu'il affiche et ses autres commandes.

Pourquoi le redémarrage : l'index est écrit via les outils MCP d'AOCI, et la session qui a exécuté init n'a pas chargé le serveur MCP que init vient d'écrire. Un hôte qui charge les serveurs MCP dynamiquement peut ne pas avoir besoin d'un redémarrage ; Intégration à l'hôte explique comment le savoir.

Si votre projet possède une base de données (PostgreSQL et MySQL sont pris en charge, ainsi qu'openGauss 6.0.5 avec contraintes), indexez-la également. Déclarez la source comme décrit dans Cognition de base de données, fournissez la variable d'environnement de chaîne de connexion dans l'environnement de l'hôte (AOCI ne stocke aucun identifiant), puis envoyez :

Build the AOCI database index for this project.

Si le contexte a été compacté, ou si vous voulez que l'agent reconstruise sa vision du système, envoyez ceci :

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.

Comment ça marche

AOCI (AI-Oriented Cognition Infrastructure) est la méthode et le protocole : une couche entre les agents de codage et les systèmes logiciels. Les modèles raisonnent, les agents planifient et exécutent, et AOCI maintient une description à jour du système, couvrant le code, la configuration, les tests et la structure de la base de données, que les agents lisent avant d'agir. AOCI-CODE est ce projet : la CLI aoci, le serveur MCP et l'index qu'ils maintiennent.

AOCI-CODE distille ce qui compte réellement pour comprendre et modifier un système en un index dense en texte brut qui combine symboles et sens. Lorsque le contexte du modèle est limité, un agent lit d'abord l'index, obtient l'essentiel des informations clés du projet en une seule passe, puis commence la tâche. Cela réduit la recherche et le réapprentissage répétés, et transporte la compréhension d'une tâche et d'une session à l'autre.

• Pas un résumé ponctuel. L'index évolue avec le système et reste dans le projet, où vous pouvez le comparer, le réviser, le versionner et le restaurer avec Git.
• Plus qu'un simple « où sont les fichiers ». Il consigne les responsabilités, les relations fortes, les contrats publics, les frontières transactionnelles, les contraintes de compatibilité et d'autres éléments difficiles à déduire de la structure du code.
• Portable. L'index est stocké avec le projet, sans être lié à un modèle, un agent ou une session. Tant qu'il est aligné avec le code, n'importe quel agent et n'importe quelle session ultérieure peuvent le réutiliser sans reconstruire leur compréhension de zéro.
• Code et bases de données ensemble. Le modèle peut construire un index séparé au niveau des tables pour les tables de base de données. Livrés ensemble, les deux donnent à l'agent une image plus complète du système.

L'index est un ensemble de fichiers en texte brut gouvernés, stockés avec le projet :

• Racine (aoci.txt) déclare ce qui compose l'index actuel et constitue son point d'entrée d'activation.
• Méta (aoci.meta.txt) contient le dictionnaire de tags, les règles FRAS et les contraintes de rédaction.
• Code (aoci.code.txt) contient les entrées rédigées par le modèle pour le code et les autres actifs du dépôt.
• Base de données (aoci.database.txt) contient les entrées facultatives au niveau des tables lorsque la Cognition de base de données est activée.

La Racine, la Méta et les Volumes d'objets participants forment ensemble le Whole-Index. Le flux de travail qui les surplombe comporte trois étapes :

1. Construire l'index sous gouvernance. Le modèle lit le code source et les preuves acceptées. AOCI-CODE gouverne le périmètre géré (Managed Scope) et les entrées que le modèle rédige pour chaque objet géré avec le rôle index.
2. Lire avant d'agir. L'agent lit les règles du projet, le guide actif et le Whole-Index actuel, puis vérifie le code source et les autres preuves pour la tâche en cours.
3. Maintenir après un changement vérifié. Une fois le code et les tests stables, les règles du projet et le flux de travail MCP amènent l'agent à mettre à jour les entrées concernées et à ramener l'index à l'état aligned.

Comme ces fichiers sont en texte brut dans le dépôt, Git les versionne. Tant que l'index reste aligné avec la version actuelle du système, n'importe quel agent et n'importe quelle session ultérieure peuvent lire et réutiliser le même Whole-Index.

Intégration manuelle

Obtenez AOCI-CODE depuis la source canonique ou utilisez un paquet signé depuis GitHub Releases. Avant d'utiliser un binaire précompilé, suivez le niveau de vérification basique, recommandé ou complet du guide d'installation, et indiquez quel niveau a été complété. Donnez ce README et le chemin absolu stable du binaire vérifié à un agent de codage en qui vous avez confiance, tel que Codex, Claude Code, Cursor ou OpenCode. L'agent peut suivre les instructions du projet pour initialiser AOCI, intégrer MCP et construire le premier index.

La durée du premier index dépend de la taille du dépôt. Une intégration normale se fait en quatre étapes : préparer le binaire, faire initialiser le dépôt cible par l'agent ou par vous-même, demander à l'hôte de « construire l'index », et vérifier l'alignement. Ensuite, vous n'avez plus besoin de terminer chaque requête par « maintenir l'index ». Les règles du projet et le flux de travail MCP amènent l'agent à maintenir l'index de façon incrémentielle chaque fois que des objets gérés changent.

Prérequis

• Un paquet de version vérifié ou une copie du dépôt source canonique d'AOCI-CODE.
• Pour les compilations depuis les sources uniquement : la chaîne d'outils Go déclarée par go.mod, make et les autres outils requis par le dépôt.
• Un hôte MCP pris en charge, tel que Codex, Claude Code, Cursor ou OpenCode.
• Un accès normal en lecture et en écriture au dépôt cible.

AOCI-CODE s'intègre à l'hôte MCP, et non à une API de fournisseur de modèle. DeepSeek et d'autres modèles peuvent utiliser AOCI-CODE lorsque l'agent ou l'hôte qui les exécute prend en charge le MCP stdio standard et peut suivre le contrat d'outils ; un nom de modèle seul ne suffit pas à établir la compatibilité.

La voie du paquet signé et les commandes de vérification de l'exécutable se trouvent dans le guide d'installation. La voie de compilation depuis les sources est ci-dessous.

RC actuelle : utilisez un paquet vérifié ou compilez depuis les sources

[!IMPORTANT] AOCI-CODE v0.1.0-rc22 est la version candidate actuelle. C'est un logiciel Fair Source/source-available sous FSL-1.1-MIT ; voir LICENSE. Compilez depuis la source canonique ou utilisez un paquet signé depuis la version GitHub v0.1.0-rc22 après avoir suivi la procédure de vérification de version.

Le binaire signé de la version s'identifie comme aoci version 0.1.0-rc22. Une compilation depuis les sources identifie à la place la copie exacte et peut indiquer une version de développement telle que v0.1.0-rc22-1-g<short-commit> (plus -dirty le cas échéant), accompagnée de son commit Git. Ce sont des entrées de compilation différentes, et non un conflit de version.

Pour télécharger avec GitHub CLI, authentifiez-vous d'abord, puis téléchargez les actifs de la version étiquetée :

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

Pour un téléchargement anonyme, ouvrez la page de la version v0.1.0-rc22 dans un navigateur et téléchargez l'archive et les actifs de vérification dont vous avez besoin.

Pour compiler depuis les sources, clonez le dépôt canonique, compilez le binaire et conservez le chemin obtenu de façon stable :

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

Sous Windows, compilez la même source dans 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

Ensuite, donnez ce README à un agent à qui vous confiez déjà le projet et demandez :

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.

L'agent doit identifier la racine du projet, utiliser un chemin absolu stable vers le binaire compilé, exécuter l'initialisation adaptée à l'hôte actuel et vous indiquer clairement quand un redémarrage de l'hôte ou une véritable approbation humaine est nécessaire. Le binaire peut rester dans le checkout AOCI-CODE ou être déplacé vers un répertoire d'outils partagé, tant que la configuration MCP pointe vers le bon chemin absolu.

Initialisation manuelle

Pour initialiser AOCI vous-même, exécutez la commande suivante depuis la racine du dépôt cible, ou passez un chemin explicite via --repo :

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

init écrit la configuration de locale, le bloc de règles AGENTS.md géré, les frontières Git et un squelette d'index vide. La configuration et les invites varient selon l'hôte ; voir Intégration de l'hôte. Il n'invente pas de signification métier à partir des noms de fichiers, des répertoires ou d'un AST.

Pour un nouveau dépôt, le premier scan établit la Baseline gérée. Pour un projet qui possède déjà une Baseline gouvernée, l'ajout, la suppression ou la modification du périmètre géré passe par le workflow formel de changement de périmètre ; scan --force n'est pas un raccourci pour redéfinir les faits de gouvernance. --force ne peut pas non plus effacer une dérive non résolue, des reçus ou des frontières de récupération.

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

Faire construire le premier index par l'agent (important)

Une fois l'initialisation et scan terminés, vérifiez si la session de l'agent expose déjà les outils AOCI ; actualisez ou redémarrez-la sinon. Ensuite, saisissez ce qui suit dans l'agent pour le projet cible :

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.

L'agent démarre le panneau en arrière-plan avec aoci ui --detach --json et vous transmet le lien. Panneau AOCI décrit ce qu'il affiche et ses autres commandes.

L'hôte lit les règles AOCI du projet et le guide en direct, inspecte le code source, les tests, la configuration et les preuves pertinentes, puis écrit des candidats FRAS pour chaque objet géré dont le rôle est index. Vous n'avez pas besoin d'orchestrer vous-même Plan, Stage, Check, Diff, CAS ou Apply.

Une fois le premier index terminé, envoyez les demandes de développement ordinaires comme d'habitude, par exemple :

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

Vous n'avez pas besoin d'ajouter « maintenez l'index AOCI à la fin ». Les règles du projet et le MCP font vérifier par l'agent les changements d'index une fois le code et les tests stabilisés, puis mettent à jour les entrées via le workflow formel. Lorsque le projet utilise automation.mode=auto, AOCI-CODE ne vous interrompt que lorsqu'une véritable approbation humaine est requise, qu'une action externe doit être effectuée, que la récupération ne peut pas être prouvée, qu'un contrôle de sécurité échoue ou qu'un conflit de concurrence tiers est détecté. Les autres modes d'automatisation suivent leurs propres contrats d'exécution.

Vérifier l'alignement

Une fois l'intégration terminée, exécutez :

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

L'index et la source gérée actuelle devraient converger vers aligned. Si ce n'est pas le cas, consultez d'abord le guide en direct ; ne dupliquez pas la machine à états interne dans un script wrapper :

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

Exécuter les diagnostics de base

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

Pour confirmer à quel AOCI l'hôte est réellement connecté, lisez ce que le serveur rapporte sur lui-même plutôt que ce qui se trouve sur le disque. Dans toute réponse aoci_overview check_only ou toute réponse aoci_maintain, cognition_receipt.mcp_service_version est la version en cours d'exécution et runtime_repository_root est le dépôt qu'il gouverne. Le chemin du binaire correspondant est le command dans le .mcp.json du projet ou la configuration d'hôte équivalente : .codex/config.toml, opencode.json ou .cursor/mcp.json. Remplacer les octets sur le disque ne modifie pas un processus MCP en cours d'exécution, donc revérifiez ces faits après une mise à niveau ou un retour arrière.

Pour une démonstration ponctuelle, utilisez examples/minimal-repository dans le dépôt.

make fast

make full
./build/aoci --version

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

Ce qui apparaît après l'initialisation

Un dépôt typique contient ces fichiers d'index :

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

L'initialisation d'un nouveau projet crée le Root, le Meta et un Code Volume vide ; la Database est absente par défaut. AOCI-CODE ne génère pas de signification métier pour le dépôt ou la base de données de lui-même.

aoci init --agent <name> écrit en outre la configuration d'intégration de l'hôte (.mcp.json, .claude/settings.json, .codex/config.toml ou opencode.json) dont les chemins de commande et de dépôt sont des chemins absolus liés à la machine. Ajoutez ces fichiers au .gitignore du dépôt et ne les commitez pas : une copie commitée casse sur toute autre machine, et comme les installateurs détectent une entrée existante par la présence de la clé, relancer init là-bas conserve silencieusement les chemins cassés.

Comment se déroule une tâche de développement

Les deux diagrammes ci-dessous montrent le workflow tel que vous le vivez, et non l'implémentation interne d'AOCI.

Nouveau projet : construire d'abord un système simple, puis intégrer AOCI

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

Un nouveau système n'a pas besoin d'AOCI-CODE dès la première ligne de code. Construisez d'abord un prototype avec les capacités existantes de l'agent ; environ 10 000 à 30 000 lignes est un bon moment pour l'intégrer (pas un seuil strict). Les équipes qui souhaitent une continuité entre sessions plus tôt peuvent l'intégrer plus tôt.

Projet existant : indexer le dépôt, puis itérer

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

Une fois le premier index terminé, les deux flux fonctionnent de la même manière au quotidien : vous décrivez l'exigence métier ou d'ingénierie ; l'agent combine le Whole-Index avec les preuves actuelles, effectue le développement et la vérification, et met à jour les objets modifiés via MCP au fur et à mesure qu'il clôt la tâche. Vous n'avez pas besoin d'apprendre les commandes internes Plan, Stage, Diff, CAS ou Baseline, ni de répéter l'exigence de maintenance dans chaque invite.

Si un lot complet est rejeté avant le début de toute écriture formelle, l'index reste inchangé. Si le workflow est interrompu après le début des écritures formelles, le système conserve l'intention immuable, les preuves d'écriture et l'état de récupération, puis reprend à partir d'une postimage prouvable ou revient à la préimage exacte. Un conflit d'octets tiers échoue en mode fermé ; AOCI-CODE n'écrase jamais une modification externe pour « terminer l'écriture ».

L'état final est toujours l'un de applied, repair_required ou stopped. stopped n'est pas un succès, et cela ne signifie pas nécessairement que rien n'a été écrit ; inspectez failed_step, les preuves d'écriture formelle et l'action de récupération renvoyée par le guide.

Qui fait quoi : le modèle et AOCI-CODE

Le modèle détient la signification

Le modèle hôte lit le code source, les tests, la configuration, la documentation et toute preuve nécessaire, puis décide :

• de ce dont un objet est réellement responsable ;
• quels fichiers, modules ou objets de base de données sont des relations fortes qui doivent être prises en compte pour le modifier en toute sécurité ;
• quelles API, commandes, formats ou contrats observables il expose ;
• quelles contraintes de transaction, d'autorisation, de concurrence, de mise en cache, de déploiement, de compatibilité ou historiques ne peuvent pas être déduites de la structure ordinaire seule.

AOCI-CODE n'assemble pas FRAS à partir de noms de fichiers, de chemins, d'extensions, d'AST ou de modèles, et il ne réécrit pas silencieusement ce que le modèle a écrit.

AOCI-CODE détient la gouvernance

AOCI-CODE est responsable de :

1. établir l'inventaire sûr, le périmètre géré et la Baseline actuelle ;
2. fournir le Whole-Index actuel et confirmer son identité ;
3. générer un plan déterministe, un ensemble cible et des valeurs SHA-256 de source ;
4. valider la structure candidate, le dictionnaire de tags, les identités de relations, le périmètre, la propriété, les budgets et la plage affectée ;
5. préserver le lien entre le contenu de vérification, de diff et de revue ;
6. valider un lot complet avec des verrous inter-processus, CAS et des écritures atomiques ;
7. faire avancer la Baseline, ajouter au registre et préserver les preuves de récupération après un échec post-écriture ;
8. prouver à nouveau l'état de gouvernance actuel via Verify, Check et le guide ;
9. dériver les observations de Lineage, Relations, Impact, Snapshot et Evolution à partir des actifs faisant autorité sans créer une seconde source de vérité.

Des résultats machine entièrement verts signifient uniquement que les contrats structurels et de gouvernance encodés sont respectés ; ils ne signifient pas que chaque affirmation écrite par le modèle est correcte.

Comment l'index est organisé

Un index AOCI comporte deux couches : les règles d'index et les entrées d'index. Le produit prend en charge deux dispositions physiques, et ce ne sont pas un seul format de fichier.

Disposition Volumes v1

Un projet Volumes sépare les responsabilités :

• aoci.txt est uniquement le Root. Il déclare les Volumes qui participent au CognitionSet actuel.
• aoci.meta.txt contient le Meta : le dictionnaire de tags, les règles FRAS, les budgets et le contrat d'écriture.
• aoci.code.txt contient les entrées pour les objets de code.
• aoci.database.txt contient les entrées pour les objets de base de données lorsque la Cognition de base de données est activée.

Les Volumes Code et Database partagent la même structure de lignes FRAS, mais ils ont des identités d'objets, des liaisons de preuves, une propriété et des cycles de vie indépendants. Le Root, le Meta et les Volumes d'objets forment ensemble le Whole-Index ; lire uniquement le Root aoci.txt ne suffit pas pour prétendre avoir lu l'ensemble du système.

Considérez-le comme une carte :

• Les règles d'index sont la légende et le système de coordonnées de la carte.
• Les entrées d'index sont les marqueurs qui décrivent chaque emplacement.
• Le Root est le catalogue et le point d'entrée de version pour l'ensemble de cartes actuel.
• Un Volume est une feuille séparée régie par le même protocole mais avec sa propre source de preuves et son propre cycle de vie.

À quoi ressemble l'en-tête d'index

Le Root et le Meta s'ouvrent chacun par des lignes d'en-tête lues par la machine. Voici ce que aoci init écrit pour un nouveau projet en-US nommé my-service, en commençant par le Root, qui est le point d'entrée d'activation :

#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

Chaque ligne #Volume: déclare un Volume participant avec son identité, son type, son chemin, son format, sa dépendance et son état d'activation. Un Volume non déclaré ici ne fait pas partie du CognitionSet actuel, quel que soit le reste du contenu de l'arbre de travail. L'activation de la Cognition de base de données ajoute une ligne supplémentaire, #Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled.

Le Meta s'ouvre ensuite avec les règles qui régissent chaque entrée :

#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 est la ligne porteuse : les limites de champs appartiennent au binaire, pas à ce texte, donc un projet ne peut pas les élargir en modifiant son propre Meta. #S-Admission et #S quota régissent spécifiquement le champ S : ce qui peut y être enregistré, et combien de caractères chaque bande d'importance peut dépenser. Le dictionnaire de tags suit immédiatement après ces lignes ; il est présenté en intégralité plus bas.

Le Code Volume s'ouvre par une seule ligne, #AOCI-CODE-VOLUME: 1, et tout ce qui suit est constitué de sections de répertoires et d'entrées.

Ce sont les valeurs de départ d'un nouveau projet, et non des constantes de protocole fixes. Le Root et le Meta propres à chaque dépôt font autorité ensuite : un projet plus ancien peut porter un dictionnaire de tags personnalisé, et un projet initialisé avec --locale zh-CN écrit #Locale: zh-CN et localise la clé #S quota: en conséquence.

Ce que définissent les règles d'index

Dans les Volumes v1, le Meta Volume du projet stocke ces règles ; dans la disposition Legacy, elles résident dans l'en-tête monolithique. Les projets peuvent utiliser différents dictionnaires de tags, tandis que la structure FRAS de base reste la même.

Ce README explique seulement comment lire ces règles. Pour les règles concrètes et exécutables, référez-vous au Meta ou à l'en-tête Legacy du projet courant, au guide AOCI et à la spécification formelle.

Ce que consigne une entrée (FRAS)

Une fois les règles en place, le modèle écrit une entrée pour chaque objet géré ayant le rôle index. Le rôle observe ne participe qu'à l'observation des changements, et le rôle exclude marque ce qui est délibérément laissé de côté ; ni l'un ni l'autre ne possède d'entrée formelle. AOCI utilise FRAS pour organiser les quatre types d'informations les plus importants dans une entrée :

• F — Function : ce dont l'objet est responsable.
• R — Relations : quels autres objets vous devez également prendre en compte pour le comprendre ou le modifier en toute sécurité.
• A — API : quelles interfaces, commandes, formats ou contrats observables il expose.
• S — Non-obvious constraints : les informations importantes que F, R et A ne couvrent pas mais dont vous avez besoin pour comprendre ou modifier l'objet en toute sécurité, telles que les contraintes clés, les exceptions, les frontières et les sémantiques spéciales. S ne doit pas répéter les trois premiers champs.

Par exemple, dans la section du répertoire ===.../internal/fs/===, une entrée utilise le nom de base :

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 

La section du répertoire et le nom de base se résolvent en une identité d'objet de code. Pour les projections inter-Volumes ou système, elle s'étend en une identité canonique telle que code:internal/fs/atomic.go. Un objet de base de données utilise sa propre identité canonique, telle que database://primary/public/orders.

L'entrée comporte deux parties :

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

Les tags compacts donnent à chaque objet des coordonnées pour la couche architecturale, le domaine fonctionnel, l'importance, les caractéristiques techniques optionnelles et la taille. Le dictionnaire de tags est défini par le Meta Volume ou l'en-tête Legacy du projet. Le programme valide le dictionnaire et la structure ; il ne décide pas du sens métier.

S n'est pas une synthèse, un résumé ordinaire ni une répétition de F, R et A. Il ajoute des informations importantes que les trois premiers champs ne couvrent pas et qui affectent la compréhension ou la justesse d'ingénierie, par exemple :

• un échec d'accès à Redis doit se rabattre sur la base de données ;
• une table particulière ne doit pas entrer dans AutoMigrate ;
• une branche de compatibilité héritée ne doit pas être supprimée par un nettoyage ordinaire ;
• le fichier original doit être préservé après un échec d'écriture.

Le modèle écrit cela à partir du code source réel et des preuves. AOCI-CODE valide la structure de l'entrée, la lie au fichier source et régit la manière dont elle entre dans l'index formel.

Lire le dictionnaire de tags de démarrage

L'extrait suivant est copié mot pour mot du modèle Meta Volume en-US courant (textassets/en-US/templates/volume-meta.txt.tmpl). C'est un dictionnaire de démarrage, pas un vocabulaire universel : le Meta formel de chaque dépôt reste la référence. Le dictionnaire de démarrage ne déclare aucun dictionnaire D ; D reste un axe optionnel et ne peut être utilisé que lorsque le Meta formel courant le déclare.

#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

Selon le dictionnaire de code de démarrage, [CG9L] signifie C SharedFoundation, G CrossDomain, 9 importance la plus élevée et L grande échelle ; aucune valeur D n'est présente. Cela explique comment lire l'entrée existante, pas comment le modèle doit attribuer les tags. Le modèle choisit toujours les tags à partir du Meta du projet courant, en se fondant sur le code source et les preuves acceptées.

Volumes de cognition

AOCI-CODE maintient un Whole-Index logique unique, tandis que chaque type d'index possède son propre fichier, sa propriété et son cycle de vie.

Chaque objet a exactement un propriétaire valide. Placer un objet dans le mauvais Volume crée un conflit de propriété. AOCI-CODE ne le répare que lorsque la machine peut prouver le propriétaire incorrect, le propriétaire correct et les faits actuels de l'objet ; il ne devine pas la propriété à partir de noms similaires.

Le Code Volume, le Database Volume et le périmètre peuvent évoluer ensemble, mais ils partagent une seule frontière de commit gouvernée. L'application d'un domaine ne doit pas écarter la projection Baseline existante d'un autre domaine. Une application de Volume, la mise à jour de la Baseline et les projections de périmètre associées sont publiées comme un seul résultat de transaction cohérent ou entrent dans une récupération prouvable. Elles ne laissent jamais un état à moitié complet où « le fichier a réussi mais un autre Volume n'a pas de baseline ».

Intégration hôte

aoci init écrit toujours les règles d'agent gérées, mais l'intégration hôte diffère :

• Codex reçoit une configuration MCP au niveau du projet et, avec --hooks, un prompt de compaction de contexte plus SessionStart(compact). Il n'installe toujours aucun hook d'édition de fichier.
• Claude Code peut installer un hook PreToolUse.
• OpenCode V1 reçoit un opencode.json strict au niveau du projet.
• Cursor renvoie seulement un extrait de configuration de référence ; rien n'est écrit dans le projet.

Après la configuration, vérifiez si la session hôte actuelle expose déjà les outils AOCI. Rafraîchissez ou rouvrez cette session de projet uniquement si elle n'a pas chargé le nouveau serveur. Une nouvelle session lit normalement les règles et le Whole-Index une fois. Tant que l'identité de l'index reste valide et qu'aucune compaction hôte connue ne s'est produite, les tâches ultérieures réutilisent ce que le modèle possède déjà ; l'index complet n'est pas réinjecté mécaniquement.

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 limite un transfert de compaction à l'identité du reçu, à l'état d'écriture ou de récupération inachevé et à une instruction de rechargement immédiat ; il ne doit ni conserver ni résumer les corps du Whole-Index ou d'Overview/Attestation. Un hook PreCompact ne peut pas injecter dans l'entrée de compaction de l'hôte ni supprimer l'historique de celle-ci, il ne peut donc pas l'appliquer seul. Révisez et faites confiance au hook de projet installé via Codex /hooks avant de vous y fier.

La sortie Legacy conserve les Niveaux 0–4 pour la compatibilité avec les hôtes et rapports existants. Le cognition-state/v2 courant exprime à quel point la représentation du système par le modèle est utilisable sous forme de Niveaux 0–3, et sépare les faits de preuve stricte et de gouvernance en dimensions indépendantes :

Ces dimensions ne se substituent pas les unes aux autres. L'attestation ne prouve que la couverture de livraison et la cohérence d'identité du matériel courant ; elle ne signifie pas que l'agent a pleinement compris toute tâche future possible. Seul current_system_cognition_reliable=true permet une affirmation sans réserve d'une compréhension complète du système actuel.

Panneau AOCI

aoci ui sert un panneau en lecture seule sur cette machine, afin que vous puissiez voir l'état de l'index sans interroger un agent :

• l'en-tête de l'index et les Volumes Code / Database mot pour mot (les lignes de section === conservées telles quelles, filtrables, copiables en bloc) ; l'onglet « All » est l'index complet exactement tel qu'un agent le reçoit via Overview
• les tokens de l'index par rapport au budget, et le plan de chunks d'Overview
• quelle quantité de code l'index couvre : fichiers, lignes, tokens et taux de compression ; combien de tables de base de données
• l'état de gouvernance et la dérive, le Managed Scope, les intégrations hôtes et les processus aoci mcp en cours
• les commandes et prompts à donner ensuite à l'agent, avec des boutons de copie

La page bascule entre le chinois et l'anglais ; l'intervalle de rafraîchissement est sélectionnable (30 s par défaut).

Plusieurs serveurs aoci mcp dans un même WSL ? Sous Linux et WSL, le panneau découvre chaque processus aoci mcp de l'utilisateur courant et son dépôt, bascule entre eux via des onglets en haut, et signale un serveur dont le binaire a été remplacé sur le disque. Limites : il ne se lie qu'aux adresses de bouclage (toute autre liaison est refusée), ne répond qu'aux requêtes GET et HEAD, ne prend aucun verrou, n'ajoute rien au registre et ne modifie aucun octet du dépôt. C'est un processus distinct, sans rapport avec aoci mcp ; le serveur MCP n'ouvre toujours aucune socket. L'enregistrement d'un panneau en arrière-plan réside dans le répertoire de cache de l'utilisateur, jamais dans le dépôt.

Commandes CLI courantes

Combinaisons courantes :

# 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

Les commandes Plan, Stage, Check, Diff, Apply, Curation, Scope Change, Bootstrap, Migration et de récupération existent toujours. Suivez le guide renvoyé par le binaire en cours d'exécution ; ne recopiez pas la machine à états interne dans des scripts.

À propos des commandes « en lecture seule »

Pour verify, check, index score et index inventory, « en lecture seule » signifie que l'index formel et la Baseline ne sont pas modifiés ; cela ne signifie pas zéro écriture sur le système de fichiers au sens strict. Lorsque le Ledger est activé, les quatre commandes peuvent ajouter des entrées au Ledger local, et verify tente également d'écrire dans Verify History. Un échec d'écriture d'audit ne modifie ni les codes de sortie existants ni les critères de gouvernance.

Si une opération strictement sans écriture de fichier est requise, utilisez une copie isolée ; la CLI publique actuelle n'expose aucun commutateur global qui désactive toutes les écritures du Ledger et de Verify History. Les commandes System Cognition ne créent pas un second état formel, mais les appels CLI ordinaires suivent toujours le contrat d'exécution de la version courante pour le Ledger et les enregistrements d'historique locaux.

Serveur MCP

aoci mcp ne nécessite aucun démon résident et expose exactement neuf outils via stdio :

En mode MCP, stdout est réservé à JSON-RPC ; les journaux et diagnostics vont vers stderr. Les descriptions d'outils, les schémas JSON et les valeurs d'état machine fournis par le binaire en cours d'exécution font foi ; ce README n'est qu'un point de départ.

La version actuelle fournit les capacités System Cognition via la CLI existante et le noyau de gouvernance. Elles n'ajoutent pas de dixième outil MCP et ne modifient ni les noms, ni les objets, ni le contrat stdio des neuf outils existants.

Sessions de longue durée et livraison Whole-Index

Au début d'une nouvelle conversation, un agent charge normalement un Overview complet pour obtenir une image du système correspondant au dépôt, à la version d'index et à l'identité de service AOCI courants. Tant que le modèle peut s'appuyer sur cette image, il n'a pas besoin de la recharger avant chaque tâche ou appel d'outil.

Au sein d'une même conversation, le modèle décide de recharger ou non selon son propre état, sauf après une compaction connue du contexte hôte. Un transfert compacté peut ne conserver que l'identité du reçu, l'état d'écriture ou de récupération inachevé et une instruction de rechargement immédiat ; il ne doit ni conserver ni résumer les corps d'en-tête, d'entrée, de découpage, de challenge ou d'attestation du Whole-Index ou de l'Overview. Un contenu d'index ou un reçu recopié dans ce transfert ne peut pas prouver que l'image actuelle du modèle est fiable.

Avant de poursuivre le travail métier après une compaction connue, l'agent recharge les règles si elles ne sont plus présentes de manière fiable, déclare context_compaction avec un nouvel ID d'événement, et effectue une séquence ordinaire complète de curseur, confirmation et attestation d'Overview. check_only et la sonde de cognition ne s'y substituent pas. Après un transport complet frais, la règle existante sur les attestations partielles ou échouées permet toujours une continuation liée à la source sans second Overview automatique. Pour un changement sémantique ou une frontière de phase majeure sans compaction connue, AOCI fournit des seuils de rafraîchissement, des points de contrôle et des faits d'identité, et le modèle décide s'il doit restaurer son image au niveau système pour la tâche.

Le corps de chaque Overview complet se compose d'un marqueur de début, du contenu exact de l'index formel courant et d'un marqueur de fin.

Lorsqu'un Overview dépasse le budget de découpage du projet :

1. la livraison commence immédiatement par le chunk 1 ;
2. l'agent doit suivre automatiquement next_cursor jusqu'au chunk final ;
3. l'agent soumet une attestation en utilisant le Whole-Index livré ;
4. la recherche locale, l'ancienne mémoire, la lecture de sources complémentaires ou la lecture directe de fichiers ne doivent pas être présentées comme une livraison complète ;
5. une récupération en attente ou un instantané incohérent échoue en mode fermé sans mélanger de contenu.

overview_delivery.chunk_tokens est le seul réglage de taille de livraison. Sa valeur par défaut est 7000, avec une plage valide de 4000 à 24000. check_only=true est un point de contrôle compact sans chaîne de découpage.

AOCI déclare une allocation de taille de résultat par outil sur aoci_overview. Un hôte qui persisterait sinon un grand résultat d'outil sur disque, ne plaçant qu'un aperçu dans le contexte du modèle (pour la livraison d'index, un échec silencieux), relève ce seuil pour cet outil uniquement. Sur Claude Code, cela rend le 24000 complet utilisable, livrant un index de 480 objets en trois chunks au lieu de cinq. Rien n'est sondé : la déclaration est statique, et un hôte qui ne la reconnaît pas l'ignore, comme l'exige la spécification MCP.

Le seuil de rafraîchissement est par défaut de 30 chemins sémantiques distincts et peut aussi être configuré par projet. Pour les règles de comptage exactes, référez-vous à la documentation Cognition Refresh et au contrat d'exécution.

Database Cognition

AOCI-CODE peut placer la structure de base de données sous le même index et la même gouvernance, avec une frontière d'accès explicite et étroite :

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

• Aucun accès réseau à la base de données n'a lieu lorsqu'aucune base n'est configurée ou qu'aucune commande de base de données explicite n'est exécutée.
• Seules les métadonnées de schéma des tables de base sont lues, pas les lignes métier ; les vues, routines et commentaires sont hors du périmètre de collecte actuel.
• Aucun DDL ni DML n'est exécuté.
• Les noms d'hôte, noms d'utilisateur, DSN et valeurs d'identifiants ne sont jamais écrits dans les fichiers d'index.
• L'application de Database Cognition s'exécute hors ligne et ne se reconnecte pas à la base de données pendant l'écriture.
• Le programme conserve et compare les preuves structurelles, mais le modèle rédige toujours les responsabilités des tables, les relations et les contraintes à forte valeur.

La prise en charge de MySQL couvre 5.7.6 et versions ultérieures. Le collecteur lit la version du serveur et n'exécute que les requêtes de catalogue auxquelles cette version peut répondre : contraintes CHECK à partir de 8.0.16, expressions d'index à partir de 8.0.13, visibilité des index à partir de 8.0.0. Un serveur 5.7 enregistre une liste de vérifications vide, car 5.7 analyse la syntaxe CHECK et ne stocke rien ; la preuve a la même forme sur toutes les versions prises en charge. MariaDB n'est pas pris en charge et est refusé plutôt que lu comme MySQL.

Le profil openGauss initial est délibérément limité à openGauss 6.0.5 LTS en mode de compatibilité A/PG et aux tables de base ordinaires non partitionnées. Les fonctionnalités de catalogue non prises en charge échouent en mode fermé au lieu d'être silencieusement réduites à des faits PostgreSQL ; cela ne revendique pas la prise en charge de MogDB, GaussDB, du mode Dolphin/B/MySQL, des partitions ou sous-partitions, du stockage en colonnes, de MOT, des tables étrangères ou temporaires, des vues, routines ou déclencheurs.

Ici, la détection en mode fermé s'applique aux objets de type table visibles sélectionnés dont la sémantique n'est pas prise en charge. Les routines et déclencheurs restent hors du domaine des objets de table v1 et ne sont jamais représentés comme des faits de table.

Le chemin openGauss utilise le correctif local revu d'AOCI appliqué au code source officiel de Connector v1.0.8. Son analyseur strict n'accepte que les paramètres de connexion revus et ne consomme pas la configuration ambiante PG*, de service, de fichier de mot de passe, de répertoire personnel ou de journalisation. Une connexion TCP hors d'une adresse de bouclage numérique doit utiliser explicitement sslmode=verify-full (et un chemin absolu de racine de confiance dans sslrootcert lorsqu'il est fourni), avec TLS 1.2 comme minimum ; les modes de rétrogradation TLS sont rejetés. sslmode=disable n'est accepté que pour une socket Unix explicite ou une adresse de bouclage numérique utilisée comme frontière locale/de test. Les administrateurs de base de données restent responsables de fournir ce DSN hors de la conversation et de provisionner le compte à privilège minimal.

Le Volume Database est absent par défaut. Il n'entre dans le Whole-Index qu'après que le projet a explicitement activé Database Cognition et achevé la gouvernance des preuves, de la liaison et du cycle de vie.

Intégration de l'accès à la base de données : nul besoin de comprendre les détails du DSN

Vous déclarez seulement une identité non sensible pour une source de base de données. Si --credential-env est omis, AOCI dérive une référence stable de variable d'environnement à partir de l'ID de source ; par exemple, primary correspond à AOCI_DB_PRIMARY_DSN :

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

Utilisez ensuite le précontrôle d'accès en lecture seule pour voir si l'environnement externe a fourni cette référence :

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

Cette commande ne se connecte pas à la base de données, ne renvoie pas de valeur d'identifiant et ne vous demande pas de coller un DSN dans une conversation. Un administrateur de base de données ou d'infrastructure fournit la variable d'environnement en dehors du processus AOCI et accorde un accès en lecture seule à privilège minimal aux catalogues système. La configuration de la source ne stocke que le nom de référence de l'identifiant, pas le secret.

La version candidate actuelle ne fournit que le fournisseur d'identifiants par environnement. Les gestionnaires de secrets cloud tels que Vault, Kubernetes Secret et AWS/GCP/Azure pourront être intégrés via la même frontière de fournisseur dans des versions ultérieures ; ils ne sont pas disponibles aujourd'hui, et ce README ne prétend pas le contraire. Cette séparation maintient les formats de compte, l'encodage DSN et la gestion du cycle de vie des secrets à l'écart des utilisateurs ordinaires tout en gardant l'autorisation explicite : AOCI ne découvre pas les identifiants automatiquement, ne scanne pas .env, ne lit pas les fichiers de secrets et ne contourne pas la frontière d'autorisation d'un administrateur de base de données.

Fondation de cognition système

Au-dessus des index de code et de base de données, AOCI-CODE fournit un ensemble d'observations de cognition système dérivées. Elles répondent à des questions telles que « d'où vient cet objet ? », « quels objets de code une modification de base de données pourrait-elle affecter ? » et « qu'est-ce qui a changé entre une observation historique et maintenant ? ». Elles ne créent pas une nouvelle couche de faits faisant autorité.

# 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

Frontière d'autorité

Chaque résultat de cognition système rapporte derived=true ; la projection de relations rapporte en outre authoritative=false. Les Volumes de cognition, les liaisons de preuves de schéma, les empreintes de Baseline et les identités liées aux reçus restent les autorités sous-jacentes. Les relations R non résolues produisent un résultat incomplet ou des diagnostics ; le programme ne devine pas et ne les complète pas.

AOCI-CODE n'est pas un système de graphe de connaissances. La projection étroite de relations est une vue pratique des relations, mais elle ne possède pas de second système de gestion d'état, ni de chemin d'écriture indépendant, ni de nouveau magasin de faits. La sortie dérivée peut être supprimée et recalculée à partir des actifs faisant autorité actuels. Si une projection entre en conflit avec les actifs faisant autorité, les actifs l'emportent.

Modes d'exécution, confidentialité et frontières des données

• AOCI-CODE est local-first par défaut, sans point de terminaison cloud par défaut, sans service hébergé de téléversement de sources et sans serveur d'arrière-plan requis.
• Le traitement des données en mode Agent-native dépend de l'hôte que vous choisissez et de ses politiques produit ; AOCI-CODE ne téléverse pas de données au nom de l'hôte.
• L'accès réseau à la base de données doit être déclenché explicitement et est limité aux métadonnées de schéma en lecture seule.
• Le registre, les brouillons, les transactions et les preuves de récupération sont stockés sous .aoci/ par défaut et sont normalement ignorés par Git ; les fichiers d'index et les actifs de gouvernance d'équipe peuvent être commités dans Git.
• Les projections de cognition système sont calculées localement à partir des actifs faisant autorité existants et ne nécessitent ni base de données de graphe, ni base de données vectorielle, ni service de graphe distant.

En quoi cela diffère d'une carte de dépôt, du RAG, du LSP ou d'un graphe de code

La recherche, les AST, le LSP, les graphes de code et le RAG excellent dans les questions structurelles et de récupération. AOCI-CODE fait un travail différent : il maintient une description versionnée du système qui couvre la portée gérée et évolue de manière incrémentale avec le logiciel. Ce que vous obtenez :

• Un Whole-Index. Une carte système couvrant la portée gérée actuelle, et non des fragments assemblés à la volée pour chaque tâche.
• Des entrées FRAS. Responsabilités, relations fortes, contrats publics et contraintes à forte valeur pour chaque objet ayant le rôle index.
• Persistance entre les sessions. Les fichiers d'index vivent avec le dépôt, de sorte que les sessions ultérieures et d'autres agents réutilisent la même version.
• Portée gérée. Un enregistrement explicite des objets qui entrent dans l'index, de ceux qui sont seulement observés pour détecter les changements et de ceux qui sont délibérément exclus.
• Détection de dérive. Distingue les états Missing, Orphan, Stale, Unbaselined, les changements de fin de ligne, les différences de curation et les sources exclues de la rédaction (vides, binaires, surdimensionnées).
• Mises à jour gouvernées. Les candidats entrent dans les fichiers formels via la liaison de source, le plan, la validation, la revue, le CAS, les écritures atomiques, la Baseline et les workflows de récupération.
• Attestation de livraison. Chunk, cursor, receipt et challenge prouvent que le Whole-Index a été livré intégralement.
• Cognition de base de données. Entrées au niveau des tables construites et gouvernées à partir de preuves de schéma PostgreSQL/MySQL/openGauss explicitement acceptées.
• Projections système. Observations de lignage, de relations étroites, d'impact base de données-vers-code, de Snapshot et d'Évolution dérivées de l'index faisant autorité et de ses liaisons sans dupliquer l'état faisant autorité ; l'Impact ne parcourt que les relations R explicites rédigées par le modèle.

AOCI-CODE complète les outils existants plutôt que de les remplacer.

La combinaison recommandée : AOCI-CODE fournit le prior sémantique global ; les graphes de code, le LSP, la recherche et le code source fournissent des preuves précises ; les tests et les résultats d'exécution fournissent l'acceptation finale. La projection Relations d'AOCI ne remplace pas un graphe d'appels précis : elle expose le confinement structurel des Volumes et les arêtes de dépendance des Roots, tandis que ses arêtes sémantiques se limitent aux relations fortes que le modèle a explicitement rédigées.

Pile technologique

AOCI-CODE ne nécessite ni Neo4j, ni base de données vectorielle, ni démon de longue durée, ni service cloud AOCI. Lorsque la cognition de base de données est activée, la base de données cible n'est qu'une source explicite et en lecture seule de preuves de schéma, et non le propre magasin d'état d'AOCI.

FAQ

Pourquoi le Legacy status --deep montre-t-il encore une dérive ?

status --deep, index score et index agent plan sont réservés au Legacy. Pour un dépôt de Volumes de cognition, exécutez le guide en direct et laissez l'hôte utiliser l'habituel aoci_maintain sans argument, soumettre le lot actuel complet via aoci_update_entry, et terminer par Verify, Check et le guide. Ne modifiez pas la Baseline directement et ne sautez pas les étapes de liaison de source et de récupération.

La mise en page Legacy elle-même est dépréciée. Volumes v1 est le chemin pris en charge pour les dépôts nouveaux et migrés, et les commandes réservées au Legacy sont prévues pour être supprimées dans la v0.2.0 ; migrez un dépôt Legacy avec aoci cognition migration avant cette échéance.

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

Pourquoi l'hôte a-t-il démarré le mauvais AOCI ?

Inspectez le chemin de l'exécutable dans la configuration MCP au niveau du projet et assurez-vous qu'il s'agit d'un chemin absolu stable, puis exécutez :

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

Pour vérifier le serveur stdio chargé plutôt que seulement le fichier sur disque, inspectez également l'exécutable réel du processus hôte, sa ligne de commande --repo et l'identité du processus après un redémarrage.

Dois-je créer un compte de base de données et fournir un DSN moi-même ?

Vous n'avez pas besoin de comprendre la syntaxe DSN, et vous ne devez pas envoyer de secrets dans le chat. Après avoir déclaré une identité de source non sensible, AOCI fournit une référence de variable d'environnement stable. Un administrateur de base de données doit néanmoins créer un compte externe à privilège minimal avec accès en lecture seule au catalogue système et fournir cette référence à l'environnement d'exécution. La version actuelle ne crée pas de compte de base de données au nom d'une organisation et ne lit pas automatiquement un magasin de secrets.

Peut-il s'exécuter en CI ?

Oui. Le scan, la vérification, les portes de gouvernance et les contrôles déterministes s'exécutent sans écrire de nouvelles entrées. Pour les commandes exactes, les écritures d'audit et les codes de sortie, référez-vous au --help du binaire actuel, aux schémas JSON et à la documentation CI du projet.

Un résultat AOCI entièrement vert prouve-t-il que la sémantique est correcte ?

Non. Un résultat vert prouve que les conditions structurelles et de gouvernance encodées sont satisfaites. Ce que le modèle a écrit doit encore être vérifié par rapport au code source, au schéma, aux tests, aux résultats d'exécution et à la revue humaine.

Le graphe de cognition système est-il une nouvelle source de vérité ?

Non. La capacité actuelle est une projection étroite de relations, et non une plateforme de graphe indépendante. Elle calcule des résultats uniquement à partir de l'index formel, des preuves, des reçus et de la Baseline, et ne persiste pas de nouveaux faits faisant autorité. Le programme ne génère pas non plus automatiquement de relations sémantiques à partir d'imports, de SQL, de noms de fichiers ou de similarité.

Documentation

Les liens vers la documentation et les contrats publics sont épinglés sur v0.1.0-rc22 afin de rester valides lorsque ce README est lu depuis une archive Release binaire, qui n'inclut pas les répertoires docs/ ou spec/public/ du dépôt.

Suites de vérification en boîte noire

Le dépôt fournit quatre suites autonomes en boîte noire sous scripts/blackbox/ qui exercent un binaire aoci compilé strictement depuis l'extérieur du processus, uniquement via le protocole MCP stdio public et la CLI :

• Conformité au protocole — 53 vérifications en lecture seule de la surface du protocole MCP, avec les phrases dépendantes de la locale répétées sous zh-CN ;
• Scénarios d'injection de fautes — 75 scénarios couvrant la falsification de curseur, la reprise après plantage, les écrivains concurrents et le hook de pré-écriture sur des dépôts de test jetables ;
• Cycle de vie sur des projets réels figés — trois projets de test versionnés : repo-a (TypeScript) et repo-b (Python + MySQL) exécutent le cycle de vie complet de init au réalignement, et repo-c (un service en couches de 453 fichiers) pilote en outre la rédaction multi-lots à la limite de lots de la machine. Une piste de modèle optionnelle fait passer un véritable agent IA — tout modèle exposé par votre installation OpenCode — par les deux petits dépôts et évalue l'état final à partir des surfaces publiques.
• Axe de mise à niveau — 80 vérifications par version publiée, sur dix formes de dépôt : chaque version publiée compile et rédige un dépôt avec son propre binaire, puis le binaire testé doit le gouverner sans déplacer une identité, sans exiger de changement de périmètre ni réécrire un actif formel, et ce qu'il rédige ensuite doit maintenir un checkout à un autre chemin aligné ; dans la dixième forme, les rôles s'inversent, et chaque version publiée doit lire un dépôt écrit par le binaire testé sans planter ni le réécrire. Les trois autres suites génèrent chaque fixture avec le binaire testé, de sorte qu'une préimage modifiée entre versions leur est invisible par construction.

Elles ne nécessitent que Python 3 et git en plus d'un binaire compilé (Docker pour la suite MySQL ; OpenCode plus votre propre abonnement de modèle pour la piste de modèle), de sorte qu'un clone du dépôt peut vérifier sa propre compilation, un portage de plateforme ou un fork — et AOCI_BIN peut pointer les suites de conformité et de scénarios vers tout binaire alternatif qui revendique les contrats publics dans spec/public/. Ces suites résident dans le clone du dépôt ; les archives Release binaires ne les incluent pas. Voir scripts/blackbox/README.md pour les commandes et l'interprétation des résultats.

Recherche, propriété intellectuelle et licence

Les articles et artefacts de recherche AOCI-CODE peuvent décrire publiquement des méthodes publiées, des protocoles expérimentaux et des résultats. Les demandes de brevet, la portée accordée, le statut juridique, les titulaires et l'effet territorial sont des faits juridiques, et ils ne doivent pas être ajoutés aux descriptions de produit sur la foi d'un README interne, d'un numéro de version historique ou d'un récit non vérifié.

Si un numéro de brevet, une date de délivrance ou une portée spécifique doit être divulgué à l'avenir, le titulaire des droits et le conseil juridique doivent le vérifier auprès des registres publics officiels et le consigner dans un document dédié de PI, NOTICE ou juridique. Ce README ne doit que renvoyer vers ce fichier faisant autorité ; il ne doit ni étendre lui-même la couverture des brevets ni présenter le statut des brevets comme une licence logicielle.

Communauté

Scannez le code avec WeChat ou WeCom (企业微信) pour rejoindre le groupe du projet AOCI et échanger avec les mainteneurs et les autres utilisateurs. Signalez les bugs et demandez des fonctionnalités via les issues GitHub afin qu'ils restent consultables, et signalez les vulnérabilités suspectées en privé comme le décrit SECURITY.md, jamais dans le groupe.

AOCI-CODE ne vise pas à faire voir plus de code à un agent. Il donne à l'agent une compréhension actuelle, structurée, traçable et gouvernée du système avant chaque action. Git versionne votre code, les migrations de base de données versionnent vos structures de données, et AOCI-CODE versionne ce que les agents savent du système, ainsi que la traçabilité, la cohérence de gouvernance et les limites de récupération de l'évolution de ces connaissances.