AOCI-CODE

AOCI-CODE

Un mapa persistente y versionado con Git de todo tu código base — escrito por tu agente de programación, gobernado por un servidor MCP local. Los agentes lo leen una vez y conocen el sistema, en lugar de releer el repositorio en cada tarea.

🇺🇸 English | 🇨🇳 简体中文

Qué hace

Construye sistemas grandes sin perder el hilo. En Codex, Claude Code, Cursor, OpenCode y agentes similares, tu agente comienza cada tarea conociendo ya todo el sistema: para qué sirve cada archivo, de qué depende y qué no debe romperse. Deja de buscar y releer el código base en cada solicitud. Las personas que no son desarrolladores profesionales pueden seguir iterando sobre sus propios sistemas; los desarrolladores profesionales pueden entregar todo el sistema a un agente y mantener su atención en la arquitectura y el diseño.

Hazte cargo de un sistema existente en un solo paso. Apunta el agente a un código base existente de hasta unos 500.000 líneas y pídele que construya el índice. Informa qué tan bien conoce cada área y luego retoma el desarrollo desde ahí. El límite práctico es el tamaño del índice, no el número de líneas: hoy en día se desarrolla así un sistema comercial de 700.000 líneas, con un índice de unos 300K tokens.

Cambia de personas, agentes o conversaciones sin empezar de cero. El índice vive en el repositorio junto al código y está versionado por Git. Cuando un proyecto cambia de manos, cambia de agente o abre una nueva conversación, una sola lectura del índice retoma donde quedaron las cosas.

Después del primer índice, el mantenimiento es automático. El servidor MCP detecta los cambios en el código y emite las entradas que necesitan actualizarse. El agente las completa al terminar cada tarea, de modo que el índice coincide con el código actual y nunca tienes que detenerte a mantenerlo.

Cómo se ve

Una línea por archivo, escrita por el modelo a partir del código fuente real. Esta es una entrada real del índice de este mismo repositorio:

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 es de lo que se encarga el archivo, R es lo que tienes que leer junto con él, A es de lo que dependen quienes lo llaman, y S es lo que no puedes inferir del código pero no debes equivocar. La etiqueta [CG9L] ubica el archivo por capa, dominio, importancia y tamaño. Unos cientos de líneas como esta cubren todo un sistema, y un agente puede leerlas de una sola pasada. El formato de entrada explica cada campo.

¿En qué se diferencia de CodeGraph?

• CodeGraph analiza tu código y lo convierte en un grafo de símbolos y llamadas. Cuando el agente hace una pregunta, devuelve el código fuente exacto y las rutas de llamadas. Es una herramienta de consulta precisa para la tarea en cuestión.
• AOCI-CODE hace que el modelo escriba una línea por archivo y por tabla: para qué sirve, a qué se conecta y qué no debe romperse. El agente lee primero todo el índice, así conoce el sistema antes de que empiece la tarea. El índice vive en Git y se mantiene sincronizado con el código.
• Usa ambos: el índice para conocer el sistema, CodeGraph para obtener el código exacto mientras trabajas.

La comparación completa también cubre RAG, LSP y los mapas de repositorio.

Qué esperar

El primer índice tarda un rato. El agente lee cada archivo gestionado y escribe una entrada por archivo: aproximadamente una hora por cada 200.000 líneas de código, según el modelo y la velocidad del agente. Se ejecuta por lotes y reanuda donde se detuvo si se interrumpe.

¿Tienes una base de datos? Indéxala también. Se admiten MySQL y PostgreSQL, y openGauss 6.0.5 con restricciones. MySQL significa 5.7.6 y posteriores; MariaDB no es compatible. Construye primero el índice de código y luego el de la base de datos. Con el conocimiento del código y de las tablas entregado en conjunto, el agente entiende el sistema de forma más completa.

Solo local: de solo lectura sobre tu sistema, sin Internet, sin credenciales almacenadas. AOCI-CODE lee tu código fuente y las estructuras de las tablas de la base de datos, nunca los datos de negocio. Escribe sus archivos de índice y su propio estado dentro del directorio del proyecto, además del registro de la página de estado en el directorio de caché de tu usuario. Nunca accede a Internet y no sube nada: las únicas conexiones que abre son a la base de datos que declares, para metadatos del catálogo, y a su propia página de estado en loopback. Las credenciales de la base de datos se referencian por el nombre de la variable de entorno y nunca se almacenan. El texto del índice lo escribe localmente tu propio agente a través del canal del modelo que ya usas; AOCI-CODE no añade ninguna salida de datos nueva.

Inicio rápido

Da a tu agente la siguiente instrucción para descargar AOCI-CODE y configurarlo. Después de reiniciar el agente, envía la segunda instrucción para construir el í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.

Después de reiniciar el agente, envía 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.

El agente inicia el panel en segundo plano con aoci ui --detach --json y te entrega el enlace. Panel de AOCI cubre lo que muestra y sus otros comandos.

Por qué el reinicio: el índice se escribe a través de las herramientas MCP de AOCI, y la sesión que ejecutó init no ha cargado el servidor MCP que init acaba de escribir. Un host que carga servidores MCP de forma dinámica puede no necesitar un reinicio; Integración con el host explica cómo saberlo.

Si tu proyecto tiene una base de datos (se admiten PostgreSQL y MySQL, además de openGauss 6.0.5 con restricciones), indéxala también. Declara la fuente como se describe en Cognición de base de datos, proporciona la variable de entorno de la cadena de conexión en el entorno del host (AOCI no almacena credenciales) y luego envía:

Build the AOCI database index for this project.

Si el contexto se ha compactado, o quieres que el agente reconstruya su imagen del sistema, envía esto:

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.

Cómo funciona

AOCI (AI-Oriented Cognition Infrastructure) es el método y el protocolo: una capa entre los agentes de programación y los sistemas de software. Los modelos razonan, los agentes planifican y ejecutan, y AOCI mantiene una descripción actualizada del sistema, que abarca código, configuración, pruebas y estructura de la base de datos, para que los agentes la lean antes de actuar. AOCI-CODE es este proyecto: la CLI aoci, el servidor MCP y el índice que mantienen.

AOCI-CODE destila lo que realmente importa para entender y cambiar un sistema en un índice de texto plano y denso que combina símbolos y significado. Cuando el contexto del modelo es limitado, un agente lee primero el índice, obtiene la mayor parte de la información clave del proyecto en una sola pasada y luego comienza la tarea. Eso reduce la búsqueda y el reaprendizaje repetidos, y traslada el entendimiento entre tareas y sesiones.

• No es un resumen único. El índice evoluciona con el sistema y permanece en el proyecto, donde puedes compararlo, revisarlo, versionarlo y revertirlo con Git.
• Más que "dónde están los archivos". Registra responsabilidades, relaciones fuertes, contratos públicos, límites de transacción, restricciones de compatibilidad y otras cosas difíciles de inferir de la estructura del código.
• Portable. El índice se almacena con el proyecto, no está atado a un modelo, un agente ni una sesión. Mientras esté alineado con el código, cualquier agente y cualquier sesión posterior pueden reutilizarlo sin reconstruir su entendimiento desde cero.
• Código y bases de datos juntos. El modelo puede construir un índice separado a nivel de tabla para las tablas de la base de datos. Entregados juntos, ambos dan al agente una imagen más completa del sistema.

El índice es un conjunto de archivos de texto plano gobernados y almacenados con el proyecto:

• Raíz (aoci.txt) declara de qué se compone el índice actual y es su punto de entrada de activación.
• Meta (aoci.meta.txt) contiene el diccionario de etiquetas, las reglas FRAS y las restricciones de autoría.
• Código (aoci.code.txt) contiene las entradas escritas por el modelo para el código y otros activos del repositorio.
• Base de datos (aoci.database.txt) contiene entradas opcionales a nivel de tabla cuando la Cognición de base de datos está habilitada.

Raíz, Meta y los Volúmenes de objetos participantes forman juntos el Whole-Index. El flujo de trabajo sobre ellos tiene tres etapas:

1. Construir el índice bajo gobernanza. El modelo lee el código fuente y la evidencia aceptada. AOCI-CODE gobierna el Ámbito Gestionado y las entradas que el modelo escribe para cada objeto gestionado con el rol index.
2. Leer antes de actuar. El agente lee las reglas del proyecto, la guía activa y el Whole-Index actual, y luego verifica el código fuente y otra evidencia para la tarea en cuestión.
3. Mantener tras un cambio verificado. Una vez que el código y las pruebas son estables, las reglas del proyecto y el flujo de trabajo MCP hacen que el agente actualice las entradas afectadas y devuelva el índice a aligned.

Como estos archivos son texto plano en el repositorio, Git los versiona. Mientras el índice permanezca alineado con la versión actual del sistema, cualquier agente y cualquier sesión posterior pueden leer y reutilizar el mismo Whole-Index.

Integración manual

Obtén AOCI-CODE de la fuente canónica o usa un paquete firmado de GitHub Releases. Antes de usar un binario precompilado, sigue el nivel de verificación básico, recomendado o completo en la guía de instalación, e informa qué nivel se completó. Da este README y la ruta absoluta estable del binario verificado a un agente de programación de tu confianza, como Codex, Claude Code, Cursor u OpenCode. El agente puede seguir las instrucciones dentro del proyecto para inicializar AOCI, integrar MCP y construir el primer índice.

Cuánto tarda el primer índice depende del tamaño del repositorio. Una integración normal consta de cuatro pasos: preparar el binario, hacer que el agente o tú mismo inicialice el repositorio objetivo, pedir al host que "construya el índice" y verificar la alineación. Después de eso no necesitas terminar cada solicitud con "mantén el índice". Las reglas del proyecto y el flujo de trabajo MCP hacen que el agente mantenga el índice de forma incremental siempre que cambien los objetos gestionados.

Requisitos

• Un paquete de versión verificado o una copia de trabajo del repositorio de código fuente canónico de AOCI-CODE.
• Solo para compilaciones desde el código fuente: la cadena de herramientas de Go declarada por go.mod, make y las demás herramientas que requiere el repositorio.
• Un host MCP compatible, como Codex, Claude Code, Cursor u OpenCode.
• Acceso normal de lectura y escritura al repositorio objetivo.

AOCI-CODE se integra con el host MCP, no con una API de proveedor de modelos. DeepSeek y otros modelos pueden usar AOCI-CODE cuando el agente o el host que los ejecuta admite MCP estándar por stdio y puede seguir el contrato de herramientas; un nombre de modelo por sí solo no establece compatibilidad.

La ruta del paquete firmado y los comandos de verificación del ejecutable están en la guía de instalación. La ruta de compilación desde el código fuente está a continuación.

RC actual: usa un paquete verificado o compila desde el código fuente

[!IMPORTANT] AOCI-CODE v0.1.0-rc22 es el candidato de versión actual. Es software Fair Source/de código disponible bajo FSL-1.1-MIT; consulta LICENSE. Compila desde el código fuente canónico o usa un paquete firmado de la versión v0.1.0-rc22 en GitHub después de seguir el procedimiento de verificación de la versión.

El binario firmado de la versión se identifica como aoci version 0.1.0-rc22. Una compilación desde el código fuente identifica en cambio la copia de trabajo exacta y puede informar una versión de desarrollo como v0.1.0-rc22-1-g<short-commit> (más -dirty cuando corresponda), junto con su commit de Git. Son entradas de compilación distintas, no un conflicto de versiones.

Para descargar con GitHub CLI, autentícate primero y luego descarga los recursos de la versión etiquetada:

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

Para una descarga anónima, abre la página de la versión v0.1.0-rc22 en un navegador y descarga el archivo y los recursos de verificación que necesites.

Para compilar desde el código fuente, clona el repositorio canónico, compila el binario y mantén estable la ruta resultante:

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

En Windows, compila el mismo código fuente en 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

Luego da este README a un agente en el que ya confíes con el proyecto y pídele:

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.

El agente debe identificar la raíz del proyecto, usar una ruta absoluta estable al binario compilado, ejecutar la inicialización que corresponda al host actual e indicarte claramente cuándo se requiere un reinicio del host o una aprobación humana real. El binario puede permanecer en el checkout de AOCI-CODE o moverse a un directorio de herramientas compartido, siempre que la configuración de MCP apunte a la ruta absoluta correcta.

Inicialización manual

Para inicializar AOCI tú mismo, ejecuta lo siguiente desde la raíz del repositorio de destino, o pasa una ruta explícita mediante --repo:

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

init escribe la configuración regional, el bloque de reglas gestionado de AGENTS.md, los límites de Git y un esqueleto de índice vacío. La configuración y el prompting varían según el host; consulta Integración con el host. No inventa significado de negocio a partir de nombres de archivo, directorios ni un AST.

Para un repositorio nuevo, el primer scan establece la Baseline gestionada. Para un proyecto que ya tiene una Baseline gobernada, agregar, quitar o cambiar el alcance gestionado pasa por el flujo formal de Scope Change; scan --force no es un atajo para redefinir hechos de gobernanza. --force tampoco puede borrar drift no resuelto, recibos ni límites de recuperación.

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

Haz que el agente construya el primer índice (importante)

Una vez completadas la inicialización y scan, verifica si la sesión del agente ya expone las herramientas de AOCI; actualízala o reiníciala si no es así. Luego ingresa lo siguiente en el agente para el proyecto 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.

El agente inicia el panel en segundo plano con aoci ui --detach --json y te entrega el enlace. Panel de AOCI cubre lo que muestra y sus otros comandos.

El host lee las reglas de AOCI del proyecto y la guía en vivo, inspecciona el código fuente, las pruebas, la configuración y la evidencia relevante, y luego escribe candidatos FRAS para cada objeto gestionado cuyo rol sea index. No necesitas orquestar tú mismo Plan, Stage, Check, Diff, CAS o Apply.

Una vez completado el primer índice, envía solicitudes de desarrollo normales como de costumbre, por ejemplo:

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

No necesitas agregar "mantén el índice de AOCI al final". Las reglas del proyecto y MCP hacen que el agente verifique si hay cambios en el índice una vez que el código y las pruebas están estables, y luego actualice las entradas afectadas mediante el flujo formal. Cuando el proyecto usa automation.mode=auto, AOCI-CODE te interrumpe solo cuando se requiere una aprobación humana real, debe realizarse una acción externa, no puede probarse la recuperación, falla una verificación de seguridad o se encuentra un conflicto de concurrencia de terceros. Otros modos de automatización siguen sus propios contratos de ejecución.

Verificar la alineación

Una vez completado el onboarding, ejecuta:

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

El índice y el código fuente gestionado actual deberían converger de nuevo a aligned. Si no lo hacen, consulta primero la guía en vivo; no dupliques la máquina de estados interna en un script contenedor:

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

Ejecutar diagnósticos básicos

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

Para confirmar a qué AOCI está realmente conectado el host, lee lo que el servidor informa sobre sí mismo en lugar de lo que hay en disco. En cualquier respuesta de aoci_overview check_only o en cualquier respuesta de aoci_maintain, cognition_receipt.mcp_service_version es la versión en ejecución y runtime_repository_root es el repositorio que gobierna. La ruta del binario correspondiente es la de command en el .mcp.json del proyecto o en la configuración equivalente del host: .codex/config.toml, opencode.json o .cursor/mcp.json. Reemplazar los bytes en disco no cambia un proceso MCP en ejecución, así que vuelve a verificar contra esos hechos después de una actualización o un rollback.

Para un recorrido puntual, usa examples/minimal-repository en el repositorio.

make fast

make full
./build/aoci --version

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

Qué aparece después de la inicialización

Un repositorio típico contiene estos archivos 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 un proyecto nuevo crea el Root, Meta y un Code Volume vacío; Database está ausente por defecto. AOCI-CODE no genera significado de negocio para el repositorio ni la base de datos por sí solo.

aoci init --agent <name> además escribe la configuración de integración con el host (.mcp.json, .claude/settings.json, .codex/config.toml o opencode.json) cuyos comandos y rutas de repositorio son rutas absolutas vinculadas a la máquina. Agrega esos archivos al .gitignore del repositorio y no los confirmes: una copia confirmada se rompe en cualquier otra máquina, y como los instaladores detectan una entrada existente por la presencia de la clave, volver a ejecutar init allí mantiene silenciosamente las rutas rotas.

Cómo se ejecuta una tarea de desarrollo

Los dos diagramas siguientes muestran el flujo de trabajo tal como lo experimentas, no la implementación interna de AOCI.

Proyecto nuevo: construye primero un sistema simple y luego incorpora 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 sistema nuevo no necesita AOCI-CODE desde la primera línea de código. Construye primero un prototipo con las capacidades existentes del agente; aproximadamente 10,000–30,000 líneas es un buen punto para incorporarlo (no es un umbral estricto). Los equipos que quieren continuidad entre sesiones antes pueden integrarlo más temprano.

Proyecto existente: indexa el repositorio y luego itera

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

Una vez completado el primer índice, ambos flujos funcionan igual en el día a día: describes el requisito de negocio o de ingeniería; el agente combina el Whole-Index con la evidencia actual, realiza el desarrollo y la verificación, y actualiza los objetos modificados mediante MCP al cerrar la tarea. No necesitas aprender los comandos internos Plan, Stage, Diff, CAS o Baseline, ni repetir el requisito de mantenimiento en cada prompt.

Si un lote completo se rechaza antes de que comience cualquier escritura formal, el índice no cambia. Si el flujo de trabajo se interrumpe después de que comienzan las escrituras formales, el sistema conserva la intención inmutable, la evidencia de escritura y el estado de recuperación, y luego reanuda desde una postimagen demostrable o revierte a la preimagen exacta. Un conflicto de bytes de terceros falla de forma cerrada; AOCI-CODE nunca sobrescribe una modificación externa para "terminar la escritura".

El estado final siempre es uno de applied, repair_required o stopped. stopped no es éxito, y no significa necesariamente que no se escribió nada; inspecciona failed_step, la evidencia de escritura formal y la acción de recuperación que devuelve la guía.

Quién hace qué: el modelo y AOCI-CODE

El modelo posee el significado

El modelo del host lee el código fuente, las pruebas, la configuración, la documentación y cualquier evidencia que necesite, y luego decide:

• de qué es realmente responsable un objeto;
• qué archivos, módulos u objetos de base de datos son relaciones fuertes que deben considerarse para cambiarlo de forma segura;
• qué APIs, comandos, formatos o contratos observables expone;
• qué restricciones de transacción, autorización, concurrencia, caché, despliegue, compatibilidad o históricas no pueden inferirse solo de la estructura ordinaria.

AOCI-CODE no ensambla FRAS a partir de nombres de archivo, rutas, extensiones, ASTs o plantillas, y no reescribe silenciosamente lo que escribió el modelo.

AOCI-CODE posee la gobernanza

AOCI-CODE es responsable de:

1. establecer el Safe Inventory, el Managed Scope y la Baseline actual;
2. entregar el Whole-Index actual y confirmar su identidad;
3. generar un plan determinista, un conjunto de objetivos y valores SHA-256 de origen;
4. validar la estructura del candidato, el diccionario de etiquetas, las identidades de relación, el alcance, la propiedad, los presupuestos y el rango afectado;
5. preservar la vinculación entre el contenido de check, diff y revisión;
6. confirmar un lote completo con bloqueos entre procesos, CAS y escrituras atómicas;
7. avanzar la Baseline, agregar al ledger y preservar la evidencia de recuperación tras una falla posterior a la escritura;
8. probar de nuevo el estado de gobernanza actual mediante Verify, Check y la guía;
9. derivar observaciones de Lineage, Relations, Impact, Snapshot y Evolution a partir de activos autoritativos sin crear una segunda fuente de verdad.

Los resultados de máquina totalmente en verde significan solo que los contratos estructurales y de gobernanza codificados se cumplen; no significan que cada afirmación que escribió el modelo sea correcta.

Cómo se organiza el índice

Un índice de AOCI tiene dos capas: las reglas del índice y las entradas del índice. El producto admite dos diseños físicos, y no son un mismo formato de archivo.

Diseño de Volumes v1

Un proyecto de Volumes separa responsabilidades:

• aoci.txt es solo el Root. Declara los Volumes que participan en el CognitionSet actual.
• aoci.meta.txt contiene Meta: el diccionario de etiquetas, las reglas FRAS, los presupuestos y el contrato de autoría.
• aoci.code.txt contiene las entradas para objetos de código.
• aoci.database.txt contiene las entradas para objetos de base de datos cuando Database Cognition está habilitado.

Los Volumes de Code y Database comparten la misma estructura de línea FRAS, pero tienen identidades de objeto, vinculaciones de evidencia, propiedad y ciclos de vida independientes. Root, Meta y los Volumes de objetos juntos forman el Whole-Index; leer solo el Root de aoci.txt no basta para afirmar que has leído todo el sistema.

Piénsalo como un mapa:

• Las reglas del índice son la leyenda y el sistema de coordenadas del mapa.
• Las entradas del índice son los marcadores que describen cada ubicación.
• Root es el catálogo y punto de entrada de versión para el conjunto de mapas actual.
• Un Volume es una hoja separada gobernada por el mismo protocolo pero con su propia fuente de evidencia y ciclo de vida.

Cómo se ve el encabezado del índice

Root y Meta comienzan cada uno con líneas de encabezado leídas por máquina. Esto es lo que aoci init escribe para un nuevo proyecto en-US llamado my-service, comenzando con el Root, que es el punto de entrada de activación:

#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 línea #Volume: declara un Volume participante con su identidad, tipo, ruta, formato, dependencia y estado de activación. Un Volume que no se declara aquí no forma parte del CognitionSet actual, sin importar qué más contenga el árbol de trabajo. Habilitar Database Cognition agrega una línea más, #Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled.

Meta luego comienza con las reglas que gobiernan 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 es la línea fundamental: los límites de campo pertenecen al binario, no a este texto, así que un proyecto no puede ampliarlos editando su propio Meta. #S-Admission y #S quota gobiernan específicamente el campo S: qué puede registrarse allí en absoluto, y cuántos caracteres puede gastar cada banda de importancia. El diccionario de etiquetas sigue inmediatamente después de estas líneas; se muestra completo más abajo.

El Code Volume comienza con una sola línea, #AOCI-CODE-VOLUME: 1, y todo lo que sigue son secciones de directorio y entradas.

Estos son los valores con los que comienza un proyecto nuevo, no constantes fijas del protocolo. El Root y el Meta propios de cada repositorio son autoritativos a partir de entonces: un proyecto más antiguo puede tener un diccionario de etiquetas personalizado, y un proyecto inicializado con --locale zh-CN escribe #Locale: zh-CN y localiza la clave #S quota: en consecuencia.

Qué definen las reglas del índice

En los Volúmenes v1, el Meta Volumen del proyecto almacena estas reglas; en el diseño Legacy, residen en la cabecera monolítica. Los proyectos pueden usar diccionarios de etiquetas diferentes, mientras que la estructura básica FRAS permanece igual.

Este README solo explica cómo leer estas reglas. Para las reglas concretas y ejecutables, remítase al Meta o la cabecera Legacy del proyecto actual, a la guía de AOCI y a la especificación formal.

Qué registra una entrada (FRAS)

Una vez establecidas las reglas, el modelo escribe una entrada por cada objeto gestionado con el rol index. El rol observe participa solo en la observación de cambios, y el rol exclude marca lo que se deja fuera deliberadamente; ninguno posee una entrada formal. AOCI usa FRAS para organizar los cuatro tipos de información más relevantes en una entrada:

• F — Función: de qué es responsable el objeto.
• R — Relaciones: qué otros objetos también debe considerar para entenderlo o modificarlo de forma segura.
• A — API: qué interfaces, comandos, formatos o contratos observables expone.
• S — Restricciones no obvias: información importante que F, R y A no cubren pero que necesita para entender o modificar el objeto de forma segura, como restricciones clave, excepciones, límites y semánticas especiales. S no debe repetir los tres primeros campos.

Por ejemplo, dentro de la sección del directorio ===.../internal/fs/===, una entrada usa el nombre 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 sección del directorio y el nombre base resuelven a una identidad de objeto de código. Para proyecciones entre Volúmenes o de sistema, se expande a una identidad canónica como code:internal/fs/atomic.go. Un objeto de base de datos usa su propia identidad canónica, como database://primary/public/orders.

La entrada tiene dos 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

Las etiquetas compactas dan a cada objeto coordenadas para la capa arquitectónica, el dominio funcional, la importancia, las características técnicas opcionales y el tamaño. El diccionario de etiquetas lo define el Meta Volumen o la cabecera Legacy del proyecto. El programa valida el diccionario y la estructura; no decide el significado de negocio.

S no es una sinopsis, un resumen ordinario ni una repetición de F, R y A. Añade información importante que los tres primeros campos no cubren y que afecta a la comprensión o a la corrección de ingeniería, por ejemplo:

• un fallo de acceso a Redis debe recurrir a la base de datos;
• una tabla concreta no debe entrar en AutoMigrate;
• una rama de compatibilidad heredada no debe eliminarse mediante una limpieza ordinaria;
• el archivo original debe preservarse tras un fallo de escritura.

El modelo escribe esto a partir del código fuente real y de la evidencia. AOCI-CODE valida la estructura de la entrada, la vincula al archivo fuente y gobierna cómo entra en el índice formal.

Lectura del diccionario de etiquetas inicial

El siguiente extracto se copia literalmente de la plantilla Meta del Volumen en-US actual (textassets/en-US/templates/volume-meta.txt.tmpl). Es un diccionario inicial, no un vocabulario universal: el Meta formal de cada repositorio sigue siendo la autoridad. El inicial no declara un diccionario D; D sigue siendo un eje opcional y solo puede usarse cuando el Meta formal actual lo declare.

#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

Según el diccionario de código inicial, [CG9L] significa C SharedFoundation, G CrossDomain, 9 importancia máxima y L escala grande; no hay ningún valor D presente. Esto explica cómo leer la entrada existente, no cómo debe asignar etiquetas el modelo. El modelo sigue eligiendo las etiquetas del Meta del proyecto actual, basándose en el código fuente y en la evidencia aceptada.

Volúmenes de cognición

AOCI-CODE mantiene un Whole-Index lógico, mientras que cada tipo de índice tiene su propio archivo, propiedad y ciclo de vida.

Cada objeto tiene exactamente un propietario válido. Colocar un objeto en el Volumen equivocado crea un conflicto de propiedad. AOCI-CODE lo repara solo cuando la máquina puede probar el propietario incorrecto, el propietario correcto y los hechos actuales del objeto; no adivina la propiedad a partir de nombres similares.

El Volumen Code, el Volumen Database y el alcance pueden evolucionar juntos, pero comparten un único límite de confirmación gobernado. Aplicar un dominio no debe descartar la proyección Baseline existente de otro dominio. La aplicación de un Volumen, la actualización del Baseline y las proyecciones de alcance relacionadas se publican como un único resultado de transacción consistente o entran en una recuperación demostrable. Nunca dejan un estado a medio completar en el que "el archivo tuvo éxito pero otro Volumen no tiene baseline".

Integración con el host

aoci init siempre escribe las reglas de agente gestionadas, pero la integración con el host difiere:

• Codex obtiene configuración MCP a nivel de proyecto y, con --hooks, un prompt de compactación de contexto más SessionStart(compact). Sigue sin instalar ningún hook de edición de archivos.
• Claude Code puede instalar un hook PreToolUse.
• OpenCode V1 obtiene un opencode.json estricto a nivel de proyecto.
• Cursor solo devuelve un fragmento de configuración de referencia; no se escribe nada en el proyecto.

Tras la configuración, compruebe si la sesión actual del host ya expone las herramientas de AOCI. Actualice o vuelva a abrir esa sesión del proyecto solo si no ha cargado el nuevo servidor. Una sesión nueva normalmente lee las reglas y el Whole-Index una vez. Mientras la identidad del índice siga siendo válida y no se haya producido ninguna compactación conocida del host, las tareas posteriores reutilizan lo que el modelo ya tiene; el índice completo no se inyecta de nuevo mecánicamente.

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 limita un traspaso de compactación a la identidad del recibo, al estado de escritura o recuperación inacabado y a una instrucción de recarga inmediata; no debe retener ni resumir cuerpos de Whole-Index ni de Overview/Attestation. Un hook PreCompact no puede inyectar en la entrada de compactación del host ni eliminar historial de ella, por lo que no puede imponer esto por sí solo. Revise y confíe en el hook del proyecto instalado mediante Codex /hooks antes de depender de él.

La salida Legacy conserva los Niveles 0–4 por compatibilidad con los hosts e informes existentes. El cognition-state/v2 actual expresa lo utilizable que es la imagen que el modelo tiene del sistema como Niveles 0–3, y separa la prueba estricta y los hechos de gobernanza en dimensiones independientes:

Estas dimensiones no se sustituyen entre sí. La atestación prueba solo la cobertura de entrega y la consistencia de identidad del material actual; no significa que el agente haya comprendido plenamente toda posible tarea futura. Solo current_system_cognition_reliable=true permite una afirmación sin reservas de comprensión completa del sistema actual.

Panel de AOCI

aoci ui sirve un panel de solo lectura en esta máquina, para que pueda ver el estado del índice sin preguntar a un agente:

• la cabecera del índice y los Volúmenes Code / Database literalmente (las líneas de sección === se mantienen tal cual, filtrables, copiables en su totalidad); la pestaña "All" es el índice completo exactamente como lo recibe un agente mediante Overview
• los tokens del índice frente al presupuesto, y el plan de fragmentos de Overview
• cuánto código cubre el índice: archivos, líneas, tokens y la ratio de compresión; cuántas tablas de base de datos
• el estado de gobernanza y la deriva, el Managed Scope, las integraciones con el host y los procesos aoci mcp en ejecución
• los comandos y prompts que dar al agente a continuación, con botones de copia

La página alterna entre chino e inglés; el intervalo de actualización es seleccionable (30 s por defecto).

¿Varios servidores aoci mcp en un mismo WSL? En Linux y WSL el panel descubre cada proceso aoci mcp del usuario actual y su repositorio, cambia entre ellos con pestañas en la parte superior y marca un servidor cuyo binario fue reemplazado en disco. Límites: solo se enlaza a direcciones de loopback (cualquier otro bind se rechaza), responde únicamente a GET y HEAD, no toma ningún lock, no añade nada al ledger y no cambia ni un byte del repositorio. Es un proceso separado sin relación con aoci mcp; el servidor MCP sigue sin abrir ningún socket. El registro de un panel en segundo plano vive en el directorio de caché del usuario, nunca en el repositorio.

Comandos CLI habituales

Combinaciones habituales:

# 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

Los comandos Plan, Stage, Check, Diff, Apply, Curation, Scope Change, Bootstrap, Migration y de recuperación siguen existiendo. Sigue la guía que devuelve el binario en ejecución; no copies la máquina de estados interna en scripts.

Acerca de los comandos "de solo lectura"

Para verify, check, index score e index inventory, "solo lectura" significa que el índice formal y la Baseline no se modifican; no significa estrictamente cero escrituras en el sistema de archivos. Cuando Ledger está habilitado, los cuatro comandos pueden añadir entradas al Ledger local, y verify también intenta escribir Verify History. Un fallo de escritura de auditoría no cambia los códigos de salida ni los criterios de gobernanza existentes.

Si se requiere una operación estricta de cero escrituras en archivos, usa una copia aislada; la CLI pública actual no expone un interruptor global que desactive todas las escrituras de Ledger y Verify History. Los comandos de System Cognition no crean un segundo estado formal, pero las llamadas ordinarias a la CLI siguen el contrato de ejecución de la versión actual para el Ledger y los registros de historial local.

Servidor MCP

aoci mcp no necesita ningún demonio residente y expone exactamente nueve herramientas por stdio:

En modo MCP, stdout está reservado para JSON-RPC; los logs y diagnósticos van a stderr. Las descripciones de herramientas, los esquemas JSON y los valores de estado de máquina que proporciona el binario en ejecución son la autoridad; este README es solo un punto de partida.

La versión actual proporciona las capacidades de System Cognition a través de la CLI existente y del kernel de gobernanza. No añaden una décima herramienta MCP ni cambian los nombres, propósitos o el contrato stdio de las nueve existentes.

Sesiones de larga duración y entrega de Whole-Index

Al inicio de una nueva conversación, un agente normalmente carga un Overview completo para obtener una imagen del sistema que coincida con el repositorio actual, la versión del índice y la identidad del servicio AOCI. Mientras el modelo pueda seguir confiando en esa imagen, no necesita recargarla antes de cada tarea o llamada a herramienta.

Dentro de la misma conversación, el modelo decide si volver a cargar según su propio estado, salvo tras una compactación conocida del contexto del anfitrión. Un traspaso compactado puede conservar solo la identidad del recibo, el estado de escritura o recuperación inacabado y una instrucción de recarga inmediata; no debe retener ni resumir los cuerpos de cabecera, entradas, chunks, desafíos o atestaciones de Whole-Index u Overview. El contenido del índice o un recibo copiado en ese traspaso no pueden demostrar que la imagen actual del modelo sea fiable.

Antes de continuar el trabajo de negocio tras una compactación conocida, el agente recarga las reglas si ya no están presentes de forma fiable, declara context_compaction con un ID de evento nuevo y completa una secuencia ordinaria de cursor, confirmación y atestación de Overview completo. check_only y la sonda de cognition no son sustitutos. Tras un transporte completo nuevo, la regla existente de atestación parcial o fallida sigue permitiendo la continuación vinculada a la fuente sin un segundo Overview automático. Para un cambio semántico o un límite de fase importante sin compactación conocida, AOCI proporciona umbrales de refresco, checkpoints y hechos de identidad, y el modelo decide si necesita restaurar su imagen a nivel de sistema para la tarea.

El cuerpo de cada Overview completo consta de un marcador de inicio, el contenido exacto del índice formal actual y un marcador de fin.

Cuando un Overview supera el presupuesto de chunks del proyecto:

1. la entrega comienza inmediatamente con el chunk 1;
2. el agente debe seguir next_cursor automáticamente hasta el chunk final;
3. el agente envía una atestación usando el Whole-Index entregado;
4. la búsqueda local, la memoria antigua, la lectura de fuentes complementarias o las lecturas directas de archivos no deben presentarse como entrega completa;
5. una recuperación pendiente o una instantánea inconsistente falla de forma cerrada sin mezclar contenido.

overview_delivery.chunk_tokens es el único ajuste de tamaño de entrega. Su valor por defecto es 7000, con un rango válido de 4000 a 24000. check_only=true es un checkpoint compacto sin cadena de chunks.

AOCI declara una asignación de tamaño de resultado por herramienta en aoci_overview. Un anfitrión que de otro modo persistiría un resultado de herramienta grande en disco, dejando solo una vista previa en el contexto del modelo (para la entrega del índice, un fallo silencioso), eleva ese umbral solo para esta herramienta. En Claude Code esto hace utilizable el 24000 completo, entregando un índice de 480 objetos en tres chunks en lugar de cinco. No se sondea nada: la declaración es estática, y un anfitrión que no la reconoce la ignora, como exige la especificación MCP.

El umbral de refresco es de 30 rutas semánticas distintas por defecto y también puede configurarse por proyecto. Para las reglas exactas de conteo, remítete a la documentación de Cognition Refresh y al contrato de ejecución.

Database Cognition

AOCI-CODE puede llevar la estructura de base de datos bajo el mismo índice y la misma gobernanza, con un límite de acceso explícito y estrecho:

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

• No se produce ningún acceso de red a la base de datos cuando no hay ninguna base de datos configurada o no se ejecuta ningún comando de base de datos explícito.
• Solo se leen metadatos de esquema de tablas base, no filas de negocio; las vistas, rutinas y comentarios quedan fuera del alcance de recolección actual.
• No se ejecuta ningún DDL ni DML.
• Los nombres de host, nombres de usuario, DSN y valores de credenciales nunca se escriben en los archivos del índice.
• La aplicación de Database Cognition se ejecuta sin conexión y no se reconecta a la base de datos mientras escribe.
• El programa conserva y compara evidencia estructural, pero el modelo sigue escribiendo las responsabilidades de las tablas, las relaciones y las restricciones de alto valor.

El soporte de MySQL cubre 5.7.6 y posteriores. El recolector lee la versión del servidor y ejecuta solo las consultas de catálogo que esa versión puede responder: restricciones CHECK desde 8.0.16, expresiones de índice desde 8.0.13, visibilidad de índice desde 8.0.0. Un servidor 5.7 registra una lista de checks vacía, porque 5.7 analiza la sintaxis CHECK y no almacena nada; la evidencia tiene la misma forma en todas las versiones soportadas. MariaDB no está soportado y se rechaza en lugar de leerse como MySQL.

El perfil inicial de openGauss está deliberadamente limitado a openGauss 6.0.5 LTS en modo de compatibilidad A/PG y a tablas base ordinarias no particionadas. Las características de catálogo no soportadas fallan de forma cerrada en lugar de reducirse silenciosamente a hechos de PostgreSQL; esto no declara soporte para MogDB, GaussDB, modo Dolphin/B/MySQL, particiones o subparticiones, column-store, MOT, tablas externas o temporales, vistas, rutinas o disparadores.

Aquí, la detección de fallo cerrado se aplica a los objetos visibles seleccionados similares a tablas con semántica no soportada. Las rutinas y los disparadores permanecen fuera del dominio de objetos de tabla de v1 y nunca se representan como hechos de tabla.

La ruta de openGauss usa el parche local revisado de AOCI sobre el código fuente oficial del Connector v1.0.8. Su analizador estricto acepta solo los parámetros de conexión revisados y no consume configuración ambiental de PG*, servicio, archivo de contraseñas, directorio home o logger. Una conexión TCP fuera de una dirección de loopback numérica debe usar explícitamente sslmode=verify-full (y una ruta absoluta de raíz de confianza en sslrootcert cuando se proporcione), con TLS 1.2 como mínimo; los modos de degradación de TLS se rechazan. sslmode=disable se acepta solo para un socket Unix explícito o una dirección de loopback numérica usada como límite local/de prueba. Los administradores de base de datos siguen siendo responsables de proporcionar ese DSN fuera de la conversación y de aprovisionar la cuenta de mínimo privilegio.

El Volume de base de datos está ausente por defecto. Entra en el Whole-Index solo después de que el proyecto habilite explícitamente Database Cognition y complete la gobernanza de evidencia, vinculación y ciclo de vida.

Incorporación al acceso a base de datos: no necesitas entender los detalles del DSN

Solo declaras una identidad no sensible para una fuente de base de datos. Si se omite --credential-env, AOCI deriva una referencia estable a variable de entorno a partir del ID de la fuente; por ejemplo, primary se asigna a AOCI_DB_PRIMARY_DSN:

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

Después usa la comprobación previa de acceso de solo lectura para ver si el entorno externo ha proporcionado esa referencia:

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

Este comando no se conecta a la base de datos, no devuelve un valor de credencial ni te pide pegar un DSN en una conversación. Un administrador de base de datos o de infraestructura proporciona la variable de entorno fuera del proceso de AOCI y concede acceso de solo lectura y de mínimo privilegio a los catálogos del sistema. La configuración de la fuente almacena solo el nombre de referencia de la credencial, no el secreto.

La versión candidata actual proporciona solo el proveedor de credenciales por entorno. Los gestores de secretos en la nube como Vault, Kubernetes Secret y AWS/GCP/Azure pueden integrarse a través del mismo límite de proveedor en versiones posteriores; hoy no están disponibles, y este README no implica lo contrario. Esta división mantiene los formatos de cuenta, la codificación DSN y la gestión del ciclo de vida de los secretos alejados de los usuarios comunes, a la vez que mantiene la autorización explícita: AOCI no descubre credenciales automáticamente, no escanea .env, no lee archivos de secretos ni omite el límite de autorización de un administrador de base de datos.

Fundamentos de la Cognición del Sistema

Sobre los índices de código y de base de datos, AOCI-CODE proporciona un conjunto de observaciones derivadas de la Cognición del Sistema. Responden a preguntas como "¿de dónde provino este objeto?", "¿qué objetos de código podría afectar un cambio en la base de datos?" y "¿qué cambió entre una observación histórica y ahora?". No crean una nueva capa de hechos 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

Límite de autoridad

Cada resultado de la Cognición del Sistema informa derived=true; la proyección de relaciones informa además authoritative=false. Los Cognition Volumes, las vinculaciones de evidencia de esquema, las huellas de Baseline y las identidades vinculadas a recibos siguen siendo las autoridades subyacentes. Las relaciones R no resueltas producen un resultado incompleto o diagnósticos; el programa no adivina ni las completa.

AOCI-CODE no es un sistema de grafos de conocimiento. La proyección estrecha de relaciones es una vista conveniente de relaciones, pero no posee un segundo sistema de gestión de estado, ni una ruta de escritura independiente, ni un nuevo almacén de hechos. La salida derivada se puede eliminar y recalcular a partir de los activos autoritativos actuales. Si una proyección entra en conflicto con los activos autoritativos, prevalecen los activos.

Modos de ejecución, privacidad y límites de datos

• AOCI-CODE es local-first por defecto, sin endpoint en la nube predeterminado, sin servicio alojado de carga de código fuente y sin servidor en segundo plano obligatorio.
• El manejo de datos en el modo nativo de agente depende del anfitrión que elija y de las políticas de su producto; AOCI-CODE no carga datos en nombre del anfitrión.
• El acceso de red a la base de datos debe activarse explícitamente y está restringido a metadatos de esquema de solo lectura.
• El libro mayor, los borradores, las transacciones y la evidencia de recuperación se almacenan bajo .aoci/ por defecto y normalmente son ignorados por Git; los archivos de índice y los activos de gobernanza del equipo pueden confirmarse en Git.
• Las proyecciones de la Cognición del Sistema se calculan localmente a partir de los activos autoritativos existentes y no requieren una base de datos de grafos, una base de datos vectorial ni un servicio de grafos remoto.

En qué se diferencia de un mapa de repositorio, RAG, LSP o un grafo de código

La búsqueda, los AST, LSP, los grafos de código y RAG son buenos para preguntas estructurales y de recuperación. AOCI-CODE hace un trabajo diferente: mantiene una descripción versionada del sistema que cubre el alcance gestionado y evoluciona incrementalmente con el software. Lo que obtienes:

• Un Whole-Index. Un mapa del sistema que cubre el alcance gestionado actual, no fragmentos ensamblados sobre la marcha para cada tarea.
• Entradas FRAS. Responsabilidades, relaciones fuertes, contratos públicos y restricciones de alto valor para cada objeto con el rol index.
• Persistencia entre sesiones. Los archivos de índice viven con el repositorio, por lo que las sesiones posteriores y otros agentes reutilizan la misma versión.
• Alcance Gestionado. Un registro explícito de qué objetos entran en el índice, cuáles solo se observan para detectar cambios y cuáles se dejan fuera deliberadamente.
• Detección de deriva. Distingue entre Missing, Orphan, Stale, Unbaselined, cambios de fin de línea, diferencias de curación y fuentes excluidas de la redacción (vacías, binarias, de tamaño excesivo).
• Actualizaciones gobernadas. Los candidatos entran en los archivos formales mediante vinculación de fuente, plan, validación, revisión, CAS, escrituras atómicas, Baseline y flujos de trabajo de recuperación.
• Atestación de entrega. Chunk, cursor, recibo y challenge demuestran que el Whole-Index se entregó en su totalidad.
• Cognición de Base de Datos. Entradas a nivel de tabla construidas y gobernadas a partir de evidencia de esquema de PostgreSQL/MySQL/openGauss aceptada explícitamente.
• Proyecciones del sistema. Observaciones de Linaje, Relaciones estrechas, Impacto de base de datos a código, Snapshot y Evolución derivadas del índice autoritativo y sus vinculaciones sin duplicar el estado autoritativo; el Impacto recorre únicamente relaciones R explícitas escritas por el modelo.

AOCI-CODE complementa las herramientas existentes en lugar de reemplazarlas.

La combinación recomendada: AOCI-CODE proporciona el prior semántico global; los grafos de código, LSP, la búsqueda y el código fuente proporcionan evidencia precisa; las pruebas y los resultados en tiempo de ejecución proporcionan la aceptación final. La proyección de Relaciones de AOCI no reemplaza un grafo de llamadas preciso: expone la contención estructural de Volume y las aristas de dependencia de Root, mientras que sus aristas semánticas se limitan a relaciones fuertes que el modelo escribió explícitamente.

Pila tecnológica

AOCI-CODE no requiere Neo4j, una base de datos vectorial, un demonio de larga duración ni un servicio en la nube de AOCI. Cuando la Cognición de Base de Datos está habilitada, la base de datos objetivo es solo una fuente explícita y de solo lectura de evidencia de esquema, no el propio almacén de estado de AOCI.

Preguntas frecuentes

¿Por qué el status --deep Legacy sigue mostrando deriva?

status --deep, index score y index agent plan son exclusivos de Legacy. Para un repositorio de Cognition Volumes, ejecuta la guía en vivo y deja que el anfitrión use el aoci_maintain ordinario sin argumentos, envíe el lote actual completo a través de aoci_update_entry y cierre con Verify, Check y la guía. No modifiques el Baseline directamente ni omitas los pasos de vinculación de fuente y recuperación.

El propio diseño Legacy está obsoleto. Volumes v1 es la ruta compatible para repositorios nuevos y migrados, y los comandos exclusivos de Legacy están programados para su eliminación en la v0.2.0; migra un repositorio Legacy con aoci cognition migration antes de esa fecha.

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

¿Por qué el anfitrión inició el AOCI equivocado?

Inspecciona la ruta del ejecutable en la configuración MCP a nivel de proyecto y asegúrate de que sea una ruta absoluta estable, luego ejecuta:

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

Para verificar el servidor stdio cargado en lugar de solo el archivo en disco, inspecciona también el ejecutable real del proceso del anfitrión, su --repo de línea de comandos y la identidad del proceso tras un reinicio.

¿Tengo que crear una cuenta de base de datos y proporcionar un DSN yo mismo?

No necesitas entender la sintaxis de DSN, y no deberías enviar secretos en el chat. Después de que declares una identidad de fuente no sensible, AOCI proporciona una referencia estable a una variable de entorno. Un administrador de base de datos todavía tiene que crear una cuenta externa con privilegios mínimos y acceso de solo lectura al catálogo del sistema, y proporcionar esa referencia al entorno de ejecución. La versión actual no crea una cuenta de base de datos en nombre de una organización ni lee un almacén de secretos automáticamente.

¿Puede ejecutarse en CI?

Sí. El escaneo, la verificación, las puertas de gobernanza y las comprobaciones deterministas se ejecutan sin escribir nuevas entradas. Para los comandos exactos, las escrituras de auditoría y los códigos de salida, remítete al --help del binario actual, a los esquemas JSON y a la documentación de CI del proyecto.

¿Un resultado de AOCI todo en verde demuestra que la semántica es correcta?

No. Un resultado en verde demuestra que se cumplen las condiciones estructurales y de gobernanza codificadas. Lo que el modelo escribió todavía debe verificarse contra el código fuente, el esquema, las pruebas, los resultados en tiempo de ejecución y la revisión humana.

¿El grafo de la Cognición del Sistema es una nueva fuente de verdad?

No. La capacidad actual es una proyección estrecha de relaciones, no una plataforma de grafos independiente. Calcula resultados solo a partir del índice formal, la evidencia, los recibos y el Baseline, y no persiste nuevos hechos autoritativos. El programa tampoco genera relaciones semánticas automáticamente a partir de importaciones, SQL, nombres de archivo o similitud.

Documentación

Los enlaces a la documentación y a los contratos públicos están fijados a v0.1.0-rc22 para que sigan siendo válidos cuando este README se lea desde un archivo Release binario, que no incluye los directorios docs/ ni spec/public/ del repositorio.

Suites de verificación de caja negra

El repositorio incluye cuatro suites de caja negra independientes en scripts/blackbox/ que ejercitan un binario aoci compilado estrictamente desde fuera del proceso, únicamente a través del protocolo MCP público sobre stdio y de la CLI:

• Conformidad del protocolo — 53 comprobaciones de solo lectura de la superficie del protocolo MCP, con las frases dependientes de la configuración regional repetidas bajo zh-CN;
• Escenarios de inyección de fallos — 75 escenarios que cubren la manipulación de cursores, la recuperación tras fallos, escritores en competencia y el hook previo a la escritura sobre repositorios de prueba desechables;
• Ciclo de vida sobre proyectos reales congelados — tres proyectos de prueba confirmados: repo-a (TypeScript) y repo-b (Python + MySQL) ejecutan el ciclo de vida completo desde init hasta la realineación, y repo-c (un servicio en capas de 453 archivos) además impulsa la autoría en múltiples lotes en el límite de lotes de la máquina. Una pista de modelo opcional somete a un agente de IA real —cualquier modelo que exponga tu instalación de OpenCode— a los dos repositorios pequeños y puntúa el estado final desde las superficies públicas.
• Eje de actualización — 80 comprobaciones por versión publicada, sobre diez formas de repositorio: cada versión publicada compila y genera la autoría de un repositorio con su propio binario, y luego el binario bajo prueba debe gobernarlo sin mover una identidad, exigir un cambio de ámbito ni reescribir un activo formal, y lo que después genere debe mantener alineado un checkout en otra ruta; en la décima forma los roles se invierten, y cada versión publicada debe leer un repositorio que el binario bajo prueba escribió sin fallar ni reescribirlo. Las otras tres suites generan cada fixture con el binario bajo prueba, por lo que una preimagen que cambió entre versiones es invisible para ellas por construcción.

Solo necesitan Python 3 y git además de un binario compilado (Docker para la suite de MySQL; OpenCode más tu propia suscripción de modelo para la pista de modelo), de modo que un clon del repositorio puede verificar su propia compilación, un port de plataforma o un fork — y AOCI_BIN puede apuntar las suites de conformidad y de escenarios a cualquier binario alternativo que reclame los contratos públicos en spec/public/. Estas suites viven en el clon del repositorio; los archivos Release binarios no las incluyen. Consulta scripts/blackbox/README.md para los comandos y la interpretación de resultados.

Investigación, propiedad intelectual y licencia

Los artículos y artefactos de investigación de AOCI-CODE pueden describir públicamente métodos publicados, protocolos experimentales y resultados. Las solicitudes de patente, el alcance concedido, la situación legal, los titulares y el efecto territorial son hechos legales, y no deben añadirse a las descripciones de producto basándose en un README interno, un número de versión histórico o un relato no verificado.

Si en el futuro debe divulgarse un número de patente, una fecha de concesión o un alcance específicos, el titular de los derechos y el asesor legal deben verificarlo contra los registros públicos oficiales y colocarlo en un documento dedicado de PI, NOTICE o legal. Este README solo debe enlazar a ese archivo autoritativo; no debe ampliar por sí mismo la cobertura de patentes ni presentar el estado de las patentes como una licencia de software.

Comunidad

Escanea el código con WeChat o WeCom (企业微信) para unirte al grupo del proyecto AOCI y hablar con los mantenedores y otros usuarios. Presenta informes de errores y solicitudes de funciones como GitHub issues para que sigan siendo buscables, y reporta las vulnerabilidades sospechadas de forma privada como se describe en SECURITY.md, nunca en el grupo.

AOCI-CODE no se trata de hacer que un agente vea más código. Le da al agente una comprensión actual, estructurada, trazable y gobernada del sistema antes de cada acción. Git versiona tu código, las migraciones de base de datos versionan tus estructuras de datos, y AOCI-CODE versiona lo que los agentes saben sobre el sistema, junto con la trazabilidad, la consistencia de la gobernanza y los límites de recuperación de cómo evoluciona ese conocimiento.