AOCI-CODE

AOCI-CODE

Peta persisten seluruh basis kode Anda yang berversi Git — ditulis oleh agen coding Anda, dikelola oleh server MCP lokal. Agen membacanya sekali dan langsung mengenal sistem, alih-alih membaca ulang repo pada setiap tugas.

🇺🇸 English | 🇨🇳 简体中文

Apa fungsinya

Bangun sistem besar tanpa kehilangan arah. Di Codex, Claude Code, Cursor, OpenCode, dan agen serupa, agen Anda memulai setiap tugas dengan sudah mengenal seluruh sistem: untuk apa setiap file, apa dependensinya, dan apa yang tidak boleh rusak. Agen berhenti mencari dan membaca ulang basis kode pada setiap permintaan. Orang yang bukan pengembang profesional dapat terus mengembangkan sistem mereka sendiri; pengembang profesional dapat menyerahkan seluruh sistem kepada agen dan memusatkan perhatian pada arsitektur dan desain.

Ambil alih sistem yang sudah ada dalam satu langkah. Arahkan agen ke basis kode yang sudah ada hingga sekitar 500.000 baris dan minta agen membangun indeks. Agen melaporkan seberapa baik ia mengenal setiap area, lalu melanjutkan pengembangan dari sana. Batas praktisnya adalah ukuran indeks, bukan jumlah baris: sistem komersial 700.000 baris dikembangkan dengan cara ini saat ini, dengan indeks sekitar 300K token.

Ganti orang, agen, atau percakapan tanpa memulai dari awal. Indeks tersimpan di repositori bersama kode dan berversi melalui Git. Ketika sebuah proyek berpindah tangan, berganti agen, atau membuka percakapan baru, satu kali pembacaan indeks melanjutkan dari titik terakhir.

Setelah indeks pertama, pemeliharaan berjalan otomatis. Server MCP mendeteksi perubahan kode dan menerbitkan entri yang perlu diperbarui. Agen mengisinya saat menyelesaikan setiap tugas, sehingga indeks sesuai dengan kode terkini dan Anda tidak perlu berhenti untuk memeliharanya.

Bentuknya

Satu baris per file, ditulis oleh model berdasarkan sumber yang sebenarnya. Ini adalah entri nyata dari indeks repositori ini sendiri:

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 adalah tanggung jawab file, R adalah yang harus Anda baca bersamanya, A adalah yang diandalkan pemanggil, dan S adalah yang tidak dapat disimpulkan dari kode tetapi tidak boleh salah. Tag [CG9L] menempatkan file berdasarkan lapisan, domain, kepentingan, dan ukuran. Beberapa ratus baris seperti ini mencakup seluruh sistem, dan agen dapat membacanya dalam satu kali lintas. Format entri menjelaskan setiap bidang.

Apa bedanya dengan CodeGraph?

• CodeGraph mengurai kode Anda menjadi graf simbol dan pemanggilan. Ketika agen mengajukan pertanyaan, ia mengembalikan sumber dan jalur pemanggilan yang tepat. Ini adalah alat pencarian presisi untuk tugas yang sedang dihadapi.
• AOCI-CODE meminta model menulis satu baris per file dan tabel: untuk apa, terhubung ke apa, dan apa yang tidak boleh rusak. Agen membaca seluruh indeks terlebih dahulu, sehingga mengenal sistem sebelum tugas dimulai. Indeks tersimpan di Git dan dijaga selaras dengan kode.
• Gunakan keduanya: indeks untuk mengenal sistem, CodeGraph untuk mengambil kode yang tepat saat bekerja.

Perbandingan lengkap juga mencakup RAG, LSP, dan repo map.

Yang perlu diharapkan

Indeks pertama membutuhkan waktu. Agen membaca setiap file terkelola dan menulis satu entri per file: sekitar satu jam per 200.000 baris kode, tergantung model dan kecepatan agen. Proses berjalan dalam batch dan melanjutkan dari titik berhenti jika terputus.

Punya basis data? Indeks juga. MySQL dan PostgreSQL didukung, serta openGauss 6.0.5 dengan batasan. MySQL berarti 5.7.6 dan yang lebih baru; MariaDB tidak didukung. Bangun indeks kode terlebih dahulu, lalu indeks basis data. Dengan pengetahuan tingkat kode dan tabel yang disampaikan bersamaan, agen memahami sistem secara lebih menyeluruh.

Hanya lokal: hanya-baca pada sistem Anda, tanpa Internet, tanpa kredensial tersimpan. AOCI-CODE membaca kode sumber dan struktur tabel basis data Anda, tidak pernah data bisnis. Ia menulis file indeks dan statusnya sendiri di dalam direktori proyek, ditambah pendaftaran halaman status di direktori cache pengguna Anda. Ia tidak pernah mengakses Internet dan tidak mengunggah apa pun: satu-satunya koneksi yang dibukanya adalah ke basis data yang Anda deklarasikan, untuk metadata katalog, dan ke halaman status loopback-nya sendiri. Kredensial basis data dirujuk berdasarkan nama variabel lingkungan dan tidak pernah disimpan. Teks indeks ditulis secara lokal oleh agen Anda sendiri melalui kanal model yang sudah Anda gunakan; AOCI-CODE tidak menambah jalur keluar data baru.

Mulai cepat

Berikan instruksi berikut kepada agen Anda untuk mengunduh AOCI-CODE dan menyiapkannya. Setelah Anda memulai ulang agen, kirim instruksi kedua untuk membangun indeks.

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.

Setelah memulai ulang agen, kirim yang ini:

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.

Agen menjalankan panel di latar belakang dengan aoci ui --detach --json dan memberikan tautannya kepada Anda. Panel AOCI menjelaskan apa yang ditampilkannya dan perintah lainnya.

Mengapa perlu memulai ulang: indeks ditulis melalui alat MCP AOCI, dan sesi yang menjalankan init belum memuat server MCP yang baru saja ditulis oleh init. Host yang memuat server MCP secara dinamis mungkin tidak perlu memulai ulang; Integrasi host menjelaskan cara mengetahuinya.

Jika proyek Anda memiliki basis data (PostgreSQL dan MySQL didukung, plus openGauss 6.0.5 dengan batasan), indeks juga. Deklarasikan sumber seperti dijelaskan pada Kognisi Basis Data, sediakan variabel lingkungan connection-string di lingkungan host (AOCI tidak menyimpan kredensial), lalu kirim:

Build the AOCI database index for this project.

Jika konteks telah dipadatkan, atau Anda ingin agen membangun ulang gambaran sistemnya, kirim ini:

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.

Cara kerjanya

AOCI (AI-Oriented Cognition Infrastructure) adalah metode dan protokolnya: lapisan antara agen coding dan sistem perangkat lunak. Model bernalar, agen merencanakan dan mengeksekusi, dan AOCI menjaga deskripsi sistem yang selalu mutakhir, mencakup kode, konfigurasi, pengujian, dan struktur basis data, untuk dibaca agen sebelum bertindak. AOCI-CODE adalah proyek ini: CLI aoci, server MCP, dan indeks yang dipeliharanya.

AOCI-CODE menyaring apa yang benar-benar penting untuk memahami dan mengubah sistem menjadi indeks teks polos yang padat yang menggabungkan simbol dan makna. Ketika konteks model terbatas, agen membaca indeks terlebih dahulu, memperoleh sebagian besar informasi kunci proyek dalam satu kali lintas, lalu memulai tugas. Ini memangkas pencarian dan pembelajaran ulang yang berulang, dan membawa pemahaman lintas tugas dan sesi.

• Bukan ringkasan sekali jadi. Indeks berkembang bersama sistem dan tetap berada di proyek, tempat Anda dapat melakukan diff, review, versi, dan rollback dengan Git.
• Lebih dari sekadar "di mana file berada." Ia mencatat tanggung jawab, hubungan kuat, kontrak publik, batas transaksi, batasan kompatibilitas, dan hal-hal lain yang sulit disimpulkan dari struktur kode.
• Portabel. Indeks disimpan bersama proyek, tidak terikat pada model, agen, atau sesi. Selama selaras dengan kode, agen mana pun dan sesi mana pun di kemudian hari dapat menggunakannya kembali tanpa membangun ulang pemahamannya dari awal.
• Kode dan basis data bersamaan. Model dapat membangun indeks terpisah tingkat tabel untuk tabel basis data. Disampaikan bersamaan, keduanya memberi agen gambaran sistem yang lebih lengkap.

Indeks adalah sekumpulan file teks polos terkelola yang disimpan bersama proyek:

• Root (aoci.txt) mendeklarasikan apa yang membentuk indeks saat ini dan merupakan titik masuk aktivasi.
• Meta (aoci.meta.txt) menyimpan kamus tag, aturan FRAS, dan batasan penulisan.
• Code (aoci.code.txt) menyimpan entri yang ditulis model untuk kode dan aset repositori lainnya.
• Database (aoci.database.txt) menyimpan entri opsional tingkat tabel ketika Kognisi Basis Data diaktifkan.

Root, Meta, dan Volume objek yang berpartisipasi bersama-sama membentuk Whole-Index. Alur kerja di atasnya memiliki tiga tahap:

1. Bangun indeks di bawah tata kelola. Model membaca kode sumber dan bukti yang diterima. AOCI-CODE mengelola Managed Scope dan entri yang ditulis model untuk setiap objek terkelola dengan peran index.
2. Baca sebelum bertindak. Agen membaca aturan proyek, panduan langsung, dan Whole-Index saat ini, lalu memeriksa sumber dan bukti lain untuk tugas yang dihadapi.
3. Pelihara setelah perubahan terverifikasi. Setelah kode dan pengujian stabil, aturan proyek dan alur kerja MCP meminta agen memperbarui entri yang terdampak dan mengembalikan indeks ke aligned.

Karena file-file ini adalah teks polos di repositori, Git memversinya. Selama indeks tetap selaras dengan versi sistem saat ini, agen mana pun dan sesi mana pun di kemudian hari dapat membaca dan menggunakan kembali Whole-Index yang sama.

Integrasi manual

Dapatkan AOCI-CODE dari sumber kanonis atau gunakan paket bertanda tangan dari GitHub Releases. Sebelum menggunakan biner siap pakai, ikuti tingkat verifikasi dasar, yang direkomendasikan, atau lengkap dalam panduan instalasi, dan laporkan tingkat mana yang selesai. Berikan README ini dan jalur absolut stabil biner yang telah diverifikasi kepada agen coding yang Anda percaya, seperti Codex, Claude Code, Cursor, atau OpenCode. Agen dapat mengikuti instruksi dalam proyek untuk menginisialisasi AOCI, mengintegrasikan MCP, dan membangun indeks pertama.

Berapa lama indeks pertama bergantung pada ukuran repositori. Integrasi normal terdiri dari empat langkah: siapkan biner, minta agen atau diri Anda sendiri menginisialisasi repositori target, minta host untuk "membangun indeks," dan verifikasi keselarasan. Setelah itu Anda tidak perlu mengakhiri setiap permintaan dengan "pelihara indeks." Aturan proyek dan alur kerja MCP meminta agen memelihara indeks secara inkremental setiap kali objek terkelola berubah.

Persyaratan

• Paket rilis yang telah diverifikasi atau checkout dari repositori sumber kanonis AOCI-CODE.
• Hanya untuk build dari sumber: toolchain Go yang dideklarasikan oleh go.mod, make, dan alat lain yang dibutuhkan repositori.
• Host MCP yang didukung, seperti Codex, Claude Code, Cursor, atau OpenCode.
• Akses baca dan tulis normal ke repositori target.

AOCI-CODE terintegrasi dengan host MCP, bukan dengan API penyedia model. DeepSeek dan model lain dapat menggunakan AOCI-CODE ketika agen atau host yang menjalankannya mendukung MCP stdio standar dan dapat mengikuti kontrak alat; nama model saja tidak menetapkan kompatibilitas.

Rute paket bertanda tangan dan perintah verifikasi eksekutabel ada di panduan instalasi. Rute build dari sumber ada di bawah.

RC saat ini: gunakan paket terverifikasi atau build dari sumber

[!IMPORTANT] AOCI-CODE v0.1.0-rc22 adalah kandidat rilis saat ini. Ini adalah perangkat lunak Fair Source/source-available di bawah FSL-1.1-MIT; lihat LICENSE. Build dari sumber kanonis atau gunakan paket bertanda tangan dari Rilis GitHub v0.1.0-rc22 setelah mengikuti prosedur verifikasi rilis.

Biner Rilis bertanda tangan mengidentifikasi dirinya sebagai aoci version 0.1.0-rc22. Build dari sumber mengidentifikasi checkout yang tepat dan dapat melaporkan versi pengembangan seperti v0.1.0-rc22-1-g<short-commit> (ditambah -dirty bila berlaku), bersama commit Git-nya. Ini adalah input build yang berbeda, bukan konflik versi.

Untuk mengunduh dengan GitHub CLI, autentikasi terlebih dahulu, lalu unduh aset Rilis bertag:

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

Untuk unduhan anonim, buka halaman Rilis v0.1.0-rc22 di peramban dan unduh arsip serta aset verifikasi yang Anda butuhkan.

Untuk build dari sumber, klon repositori kanonis, build biner, dan pertahankan jalur yang dihasilkan agar stabil:

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

Di Windows, build sumber yang sama di 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

Lalu berikan README ini kepada agen yang sudah Anda percayai dengan proyek tersebut dan minta:

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.

Agen harus mengidentifikasi akar proyek, menggunakan jalur absolut yang stabil ke biner yang telah dibangun, menjalankan inisialisasi yang sesuai dengan host saat ini, dan memberi tahu Anda dengan jelas kapan diperlukan restart host atau persetujuan manusia yang sebenarnya. Biner dapat tetap berada di checkout AOCI-CODE atau dipindahkan ke direktori alat bersama, selama konfigurasi MCP menunjuk ke jalur absolut yang benar.

Inisialisasi manual

Untuk menginisialisasi AOCI sendiri, jalankan perintah berikut dari akar repositori target, atau berikan jalur eksplisit melalui --repo:

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

init menulis konfigurasi locale, blok aturan AGENTS.md yang dikelola, batas Git, dan kerangka indeks kosong. Konfigurasi dan prompting berbeda-beda per host; lihat Integrasi host. Perintah ini tidak mengarang makna bisnis dari nama file, direktori, atau AST.

Untuk repositori baru, scan pertama menetapkan Baseline yang dikelola. Untuk proyek yang sudah memiliki Baseline yang diatur, menambah, menghapus, atau mengubah cakupan yang dikelola harus melalui alur kerja Perubahan Cakupan formal; scan --force bukan jalan pintas untuk mendefinisikan ulang fakta tata kelola. --force juga tidak dapat menghapus drift, receipt, atau batas pemulihan yang belum terselesaikan.

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

Minta agen membangun indeks pertama (penting)

Setelah inisialisasi dan scan selesai, periksa apakah sesi agen sudah mengekspos alat AOCI; segarkan atau mulai ulang jika belum. Lalu masukkan perintah berikut di agen untuk proyek target:

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.

Agen memulai panel di latar belakang dengan aoci ui --detach --json dan memberikan tautannya kepada Anda. Panel AOCI mencakup apa yang ditampilkannya dan perintah lainnya.

Host membaca aturan AOCI proyek dan panduan langsung, memeriksa kode sumber, pengujian, konfigurasi, dan bukti yang relevan, lalu menulis kandidat FRAS untuk setiap objek yang dikelola yang perannya adalah index. Anda tidak perlu mengatur sendiri Plan, Stage, Check, Diff, CAS, atau Apply.

Setelah indeks pertama selesai, kirim permintaan pengembangan biasa seperti biasa, misalnya:

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

Anda tidak perlu menambahkan "pertahankan indeks AOCI di akhir." Aturan proyek dan MCP membuat agen memeriksa perubahan indeks setelah kode dan pengujian stabil, lalu memperbarui entri yang terdampak melalui alur kerja formal. Ketika proyek menggunakan automation.mode=auto, AOCI-CODE hanya menginterupsi Anda ketika diperlukan persetujuan manusia yang sebenarnya, tindakan eksternal harus dilakukan, pemulihan tidak dapat dibuktikan, pemeriksaan keselamatan gagal, atau ditemukan konflik konkurensi pihak ketiga. Mode otomasi lain mengikuti kontrak runtime masing-masing.

Verifikasi keselarasan

Setelah onboarding selesai, jalankan:

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

Indeks dan sumber daya terkelola saat ini harus kembali konvergen ke aligned. Jika tidak, konsultasikan panduan langsung terlebih dahulu; jangan menduplikasi mesin status internal dalam skrip pembungkus:

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

Jalankan diagnostik dasar

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

Untuk memastikan AOCI mana yang sebenarnya terhubung dengan host, baca apa yang dilaporkan server tentang dirinya sendiri, bukan apa yang ada di disk. Dalam respons aoci_overview check_only apa pun atau respons aoci_maintain apa pun, cognition_receipt.mcp_service_version adalah versi yang berjalan dan runtime_repository_root adalah repositori yang diaturnya. Jalur biner yang cocok adalah command dalam .mcp.json proyek atau konfigurasi host yang setara: .codex/config.toml, opencode.json, atau .cursor/mcp.json. Mengganti byte di disk tidak mengubah proses MCP yang sedang berjalan, jadi periksa ulang terhadap fakta-fakta tersebut setelah peningkatan atau rollback.

Untuk panduan sekali jalan, gunakan examples/minimal-repository di repositori.

make fast

make full
./build/aoci --version

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

Apa yang muncul setelah inisialisasi

Repositori tipikal berisi file indeks berikut:

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

Menginisialisasi proyek baru membuat Root, Meta, dan Code Volume kosong; Database tidak ada secara default. AOCI-CODE tidak menghasilkan makna bisnis untuk repositori atau database dengan sendirinya.

aoci init --agent <name> juga menulis konfigurasi integrasi host (.mcp.json, .claude/settings.json, .codex/config.toml, atau opencode.json) yang jalur perintah dan repositorinya adalah jalur absolut yang terikat mesin. Tambahkan file-file tersebut ke .gitignore repositori dan jangan commit: salinan yang di-commit akan rusak di setiap mesin lain, dan karena installer mendeteksi entri yang ada berdasarkan keberadaan kunci, menjalankan ulang init di sana secara diam-diam akan mempertahankan jalur yang rusak.

Bagaimana tugas pengembangan berjalan

Dua diagram di bawah ini menunjukkan alur kerja sebagaimana yang Anda alami, bukan implementasi internal AOCI.

Proyek baru: bangun sistem sederhana terlebih dahulu, lalu bawa 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

Sistem baru tidak memerlukan AOCI-CODE sejak baris kode pertama. Bangun prototipe dengan kemampuan agen yang sudah ada terlebih dahulu; sekitar 10.000–30.000 baris adalah titik yang baik untuk membawanya masuk (bukan ambang batas keras). Tim yang menginginkan kesinambungan lintas sesi lebih awal dapat mengintegrasikannya lebih cepat.

Proyek yang sudah ada: indeks repositori, lalu iterasi

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

Setelah indeks pertama selesai, kedua alur bekerja dengan cara yang sama dari hari ke hari: Anda menjelaskan kebutuhan bisnis atau rekayasa; agen menggabungkan Whole-Index dengan bukti terkini, melakukan pengembangan dan verifikasi, dan memperbarui objek yang berubah melalui MCP saat menutup tugas. Anda tidak perlu mempelajari perintah internal Plan, Stage, Diff, CAS, atau Baseline, atau mengulangi persyaratan pemeliharaan di setiap prompt.

Jika batch lengkap ditolak sebelum penulisan formal apa pun dimulai, indeks tidak berubah. Jika alur kerja terputus setelah penulisan formal dimulai, sistem mempertahankan niat yang tidak dapat diubah, bukti penulisan, dan status pemulihan, lalu melanjutkan dari postimage yang dapat dibuktikan atau melakukan rollback ke preimage yang tepat. Konflik byte pihak ketiga gagal secara tertutup; AOCI-CODE tidak pernah menimpa modifikasi eksternal untuk "menyelesaikan penulisan."

Status akhir selalu salah satu dari applied, repair_required, atau stopped. stopped bukan keberhasilan, dan tidak selalu berarti tidak ada yang ditulis; periksa failed_step, bukti penulisan formal, dan tindakan pemulihan yang dikembalikan panduan.

Siapa melakukan apa: model dan AOCI-CODE

Model memiliki makna

Model host membaca kode sumber, pengujian, konfigurasi, dokumentasi, dan bukti apa pun yang diperlukan, lalu memutuskan:

• apa yang sebenarnya menjadi tanggung jawab suatu objek;
• file, modul, atau objek database mana yang merupakan hubungan kuat yang harus dipertimbangkan untuk mengubahnya dengan aman;
• API, perintah, format, atau kontrak yang dapat diamati apa yang dieksposnya;
• batasan transaksi, otorisasi, konkurensi, caching, deployment, kompatibilitas, atau historis mana yang tidak dapat disimpulkan hanya dari struktur biasa.

AOCI-CODE tidak menyusun FRAS dari nama file, jalur, ekstensi, AST, atau templat, dan tidak secara diam-diam menulis ulang apa yang ditulis model.

AOCI-CODE memiliki tata kelola

AOCI-CODE bertanggung jawab untuk:

1. menetapkan Safe Inventory, Managed Scope, dan Baseline saat ini;
2. mengirimkan Whole-Index saat ini dan mengonfirmasi identitasnya;
3. menghasilkan rencana deterministik, kumpulan target, dan nilai SHA-256 sumber;
4. memvalidasi struktur kandidat, kamus tag, identitas hubungan, cakupan, kepemilikan, anggaran, dan rentang yang terdampak;
5. mempertahankan keterikatan antara konten pemeriksaan, diff, dan tinjauan;
6. melakukan commit batch lengkap dengan kunci lintas proses, CAS, dan penulisan atomik;
7. memajukan Baseline, menambahkan ledger, dan mempertahankan bukti pemulihan setelah kegagalan pasca-penulisan;
8. membuktikan status tata kelola saat ini lagi melalui Verify, Check, dan panduan;
9. menurunkan observasi Lineage, Relations, Impact, Snapshot, dan Evolution dari aset otoritatif tanpa membuat sumber kebenaran kedua.

Hasil mesin yang semuanya hijau hanya berarti bahwa kontrak struktural dan tata kelola yang dikodekan terpenuhi; itu tidak berarti bahwa setiap pernyataan yang ditulis model benar.

Bagaimana indeks diorganisasi

Indeks AOCI memiliki dua lapisan: aturan indeks dan entri indeks. Produk mendukung dua tata letak fisik, dan keduanya bukan satu format file.

Tata letak Volumes v1

Proyek Volumes memisahkan tanggung jawab:

• aoci.txt hanyalah Root. Ini mendeklarasikan Volumes yang berpartisipasi dalam CognitionSet saat ini.
• aoci.meta.txt menyimpan Meta: kamus tag, aturan FRAS, anggaran, dan kontrak penulisan.
• aoci.code.txt menyimpan entri untuk objek kode.
• aoci.database.txt menyimpan entri untuk objek database ketika Database Cognition diaktifkan.

Code dan Database Volume berbagi struktur baris FRAS yang sama, tetapi memiliki identitas objek, keterikatan bukti, kepemilikan, dan siklus hidup yang independen. Root, Meta, dan Volume objek bersama-sama membentuk Whole-Index; membaca hanya Root aoci.txt tidak cukup untuk mengklaim Anda telah membaca seluruh sistem.

Anggap saja sebagai peta:

• Aturan indeks adalah legenda dan sistem koordinat peta.
• Entri indeks adalah penanda yang mendeskripsikan setiap lokasi.
• Root adalah titik masuk katalog dan versi untuk kumpulan peta saat ini.
• Volume adalah lembar terpisah yang diatur oleh protokol yang sama tetapi dengan sumber bukti dan siklus hidupnya sendiri.

Bagaimana tampilan header indeks

Root dan Meta masing-masing dibuka dengan baris header yang dibaca mesin. Inilah yang ditulis aoci init untuk proyek en-US baru bernama my-service, dimulai dengan Root, yang merupakan titik masuk aktivasi:

#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

Setiap baris #Volume: mendeklarasikan satu Volume yang berpartisipasi dengan identitas, jenis, jalur, format, dependensi, dan status aktivasinya. Volume yang tidak dideklarasikan di sini bukan bagian dari CognitionSet saat ini, apa pun yang ada di working tree. Mengaktifkan Database Cognition menambahkan satu baris lagi, #Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled.

Meta kemudian dibuka dengan aturan yang mengatur setiap entri:

#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 adalah baris yang menanggung beban: batas bidang milik biner, bukan milik teks ini, sehingga proyek tidak dapat memperluasnya dengan mengedit Meta-nya sendiri. #S-Admission dan #S quota mengatur bidang S secara khusus: apa yang boleh dicatat di sana sama sekali, dan berapa banyak karakter yang boleh digunakan setiap pita kepentingan. Kamus tag menyusul tepat setelah baris-baris ini; ditampilkan secara lengkap lebih jauh di bawah.

Code Volume dibuka dengan satu baris, #AOCI-CODE-VOLUME: 1, dan semua yang setelahnya adalah bagian direktori dan entri.

Ini adalah nilai yang menjadi titik awal proyek baru, bukan konstanta protokol yang tetap. Root dan Meta masing-masing repositori menjadi otoritatif setelahnya: proyek yang lebih lama mungkin membawa kamus tag kustom, dan proyek yang diinisialisasi dengan --locale zh-CN menulis #Locale: zh-CN dan melokalkan kunci #S quota: sesuai dengan itu.

Apa yang didefinisikan aturan indeks

Dalam Volume v1, Meta Volume proyek menyimpan aturan-aturan ini; dalam tata letak Legacy, aturan-aturan ini berada di header monolitik. Proyek dapat menggunakan kamus tag yang berbeda, sementara struktur FRAS dasar tetap sama.

README ini hanya menjelaskan cara membaca aturan-aturan ini. Untuk aturan konkret yang dapat dieksekusi, rujuk ke header Meta atau Legacy proyek saat ini, panduan AOCI, dan spesifikasi formal.

Apa yang dicatat satu entri (FRAS)

Setelah aturan ditetapkan, model menulis satu entri untuk setiap objek terkelola dengan peran index. Peran observe hanya berpartisipasi dalam observasi perubahan, dan peran exclude menandai apa yang sengaja dikecualikan; keduanya tidak memiliki entri formal. AOCI menggunakan FRAS untuk mengorganisasi empat jenis informasi yang paling penting dalam sebuah entri:

• F — Function: apa yang menjadi tanggung jawab objek.
• R — Relations: objek lain mana yang juga harus dipertimbangkan untuk memahami atau mengubahnya dengan aman.
• A — API: antarmuka, perintah, format, atau kontrak yang dapat diamati yang dieksposnya.
• S — Non-obvious constraints: informasi penting yang tidak dicakup F, R, dan A tetapi diperlukan untuk memahami atau mengubah objek dengan aman, seperti batasan kunci, pengecualian, batas, dan semantik khusus. S tidak boleh mengulang tiga bidang pertama.

Sebagai contoh, di dalam bagian direktori ===.../internal/fs/===, sebuah entri menggunakan 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 

Bagian direktori dan basename merujuk ke identitas objek kode. Untuk proyeksi lintas-Volume atau sistem, ini diperluas menjadi identitas kanonis seperti code:internal/fs/atomic.go. Objek basis data menggunakan identitas kanonisnya sendiri, seperti database://primary/public/orders.

Entri memiliki dua bagian:

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

Tag ringkas memberi setiap objek koordinat untuk lapisan arsitektural, domain fungsional, kepentingan, karakteristik teknis opsional, dan ukuran. Kamus tag didefinisikan oleh Meta Volume atau header Legacy proyek. Program memvalidasi kamus dan struktur; program tidak memutuskan makna bisnis.

S bukan sinopsis, ringkasan biasa, atau pengulangan F, R, dan A. S menambahkan informasi penting yang tidak dicakup tiga bidang pertama dan yang memengaruhi pemahaman atau kebenaran rekayasa, misalnya:

• kegagalan akses Redis harus fallback ke basis data;
• tabel tertentu tidak boleh masuk ke AutoMigrate;
• cabang kompatibilitas legacy tidak boleh dihapus oleh pembersihan biasa;
• file asli harus dipertahankan setelah kegagalan penulisan.

Model menulis ini dari kode sumber aktual dan bukti. AOCI-CODE memvalidasi struktur entri, mengikatnya ke file sumber, dan mengatur bagaimana entri masuk ke indeks formal.

Membaca kamus tag pemula

Kutipan berikut disalin verbatim dari templat Meta Volume en-US saat ini (textassets/en-US/templates/volume-meta.txt.tmpl). Ini adalah kamus pemula, bukan kosakata universal: Meta formal setiap repositori tetap menjadi acuan. Pemula tidak mendeklarasikan kamus D; D tetap menjadi sumbu opsional dan hanya boleh digunakan ketika Meta formal saat ini mendeklarasikannya.

#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

Di bawah kamus kode pemula, [CG9L] berarti C SharedFoundation, G CrossDomain, 9 kepentingan tertinggi, dan L skala besar; tidak ada nilai D. Ini menjelaskan cara membaca entri yang ada, bukan bagaimana model harus menetapkan tag. Model tetap memilih tag dari Meta proyek saat ini, berdasarkan sumber dan bukti yang diterima.

Volume Kognisi

AOCI-CODE memelihara satu Whole-Index logis, sementara setiap jenis indeks memiliki file, kepemilikan, dan siklus hidupnya sendiri.

Setiap objek memiliki tepat satu pemilik yang valid. Menempatkan objek di Volume yang salah menciptakan konflik kepemilikan. AOCI-CODE memperbaikinya hanya ketika mesin dapat membuktikan pemilik yang salah, pemilik yang benar, dan fakta objek saat ini; AOCI-CODE tidak menebak kepemilikan dari nama yang serupa.

Code Volume, Database Volume, dan cakupan dapat berevolusi bersama, tetapi mereka berbagi satu batas commit yang diatur. Menerapkan satu domain tidak boleh membuang proyeksi Baseline domain lain yang sudah ada. Penerapan Volume, pembaruan Baseline, dan proyeksi cakupan terkait diterbitkan sebagai satu hasil transaksi yang konsisten atau masuk ke pemulihan yang dapat dibuktikan. Mereka tidak pernah meninggalkan keadaan setengah selesai di mana "file berhasil tetapi Volume lain tidak memiliki baseline."

Integrasi host

aoci init selalu menulis aturan agen terkelola, tetapi integrasi host berbeda:

• Codex mendapatkan konfigurasi MCP tingkat proyek dan, dengan --hooks, prompt pemadatan konteks plus SessionStart(compact). Codex tetap tidak memasang hook pengeditan file.
• Claude Code dapat memasang hook PreToolUse.
• OpenCode V1 mendapatkan opencode.json tingkat proyek yang ketat.
• Cursor hanya mengembalikan cuplikan konfigurasi referensi; tidak ada yang ditulis ke proyek.

Setelah konfigurasi, periksa apakah sesi host saat ini sudah mengekspos alat AOCI. Segarkan atau buka kembali sesi proyek tersebut hanya jika sesi belum memuat server baru. Sesi baru biasanya membaca aturan dan Whole-Index sekali. Selama identitas indeks tetap valid dan tidak ada pemadatan host yang diketahui terjadi, tugas-tugas berikutnya menggunakan kembali apa yang sudah dimiliki model; seluruh indeks tidak disuntikkan ulang secara mekanis.

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 membatasi serah-terima pemadatan pada identitas tanda terima, keadaan penulisan atau pemulihan yang belum selesai, dan instruksi muat ulang segera; Codex tidak boleh menyimpan atau merangkum isi Whole-Index atau Overview/Attestation. Hook PreCompact tidak dapat menyuntikkan ke, atau menghapus riwayat dari, input pemadatan host, sehingga hook tidak dapat menegakkan ini sendirian. Tinjau dan percayai hook proyek yang terpasang melalui Codex /hooks sebelum mengandalkannya.

Keluaran Legacy mempertahankan Level 0–4 untuk kompatibilitas dengan host dan laporan yang ada. cognition-state/v2 saat ini menyatakan seberapa dapat digunakan gambaran model tentang sistem sebagai Level 0–3, dan memisahkan fakta pembuktian ketat serta tata kelola ke dalam dimensi independen:

Dimensi-dimensi ini tidak saling menggantikan. Attestation hanya membuktikan cakupan pengiriman dan konsistensi identitas untuk materi saat ini; ini tidak berarti agen telah sepenuhnya memahami setiap kemungkinan tugas di masa depan. Hanya current_system_cognition_reliable=true yang mengizinkan klaim tanpa kualifikasi tentang pemahaman sistem saat ini yang lengkap.

Panel AOCI

aoci ui menyajikan panel baca-saja di mesin ini, sehingga Anda dapat melihat keadaan indeks tanpa bertanya kepada agen:

• header indeks dan Code / Database Volume verbatim (baris bagian === dipertahankan apa adanya, dapat difilter, dapat disalin secara keseluruhan); tab "All" adalah indeks lengkap persis seperti yang diterima agen melalui Overview
• token indeks terhadap anggaran, dan rencana chunk Overview
• seberapa banyak kode yang dicakup indeks: file, baris, token, dan rasio kompresi; berapa banyak tabel basis data
• keadaan tata kelola dan drift, Managed Scope, integrasi host, dan proses aoci mcp yang berjalan
• perintah dan prompt yang harus diberikan kepada agen berikutnya, dengan tombol salin

Halaman beralih antara bahasa Tionghoa dan Inggris; interval penyegaran dapat dipilih (30 dtk secara default).

Beberapa server aoci mcp dalam satu WSL? Di Linux dan WSL, panel menemukan setiap proses aoci mcp milik pengguna saat ini dan repositorinya, beralih di antaranya dengan tab di bagian atas, dan menandai server yang binernya diganti di disk. Batas: ia hanya mengikat alamat loopback (bind lain ditolak), hanya menjawab GET dan HEAD, tidak mengambil lock, tidak menambahkan apa pun ke ledger, dan tidak mengubah satu byte pun pada repositori. Ini adalah proses terpisah yang tidak terkait dengan aoci mcp; server MCP tetap tidak membuka socket. Registrasi panel latar belakang berada di direktori cache pengguna, tidak pernah di repositori.

Perintah CLI umum

Kombinasi umum:

# 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

Perintah Plan, Stage, Check, Diff, Apply, Curation, Scope Change, Bootstrap, Migration, dan pemulihan masih ada. Ikuti panduan yang dikembalikan biner yang berjalan; jangan menyalin state machine internal ke dalam skrip.

Tentang perintah "read-only"

Untuk verify, check, index score, dan index inventory, "read-only" berarti indeks formal dan Baseline tidak diubah; itu tidak berarti benar-benar nol penulisan ke filesystem. Saat Ledger diaktifkan, keempat perintah tersebut dapat menambahkan entri ke Ledger lokal, dan verify juga mencoba menulis Verify History. Kegagalan penulisan audit tidak mengubah kode keluar atau kriteria tata kelola yang ada.

Jika diperlukan operasi yang benar-benar nol penulisan file, gunakan salinan terisolasi; CLI publik saat ini tidak menyediakan sakelar menyeluruh yang menonaktifkan setiap penulisan Ledger dan Verify History. Perintah System Cognition tidak membuat state formal kedua, tetapi pemanggilan CLI biasa tetap mengikuti kontrak runtime versi saat ini untuk Ledger dan catatan riwayat lokal.

Server MCP

aoci mcp tidak memerlukan daemon residen dan mengekspos tepat sembilan tool melalui stdio:

Dalam mode MCP, stdout dicadangkan untuk JSON-RPC; log dan diagnostik dikirim ke stderr. Deskripsi tool, skema JSON, dan nilai machine-state yang disediakan biner yang berjalan adalah otoritatif; README ini hanya titik awal.

Rilis saat ini menyediakan kapabilitas System Cognition melalui CLI dan kernel tata kelola yang sudah ada. Kapabilitas tersebut tidak menambahkan tool MCP kesepuluh atau mengubah nama, tujuan, maupun kontrak stdio dari sembilan tool yang ada.

Sesi berjalan lama dan pengiriman Whole-Index

Pada awal percakapan baru, agen biasanya memuat satu Overview lengkap untuk mendapatkan gambaran sistem yang sesuai dengan repositori, versi indeks, dan identitas layanan AOCI saat ini. Selama model masih dapat mengandalkan gambaran tersebut, model tidak perlu memuat ulang sebelum setiap tugas atau pemanggilan tool.

Dalam percakapan yang sama, model memutuskan apakah perlu memuat ulang berdasarkan state-nya sendiri, kecuali setelah kompaksi konteks host yang diketahui. Serah-terima hasil kompaksi mungkin hanya mempertahankan identitas receipt, state penulisan atau pemulihan yang belum selesai, dan instruksi muat ulang segera; serah-terima tersebut tidak boleh menyimpan atau merangkum isi header, entri, chunk, challenge, atau attestation Whole-Index maupun Overview. Konten indeks atau receipt yang disalin ke dalam serah-terima tersebut tidak dapat membuktikan bahwa gambaran model saat ini dapat diandalkan.

Sebelum melanjutkan pekerjaan bisnis setelah kompaksi yang diketahui, agen memuat ulang aturan jika aturan tersebut tidak lagi tersedia secara andal, mendeklarasikan context_compaction dengan event ID baru, dan menyelesaikan satu urutan kursor, konfirmasi, dan attestation Overview lengkap yang biasa. check_only dan probe cognition bukan pengganti. Setelah transport lengkap yang baru, aturan attestation parsial atau gagal yang ada tetap mengizinkan kelanjutan yang terikat sumber tanpa Overview otomatis kedua. Untuk perubahan semantik atau batas fase utama tanpa kompaksi yang diketahui, AOCI menyediakan ambang refresh, checkpoint, dan fakta identitas, dan model memutuskan apakah perlu memulihkan gambaran tingkat sistemnya untuk tugas tersebut.

Isi setiap Overview lengkap terdiri dari penanda awal, konten persis indeks formal saat ini, dan penanda akhir.

Ketika Overview melebihi anggaran chunk proyek:

1. pengiriman dimulai segera dengan chunk 1;
2. agen harus mengikuti next_cursor secara otomatis hingga chunk terakhir;
3. agen mengirimkan satu attestation menggunakan Whole-Index yang telah dikirim;
4. pencarian lokal, memori lama, pembacaan sumber tambahan, atau pembacaan file langsung tidak boleh disajikan sebagai pengiriman lengkap;
5. pemulihan yang tertunda atau snapshot yang tidak konsisten gagal secara tertutup tanpa mencampur konten.

overview_delivery.chunk_tokens adalah satu-satunya pengaturan ukuran pengiriman. Nilai bawaannya adalah 7000, dengan rentang valid dari 4000 hingga 24000. check_only=true adalah checkpoint ringkas tanpa rantai chunk.

AOCI mendeklarasikan batas ukuran hasil per tool pada aoci_overview. Host yang jika tidak demikian akan menyimpan hasil tool berukuran besar ke disk, sehingga hanya menyisakan pratinjau di konteks model (untuk pengiriman indeks, kegagalan senyap), menaikkan ambang tersebut khusus untuk tool ini. Di Claude Code, hal ini membuat 24000 lengkap dapat digunakan, mengirimkan indeks 480 objek dalam tiga chunk alih-alih lima. Tidak ada yang diprobe: deklarasi bersifat statis, dan host yang tidak mengenalinya akan mengabaikannya, sebagaimana disyaratkan spesifikasi MCP.

Ambang refresh secara bawaan adalah 30 jalur semantik berbeda dan juga dapat dikonfigurasi per proyek. Untuk aturan penghitungan yang tepat, rujuk dokumentasi Cognition Refresh dan kontrak runtime.

Database Cognition

AOCI-CODE dapat membawa struktur basis data ke dalam indeks yang sama dan tata kelola yang sama, dengan batas akses yang eksplisit dan sempit:

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

• Tidak ada akses jaringan basis data yang terjadi ketika tidak ada basis data yang dikonfigurasi atau tidak ada perintah basis data eksplisit yang dijalankan.
• Hanya metadata skema untuk tabel dasar yang dibaca, bukan baris bisnis; view, routine, dan komentar berada di luar cakupan pengumpulan saat ini.
• Tidak ada DDL atau DML yang dijalankan.
• Nama host, nama pengguna, DSN, dan nilai kredensial tidak pernah ditulis ke dalam file indeks.
• Penerapan Database Cognition berjalan offline dan tidak menyambung ulang ke basis data saat menulis.
• Program mempertahankan dan membandingkan bukti struktural, tetapi model tetap menulis tanggung jawab tabel, relasi, dan constraint bernilai tinggi.

Dukungan MySQL mencakup 5.7.6 dan yang lebih baru. Kolektor membaca versi server dan hanya menjalankan kueri katalog yang dapat dijawab oleh rilis tersebut: constraint CHECK sejak 8.0.16, ekspresi indeks sejak 8.0.13, visibilitas indeks sejak 8.0.0. Server 5.7 mencatat daftar check kosong, karena 5.7 mem-parsing sintaks CHECK dan tidak menyimpan apa pun; bukti memiliki bentuk yang sama pada setiap rilis yang didukung. MariaDB tidak didukung dan ditolak alih-alih dibaca sebagai MySQL.

Profil openGauss awal sengaja dibatasi pada openGauss 6.0.5 LTS dalam mode kompatibilitas A/PG dan tabel dasar biasa yang tidak terpartisi. Fitur katalog yang tidak didukung gagal secara tertutup alih-alih secara senyap direduksi menjadi fakta PostgreSQL; ini tidak mengklaim dukungan untuk MogDB, GaussDB, mode Dolphin/B/MySQL, partisi atau subpartisi, column-store, MOT, tabel asing atau sementara, view, routine, atau trigger.

Di sini, deteksi fail-closed berlaku untuk objek mirip tabel terpilih yang terlihat dengan semantik yang tidak didukung. Routine dan trigger tetap berada di luar domain objek tabel v1 dan tidak pernah direpresentasikan sebagai fakta tabel.

Jalur openGauss menggunakan patch lokal yang telah ditinjau AOCI atas sumber resmi Connector v1.0.8. Parser ketatnya hanya menerima parameter koneksi yang telah ditinjau dan tidak mengonsumsi PG*, service, password-file, home-directory, atau konfigurasi logger dari lingkungan. Koneksi TCP di luar alamat loopback numerik harus secara eksplisit menggunakan sslmode=verify-full (dan jalur trusted-root absolut di sslrootcert bila disediakan), dengan TLS 1.2 sebagai minimum; mode downgrade TLS ditolak. sslmode=disable hanya diterima untuk Unix socket eksplisit atau alamat loopback numerik yang digunakan sebagai batas lokal/pengujian. Administrator basis data tetap bertanggung jawab menyediakan DSN tersebut di luar percakapan dan menyediakan akun dengan hak istimewa paling rendah.

Database Volume tidak ada secara bawaan. Volume ini masuk ke Whole-Index hanya setelah proyek secara eksplisit mengaktifkan Database Cognition dan menyelesaikan tata kelola bukti, pengikatan, dan siklus hidup.

Onboarding akses basis data: Anda tidak perlu memahami detail DSN

Anda hanya mendeklarasikan identitas non-sensitif untuk sumber basis data. Jika --credential-env dihilangkan, AOCI menurunkan referensi variabel lingkungan yang stabil dari ID sumber; misalnya, primary dipetakan ke AOCI_DB_PRIMARY_DSN:

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

Kemudian gunakan preflight akses read-only untuk melihat apakah lingkungan eksternal telah menyediakan referensi tersebut:

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

Perintah ini tidak menyambung ke basis data, tidak mengembalikan nilai kredensial, dan tidak meminta Anda menempelkan DSN ke dalam percakapan. Administrator basis data atau infrastruktur menyediakan variabel lingkungan di luar proses AOCI dan memberikan akses read-only dengan hak istimewa paling rendah ke katalog sistem. Konfigurasi sumber hanya menyimpan nama referensi kredensial, bukan rahasianya.

Kandidat rilis saat ini hanya menyediakan penyedia kredensial lingkungan. Pengelola rahasia cloud seperti Vault, Kubernetes Secret, dan AWS/GCP/Azure dapat diintegrasikan melalui batas penyedia yang sama pada versi mendatang; semuanya belum tersedia saat ini, dan README ini tidak menyiratkan sebaliknya. Pemisahan ini menjauhkan format akun, pengodean DSN, dan pengelolaan siklus hidup rahasia dari pengguna biasa sekaligus menjaga otorisasi tetap eksplisit: AOCI tidak menemukan kredensial secara otomatis, memindai .env, membaca berkas rahasia, atau melewati batas otorisasi administrator basis data.

Fondasi Kognisi Sistem

Di atas indeks kode dan basis data, AOCI-CODE menyediakan sekumpulan observasi Kognisi Sistem turunan. Observasi ini menjawab pertanyaan seperti "dari mana objek ini berasal?", "objek kode mana yang mungkin terdampak oleh perubahan basis data?", dan "apa yang berubah antara observasi historis dan saat ini?" Observasi ini tidak menciptakan lapisan baru berisi fakta otoritatif.

# 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

Batas kewenangan

Setiap hasil Kognisi Sistem melaporkan derived=true; proyeksi relasi juga melaporkan authoritative=false. Cognition Volume, pengikatan bukti skema, sidik jari Baseline, dan identitas terikat tanda terima tetap menjadi otoritas yang mendasarinya. Relasi R yang belum terselesaikan menghasilkan hasil yang tidak lengkap atau diagnostik; program tidak menebak dan mengisinya.

AOCI-CODE bukan sistem knowledge-graph. Proyeksi relasi yang sempit ini adalah tampilan relasi yang praktis, tetapi tidak memiliki sistem pengelolaan status kedua, tidak memiliki jalur tulis independen, dan tidak memiliki penyimpanan fakta baru. Output turunan dapat dihapus dan dihitung ulang dari aset otoritatif saat ini. Jika proyeksi bertentangan dengan aset otoritatif, aset yang menang.

Mode eksekusi, privasi, dan batas data

• AOCI-CODE bersifat local-first secara default, tanpa endpoint cloud default, tanpa layanan unggah sumber yang dihosting, dan tanpa server latar belakang yang wajib.
• Penanganan data dalam mode Agent-native bergantung pada host yang Anda pilih dan kebijakan produknya; AOCI-CODE tidak mengunggah data atas nama host.
• Akses jaringan basis data harus dipicu secara eksplisit dan dibatasi pada metadata skema baca-saja.
• Ledger, draf, transaksi, dan bukti pemulihan disimpan di bawah .aoci/ secara default dan biasanya diabaikan oleh Git; berkas indeks dan aset tata kelola tim dapat di-commit ke Git.
• Proyeksi Kognisi Sistem dihitung secara lokal dari aset otoritatif yang ada dan tidak memerlukan basis data graf, basis data vektor, atau layanan graf jarak jauh.

Perbedaannya dengan repo map, RAG, LSP, atau code graph

Pencarian, AST, LSP, code graph, dan RAG unggul dalam pertanyaan struktural dan pengambilan. AOCI-CODE melakukan tugas yang berbeda: ia memelihara deskripsi sistem berversi yang mencakup cakupan terkelola dan berkembang secara inkremental bersama perangkat lunak. Yang Anda dapatkan:

• Whole-Index. Satu peta sistem yang mencakup cakupan terkelola saat ini, bukan fragmen yang dirakit saat itu juga untuk setiap tugas.
• Entri FRAS. Tanggung jawab, relasi kuat, kontrak publik, dan batasan bernilai tinggi untuk setiap objek dengan peran index.
• Persistensi antar sesi. Berkas indeks berada bersama repositori, sehingga sesi berikutnya dan agen lain menggunakan versi yang sama.
• Managed Scope. Catatan eksplisit tentang objek mana yang masuk ke indeks, mana yang hanya diamati perubahannya, dan mana yang sengaja dikecualikan.
• Deteksi drift. Membedakan Missing, Orphan, Stale, Unbaselined, perubahan akhir baris, perbedaan kurasi, dan sumber yang dikecualikan dari penulisan (kosong, biner, kelebihan ukuran).
• Pembaruan terkelola. Kandidat masuk ke berkas formal melalui pengikatan sumber, rencana, validasi, tinjauan, CAS, penulisan atomik, Baseline, dan alur kerja pemulihan.
• Atestasi pengiriman. Chunk, cursor, receipt, dan challenge membuktikan bahwa Whole-Index telah dikirim secara lengkap.
• Kognisi Basis Data. Entri tingkat tabel yang dibangun dan dikelola dari bukti skema PostgreSQL/MySQL/openGauss yang diterima secara eksplisit.
• Proyeksi sistem. Observasi Lineage, Relations sempit, Impact basis data-ke-kode, Snapshot, dan Evolution yang diturunkan dari indeks otoritatif dan pengikatannya tanpa menduplikasi status otoritatif; Impact hanya menelusuri relasi R eksplisit yang ditulis model.

AOCI-CODE melengkapi alat yang ada, bukan menggantikannya.

Kombinasi yang disarankan: AOCI-CODE menyediakan prior semantik global; code graph, LSP, pencarian, dan sumber menyediakan bukti yang presisi; pengujian dan hasil runtime menyediakan penerimaan akhir. Proyeksi Relations AOCI tidak menggantikan call graph yang presisi: ia mengekspos penampungan Volume struktural dan tepi dependensi Root, sementara tepi semantiknya terbatas pada relasi kuat yang secara eksplisit ditulis model.

Tumpukan teknologi

AOCI-CODE tidak memerlukan Neo4j, basis data vektor, daemon yang berjalan lama, atau layanan cloud AOCI. Saat Kognisi Basis Data diaktifkan, basis data target hanyalah sumber bukti skema baca-saja yang eksplisit, bukan penyimpanan status milik AOCI sendiri.

FAQ

Mengapa status --deep Legacy masih menunjukkan drift?

status --deep, index score, dan index agent plan hanya untuk Legacy. Untuk repositori Cognition Volume, jalankan panduan langsung dan biarkan host menggunakan aoci_maintain biasa tanpa argumen, kirimkan batch terkini yang lengkap melalui aoci_update_entry, lalu tutup dengan Verify, Check, dan panduan. Jangan mengubah Baseline secara langsung atau melewati langkah pengikatan sumber dan pemulihan.

Tata letak Legacy sendiri sudah usang. Volumes v1 adalah jalur yang didukung untuk repositori baru dan yang dimigrasikan, dan perintah khusus Legacy dijadwalkan untuk dihapus pada v0.2.0; migrasikan repositori Legacy dengan aoci cognition migration sebelum itu.

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

Mengapa host memulai AOCI yang salah?

Periksa jalur eksekutabel dalam konfigurasi MCP tingkat proyek dan pastikan itu jalur absolut yang stabil, lalu jalankan:

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

Untuk memverifikasi server stdio yang dimuat, bukan hanya berkas di disk, periksa juga eksekutabel aktual proses host, --repo baris perintahnya, dan identitas proses setelah restart.

Apakah saya harus membuat akun basis data dan menyediakan DSN sendiri?

Anda tidak perlu memahami sintaks DSN, dan Anda tidak boleh mengirim rahasia di obrolan. Setelah Anda mendeklarasikan identitas sumber yang tidak sensitif, AOCI menyediakan referensi variabel lingkungan yang stabil. Administrator basis data tetap harus membuat akun eksternal dengan hak istimewa minimum yang memiliki akses baca-saja ke katalog sistem dan menyediakan referensi tersebut ke lingkungan runtime. Versi saat ini tidak membuat akun basis data atas nama organisasi atau membaca penyimpanan rahasia secara otomatis.

Apakah bisa dijalankan di CI?

Ya. Pemindaian, verifikasi, gerbang tata kelola, dan pemeriksaan deterministik berjalan tanpa menulis entri baru. Untuk perintah persisnya, penulisan audit, dan kode keluar, rujuk ke --help biner saat ini, skema JSON, dan dokumentasi CI proyek.

Apakah hasil AOCI yang semuanya hijau membuktikan bahwa semantiknya benar?

Tidak. Hasil hijau membuktikan bahwa kondisi struktural dan tata kelola yang dikodekan terpenuhi. Apa yang ditulis model tetap harus diperiksa terhadap kode sumber, skema, pengujian, hasil runtime, dan tinjauan manusia.

Apakah graf Kognisi Sistem merupakan sumber kebenaran baru?

Tidak. Kemampuan saat ini adalah proyeksi relasi yang sempit, bukan platform graf independen. Ia menghitung hasil hanya dari indeks formal, bukti, tanda terima, dan Baseline, dan tidak menyimpan fakta otoritatif baru. Program juga tidak menghasilkan relasi semantik secara otomatis dari impor, SQL, nama berkas, atau kemiripan.

Dokumentasi

Tautan dokumentasi dan kontrak publik dipatok ke v0.1.0-rc22 agar tetap valid saat README ini dibaca dari arsip Rilis biner, yang tidak menyertakan direktori docs/ atau spec/public/ milik repositori.

Rangkaian verifikasi black-box

Repositori ini menyertakan empat rangkaian black-box mandiri di bawah scripts/blackbox/ yang menguji biner aoci yang telah dibangun secara ketat dari luar proses, hanya melalui protokol MCP stdio publik dan CLI:

• Kesesuaian protokol — 53 pemeriksaan baca-saja pada permukaan wire MCP, dengan kalimat yang bergantung pada lokal diulang di bawah zh-CN;
• Skenario injeksi kesalahan — 75 skenario yang mencakup manipulasi kursor, pemulihan setelah crash, penulis yang berlomba, dan hook pra-tulis pada repositori fixture sekali pakai;
• Siklus hidup pada proyek nyata yang dibekukan — tiga proyek fixture yang di-commit: repo-a (TypeScript) dan repo-b (Python + MySQL) menjalankan siklus hidup penuh dari init hingga realignment, dan repo-c (layanan berlapis dengan 453 file) juga menjalankan penulisan multi-batch pada batas batch mesin. Jalur model opsional menempatkan agen AI nyata — model apa pun yang diekspos oleh instalasi OpenCode Anda — melalui dua repositori kecil tersebut dan menilai keadaan akhir dari permukaan publik.
• Sumbu peningkatan — 80 pemeriksaan per versi yang dirilis, pada sepuluh bentuk repositori: setiap rilis yang diterbitkan membangun dan menulis repositori dengan biner miliknya sendiri, lalu biner yang diuji harus mengelolanya tanpa memindahkan identitas, menuntut Perubahan Cakupan, atau menulis ulang aset formal, dan apa yang kemudian ditulisnya harus menjaga checkout di jalur lain tetap selaras; pada bentuk kesepuluh peran berbalik, dan setiap rilis yang diterbitkan harus membaca repositori yang ditulis oleh biner yang diuji tanpa crash atau menulis ulangnya. Tiga rangkaian lainnya mencetak setiap fixture dengan biner yang diuji, sehingga preimage yang berubah antar versi tidak terlihat oleh mereka secara konstruksi.

Rangkaian ini hanya membutuhkan Python 3 dan git di atas biner yang telah dibangun (Docker untuk rangkaian MySQL; OpenCode plus langganan model Anda sendiri untuk jalur model), sehingga klon repositori dapat memverifikasi build-nya sendiri, port platform, atau fork — dan AOCI_BIN dapat mengarahkan rangkaian kesesuaian dan skenario ke biner alternatif mana pun yang mengklaim kontrak publik di spec/public/. Rangkaian ini berada di klon repositori; arsip Rilis biner tidak menyertakannya. Lihat scripts/blackbox/README.md untuk perintah dan interpretasi hasil.

Riset, kekayaan intelektual, dan lisensi

Makalah dan artefak riset AOCI-CODE dapat secara publik menjelaskan metode yang dirilis, protokol eksperimen, dan hasil. Aplikasi paten, cakupan yang diberikan, status hukum, pemilik, dan efek teritorial adalah fakta hukum, dan tidak boleh ditambahkan ke deskripsi produk berdasarkan README internal, nomor versi historis, atau penuturan ulang yang belum terverifikasi.

Jika nomor paten tertentu, tanggal pemberian, atau cakupan harus diungkapkan di masa depan, pemegang hak dan penasihat hukum harus memverifikasinya terhadap catatan publik resmi dan menempatkannya dalam dokumen IP, NOTICE, atau dokumen hukum khusus. README ini hanya boleh menautkan ke file otoritatif tersebut; README ini tidak boleh memperluas cakupan paten sendiri maupun menyajikan status paten sebagai lisensi perangkat lunak.

Komunitas

Pindai kode dengan WeChat atau WeCom (企业微信) untuk bergabung dengan grup proyek AOCI dan berbicara dengan maintainer serta pengguna lain. Laporkan bug dan permintaan fitur sebagai GitHub issues agar tetap dapat dicari, dan laporkan dugaan kerentanan secara privat seperti yang dijelaskan SECURITY.md, jangan pernah di grup.

AOCI-CODE bukan tentang membuat agen melihat lebih banyak kode. AOCI-CODE memberikan agen pemahaman yang terkini, terstruktur, dapat dilacak, dan terkelola tentang sistem sebelum setiap tindakan. Git memversikan kode Anda, migrasi basis data memversikan struktur data Anda, dan AOCI-CODE memversikan apa yang diketahui agen tentang sistem, beserta keterlacakan, konsistensi tata kelola, dan batas pemulihan dari bagaimana pengetahuan itu berkembang.