AOCI-CODE

AOCI-CODE

Um mapa persistente e versionado no Git de todo o seu código-fonte — escrito pelo seu agente de programação, governado por um servidor MCP local. Os agentes o leem uma vez e conhecem o sistema, em vez de reler o repositório a cada tarefa.

🇺🇸 English | 🇨🇳 简体中文

O que ele faz

Construa grandes sistemas sem perder o fio da meada. No Codex, Claude Code, Cursor, OpenCode e agentes semelhantes, seu agente começa cada tarefa já conhecendo o sistema inteiro: para que serve cada arquivo, do que ele depende e o que não pode quebrar. Ele para de procurar e reler o código-fonte a cada solicitação. Pessoas que não são desenvolvedoras profissionais podem continuar iterando em seus próprios sistemas; desenvolvedores profissionais podem entregar o sistema inteiro a um agente e manter a atenção na arquitetura e no design.

Assuma um sistema existente em um único passo. Aponte o agente para um código-fonte existente de até cerca de 500.000 linhas e peça que ele construa o índice. Ele informa o quão bem conhece cada área e, a partir daí, retoma o desenvolvimento. O limite prático é o tamanho do índice, não a contagem de linhas: um sistema comercial de 700.000 linhas é desenvolvido assim hoje, com um índice de cerca de 300K tokens.

Troque de pessoas, agentes ou conversas sem começar de novo. O índice fica no repositório, ao lado do código, e é versionado pelo Git. Quando um projeto muda de mãos, troca de agente ou abre uma nova conversa, uma leitura do índice retoma de onde parou.

Após o primeiro índice, a manutenção é automática. O servidor MCP detecta mudanças no código e emite as entradas que precisam de atualização. O agente as preenche ao concluir cada tarefa, de modo que o índice corresponde ao código atual e você nunca precisa parar para mantê-lo.

Como ele se parece

Uma linha por arquivo, escrita pelo modelo a partir do código-fonte real. Esta é uma entrada real do índice deste próprio repositório:

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 é pelo que o arquivo é responsável, R é o que você precisa ler junto com ele, A é do que os chamadores dependem e S é o que você não consegue inferir do código mas não pode errar. A tag [CG9L] posiciona o arquivo por camada, domínio, importância e tamanho. Algumas centenas de linhas como esta cobrem um sistema inteiro, e um agente pode lê-las em uma única passada. O formato da entrada explica cada campo.

Como isso é diferente do CodeGraph?

• CodeGraph analisa seu código em um grafo de símbolos e chamadas. Quando o agente faz uma pergunta, ele retorna o código-fonte e os caminhos de chamada exatos. É uma ferramenta de consulta precisa para a tarefa em questão.
• AOCI-CODE faz o modelo escrever uma linha por arquivo e tabela: para que serve, ao que se conecta e o que não pode quebrar. O agente lê o índice inteiro primeiro, de modo que conhece o sistema antes de a tarefa começar. O índice fica no Git e é mantido em sincronia com o código.
• Use ambos: o índice para conhecer o sistema, o CodeGraph para buscar o código exato durante o trabalho.

A comparação completa também aborda RAG, LSP e mapas de repositório.

O que esperar

O primeiro índice leva um tempo. O agente lê cada arquivo gerenciado e escreve uma entrada por arquivo: cerca de uma hora por 200.000 linhas de código, dependendo do modelo e da velocidade do agente. Ele roda em lotes e retoma de onde parou se for interrompido.

Tem um banco de dados? Indexe-o também. MySQL e PostgreSQL são suportados, e openGauss 6.0.5 com restrições. MySQL significa 5.7.6 e posteriores; MariaDB não é suportado. Construa primeiro o índice de código, depois o índice de banco de dados. Com o conhecimento de código e de tabelas entregue em conjunto, o agente entende o sistema de forma mais completa.

Apenas local: somente leitura no seu sistema, sem Internet, sem credenciais armazenadas. O AOCI-CODE lê seu código-fonte e as estruturas das tabelas do banco de dados, nunca dados de negócio. Ele grava seus arquivos de índice e seu próprio estado dentro do diretório do projeto, além do registro da página de status no diretório de cache do seu usuário. Ele nunca acessa a Internet e não envia nada: as únicas conexões que abre são para o banco de dados que você declara, para metadados de catálogo, e para sua própria página de status em loopback. As credenciais do banco de dados são referenciadas pelo nome da variável de ambiente e nunca armazenadas. O texto do índice é escrito localmente pelo seu próprio agente através do canal de modelo que você já usa; o AOCI-CODE não adiciona nenhuma nova saída de dados.

Início rápido

Dê ao seu agente a instrução a seguir para baixar o AOCI-CODE e configurá-lo. Depois de reiniciar o agente, envie a segunda instrução para construir o índice.

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.

Depois de reiniciar o agente, envie esta:

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.

O agente inicia o painel em segundo plano com aoci ui --detach --json e entrega o link a você. Painel AOCI cobre o que ele mostra e seus outros comandos.

Por que reiniciar: o índice é escrito através das ferramentas MCP do AOCI, e a sessão que executou init não carregou o servidor MCP que init acabou de gravar. Um host que carrega servidores MCP dinamicamente pode não precisar de reinício; Integração com o host explica como saber.

Se o seu projeto tem um banco de dados (PostgreSQL e MySQL são suportados, além do openGauss 6.0.5 com restrições), indexe-o também. Declare a fonte conforme descrito em Cognição de Banco de Dados, forneça a variável de ambiente da string de conexão no ambiente do host (o AOCI não armazena credenciais) e então envie:

Build the AOCI database index for this project.

Se o contexto foi compactado, ou se você quer que o agente reconstrua sua visão do sistema, envie isto:

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.

Como funciona

AOCI (AI-Oriented Cognition Infrastructure) é o método e o protocolo: uma camada entre agentes de programação e sistemas de software. Os modelos raciocinam, os agentes planejam e executam, e o AOCI mantém uma descrição atualizada do sistema, cobrindo código, configuração, testes e estrutura de banco de dados, para os agentes lerem antes de agir. AOCI-CODE é este projeto: a CLI aoci, o servidor MCP e o índice que eles mantêm.

O AOCI-CODE destila o que realmente importa para entender e alterar um sistema em um índice denso, em texto simples, que combina símbolos e significado. Quando o contexto do modelo é limitado, um agente lê o índice primeiro, obtém a maior parte das informações-chave do projeto em uma única passada e então começa a tarefa. Isso reduz a busca e o reaprendizado repetidos, e carrega o entendimento entre tarefas e sessões.

• Não é um resumo único. O índice evolui com o sistema e permanece no projeto, onde você pode fazer diff, revisar, versionar e reverter com o Git.
• Mais do que "onde ficam os arquivos". Ele registra responsabilidades, relacionamentos fortes, contratos públicos, limites de transação, restrições de compatibilidade e outras coisas difíceis de inferir da estrutura do código.
• Portátil. O índice é armazenado com o projeto, não vinculado a um modelo, a um agente ou a uma sessão. Enquanto estiver alinhado com o código, qualquer agente e qualquer sessão posterior podem reutilizá-lo sem reconstruir o entendimento do zero.
• Código e bancos de dados juntos. O modelo pode construir um índice separado, em nível de tabela, para as tabelas do banco de dados. Entregues juntos, os dois dão ao agente uma visão mais completa do sistema.

O índice é um conjunto de arquivos de texto simples governados, armazenados com o projeto:

• Root (aoci.txt) declara o que compõe o índice atual e é seu ponto de entrada de ativação.
• Meta (aoci.meta.txt) contém o dicionário de tags, as regras FRAS e as restrições de autoria.
• Code (aoci.code.txt) contém as entradas de código e outros ativos do repositório escritas pelo modelo.
• Database (aoci.database.txt) contém entradas opcionais em nível de tabela quando a Cognição de Banco de Dados está habilitada.

Root, Meta e os Volumes de objetos participantes juntos formam o Whole-Index. O fluxo de trabalho sobre eles tem três estágios:

1. Construir o índice sob governança. O modelo lê o código-fonte e as evidências aceitas. O AOCI-CODE governa o Escopo Gerenciado e as entradas que o modelo escreve para cada objeto gerenciado com o papel index.
2. Ler antes de agir. O agente lê as regras do projeto, o guia ativo e o Whole-Index atual, e então verifica o código-fonte e outras evidências para a tarefa em questão.
3. Manter após mudança verificada. Uma vez que o código e os testes estejam estáveis, as regras do projeto e o fluxo de trabalho MCP fazem o agente atualizar as entradas afetadas e trazer o índice de volta a aligned.

Como esses arquivos são texto simples no repositório, o Git os versiona. Enquanto o índice permanecer alinhado com a versão atual do sistema, qualquer agente e qualquer sessão posterior podem ler e reutilizar o mesmo Whole-Index.

Integração manual

Obtenha o AOCI-CODE da fonte canônica ou use um pacote assinado do GitHub Releases. Antes de usar um binário pré-compilado, siga o nível de verificação básico, recomendado ou completo no guia de instalação, e informe qual nível foi concluído. Dê este README e o caminho absoluto estável do binário verificado a um agente de programação em que você confia, como Codex, Claude Code, Cursor ou OpenCode. O agente pode seguir as instruções no projeto para inicializar o AOCI, integrar o MCP e construir o primeiro índice.

Quanto tempo o primeiro índice leva depende do tamanho do repositório. Uma integração normal tem quatro passos: preparar o binário, fazer o agente ou você mesmo inicializar o repositório de destino, pedir ao host para "construir o índice" e verificar o alinhamento. Depois disso, você não precisa terminar cada solicitação com "manter o índice". As regras do projeto e o fluxo de trabalho MCP fazem o agente manter o índice de forma incremental sempre que objetos gerenciados mudarem.

Requisitos

• Um pacote de release verificado ou um checkout do repositório de código-fonte canônico do AOCI-CODE.
• Apenas para builds a partir do código-fonte: a toolchain Go declarada por go.mod, make e as demais ferramentas exigidas pelo repositório.
• Um host MCP suportado, como Codex, Claude Code, Cursor ou OpenCode.
• Acesso normal de leitura e escrita ao repositório de destino.

O AOCI-CODE se integra ao host MCP, não a uma API de provedor de modelo. DeepSeek e outros modelos podem usar o AOCI-CODE quando o agente ou host que os executa suporta MCP stdio padrão e consegue seguir o contrato de ferramentas; um nome de modelo sozinho não estabelece compatibilidade.

A rota do pacote assinado e os comandos de verificação do executável estão no guia de instalação. A rota de build a partir do código-fonte está abaixo.

RC atual: use um pacote verificado ou compile a partir do código-fonte

[!IMPORTANT] O AOCI-CODE v0.1.0-rc22 é o candidato a release atual. É software Fair Source/source-available sob a FSL-1.1-MIT; veja LICENSE. Compile a partir do código-fonte canônico ou use um pacote assinado do GitHub Release v0.1.0-rc22 após seguir o procedimento de verificação de release.

O binário assinado do Release se identifica como aoci version 0.1.0-rc22. Um build a partir do código-fonte identifica o checkout exato e pode relatar uma versão de desenvolvimento como v0.1.0-rc22-1-g<short-commit> (mais -dirty quando aplicável), junto com seu commit Git. São entradas de build diferentes, não um conflito de versão.

Para baixar com o GitHub CLI, autentique-se primeiro e então baixe os ativos do Release com a tag:

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

Para um download anônimo, abra a página do Release v0.1.0-rc22 em um navegador e baixe o arquivo e os ativos de verificação de que você precisa.

Para compilar a partir do código-fonte, clone o repositório canônico, compile o binário e mantenha o caminho resultante estável:

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

No Windows, compile o mesmo código-fonte no 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

Em seguida, dê este README a um agente em quem você já confia com o projeto e peça:

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.

O agente deve identificar a raiz do projeto, usar um caminho absoluto estável para o binário compilado, executar a inicialização adequada ao host atual e informar claramente quando for necessário reiniciar o host ou obter aprovação humana real. O binário pode permanecer no checkout do AOCI-CODE ou ser movido para um diretório de ferramentas compartilhado, desde que a configuração do MCP aponte para o caminho absoluto correto.

Inicialização manual

Para inicializar o AOCI por conta própria, execute o seguinte a partir da raiz do repositório de destino, ou passe um caminho explícito por meio de --repo:

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

init grava a configuração de locale, o bloco gerenciado de regras AGENTS.md, os limites do Git e um esqueleto de índice vazio. A configuração e o prompting variam conforme o host; consulte Integração com o host. Ele não inventa significado de negócio a partir de nomes de arquivos, diretórios ou de uma AST.

Para um novo repositório, o primeiro scan estabelece o Baseline gerenciado. Para um projeto que já possui um Baseline governado, adicionar, remover ou alterar o escopo gerenciado passa pelo fluxo formal de Scope Change; scan --force não é um atalho para redefinir fatos de governança. --force também não pode apagar drift não resolvido, recibos ou limites de recuperação.

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

Peça ao agente para construir o primeiro índice (importante)

Depois que a inicialização e o scan estiverem concluídos, verifique se a sessão do agente já expõe as ferramentas do AOCI; atualize ou reinicie-a caso contrário. Em seguida, insira o seguinte no agente para o projeto de destino:

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.

O agente inicia o painel em segundo plano com aoci ui --detach --json e entrega o link a você. Painel do AOCI cobre o que ele exibe e seus outros comandos.

O host lê as regras do AOCI do projeto e o guia ao vivo, inspeciona código-fonte, testes, configuração e evidências relevantes, e então grava candidatos FRAS para cada objeto gerenciado cujo papel é index. Você não precisa orquestrar Plan, Stage, Check, Diff, CAS ou Apply por conta própria.

Depois que o primeiro índice estiver completo, envie solicitações de desenvolvimento comuns normalmente, por exemplo:

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

Você não precisa acrescentar "mantenha o índice do AOCI ao final". As regras do projeto e o MCP fazem o agente verificar mudanças no índice quando o código e os testes estiverem estáveis, e então atualizar as entradas afetadas pelo fluxo formal. Quando o projeto usa automation.mode=auto, o AOCI-CODE interrompe você apenas quando é necessária aprovação humana real, quando uma ação externa precisa ser executada, quando a recuperação não pode ser comprovada, quando uma verificação de segurança falha ou quando é encontrado um conflito de concorrência de terceiros. Outros modos de automação seguem seus próprios contratos de execução.

Verifique o alinhamento

Depois que o onboarding for concluído, execute:

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

O índice e o código-fonte gerenciado atual devem convergir de volta para aligned. Caso contrário, consulte primeiro o guia ao vivo; não duplique a máquina de estados interna em um script wrapper:

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

Execute diagnósticos básicos

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

Para confirmar a qual AOCI o host está realmente conectado, leia o que o servidor relata sobre si mesmo em vez do que está no disco. Em qualquer resposta aoci_overview check_only ou em qualquer resposta aoci_maintain, cognition_receipt.mcp_service_version é a versão em execução e runtime_repository_root é o repositório que ele governa. O caminho do binário correspondente é o command no .mcp.json do projeto ou na configuração equivalente do host: .codex/config.toml, opencode.json ou .cursor/mcp.json. Substituir os bytes no disco não altera um processo MCP em execução, então verifique novamente com base nesses fatos após uma atualização ou um rollback.

Para um passo a passo pontual, use examples/minimal-repository no repositório.

make fast

make full
./build/aoci --version

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

O que aparece após a inicialização

Um repositório típico contém estes arquivos de índice:

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

Inicializar um novo projeto cria o Root, o Meta e um Code Volume vazio; o Database fica ausente por padrão. O AOCI-CODE não gera significado de negócio para o repositório ou o banco de dados por conta própria.

aoci init --agent <name> também grava a configuração de integração com o host (.mcp.json, .claude/settings.json, .codex/config.toml ou opencode.json) cujos caminhos de comando e de repositório são caminhos absolutos vinculados à máquina. Adicione esses arquivos ao .gitignore do repositório e não os faça commit: uma cópia commitada quebra em qualquer outra máquina, e como os instaladores detectam uma entrada existente pela presença da chave, executar novamente init ali mantém silenciosamente os caminhos quebrados.

Como uma tarefa de desenvolvimento é executada

Os dois diagramas abaixo mostram o fluxo de trabalho como você o vivencia, não a implementação interna do AOCI.

Novo projeto: construa primeiro um sistema simples, depois traga o 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

Um novo sistema não precisa do AOCI-CODE desde a primeira linha de código. Construa primeiro um protótipo com as capacidades existentes do agente; cerca de 10.000–30.000 linhas é um bom ponto para trazê-lo (não é um limite rígido). Equipes que desejam continuidade entre sessões mais cedo podem integrar antes.

Projeto existente: indexe o repositório e depois itere

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

Depois que o primeiro índice estiver completo, ambos os fluxos funcionam da mesma forma no dia a dia: você descreve o requisito de negócio ou de engenharia; o agente combina o Whole-Index com as evidências atuais, realiza o desenvolvimento e a verificação, e atualiza os objetos alterados por meio do MCP à medida que encerra a tarefa. Você não precisa aprender os comandos internos Plan, Stage, Diff, CAS ou Baseline, nem repetir o requisito de manutenção em cada prompt.

Se um lote completo for rejeitado antes de qualquer gravação formal começar, o índice permanece inalterado. Se o fluxo for interrompido após o início das gravações formais, o sistema mantém a intenção imutável, a evidência de gravação e o estado de recuperação, e então retoma a partir de uma pós-imagem comprovável ou reverte para a pré-imagem exata. Um conflito de bytes de terceiros falha de forma fechada; o AOCI-CODE nunca sobrescreve uma modificação externa para "concluir a gravação".

O estado final é sempre um de applied, repair_required ou stopped. stopped não é sucesso, e não significa necessariamente que nada foi gravado; inspecione failed_step, a evidência de gravação formal e a ação de recuperação retornada pelo guia.

Quem faz o quê: o modelo e o AOCI-CODE

O modelo é dono do significado

O modelo do host lê código-fonte, testes, configuração, documentação e quaisquer evidências de que precise, e então decide:

• pelo que um objeto é realmente responsável;
• quais arquivos, módulos ou objetos de banco de dados são relacionamentos fortes que devem ser considerados para alterá-lo com segurança;
• quais APIs, comandos, formatos ou contratos observáveis ele expõe;
• quais restrições de transação, autorização, concorrência, cache, implantação, compatibilidade ou históricas não podem ser inferidas apenas pela estrutura comum.

O AOCI-CODE não monta FRAS a partir de nomes de arquivos, caminhos, extensões, ASTs ou templates, e não reescreve silenciosamente o que o modelo escreveu.

O AOCI-CODE é dono da governança

O AOCI-CODE é responsável por:

1. estabelecer o Safe Inventory, o Managed Scope e o Baseline atual;
2. entregar o Whole-Index atual e confirmar sua identidade;
3. gerar um plano determinístico, o conjunto de alvos e os valores SHA-256 de origem;
4. validar a estrutura do candidato, o dicionário de tags, as identidades de relacionamento, o escopo, a propriedade, os orçamentos e o intervalo afetado;
5. preservar a vinculação entre o conteúdo de verificação, diff e revisão;
6. confirmar um lote completo com bloqueios entre processos, CAS e gravações atômicas;
7. avançar o Baseline, anexar ao ledger e preservar a evidência de recuperação após uma falha pós-gravação;
8. comprovar novamente o estado atual de governança por meio de Verify, Check e do guia;
9. derivar observações de Lineage, Relations, Impact, Snapshot e Evolution a partir de ativos autoritativos sem criar uma segunda fonte de verdade.

Resultados de máquina totalmente verdes significam apenas que os contratos estruturais e de governança codificados se mantêm; eles não significam que toda afirmação escrita pelo modelo está correta.

Como o índice é organizado

Um índice do AOCI tem duas camadas: as regras do índice e as entradas do índice. O produto suporta dois layouts físicos, e eles não são um único formato de arquivo.

Layout Volumes v1

Um projeto Volumes separa responsabilidades:

• aoci.txt é apenas o Root. Ele declara os Volumes que participam do CognitionSet atual.
• aoci.meta.txt contém o Meta: o dicionário de tags, as regras FRAS, os orçamentos e o contrato de autoria.
• aoci.code.txt contém as entradas para objetos de código.
• aoci.database.txt contém as entradas para objetos de banco de dados quando o Database Cognition está habilitado.

Os Volumes de Code e Database compartilham a mesma estrutura de linha FRAS, mas têm identidades de objeto, vinculações de evidência, propriedade e ciclos de vida independentes. Root, Meta e os Volumes de objetos juntos formam o Whole-Index; ler apenas o Root aoci.txt não é suficiente para afirmar que você leu o sistema inteiro.

Pense nisso como um mapa:

• As regras do índice são a legenda e o sistema de coordenadas do mapa.
• As entradas do índice são os marcadores que descrevem cada local.
• O Root é o catálogo e ponto de entrada de versão para o conjunto de mapas atual.
• Um Volume é uma folha separada regida pelo mesmo protocolo, mas com sua própria fonte de evidência e ciclo de vida.

Como é o cabeçalho do índice

Root e Meta abrem cada um com linhas de cabeçalho lidas por máquina. Isto é o que aoci init grava para um novo projeto en-US chamado my-service, começando pelo Root, que é o ponto de entrada de ativação:

#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

Cada linha #Volume: declara um Volume participante com sua identidade, tipo, caminho, formato, dependência e estado de ativação. Um Volume não declarado aqui não faz parte do CognitionSet atual, independentemente do que mais a árvore de trabalho contenha. Habilitar o Database Cognition adiciona mais uma linha, #Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled.

O Meta então abre com as regras que governam cada entrada:

#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 é a linha estrutural: os limites de campo pertencem ao binário, não a este texto, então um projeto não pode ampliá-los editando seu próprio Meta. #S-Admission e #S quota governam especificamente o campo S: o que pode ser registrado ali e quantos caracteres cada faixa de importância pode gastar. O dicionário de tags vem imediatamente após essas linhas; ele é mostrado na íntegra mais abaixo.

O Code Volume abre com uma única linha, #AOCI-CODE-VOLUME: 1, e tudo depois dela são seções de diretório e entradas.

Estes são os valores com que um novo projeto começa, não constantes fixas do protocolo. O Root e o Meta de cada repositório são autoritativos a partir daí: um projeto mais antigo pode carregar um dicionário de tags personalizado, e um projeto inicializado com --locale zh-CN grava #Locale: zh-CN e localiza a chave #S quota: de acordo.

O que as regras do índice definem

Nos Volumes v1, o Meta Volume do projeto armazena essas regras; no layout Legacy, elas ficam no cabeçalho monolítico. Os projetos podem usar dicionários de tags diferentes, enquanto a estrutura básica do FRAS permanece a mesma.

Este README apenas explica como ler essas regras. Para as regras concretas e executáveis, consulte o Meta ou o cabeçalho Legacy do projeto atual, o guia do AOCI e a especificação formal.

O que uma entrada registra (FRAS)

Com as regras estabelecidas, o modelo escreve uma entrada para cada objeto gerenciado com o papel index. O papel observe participa apenas da observação de mudanças, e o papel exclude marca o que é deliberadamente deixado de fora; nenhum dos dois possui uma entrada formal. O AOCI usa FRAS para organizar os quatro tipos de informação mais importantes em uma entrada:

• F — Function: pelo que o objeto é responsável.
• R — Relations: quais outros objetos você também deve considerar para entendê-lo ou alterá-lo com segurança.
• A — API: quais interfaces, comandos, formatos ou contratos observáveis ele expõe.
• S — Non-obvious constraints: informações importantes que F, R e A não cobrem, mas que você precisa para entender ou alterar o objeto com segurança, como restrições-chave, exceções, limites e semânticas especiais. S não deve repetir os três primeiros campos.

Por exemplo, dentro da seção do diretório ===.../internal/fs/===, uma entrada usa o basename:

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 

A seção do diretório e o basename resolvem para uma identidade de objeto de código. Para projeções entre Volumes ou de sistema, ela se expande para uma identidade canônica como code:internal/fs/atomic.go. Um objeto de banco de dados usa sua própria identidade canônica, como database://primary/public/orders.

A entrada tem duas partes:

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

Tags compactas dão a cada objeto coordenadas para camada arquitetural, domínio funcional, importância, características técnicas opcionais e tamanho. O dicionário de tags é definido pelo Meta Volume ou pelo cabeçalho Legacy do projeto. O programa valida o dicionário e a estrutura; ele não decide o significado de negócio.

S não é uma sinopse, um resumo comum nem uma repetição de F, R e A. Ele adiciona informações importantes que os três primeiros campos não cobrem e que afetam o entendimento ou a correção de engenharia, por exemplo:

• uma falha de acesso ao Redis deve recorrer ao banco de dados;
• uma tabela específica não deve entrar no AutoMigrate;
• um ramo de compatibilidade legado não deve ser removido por uma limpeza comum;
• o arquivo original deve ser preservado após uma falha de gravação.

O modelo escreve isso a partir do código-fonte real e de evidências. O AOCI-CODE valida a estrutura da entrada, vincula-a ao arquivo-fonte e governa como ela entra no índice formal.

Lendo o dicionário de tags inicial

O trecho a seguir é copiado literalmente do template atual do Meta Volume en-US (textassets/en-US/templates/volume-meta.txt.tmpl). É um dicionário inicial, não um vocabulário universal: o Meta formal de cada repositório permanece autoritativo. O inicial não declara um dicionário D; D permanece um eixo opcional e só pode ser usado quando o Meta formal atual o declarar.

#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

Sob o dicionário de código inicial, [CG9L] significa C SharedFoundation, G CrossDomain, 9 importância máxima e L escala grande; nenhum valor D está presente. Isso explica como ler a entrada existente, não como o modelo deve atribuir tags. O modelo ainda escolhe as tags a partir do Meta do projeto atual, com base no código-fonte e em evidências aceitas.

Volumes de Cognição

O AOCI-CODE mantém um Whole-Index lógico, enquanto cada tipo de índice tem seu próprio arquivo, propriedade e ciclo de vida.

Cada objeto tem exatamente um proprietário válido. Colocar um objeto no Volume errado cria um conflito de propriedade. O AOCI-CODE o corrige apenas quando a máquina consegue provar o proprietário incorreto, o proprietário correto e os fatos atuais do objeto; ele não adivinha a propriedade a partir de nomes semelhantes.

O Code Volume, o Database Volume e o escopo podem evoluir juntos, mas compartilham um único limite de commit governado. Aplicar um domínio não deve descartar a projeção de Baseline existente de outro domínio. A aplicação de um Volume, a atualização do Baseline e as projeções de escopo relacionadas são publicadas como um único resultado de transação consistente ou entram em recuperação comprovável. Elas nunca deixam um estado meio completo em que "o arquivo teve sucesso, mas outro Volume não tem baseline."

Integração com o host

aoci init sempre grava as regras de agente gerenciadas, mas a integração com o host difere:

• Codex recebe configuração MCP em nível de projeto e, com --hooks, um prompt de compactação de contexto mais SessionStart(compact). Ele ainda não instala nenhum hook de edição de arquivo.
• Claude Code pode instalar um hook PreToolUse.
• OpenCode V1 recebe um opencode.json estrito em nível de projeto.
• Cursor apenas retorna um trecho de configuração de referência; nada é gravado no projeto.

Após a configuração, verifique se a sessão atual do host já expõe as ferramentas do AOCI. Atualize ou reabra a sessão desse projeto apenas se ela não tiver carregado o novo servidor. Uma nova sessão normalmente lê as regras e o Whole-Index uma vez. Enquanto a identidade do índice permanecer válida e nenhuma compactação conhecida do host tiver ocorrido, as tarefas posteriores reutilizam o que o modelo já tem; o índice inteiro não é injetado novamente de forma mecânica.

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

O --hooks do Codex limita uma transferência de compactação à identidade do recibo, ao estado de gravação ou recuperação inacabado e a uma instrução de recarga imediata; ele não deve reter nem resumir corpos de Whole-Index ou de Overview/Attestation. Um hook PreCompact não consegue injetar na entrada de compactação do host nem excluir histórico dela, portanto não pode impor isso sozinho. Revise e confie no hook de projeto instalado via /hooks do Codex antes de depender dele.

A saída Legacy mantém os Níveis 0–4 para compatibilidade com hosts e relatórios existentes. O cognition-state/v2 atual expressa quão utilizável é a imagem que o modelo tem do sistema como Níveis 0–3, e separa fatos estritos de prova e governança em dimensões independentes:

Essas dimensões não substituem umas às outras. A atestação prova apenas a cobertura de entrega e a consistência de identidade para o material atual; ela não significa que o agente compreendeu plenamente toda tarefa futura possível. Apenas current_system_cognition_reliable=true permite uma afirmação sem qualificação de compreensão completa do sistema atual.

Painel do AOCI

aoci ui serve um painel somente leitura nesta máquina, para que você possa ver o estado do índice sem perguntar a um agente:

• o cabeçalho do índice e os Volumes Code / Database literalmente (linhas de seção === mantidas como estão, filtráveis, copiáveis como um todo); a aba "All" é o índice completo exatamente como um agente o recebe via Overview
• tokens do índice em relação ao orçamento, e o plano de chunks do Overview
• quanto código o índice cobre: arquivos, linhas, tokens e a taxa de compressão; quantas tabelas de banco de dados
• estado de governança e drift, Managed Scope, integrações com hosts e os processos aoci mcp em execução
• os comandos e prompts a fornecer ao agente em seguida, com botões de cópia

A página alterna entre chinês e inglês; o intervalo de atualização é selecionável (30 s por padrão).

Vários servidores aoci mcp em um único WSL? No Linux e no WSL, o painel descobre todos os processos aoci mcp do usuário atual e de seu repositório, alterna entre eles com abas no topo e marca um servidor cujo binário foi substituído no disco. Limites: ele vincula apenas endereços de loopback (qualquer outro bind é recusado), responde apenas a GET e HEAD, não adquire lock, não acrescenta nada ao ledger e não altera nenhum byte do repositório. É um processo separado, sem relação com aoci mcp; o servidor MCP continua sem abrir socket. O registro de um painel em segundo plano fica no diretório de cache do usuário, nunca no repositório.

Comandos CLI comuns

Combinações comuns:

# 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

Os comandos Plan, Stage, Check, Diff, Apply, Curation, Scope Change, Bootstrap, Migration e de recuperação ainda existem. Siga o guia retornado pelo binário em execução; não copie a máquina de estados interna para scripts.

Sobre comandos "somente leitura"

Para verify, check, index score e index inventory, "somente leitura" significa que o índice formal e a Baseline não são modificados; não significa estritamente zero gravações no sistema de arquivos. Quando o Ledger está habilitado, todos os quatro comandos podem acrescentar ao Ledger local, e o verify também tenta gravar o Verify History. Uma falha de gravação de auditoria não altera os códigos de saída existentes nem os critérios de governança.

Se for necessária uma operação estritamente sem gravação de arquivos, use uma cópia isolada; a CLI pública atual não expõe uma chave geral que desabilite toda gravação no Ledger e no Verify History. Os comandos de System Cognition não criam um segundo estado formal, mas chamadas comuns da CLI ainda seguem o contrato de runtime da versão atual para o Ledger e os registros de histórico local.

Servidor MCP

aoci mcp não precisa de daemon residente e expõe exatamente nove ferramentas via stdio:

No modo MCP, o stdout é reservado para JSON-RPC; logs e diagnósticos vão para o stderr. As descrições das ferramentas, os schemas JSON e os valores de estado de máquina fornecidos pelo binário em execução são autoritativos; este README é apenas um ponto de partida.

A versão atual fornece as capacidades de System Cognition por meio da CLI existente e do kernel de governança. Elas não adicionam uma décima ferramenta MCP nem alteram os nomes, propósitos ou o contrato stdio das nove existentes.

Sessões de longa duração e entrega de Whole-Index

No início de uma nova conversa, um agente normalmente carrega um Overview completo para obter uma visão do sistema que corresponda ao repositório atual, à versão do índice e à identidade do serviço AOCI. Enquanto o modelo ainda puder confiar nessa visão, ele não precisa recarregar antes de cada tarefa ou chamada de ferramenta.

Dentro da mesma conversa, o modelo decide se deve carregar novamente com base em seu próprio estado, exceto após uma compactação de contexto conhecida no host. Um handoff compactado pode preservar apenas a identidade do recibo, o estado inacabado de gravação ou recuperação e uma instrução de recarga imediata; ele não deve reter nem resumir corpos de Whole-Index ou de cabeçalho, entrada, chunk, challenge ou atestação do Overview. Conteúdo de índice ou um recibo copiado para esse handoff não pode provar que a visão atual do modelo é confiável.

Antes de continuar o trabalho de negócio após uma compactação conhecida, o agente recarrega as regras se elas não estiverem mais presentes de forma confiável, declara context_compaction com um novo event ID e completa uma sequência comum de cursor, confirmação e atestação de Overview completo. check_only e a sonda de cognition não são substitutos. Após um transporte completo novo, a regra existente de atestação parcial ou falha ainda permite a continuação vinculada à fonte sem um segundo Overview automático. Para uma mudança semântica ou um limite de fase importante sem compactação conhecida, o AOCI fornece limites de refresh, checkpoints e fatos de identidade, e o modelo decide se precisa restaurar sua visão de nível de sistema para a tarefa.

O corpo de cada Overview completo consiste em um marcador de início, o conteúdo exato do índice formal atual e um marcador de fim.

Quando um Overview excede o orçamento de chunks do projeto:

1. a entrega começa imediatamente com o chunk 1;
2. o agente deve seguir next_cursor automaticamente até o chunk final;
3. o agente envia uma atestação usando o Whole-Index entregue;
4. busca local, memória antiga, leitura suplementar de fontes ou leituras diretas de arquivos não devem ser apresentadas como entrega completa;
5. recuperação pendente ou um snapshot inconsistente falha de forma fechada sem misturar conteúdo.

overview_delivery.chunk_tokens é a única configuração de tamanho de entrega. Seu padrão é 7000, com faixa válida de 4000 a 24000. check_only=true é um checkpoint compacto sem cadeia de chunks.

O AOCI declara uma permissão de tamanho de resultado por ferramenta em aoci_overview. Um host que, de outra forma, persistiria um resultado grande de ferramenta em disco, colocando apenas uma pré-visualização no contexto do modelo (para entrega de índice, uma falha silenciosa), eleva esse limite apenas para esta ferramenta. No Claude Code, isso torna o 24000 completo utilizável, entregando um índice de 480 objetos em três chunks em vez de cinco. Nada é sondado: a declaração é estática, e um host que não a reconhece a ignora, conforme exige a especificação MCP.

O limite de refresh tem como padrão 30 caminhos semânticos distintos e também pode ser configurado por projeto. Para regras exatas de contagem, consulte a documentação de Cognition Refresh e o contrato de runtime.

Database Cognition

O AOCI-CODE pode trazer a estrutura do banco de dados para o mesmo índice e a mesma governança, com um limite de acesso explícito e estreito:

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

• Nenhum acesso de rede ao banco de dados ocorre quando nenhum banco está configurado ou nenhum comando explícito de banco é executado.
• Apenas metadados de schema de tabelas base são lidos, não linhas de negócio; views, rotinas e comentários estão fora do escopo de coleta atual.
• Nenhum DDL ou DML é executado.
• Nomes de host, nomes de usuário, DSNs e valores de credenciais nunca são gravados nos arquivos de índice.
• O apply de Database Cognition é executado offline e não se reconecta ao banco de dados durante a gravação.
• O programa preserva e compara evidências estruturais, mas o modelo ainda escreve responsabilidades de tabelas, relacionamentos e restrições de alto valor.

O suporte a MySQL cobre 5.7.6 e versões posteriores. O coletor lê a versão do servidor e executa apenas as consultas de catálogo que aquela versão consegue responder: restrições CHECK a partir de 8.0.16, expressões de índice a partir de 8.0.13, visibilidade de índice a partir de 8.0.0. Um servidor 5.7 registra uma lista de checks vazia, porque o 5.7 analisa a sintaxe CHECK e não armazena nada; a evidência tem o mesmo formato em todas as versões suportadas. MariaDB não é suportado e é recusado em vez de ser lido como MySQL.

O perfil inicial do openGauss é deliberadamente limitado ao openGauss 6.0.5 LTS no modo de compatibilidade A/PG e a tabelas base comuns não particionadas. Recursos de catálogo não suportados falham de forma fechada em vez de serem silenciosamente reduzidos a fatos do PostgreSQL; isso não reivindica suporte a MogDB, GaussDB, modo Dolphin/B/MySQL, partições ou subpartições, column-store, MOT, tabelas externas ou temporárias, views, rotinas ou triggers.

Aqui, a detecção de falha fechada se aplica a objetos visíveis semelhantes a tabelas selecionados com semântica não suportada. Rotinas e triggers permanecem fora do domínio de objetos de tabela da v1 e nunca são representados como fatos de tabela.

O caminho do openGauss usa o patch local revisado do AOCI sobre o código-fonte oficial do Connector v1.0.8. Seu parser estrito aceita apenas os parâmetros de conexão revisados e não consome PG*, service, password-file, home-directory ou configuração de logger do ambiente. Uma conexão TCP fora de um endereço de loopback numérico deve usar explicitamente sslmode=verify-full (e um caminho absoluto de raiz confiável em sslrootcert quando fornecido), com TLS 1.2 como mínimo; modos de downgrade de TLS são rejeitados. sslmode=disable é aceito apenas para um socket Unix explícito ou endereço de loopback numérico usado como limite local/de teste. Os administradores de banco de dados continuam responsáveis por fornecer esse DSN fora da conversa e por provisionar a conta de menor privilégio.

O Database Volume está ausente por padrão. Ele entra no Whole-Index apenas depois que o projeto habilita explicitamente o Database Cognition e conclui a governança de evidência, vinculação e ciclo de vida.

Onboarding de acesso ao banco de dados: você não precisa entender detalhes de DSN

Você apenas declara uma identidade não sensível para uma fonte de banco de dados. Se --credential-env for omitido, o AOCI deriva uma referência estável de variável de ambiente a partir do ID da fonte; por exemplo, primary mapeia para AOCI_DB_PRIMARY_DSN:

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

Em seguida, use a verificação prévia de acesso somente leitura para ver se o ambiente externo forneceu essa referência:

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

Este comando não se conecta ao banco de dados, não retorna um valor de credencial nem pede que você cole um DSN em uma conversa. Um administrador de banco de dados ou de infraestrutura fornece a variável de ambiente fora do processo do AOCI e concede acesso somente leitura, de menor privilégio, aos catálogos do sistema. A configuração da fonte armazena apenas o nome de referência da credencial, não o segredo.

A versão candidata atual fornece apenas o provedor de credenciais por ambiente. Gerenciadores de segredos em nuvem como Vault, Kubernetes Secret e AWS/GCP/Azure podem ser integrados pelo mesmo limite de provedor em versões futuras; eles não estão disponíveis hoje, e este README não sugere o contrário. Esta divisão mantém formatos de conta, codificação de DSN e gestão do ciclo de vida de segredos longe dos usuários comuns, ao mesmo tempo que mantém a autorização explícita: o AOCI não descobre credenciais automaticamente, não varre .env, não lê arquivos de segredos nem contorna a fronteira de autorização de um administrador de banco de dados.

Fundação de Cognição do Sistema

Sobre os índices de código e de banco de dados, o AOCI-CODE fornece um conjunto de observações derivadas de Cognição do Sistema. Elas respondem a perguntas como "de onde veio este objeto?", "quais objetos de código uma alteração no banco de dados pode afetar?" e "o que mudou entre uma observação histórica e agora?". Elas não criam uma nova camada de fatos autoritativos.

# 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

Fronteira de autoridade

Todo resultado de Cognição do Sistema informa derived=true; a projeção de relações informa adicionalmente authoritative=false. Cognition Volumes, vínculos de evidência de esquema, impressões digitais de Baseline e identidades vinculadas a recibos continuam sendo as autoridades subjacentes. Relacionamentos R não resolvidos produzem um resultado incompleto ou diagnósticos; o programa não adivinha nem os preenche.

O AOCI-CODE não é um sistema de grafo de conhecimento. A projeção estreita de relações é uma visão conveniente de relacionamentos, mas não possui um segundo sistema de gestão de estado, nem um caminho de escrita independente, nem um novo armazenamento de fatos. A saída derivada pode ser excluída e recalculada a partir dos ativos autoritativos atuais. Se uma projeção entrar em conflito com os ativos autoritativos, os ativos prevalecem.

Modos de execução, privacidade e fronteiras de dados

• O AOCI-CODE é local-first por padrão, sem endpoint de nuvem padrão, sem serviço hospedado de upload de código-fonte e sem servidor em segundo plano obrigatório.
• O tratamento de dados no modo Agent-native depende do host que você escolher e das políticas de produto dele; o AOCI-CODE não faz upload de dados em nome do host.
• O acesso de rede ao banco de dados deve ser acionado explicitamente e é restrito a metadados de esquema somente leitura.
• O ledger, os rascunhos, as transações e as evidências de recuperação são armazenados em .aoci/ por padrão e normalmente são ignorados pelo Git; os arquivos de índice e os ativos de governança da equipe podem ser commitados no Git.
• As projeções de Cognição do Sistema são calculadas localmente a partir dos ativos autoritativos existentes e não exigem banco de dados de grafo, banco de dados vetorial nem serviço de grafo remoto.

Como difere de um mapa de repositório, RAG, LSP ou grafo de código

Busca, ASTs, LSP, grafos de código e RAG são bons em questões estruturais e de recuperação. O AOCI-CODE faz um trabalho diferente: mantém uma descrição versionada do sistema que cobre o escopo gerenciado e evolui incrementalmente com o software. O que você obtém:

• Um Whole-Index. Um mapa do sistema cobrindo o escopo gerenciado atual, não fragmentos montados na hora para cada tarefa.
• Entradas FRAS. Responsabilidades, relacionamentos fortes, contratos públicos e restrições de alto valor para cada objeto com o papel index.
• Persistência entre sessões. Os arquivos de índice vivem com o repositório, então sessões posteriores e outros agentes reutilizam a mesma versão.
• Escopo Gerenciado. Um registro explícito de quais objetos entram no índice, quais são apenas observados para mudanças e quais são deliberadamente deixados de fora.
• Detecção de drift. Distingue Missing, Orphan, Stale, Unbaselined, mudanças de fim de linha, diferenças de curadoria e fontes mantidas fora da autoria (vazias, binárias, grandes demais).
• Atualizações governadas. Candidatos entram nos arquivos formais por meio de vínculo de fonte, plano, validação, revisão, CAS, escritas atômicas, Baseline e fluxos de recuperação.
• Atestação de entrega. Chunk, cursor, recibo e desafio provam que o Whole-Index foi entregue por completo.
• Cognição de Banco de Dados. Entradas em nível de tabela construídas e governadas a partir de evidências de esquema PostgreSQL/MySQL/openGauss explicitamente aceitas.
• Projeções do sistema. Observações de Linhagem, Relações estreitas, Impacto de banco de dados para código, Snapshot e Evolução derivadas do índice autoritativo e de seus vínculos sem duplicar o estado autoritativo; o Impacto percorre apenas relacionamentos R explícitos escritos pelo modelo.

O AOCI-CODE complementa as ferramentas existentes em vez de substituí-las.

A combinação recomendada: o AOCI-CODE fornece o prior semântico global; grafos de código, LSP, busca e código-fonte fornecem evidências precisas; testes e resultados de execução fornecem a aceitação final. A projeção de Relações do AOCI não substitui um grafo de chamadas preciso: ela expõe a contenção estrutural de Volume e as arestas de dependência de Root, enquanto suas arestas semânticas se limitam a relacionamentos fortes que o modelo escreveu explicitamente.

Stack de tecnologia

O AOCI-CODE não exige Neo4j, um banco de dados vetorial, um daemon de longa duração nem um serviço de nuvem AOCI. Quando a Cognição de Banco de Dados está habilitada, o banco de dados de destino é apenas uma fonte explícita e somente leitura de evidências de esquema, não o próprio armazenamento de estado do AOCI.

FAQ

Por que o status --deep Legacy ainda mostra drift?

status --deep, index score e index agent plan são exclusivos do Legacy. Para um repositório de Cognition Volumes, execute o guia ao vivo e deixe o host usar o aoci_maintain comum sem argumentos, envie o lote atual completo por meio de aoci_update_entry e encerre com Verify, Check e o guia. Não modifique o Baseline diretamente nem pule as etapas de vínculo de fonte e recuperação.

O próprio layout Legacy está obsoleto. O Volumes v1 é o caminho suportado para repositórios novos e migrados, e os comandos exclusivos do Legacy estão programados para remoção na v0.2.0; migre um repositório Legacy com aoci cognition migration antes disso.

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

Por que o host iniciou o AOCI errado?

Inspecione o caminho do executável na configuração MCP em nível de projeto e certifique-se de que seja um caminho absoluto estável, depois execute:

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

Para verificar o servidor stdio carregado em vez de apenas o arquivo em disco, inspecione também o executável real do processo host, sua linha de comando --repo e a identidade do processo após uma reinicialização.

Preciso criar uma conta de banco de dados e fornecer um DSN por conta própria?

Você não precisa entender a sintaxe de DSN, e não deve enviar segredos no chat. Depois de declarar uma identidade de fonte não sensível, o AOCI fornece uma referência estável de variável de ambiente. Um administrador de banco de dados ainda precisa criar uma conta externa de menor privilégio com acesso somente leitura ao catálogo do sistema e fornecer essa referência ao ambiente de execução. A versão atual não cria uma conta de banco de dados em nome de uma organização nem lê um armazenamento de segredos automaticamente.

Pode rodar em CI?

Sim. Varredura, verificação, portões de governança e checagens determinísticas rodam sem escrever novas entradas. Para comandos exatos, gravações de auditoria e códigos de saída, consulte o --help do binário atual, os esquemas JSON e a documentação de CI do projeto.

Um resultado do AOCI todo verde prova que a semântica está correta?

Não. Um resultado verde prova que as condições estruturais e de governança codificadas se mantêm. O que o modelo escreveu ainda precisa ser verificado contra o código-fonte, o esquema, os testes, os resultados de execução e a revisão humana.

O grafo de Cognição do Sistema é uma nova fonte de verdade?

Não. A capacidade atual é uma projeção estreita de relações, não uma plataforma de grafo independente. Ela calcula resultados apenas a partir do índice formal, das evidências, dos recibos e do Baseline, e não persiste novos fatos autoritativos. O programa também não gera relacionamentos semânticos automaticamente a partir de imports, SQL, nomes de arquivos ou similaridade.

Documentação

Os links de documentação e de contrato público estão fixados em v0.1.0-rc22 para que permaneçam válidos quando este README for lido a partir de um arquivo de Release binário, que não inclui os diretórios docs/ ou spec/public/ do repositório.

Suítes de verificação de caixa-preta

O repositório inclui quatro suítes de caixa-preta independentes em scripts/blackbox/ que exercitam um binário aoci compilado estritamente de fora do processo, apenas pelo protocolo MCP público via stdio e pela CLI:

• Conformidade de protocolo — 53 verificações somente leitura da superfície de rede do MCP, com as frases dependentes de locale repetidas em zh-CN;
• Cenários de injeção de falhas — 75 cenários cobrindo adulteração de cursor, recuperação de falhas, escritores concorrentes e o hook de pré-escrita em repositórios de fixture descartáveis;
• Ciclo de vida sobre projetos reais congelados — três projetos de fixture commitados: repo-a (TypeScript) e repo-b (Python + MySQL) executam o ciclo de vida completo de init até o realinhamento, e repo-c (um serviço em camadas de 453 arquivos) adicionalmente conduz a autoria em múltiplos lotes no limite de lote da máquina. Uma trilha de modelo opcional coloca um agente de IA real — qualquer modelo que sua instalação do OpenCode exponha — pelos dois repositórios pequenos e pontua o estado final a partir de superfícies públicas.
• Eixo de atualização — 80 verificações por versão lançada, sobre dez formatos de repositório: cada release publicada compila e cria a autoria de um repositório com seu próprio binário, então o binário em teste deve governá-lo sem mover uma identidade, exigir uma Mudança de Escopo ou reescrever um ativo formal, e o que ele então cria em autoria deve manter um checkout em outro caminho alinhado; no décimo formato os papéis se invertem, e cada release publicada deve ler um repositório que o binário em teste escreveu sem travar ou reescrevê-lo. As outras três suítes criam cada fixture com o binário em teste, então uma pré-imagem que mudou entre versões é invisível para elas por construção.

Elas precisam apenas de Python 3 e git além de um binário compilado (Docker para a suíte MySQL; OpenCode mais sua própria assinatura de modelo para a trilha de modelo), então um clone do repositório pode verificar sua própria compilação, uma porta de plataforma ou um fork — e AOCI_BIN pode apontar as suítes de conformidade e de cenários para qualquer binário alternativo que reivindique os contratos públicos em spec/public/. Essas suítes vivem no clone do repositório; arquivos de Release binário não as incluem. Consulte scripts/blackbox/README.md para comandos e interpretação de resultados.

Pesquisa, propriedade intelectual e licença

Artigos e artefatos de pesquisa da AOCI-CODE podem descrever publicamente métodos lançados, protocolos experimentais e resultados. Pedidos de patente, escopo concedido, status legal, titulares e efeito territorial são fatos legais, e não devem ser adicionados a descrições de produto com base em um README interno, um número de versão histórico ou um relato não verificado.

Se um número de patente específico, data de concessão ou escopo precisar ser divulgado no futuro, o titular dos direitos e o assessor jurídico devem verificá-lo junto a registros públicos oficiais e colocá-lo em um documento dedicado de PI, NOTICE ou legal. Este README deve apenas linkar para esse arquivo autoritativo; ele não deve expandir a cobertura de patente por conta própria nem apresentar o status de patente como uma licença de software.

Comunidade

Escaneie o código com WeChat ou WeCom (企业微信) para entrar no grupo do projeto AOCI e conversar com os mantenedores e outros usuários. Registre relatos de bugs e solicitações de recursos como issues do GitHub para que permaneçam pesquisáveis, e relate vulnerabilidades suspeitas de forma privada conforme descrito no SECURITY.md, nunca no grupo.

AOCI-CODE não se trata de fazer um agente ver mais código. Ele dá ao agente uma compreensão atual, estruturada, rastreável e governada do sistema antes de cada ação. O Git versiona seu código, as migrações de banco de dados versionam suas estruturas de dados, e o AOCI-CODE versiona o que os agentes sabem sobre o sistema, juntamente com a rastreabilidade, a consistência de governança e os limites de recuperação de como esse conhecimento evolui.