AOCI-CODE

AOCI-CODE

コードベース全体を永続的に Git でバージョン管理されたマップとして保持 — コーディングエージェントが書き、ローカル MCP サーバーが管理します。 エージェントは一度読むだけでシステムを把握し、タスクごとにリポジトリを読み直す必要がありません。

🇺🇸 English | 🇨🇳 简体中文

できること

大規模システムを全体像を見失わずに構築できます。 Codex、Claude Code、Cursor、OpenCode などのエージェントでは、エージェントがタスクを開始する時点で既にシステム全体を把握しています。各ファイルの役割、依存関係、壊してはいけないものが分かっている状態です。リクエストのたびにコードベースを検索して読み直すことはなくなります。プロの開発者でない人も自分のシステムを反復改善し続けられますし、プロの開発者はシステム全体をエージェントに任せ、アーキテクチャと設計に集中できます。

既存システムを一歩で引き継げます。 最大約 50 万行の既存コードベースをエージェントに指定し、インデックスの構築を依頼します。エージェントは各領域をどれだけ把握しているかを報告し、そこから開発を引き継ぎます。実用的な上限は行数ではなくインデックスのサイズです。現在、約 30 万トークンのインデックスで 70 万行の商用システムがこの方法で開発されています。

人、エージェント、会話を変えても最初からやり直す必要はありません。 インデックスはコードの隣、リポジトリ内に置かれ、Git でバージョン管理されます。プロジェクトの担当者が変わったり、エージェントを切り替えたり、新しい会話を開いたりしても、インデックスを一度読むだけで前回の続きから再開できます。

最初のインデックス構築後は、メンテナンスは自動です。 MCP サーバーがコードの変更を検出し、更新が必要なエントリを発行します。エージェントは各タスクの完了時にそれらを記入するため、インデックスは現在のコードと一致し、メンテナンスのために手を止める必要はありません。

実際の見た目

実際のソースからモデルが書いた、ファイルごとに 1 行のエントリです。これはこのリポジトリ自身のインデックスからの実際のエントリです:

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 はそのファイルの責務、R は一緒に読む必要があるもの、A は呼び出し元が依存しているもの、S はコードから推測できないが間違えてはならないものです。タグ [CG9L] は、そのファイルをレイヤー、ドメイン、重要度、サイズで位置づけます。このような行が数百行あればシステム全体をカバーでき、エージェントは一度のパスで読み通せます。各フィールドの説明はエントリ形式にあります。

CodeGraph との違い

• CodeGraph はコードをシンボルと呼び出しのグラフに解析します。エージェントが質問すると、正確なソースと呼び出しパスを返します。目の前のタスクのための精密な検索ツールです。
• AOCI-CODE はモデルがファイルとテーブルごとに 1 行を書き、その役割、接続先、壊してはいけないものを記録します。エージェントはまずインデックス全体を読むため、タスク開始前にシステムを把握しています。インデックスは Git に置かれ、コードと同期が保たれます。
• 両方を併用できます。システムを把握するにはインデックス、作業中に正確なコードを取得するには CodeGraph を使います。

詳細な比較では RAG、LSP、リポジトリマップについても扱っています。

期待されること

最初のインデックス構築には時間がかかります。 エージェントは管理対象のすべてのファイルを読み、ファイルごとに 1 エントリを書きます。所要時間はコード 20 万行あたり約 1 時間で、モデルとエージェントの速度によって変わります。バッチ単位で実行され、中断しても停止した位置から再開します。

データベースがある場合は、それもインデックス化しましょう。 MySQL と PostgreSQL に対応しており、制約付きの openGauss 6.0.5 にも対応しています。MySQL は 5.7.6 以降を意味し、MariaDB はサポートされません。まずコードインデックスを構築し、次にデータベースインデックスを構築してください。コードとテーブルレベルの知識が一緒に提供されることで、エージェントはシステムをより完全に理解できます。

ローカルのみ: システムに対して読み取り専用、インターネット接続なし、認証情報の保存なし。 AOCI-CODE はソースコードとデータベースのテーブル構造を読み取り、業務データには決して触れません。書き込むのはプロジェクトディレクトリ内のインデックスファイルと自身の状態、およびユーザーキャッシュディレクトリ内のステータスページの登録のみです。インターネットに接続することはなく、何もアップロードしません。開く接続は、宣言されたデータベースへのカタログメタデータ取得のためのものと、自身のループバックステータスページへのものだけです。データベースの認証情報は環境変数名で参照され、保存されることはありません。インデックスのテキストは、既に使用しているモデルチャネルを通じて、あなた自身のエージェントによってローカルに書かれます。AOCI-CODE が新たなデータの出口を追加することはありません。

クイックスタート

以下の指示をエージェントに渡すと、AOCI-CODE をダウンロードして設定します。エージェントを再起動した後、2 つ目の指示を送ってインデックスを構築します。

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.

エージェントを再起動した後、こちらを送ってください:

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.

エージェントは aoci ui --detach --json でバックグラウンドでパネルを起動し、リンクを渡します。表示内容とその他のコマンドについては AOCI パネルを参照してください。

再起動が必要な理由: インデックスは AOCI の MCP ツールを通じて書かれますが、init を実行したセッションは、init が書き込んだばかりの MCP サーバーをまだ読み込んでいません。MCP サーバーを動的に読み込むホストでは再起動が不要な場合があります。判別方法はホスト統合で説明しています。

プロジェクトにデータベースがある場合 (PostgreSQL と MySQL、および制約付き openGauss 6.0.5 に対応)、それもインデックス化してください。データベース認知の説明に従ってソースを宣言し、接続文字列の環境変数をホスト環境で提供し (AOCI は認証情報を保存しません)、次にこれを送ってください:

Build the AOCI database index for this project.

コンテキストが圧縮された場合、またはエージェントにシステムの全体像を再構築させたい場合は、これを送ってください:

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.

仕組み

AOCI (AI-Oriented Cognition Infrastructure) は手法とプロトコルです。コーディングエージェントとソフトウェアシステムの間にあるレイヤーであり、モデルが推論し、エージェントが計画・実行し、AOCI がコード、設定、テスト、データベース構造を網羅するシステムの最新の記述をエージェントが行動する前に読めるように保ちます。AOCI-CODE はこのプロジェクトであり、aoci CLI、MCP サーバー、およびそれらが維持するインデックスです。

AOCI-CODE は、システムを理解し変更するために実際に重要な情報を、シンボルと意味を組み合わせた高密度なプレーンテキストのインデックスに凝縮します。モデルのコンテキストが限られている場合、エージェントはまずインデックスを読み、一度のパスでプロジェクトの主要な情報の大部分を取得してからタスクを開始します。これにより繰り返しの検索と再学習が削減され、タスクやセッションをまたいで理解が引き継がれます。

• 一度きりの要約ではありません。 インデックスはシステムとともに進化し、プロジェクト内に残るため、Git で差分、レビュー、バージョン管理、ロールバックができます。
• 「ファイルの場所」以上のものです。 責務、強い関係、公開契約、トランザクション境界、互換性制約など、コード構造から推測しにくい事柄を記録します。
• ポータブルです。 インデックスはプロジェクトとともに保存され、モデル、エージェント、セッションに縛られません。コードと整合している限り、どのエージェントも後続のどのセッションも、理解をゼロから再構築することなく再利用できます。
• コードとデータベースを一緒に。 モデルはデータベーステーブル用に別のテーブルレベルのインデックスを構築できます。一緒に提供されることで、エージェントはシステムをより完全に把握できます。

インデックスは、プロジェクトとともに保存される管理されたプレーンテキストファイルの集合です:

• ルート (aoci.txt) は現在のインデックスを構成するものを宣言し、その有効化のエントリポイントです。
• メタ (aoci.meta.txt) はタグ辞書、FRAS ルール、および作成上の制約を保持します。
• コード (aoci.code.txt) はコードおよびその他のリポジトリ資産に対するモデル作成のエントリを保持します。
• データベース (aoci.database.txt) はデータベース認知が有効な場合の、オプションのテーブルレベルエントリを保持します。

ルート、メタ、および参加するオブジェクトボリュームが一体となって Whole-Index を形成します。その上に乗るワークフローには 3 つの段階があります:

1. ガバナンスの下でインデックスを構築する。 モデルはソースコードと受け入れられた証拠を読みます。AOCI-CODE は管理対象スコープと、index ロールでモデルが管理対象オブジェクトごとに書くエントリを統治します。
2. 行動する前に読む。 エージェントはプロジェクトルール、ライブガイド、現在の Whole-Index を読み、次に目の前のタスクのためにソースやその他の証拠を確認します。
3. 検証済みの変更後に維持する。 コードとテストが安定したら、プロジェクトルールと MCP ワークフローにより、エージェントは影響を受けるエントリを更新し、インデックスを aligned に戻します。

これらのファイルはリポジトリ内のプレーンテキストであるため、Git がバージョン管理します。インデックスが現在のシステムバージョンと整合している限り、どのエージェントも後続のどのセッションも同じ Whole-Index を読んで再利用できます。

手動統合

AOCI-CODE は正規のソースから取得するか、GitHub Releases の署名済みパッケージを使用してください。ビルド済みバイナリを使用する前に、インストールガイドの基本、推奨、または完全の検証レベルに従い、どのレベルが完了したかを報告してください。この README と、検証済みバイナリの安定した絶対パスを、信頼できるコーディングエージェント (Codex、Claude Code、Cursor、OpenCode など) に渡してください。エージェントはプロジェクト内の指示に従って AOCI を初期化し、MCP を統合し、最初のインデックスを構築できます。

最初のインデックスにかかる時間はリポジトリのサイズによって異なります。通常の統合は 4 つのステップです: バイナリを準備し、エージェントまたはあなた自身が対象リポジトリを初期化し、ホストに「インデックスを構築して」と依頼し、整合性を検証します。その後は、リクエストのたびに「インデックスを維持して」と付け加える必要はありません。管理対象オブジェクトが変更されるたびに、プロジェクトルールと MCP ワークフローによりエージェントがインデックスを増分で維持します。

要件

• 検証済みのリリースパッケージ、または正規の AOCI-CODE ソースリポジトリのチェックアウト。
• ソースビルドのみ: go.mod、make、およびリポジトリが要求するその他のツールで宣言された Go ツールチェーン。
• サポートされている MCP ホスト (Codex、Claude Code、Cursor、OpenCode など)。
• 対象リポジトリへの通常の読み取りおよび書き込みアクセス。

AOCI-CODE はモデルプロバイダーの API ではなく、MCP ホストと統合します。DeepSeek やその他のモデルは、それらを実行するエージェントまたはホストが標準の stdio MCP を サポートし、ツール契約に従える場合に AOCI-CODE を使用できます。モデル名だけでは 互換性は確立されません。

署名済みパッケージの経路と実行可能ファイルの検証コマンドはインストールガイドにあります。ソースビルドの経路は以下です。

現在の RC: 検証済みパッケージを使用するか、ソースからビルドする

[!IMPORTANT] AOCI-CODE v0.1.0-rc22 が現在のリリース候補です。これは FSL-1.1-MIT の下での Fair Source/ソース公開ソフトウェアです。LICENSE を参照してください。リリース検証手順に従った上で、正規のソースからビルドするか、v0.1.0-rc22 GitHub Release の署名済みパッケージを使用してください。

署名済みの Release バイナリは自身を aoci version 0.1.0-rc22 と識別します。 ソースビルドは代わりに正確なチェックアウトを識別し、v0.1.0-rc22-1-g<short-commit> (該当する場合は -dirty も) のような開発バージョンと、その Git コミットを報告することがあります。 これらは異なるビルド入力であり、バージョンの競合ではありません。

GitHub CLI でダウンロードするには、まず認証してから、タグ付けされた Release アセットをダウンロードします:

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

匿名でダウンロードするには、ブラウザで v0.1.0-rc22 Release ページ を開き、必要なアーカイブと検証用アセットをダウンロードしてください。

ソースからビルドするには、正規のリポジトリをクローンし、バイナリをビルドし、得られたパスを安定させておきます:

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

Windows では、同じソースを 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

次に、この README をプロジェクトを任せている信頼できるエージェントに渡し、こう依頼してください:

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.

エージェントはプロジェクトルートを特定し、ビルド済みバイナリへの安定した絶対パスを使用し、現在のホストに適した初期化を実行し、ホストの再起動や実際の人間による承認が必要な場合は明確に伝える必要があります。バイナリは AOCI-CODE のチェックアウト内に置いたままでも、共有ツールディレクトリに移動してもかまいません。ただし、MCP 設定が正しい絶対パスを指している必要があります。

手動初期化

AOCI を自分で初期化するには、対象リポジトリのルートから以下を実行するか、--repo で明示的なパスを渡してください:

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

init はロケール設定、管理対象の AGENTS.md ルールブロック、Git 境界、および空のインデックススケルトンを書き込みます。設定とプロンプトはホストによって異なります。ホスト統合 を参照してください。ファイル名、ディレクトリ、AST からビジネス上の意味を勝手に作り出すことはありません。

新しいリポジトリでは、最初の scan が管理対象の Baseline を確立します。すでに管理された Baseline を持つプロジェクトでは、管理対象スコープの追加、削除、変更は正式な Scope Change ワークフローを通じて行われます。scan --force はガバナンス上の事実を再定義するための近道ではありません。--force も、未解決のドリフト、レシート、復旧境界を消去することはできません。

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

エージェントに最初のインデックスを構築させる (重要)

初期化と scan が完了したら、エージェントセッションで AOCI ツールがすでに公開されているか確認してください。公開されていない場合は更新または再起動してください。次に、対象プロジェクトについてエージェントに以下を入力します:

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.

エージェントは aoci ui --detach --json でバックグラウンドでパネルを起動し、リンクを渡します。AOCI パネル では、表示内容とその他のコマンドについて説明しています。

ホストはプロジェクトの AOCI ルールとライブガイドを読み、ソースコード、テスト、設定、および関連する証拠を検査し、ロールが index であるすべての管理対象オブジェクトに対して FRAS 候補を書き込みます。Plan、Stage、Check、Diff、CAS、Apply を自分でオーケストレーションする必要はありません。

最初のインデックスが完了したら、通常どおりの開発リクエストを送信します。たとえば:

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

「最後に AOCI インデックスを保守する」と付け加える必要はありません。プロジェクトルールと MCP により、エージェントはコードとテストが安定した時点でインデックスの変更を確認し、影響を受けるエントリを正式なワークフローを通じて更新します。プロジェクトが automation.mode=auto を使用している場合、AOCI-CODE が割り込むのは、実際の人間による承認が必要なとき、外部アクションを実行する必要があるとき、復旧を証明できないとき、安全チェックが失敗したとき、またはサードパーティの並行性競合が見つかったときだけです。その他の自動化モードは、それぞれ独自のランタイム契約に従います。

整合性を検証する

オンボーディングが完了したら、以下を実行します:

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

インデックスと現在の管理対象ソースは aligned に収束するはずです。収束しない場合は、まずライブガイドを参照してください。内部状態マシンをラッパースクリプトで複製しないでください:

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

基本診断を実行する

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

ホストが実際にどの AOCI に接続しているかを確認するには、ディスク上の内容ではなく、サーバーが自身について報告する内容を読み取ってください。任意の aoci_overview の check_only レスポンス、または任意の aoci_maintain レスポンスにおいて、cognition_receipt.mcp_service_version は実行中のバージョンであり、runtime_repository_root はそれが統治するリポジトリです。対応するバイナリパスは、プロジェクトの .mcp.json または同等のホスト設定における command です: .codex/config.toml、opencode.json、または .cursor/mcp.json。ディスク上のバイトを置き換えても実行中の MCP プロセスは変わりません。そのため、アップグレードやロールバックの後は、これらの事実に照らして再確認してください。

一度きりのウォークスルーには、リポジトリ内で examples/minimal-repository を使用してください。

make fast

make full
./build/aoci --version

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

初期化後に現れるもの

典型的なリポジトリには、以下のインデックスファイルが含まれます:

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

新しいプロジェクトを初期化すると、Root、Meta、および空の Code Volume が作成されます。Database はデフォルトでは存在しません。AOCI-CODE は、リポジトリやデータベースのビジネス上の意味を独自に生成することはありません。

aoci init --agent <name> はさらにホスト統合設定 (.mcp.json、.claude/settings.json、.codex/config.toml、または opencode.json) を書き込みます。そのコマンドとリポジトリのパスはマシンにバインドされた絶対パスです。これらの ファイルをリポジトリの .gitignore に追加し、コミットしないでください。コミットされたコピーは 他のすべてのマシンで壊れます。また、インストーラーはキーの存在によって既存の エントリを検出するため、そこで init を再実行すると、壊れたパスが黙って維持されます。

開発タスクの実行方法

以下の 2 つの図は、AOCI の内部実装ではなく、あなたが体験するワークフローを示しています。

新規プロジェクト: まずシンプルなシステムを構築し、その後 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

新しいシステムは、コードの最初の行から AOCI-CODE を必要とするわけではありません。まずエージェントの既存の機能でプロトタイプを構築してください。およそ 10,000〜30,000 行が導入の良い目安です (厳密なしきい値ではありません)。セッションをまたぐ継続性をより早く求めるチームは、もっと早く統合できます。

既存プロジェクト: リポジトリをインデックス化し、その後反復する

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

最初のインデックスが完了した後は、どちらのフローも日々の運用では同じように機能します。あなたはビジネスまたはエンジニアリングの要件を説明します。エージェントは Whole-Index と現在の証拠を組み合わせ、開発と検証を行い、タスクを完了する際に MCP を通じて変更されたオブジェクトを更新します。内部の Plan、Stage、Diff、CAS、Baseline コマンドを学ぶ必要はなく、すべてのプロンプトで保守要件を繰り返す必要もありません。

完全なバッチが正式な書き込みが始まる前に拒否された場合、インデックスは変更されません。正式な書き込みが始まった後にワークフローが中断された場合、システムは不変の意図、書き込み証拠、および復旧状態を保持し、証明可能なポストイメージから再開するか、正確なプリイメージにロールバックします。サードパーティのバイト競合はフェイルクローズします。AOCI-CODE は「書き込みを完了する」ために外部の変更を上書きすることは決してありません。

最終状態は常に applied、repair_required、または stopped のいずれかです。stopped は成功ではなく、何も書き込まれなかったことを必ずしも意味するわけでもありません。failed_step、正式な書き込み証拠、およびガイドが返す復旧アクションを検査してください。

誰が何をするか: モデルと AOCI-CODE

モデルは意味を所有する

ホストモデルはソースコード、テスト、設定、ドキュメント、および必要な証拠を読み取り、次に決定します:

• オブジェクトが実際に何に責任を持つか;
• どのファイル、モジュール、またはデータベースオブジェクトが、安全に変更するために考慮すべき強い関係であるか;
• どの API、コマンド、フォーマット、または観測可能な契約を公開しているか;
• どのトランザクション、認可、並行性、キャッシュ、デプロイ、互換性、または履歴上の制約が、通常の構造だけからは推測できないか。

AOCI-CODE はファイル名、パス、拡張子、AST、またはテンプレートから FRAS を組み立てることはなく、モデルが書いた内容を黙って書き換えることもありません。

AOCI-CODE はガバナンスを所有する

AOCI-CODE は以下に責任を持ちます:

1. Safe Inventory、Managed Scope、および現在の Baseline を確立する;
2. 現在の Whole-Index を提供し、その同一性を確認する;
3. 決定論的なプラン、ターゲットセット、およびソース SHA-256 値を生成する;
4. 候補の構造、タグ辞書、関係の同一性、スコープ、所有権、予算、および影響範囲を検証する;
5. チェック、差分、およびレビュー内容の間のバインディングを保持する;
6. プロセス間ロック、CAS、およびアトミック書き込みで完全なバッチをコミットする;
7. Baseline を進め、台帳を追記し、書き込み後の障害の後に復旧証拠を保持する;
8. Verify、Check、およびガイドを通じて現在のガバナンス状態を再び証明する;
9. 第二の真実の源を作成することなく、権威ある資産から Lineage、Relations、Impact、Snapshot、および Evolution の観測を導出する。

オールグリーンのマシン結果は、エンコードされた構造的およびガバナンス上の契約が成立していることのみを意味します。モデルが書いたすべての記述が正しいことを意味するわけではありません。

インデックスの構成

AOCI インデックスには 2 つの層があります: インデックスルールとインデックスエントリです。製品は 2 つの物理レイアウトをサポートしており、それらは 1 つのファイル形式ではありません。

Volumes v1 レイアウト

Volumes プロジェクトは責任を分離します:

• aoci.txt は Root のみです。現在の CognitionSet に参加する Volumes を宣言します。
• aoci.meta.txt は Meta を保持します: タグ辞書、FRAS ルール、予算、およびオーサリング契約。
• aoci.code.txt はコードオブジェクトのエントリを保持します。
• aoci.database.txt は Database Cognition が有効な場合にデータベースオブジェクトのエントリを保持します。

Code と Database の Volumes は同じ FRAS 行構造を共有しますが、独立したオブジェクト同一性、証拠バインディング、所有権、およびライフサイクルを持ちます。Root、Meta、およびオブジェクト Volumes が一緒になって Whole-Index を形成します。aoci.txt の Root だけを読むことは、システム全体を読んだと主張するには不十分です。

これを地図のように考えてください:

• インデックスルールは地図の凡例と座標系です。
• インデックスエントリは各地点を記述するマーカーです。
• Root は現在の地図セットのカタログとバージョンのエントリポイントです。
• Volume は同じプロトコルに従うが独自の証拠ソースとライフサイクルを持つ別のシートです。

インデックスヘッダーの見た目

Root と Meta はそれぞれ、マシンが読み取るヘッダー行で始まります。これは aoci init が my-service という名前の新しい en-US プロジェクトに対して書き込む内容で、アクティベーションのエントリポイントである Root から始まります:

#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

各 #Volume: 行は、1 つの参加 Volume をその同一性、種類、パス、フォーマット、依存関係、およびアクティベーション状態とともに宣言します。ここで宣言されていない Volume は、作業ツリーに他に何が含まれていても、現在の CognitionSet の一部ではありません。Database Cognition を有効にすると、もう 1 行 #Volume: id=database kind=database path=aoci.database.txt format=table-fras-v2 depends=meta state=enabled が追加されます。

次に Meta は、すべてのエントリを統治するルールで始まります:

#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 は重要な行です: フィールド制限はこのテキストではなくバイナリに属するため、プロジェクトは自身の Meta を編集して制限を広げることはできません。#S-Admission と #S quota は特に S フィールドを統治します: そこにそもそも何を記録できるか、および各重要度バンドが何文字を使えるかです。タグ辞書はこれらの行の直後に続きます。以下で完全に示します。

Code Volume は 1 行 #AOCI-CODE-VOLUME: 1 で始まり、その後のすべてはディレクトリセクションとエントリです。

これらは新しいプロジェクトが開始する値であり、固定されたプロトコル定数ではありません。その後は各リポジトリ自身の Root と Meta が権威となります: 古いプロジェクトはカスタムタグ辞書を持つ場合があり、--locale zh-CN で初期化されたプロジェクトは #Locale: zh-CN を書き込み、それに応じて #S quota: キーをローカライズします。

インデックスルールが定義するもの

Volumes v1 では、プロジェクトの Meta Volume がこれらのルールを保存します。Legacy レイアウトでは、それらはモノリシックなヘッダーに存在します。プロジェクトは異なるタグ辞書を使用できますが、基本的な FRAS 構造は同じままです。

この README は、これらのルールをどのように読むかだけを説明します。具体的で実行可能なルールについては、現在のプロジェクトの Meta または Legacy ヘッダー、AOCI ガイド、および正式な仕様に従ってください。

1 つのエントリが記録するもの (FRAS)

ルールが整ったら、モデルは index ロールを持つすべての管理対象オブジェクトに対して 1 つのエントリを書き込みます。observe ロールは変更の観察にのみ関与し、exclude ロールは意図的に除外されたものを示します。どちらも正式なエントリを所有しません。AOCI は FRAS を使用して、エントリで最も重要な 4 種類の情報を整理します。

• F — Function (機能): そのオブジェクトが何に責任を持つか。
• R — Relations (関係): それを安全に理解または変更するために、他にどのオブジェクトを併せて考慮する必要があるか。
• A — API: どのインターフェース、コマンド、フォーマット、または観測可能な契約を公開しているか。
• S — Non-obvious constraints (自明でない制約): F、R、A ではカバーされないが、オブジェクトを安全に理解または変更するために必要な重要な情報。たとえば、主要な制約、例外、境界、特別なセマンティクスなど。S は最初の 3 つのフィールドを繰り返すべきではありません。

たとえば、===.../internal/fs/=== ディレクトリセクション内では、エントリはベース名を使用します。

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 

ディレクトリセクションとベース名は、コードオブジェクトの同一性に解決されます。クロス Volume またはシステム投影の場合、code:internal/fs/atomic.go のような正規の同一性に展開されます。データベースオブジェクトは、database://primary/public/orders のような独自の正規の同一性を使用します。

エントリには 2 つの部分があります。

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

簡潔なタグは、各オブジェクトにアーキテクチャ層、機能ドメイン、重要度、オプションの技術的特性、およびサイズの座標を与えます。タグ辞書はプロジェクトの Meta Volume または Legacy ヘッダーによって定義されます。プログラムは辞書と構造を検証しますが、ビジネス上の意味を決定するわけではありません。

S は要約でも、通常のまとめでも、F、R、A の繰り返しでもありません。 最初の 3 つのフィールドではカバーされず、理解やエンジニアリングの正確性に影響する重要な情報を追加します。たとえば:

• Redis アクセス障害はデータベースにフォールバックする必要がある;
• 特定のテーブルは AutoMigrate に入れてはならない;
• レガシー互換性ブランチは通常のクリーンアップで削除してはならない;
• 書き込み失敗後も元のファイルを保持する必要がある。

モデルはこれを実際のソースコードと証拠から書きます。AOCI-CODE はエントリの構造を検証し、それをソースファイルにバインドし、正式なインデックスへの入り方を統治します。

スタータータグ辞書の読み方

以下の抜粋は、現在の en-US Volume Meta テンプレート (textassets/en-US/templates/volume-meta.txt.tmpl) からそのままコピーしたものです。これはスターター辞書であり、普遍的な語彙ではありません。各リポジトリの正式な Meta が引き続き権威です。スターターは D 辞書を宣言していません。D はオプションの軸のままであり、現在の正式な Meta が宣言した場合にのみ使用できます。

#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

スターターコード辞書の下では、[CG9L] は C SharedFoundation、G CrossDomain、9 最高重要度、L 大規模を意味し、D 値は存在しません。これは既存のエントリをどのように読むかを説明するものであり、モデルがタグをどのように割り当てるべきかではありません。モデルは引き続き、ソースと受け入れられた証拠に基づいて、現在のプロジェクト Meta からタグを選択します。

Cognition Volumes

AOCI-CODE は 1 つの論理的な Whole-Index を維持しますが、各種類のインデックスには独自のファイル、所有権、およびライフサイクルがあります。

各オブジェクトには、ちょうど 1 つの有効な所有者があります。オブジェクトを誤った Volume に配置すると、所有権の競合が発生します。AOCI-CODE は、マシンが誤った所有者、正しい所有者、および現在のオブジェクトの事実を証明できる場合にのみ修復します。類似した名前から所有権を推測することはありません。

Code Volume、Database Volume、およびスコープは一緒に進化できますが、1 つの統治されたコミット境界を共有します。1 つのドメインを適用しても、別のドメインの既存の Baseline 投影を破棄してはなりません。Volume の適用、Baseline の更新、および関連するスコープ投影は、1 つの一貫したトランザクション結果として公開されるか、証明可能なリカバリに入ります。「ファイルは成功したが別の Volume にベースラインがない」という半端な状態を残すことは決してありません。

ホスト統合

aoci init は常に管理対象のエージェントルールを書き込みますが、ホスト統合は異なります:

• Codex はプロジェクトレベルの MCP 設定を取得し、--hooks を指定するとコンテキスト圧縮プロンプトと SessionStart(compact) を取得します。それでもファイル編集フックはインストールしません。
• Claude Code は PreToolUse フックをインストールできます。
• OpenCode V1 は厳格なプロジェクトレベルの opencode.json を取得します。
• Cursor は参照設定スニペットを返すだけで、プロジェクトには何も書き込みません。

設定後、現在のホストセッションがすでに AOCI ツールを公開しているか確認してください。新しいサーバーを読み込んでいない場合にのみ、そのプロジェクトセッションを更新または再オープンしてください。新しいセッションは通常、ルールと Whole-Index を 1 回読み込みます。インデックスの同一性が有効なままで、既知のホスト圧縮が発生していない限り、以降のタスクはモデルがすでに持っているものを再利用します。インデックス全体が機械的に再注入されることはありません。

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 は、圧縮ハンドオフをレシートの同一性、未完了の書き込みまたはリカバリ状態、および即時の再読み込み指示に限定します。Whole-Index または Overview/Attestation の本文を保持または要約してはなりません。PreCompact フックは、ホストの圧縮入力に注入したり、そこから履歴を削除したりすることはできないため、これだけでは強制できません。依存する前に、Codex /hooks を介してインストールされたプロジェクトフックをレビューして信頼してください。

Legacy 出力は、既存のホストおよびレポートとの互換性のためにレベル 0〜4 を保持します。現在の cognition-state/v2 は、モデルのシステム像がどれだけ使用可能かをレベル 0〜3 として表現し、厳格な証明とガバナンスの事実を独立した次元に分離します:

これらの次元は互いの代わりにはなりません。Attestation は現在の素材に対する配信カバレッジと同一性の一貫性のみを証明し、エージェントがすべての可能な将来のタスクを完全に理解したことを意味するものではありません。current_system_cognition_reliable=true のみが、完全な現在システム理解の無条件の主張を許可します。

AOCI パネル

aoci ui はこのマシン上で読み取り専用パネルを提供するため、エージェントに尋ねることなくインデックスの状態を確認できます:

• インデックスヘッダーと Code / Database Volumes をそのまま表示 (=== セクション行はそのまま保持され、フィルタ可能、全体としてコピー可能)。「All」タブは、エージェントが Overview を介して受け取るのとまったく同じ完全なインデックスです
• 予算に対するインデックストークン、および Overview チャンクプラン
• インデックスがカバーするコード量: ファイル、行、トークン、および圧縮率。データベーステーブルの数
• ガバナンス状態とドリフト、Managed Scope、ホスト統合、および実行中の aoci mcp プロセス
• 次にエージェントに与えるコマンドとプロンプト (コピーボタン付き)

ページは中国語と英語を切り替えられます。更新間隔は選択可能です (デフォルトは 30 秒)。

1 つの WSL 内に複数の aoci mcp サーバーがある場合? Linux および WSL では、パネルは現在のユーザーのすべての aoci mcp プロセスとそのリポジトリを検出し、上部のタブでそれらを切り替え、ディスク上でバイナリが置き換えられたサーバーにマークを付けます。 境界: ループバックアドレスのみにバインドし（それ以外のバインドは拒否される）、GET と HEAD のみに応答し、ロックを取得せず、台帳に何も追記せず、リポジトリのいかなるバイトも変更しない。これは aoci mcp とは無関係の別プロセスであり、MCP サーバーは依然としてソケットを開かない。バックグラウンドパネルの登録はユーザーのキャッシュディレクトリに存在し、リポジトリには決して置かれない。

一般的な CLI コマンド

一般的な組み合わせ:

# 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

Plan、Stage、Check、Diff、Apply、Curation、Scope Change、Bootstrap、Migration、および復旧コマンドは引き続き存在する。実行中のバイナリが返すガイドに従うこと。内部状態機械をスクリプトにコピーしないこと。

「読み取り専用」コマンドについて

verify、check、index score、index inventory において、「読み取り専用」とは正式なインデックスと Baseline が変更されないことを意味し、ファイルシステムへの書き込みが厳密にゼロであることを意味しない。Ledger が有効な場合、これら 4 つのコマンドはすべてローカル Ledger に追記する可能性があり、verify はさらに Verify History の書き込みを試みる。監査書き込みの失敗は、既存の終了コードやガバナンス基準を変更しない。

厳密なゼロファイル書き込みの操作が必要な場合は、分離されたコピーを使用すること。現在の公開 CLI は、すべての Ledger および Verify History の書き込みを無効にする包括的なスイッチを公開していない。System Cognition コマンドは第二の正式状態を作成しないが、通常の CLI 呼び出しは依然として現在のバージョンの Ledger およびローカル履歴レコードに関するランタイム契約に従う。

MCP サーバー

aoci mcp は常駐デーモンを必要とせず、stdio 経由で正確に 9 つのツールを公開する:

MCP モードでは、stdout は JSON-RPC 用に予約され、ログと診断は stderr に出力される。実行中のバイナリが提供するツールの説明、JSON スキーマ、およびマシン状態の値が権威であり、この README は出発点にすぎない。

現在のリリースは、既存の CLI とガバナンスカーネルを通じて System Cognition 機能を提供する。それらは 10 番目の MCP ツールを追加したり、既存の 9 つの名前、目的、または stdio 契約を変更したりしない。

長時間セッションと Whole-Index 配信

新しい会話の開始時に、エージェントは通常、現在のリポジトリ、インデックスバージョン、および AOCI サービスアイデンティティに一致するシステム像を得るために、完全な Overview を 1 つ読み込む。モデルがその像に依然として依拠できる間は、各タスクやツール呼び出しの前に再読み込みする必要はない。

同じ会話内では、モデルは既知のホストコンテキスト圧縮の後を除き、自身の状態に基づいて再読み込みするかどうかを決定する。圧縮されたハンドオフは、レシートのアイデンティティ、未完了の書き込みまたは復旧状態、および即時の再読み込み指示のみを保持してよい。Whole-Index または Overview のヘッダー、エントリ、チャンク、チャレンジ、またはアテステーションの本文を保持または要約してはならない。そのハンドオフにコピーされたインデックス内容やレシートは、モデルの現在の像が信頼できることを証明できない。

既知の圧縮後に業務作業を続ける前に、エージェントはルールがもはや確実に存在しない場合はルールを再読み込みし、新しいイベント ID で context_compaction を宣言し、通常の完全な Overview カーソル、確認、およびアテステーションのシーケンスを 1 回完了する。check_only と cognition probe は代替にはならない。新たな完全なトランスポートの後、既存の部分的なまたは失敗したアテステーションのルールは、2 回目の自動 Overview なしでのソースに束縛された継続を依然として許可する。既知の圧縮を伴わない意味的変更または主要なフェーズ境界については、AOCI がリフレッシュしきい値、チェックポイント、およびアイデンティティファクトを提供し、モデルはタスクのためにシステムレベルの像を復元する必要があるかどうかを決定する。

各完全な Overview の本文は、開始マーカー、現在の正式インデックスの正確な内容、および終了マーカーで構成される。

Overview がプロジェクトのチャンク予算を超える場合:

1. 配信はチャンク 1 から直ちに開始される。
2. エージェントは最終チャンクまで next_cursor に自動的に従わなければならない。
3. エージェントは配信された Whole-Index を使用して 1 つのアテステーションを提出する。
4. ローカル検索、古い記憶、補足ソースの読み取り、または直接のファイル読み取りを完全な配信として提示してはならない。
5. 保留中の復旧または不整合なスナップショットは、内容を混在させることなくフェイルクローズする。

overview_delivery.chunk_tokens は唯一の配信サイズ設定である。デフォルトは 7000 で、有効範囲は 4000 から 24000 である。check_only=true はチャンクチェーンを持たないコンパクトなチェックポイントである。

AOCI は aoci_overview 上でツールごとの結果サイズ許容量を宣言する。そうでなければ大きなツール結果をディスクに永続化し、モデルのコンテキストにはプレビューだけを置くホスト（インデックス配信にとってはサイレントな失敗）は、このツールのみに対してそのしきい値を引き上げる。Claude Code では、これにより完全な 24000 が使用可能になり、480 オブジェクトのインデックスを 5 チャンクではなく 3 チャンクで配信する。何もプローブされない。宣言は静的であり、それを認識しないホストは MCP 仕様が要求するように無視する。

リフレッシュしきい値はデフォルトで 30 個の異なるセマンティックパスであり、プロジェクトごとに構成することもできる。正確なカウント規則については、Cognition Refresh のドキュメントとランタイム契約に従うこと。

Database Cognition

AOCI-CODE は、明示的で狭いアクセス境界をもって、データベース構造を同じインデックスと同じガバナンスの下にもたらすことができる:

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

• データベースが構成されていない場合、または明示的なデータベースコマンドが実行されていない場合、データベースネットワークアクセスは発生しない。
• 読み取られるのはベーステーブルのスキーマメタデータのみであり、業務行は読み取られない。ビュー、ルーチン、およびコメントは現在の収集スコープ外である。
• DDL または DML は実行されない。
• ホスト名、ユーザー名、DSN、および資格情報の値は、インデックスファイルに決して書き込まれない。
• Database Cognition の適用はオフラインで実行され、書き込み中にデータベースへ再接続しない。
• プログラムは構造的エビデンスを保持および比較するが、テーブルの責務、関係、および高価値の制約は依然としてモデルが記述する。

MySQL サポートは 5.7.6 以降を対象とする。コレクターはサーバーバージョンを読み取り、そのリリースが応答できるカタログクエリのみを実行する: CHECK 制約は 8.0.16 から、インデックス式は 8.0.13 から、インデックス可視性は 8.0.0 から。5.7 サーバーは空のチェックリストを記録する。5.7 は CHECK 構文を解析するが何も保存しないためである。エビデンスはサポートされるすべてのリリースで同じ形状を持つ。MariaDB はサポートされず、MySQL として読み取られるのではなく拒否される。

初期の openGauss プロファイルは、A/PG 互換モードの openGauss 6.0.5 LTS および通常の非パーティション化ベーステーブルに意図的に限定されている。サポートされないカタログ機能は、PostgreSQL のファクトへ黙って縮小されるのではなくフェイルクローズする。これは MogDB、GaussDB、Dolphin/B/MySQL モード、パーティションまたはサブパーティション、カラムストア、MOT、外部テーブルまたは一時テーブル、ビュー、ルーチン、またはトリガーのサポートを主張するものではない。

ここで、フェイルクローズ検出は、サポートされないセマンティクスを持つ選択された可視のテーブル様オブジェクトに適用される。ルーチンとトリガーは v1 のテーブルオブジェクトドメイン外のままであり、テーブルファクトとして表現されることは決してない。

openGauss の経路は、公式 Connector v1.0.8 ソースに対する AOCI のレビュー済みローカルパッチを使用する。その厳格なパーサーはレビュー済みの接続パラメータのみを受け入れ、周囲の PG*、サービス、パスワードファイル、ホームディレクトリ、またはロガー構成を消費しない。数値ループバックアドレス外の TCP 接続は、明示的に sslmode=verify-full を使用し（および提供される場合は sslrootcert 内の絶対信頼ルートパスを使用し）、TLS 1.2 を最小とする必要がある。TLS ダウングレードモードは拒否される。sslmode=disable は、ローカル/テスト境界として使用される明示的な Unix ソケットまたは数値ループバックアドレスに対してのみ受け入れられる。データベース管理者は、その DSN を会話外で提供し、最小権限アカウントをプロビジョニングする責任を依然として負う。

Database Volume はデフォルトでは存在しない。プロジェクトが Database Cognition を明示的に有効化し、エビデンス、バインディング、およびライフサイクルガバナンスを完了した後にのみ、Whole-Index に入る。

データベースアクセスのオンボーディング: DSN の詳細を理解する必要はない

データベースソースに対して非機密のアイデンティティを宣言するだけである。--credential-env が省略された場合、AOCI はソース ID から安定した環境変数参照を導出する。たとえば、primary は AOCI_DB_PRIMARY_DSN にマップされる:

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

次に、読み取り専用のアクセスプリフライトを使用して、外部環境がその参照を提供しているかを確認する:

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

このコマンドはデータベースに接続せず、資格情報の値を返さず、DSN を会話に貼り付けるよう求めない。データベースまたはインフラストラクチャの管理者が、AOCI プロセスの外部で環境変数を提供し、システムカタログへの読み取り専用の最小権限アクセスを付与する。ソース構成は資格情報の参照名のみを保存し、シークレットは保存しない。

現在のリリース候補は環境資格情報プロバイダーのみを提供する。Vault、Kubernetes Secret、AWS/GCP/Azure などのクラウドシークレットマネージャーは、将来のバージョンで同じプロバイダー境界を通じて統合される可能性がある。これらは今日利用可能ではなく、この README はそうでないことを示唆しない。 この分割により、アカウント形式、DSN エンコーディング、シークレットのライフサイクル管理を一般ユーザーから切り離しつつ、認可を明示的に保ちます。AOCI は認証情報を自動検出したり、.env をスキャンしたり、シークレットファイルを読み取ったり、データベース管理者の認可境界を迂回したりしません。

システム認知の基盤

コードとデータベースのインデックスの上に、AOCI-CODE は一連の派生したシステム認知の観測結果を提供します。これらは「このオブジェクトはどこから来たのか?」「データベースの変更が影響を与える可能性のあるコードオブジェクトはどれか?」「過去の観測時点と現在の間で何が変わったのか?」といった問いに答えます。これらは権威ある事実の新しい層を作り出すものではありません。

# 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

権限の境界

すべてのシステム認知の結果は derived=true を報告し、関係の投影はさらに authoritative=false を報告します。Cognition Volume、スキーマのエビデンスバインディング、Baseline のフィンガープリント、レシートに紐づく識別子が引き続き基盤となる権威です。未解決の R 関係は不完全な結果または診断情報を生み出します。プログラムは推測して補完することはありません。

AOCI-CODE はナレッジグラフシステムではありません。 限定的な関係の投影は便利な関係ビューですが、第二の状態管理システム、独立した書き込み経路、新しい事実ストアを所有するものではありません。派生した出力は削除し、現在の権威ある資産から再計算できます。投影が権威ある資産と矛盾する場合、資産が優先されます。

実行モード、プライバシー、データ境界

• AOCI-CODE はデフォルトでローカルファーストであり、デフォルトのクラウドエンドポイント、ホスト型のソースアップロードサービス、必須のバックグラウンドサーバーはありません。
• Agent-native モードでのデータの取り扱いは、選択したホストとその製品ポリシーに依存します。AOCI-CODE はホストに代わってデータをアップロードしません。
• データベースへのネットワークアクセスは明示的にトリガーする必要があり、読み取り専用のスキーマメタデータに限定されます。
• 台帳、下書き、トランザクション、復旧エビデンスはデフォルトで .aoci/ の下に保存され、通常は Git によって無視されます。インデックスファイルとチームガバナンス資産は Git にコミットできます。
• システム認知の投影は既存の権威ある資産からローカルで計算され、グラフデータベース、ベクトルデータベース、リモートグラフサービスを必要としません。

リポジトリマップ、RAG、LSP、コードグラフとの違い

検索、AST、LSP、コードグラフ、RAG は構造的および検索に関する問いに優れています。AOCI-CODE は別の仕事をします。すなわち、管理対象スコープを網羅し、ソフトウェアとともに段階的に進化する、システムのバージョン管理された記述を維持します。得られるものは次のとおりです。

• Whole-Index。 タスクごとにその場で組み立てられた断片ではなく、現在の管理対象スコープを網羅する単一のシステムマップ。
• FRAS エントリ。 index の役割を持つすべてのオブジェクトについての責務、強い関係、公開契約、価値の高い制約。
• セッションをまたぐ永続性。 インデックスファイルはリポジトリとともに存在するため、後のセッションや他のエージェントが同じバージョンを再利用できます。
• 管理対象スコープ。 どのオブジェクトがインデックスに入り、どれが変更の観測のみを受け、どれが意図的に除外されるかの明示的な記録。
• ドリフト検出。 Missing、Orphan、Stale、Unbaselined、行末の変更、キュレーションの差異、作成対象から除外されたソース(空、バイナリ、サイズ超過)を区別します。
• ガバナンスされた更新。 候補はソースバインディング、計画、検証、レビュー、CAS、アトミック書き込み、Baseline、復旧のワークフローを通じて正式なファイルに入ります。
• 配信の証明。 チャンク、カーソル、レシート、チャレンジによって、Whole-Index が完全に配信されたことを証明します。
• データベース認知。 明示的に受理された PostgreSQL/MySQL/openGauss のスキーマエビデンスから構築・ガバナンスされるテーブルレベルのエントリ。
• システム投影。 権威あるインデックスとそのバインディングから派生した Lineage、限定的な Relations、データベースからコードへの Impact、Snapshot、Evolution の観測結果であり、権威ある状態を複製しません。Impact はモデルが作成した明示的な R 関係のみをたどります。

AOCI-CODE は既存のツールを置き換えるのではなく補完します。

推奨される組み合わせ:AOCI-CODE がグローバルな意味論的事前情報を提供し、コードグラフ、LSP、検索、ソースが正確なエビデンスを提供し、テストと実行結果が最終的な受け入れを提供します。AOCI の Relations 投影は正確なコールグラフを置き換えるものではありません。構造的な Volume の包含関係と Root の依存エッジを公開し、その意味論的エッジはモデルが明示的に作成した強い関係に限定されます。

技術スタック

AOCI-CODE は Neo4j、ベクトルデータベース、長時間稼働するデーモン、AOCI クラウドサービスを必要としません。データベース認知が有効な場合、対象データベースはスキーマエビデンスの明示的な読み取り専用ソースにすぎず、AOCI 自身の状態ストアではありません。

FAQ

Legacy の status --deep でまだドリフトが表示されるのはなぜですか?

status --deep、index score、index agent plan は Legacy 専用です。Cognition Volumes リポジトリの場合は、ライブガイドを実行し、ホストに通常の引数なしの aoci_maintain を使わせ、完全な現在のバッチを aoci_update_entry を通じて提出し、Verify、Check、ガイドで締めくくってください。Baseline を直接変更したり、ソースバインディングや復旧の手順を省略したりしないでください。

Legacy レイアウト自体は非推奨です。Volumes v1 は新規および移行済みリポジトリでサポートされる経路であり、Legacy 専用コマンドは v0.2.0 で削除が予定されています。それまでに aoci cognition migration で Legacy リポジトリを移行してください。

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

ホストが誤った AOCI を起動したのはなぜですか?

プロジェクトレベルの MCP 設定にある実行ファイルのパスを確認し、それが安定した絶対パスであることを確かめてから、次を実行してください:

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

ディスク上のファイルだけでなく、読み込まれた stdio サーバーを検証するには、ホストプロセスの実際の実行ファイル、そのコマンドライン --repo、再起動後のプロセス識別情報も確認してください。

データベースアカウントを作成し、DSN を自分で提供する必要がありますか?

DSN の構文を理解する必要はなく、チャットでシークレットを送るべきでもありません。機密性のないソース識別情報を宣言すると、AOCI は安定した環境変数参照を提供します。データベース管理者は依然として、読み取り専用のシステムカタログアクセスを持つ外部の最小権限アカウントを作成し、その参照をランタイム環境に提供する必要があります。現在のバージョンは、組織に代わってデータベースアカウントを作成したり、シークレットストアを自動的に読み取ったりしません。

CI で実行できますか?

はい。スキャン、検証、ガバナンスゲート、決定論的チェックは、新しいエントリを書き込むことなく実行されます。正確なコマンド、監査書き込み、終了コードについては、現在のバイナリの --help、JSON スキーマ、プロジェクトの CI ドキュメントに従ってください。

AOCI の結果がすべてグリーンであれば、セマンティクスが正しいことの証明になりますか?

いいえ。グリーンの結果は、エンコードされた構造的およびガバナンス上の条件が成立していることを証明するだけです。モデルが書き込んだ内容は、依然としてソースコード、スキーマ、テスト、実行結果、人間のレビューと照らし合わせて確認する必要があります。

システム認知のグラフは新しい信頼できる情報源ですか?

いいえ。現在の機能は限定的な関係の投影であり、独立したグラフプラットフォームではありません。正式なインデックス、エビデンス、レシート、Baseline のみから結果を計算し、新しい権威ある事実を永続化しません。また、プログラムはインポート、SQL、ファイル名、類似性から意味論的な関係を自動的に生成することもありません。

ドキュメント

ドキュメントおよび公開契約へのリンクは v0.1.0-rc22 に固定されているため、 この README がバイナリリリースアーカイブから読まれた場合でも有効なままです。 バイナリリリースアーカイブにはリポジトリの docs/ や spec/public/ ディレクトリは含まれません。

ブラックボックス検証スイート

リポジトリには、ビルド済みの aoci バイナリをプロセスの外部から厳密に、公開 stdio MCP プロトコルと CLI のみを介して検証する 4 つの独立したブラックボックススイートが scripts/blackbox/ の下に同梱されています。

• プロトコル適合性 — MCP ワイヤーサーフェスの 53 の読み取り専用チェックで、 ロケール依存の文は zh-CN の下で繰り返されます。
• 障害注入シナリオ — 使い捨てのフィクスチャリポジトリ上で、カーソル改ざん、 クラッシュリカバリ、ライターの競合、書き込み前フックをカバーする 75 のシナリオ。
• 凍結された実プロジェクトに対するライフサイクル — コミット済みの 3 つのフィクスチャプロジェクト: repo-a (TypeScript) と repo-b (Python + MySQL) は init から再整合までのライフサイクル全体を実行し、repo-c (453 ファイルの階層型サービス) はさらにマシンのバッチ上限でのマルチバッチオーサリングを駆動します。オプションの モデルトラックでは、実際の AI エージェント — お使いの OpenCode インストールが公開する任意のモデル — を 2 つの小規模リポジトリに通し、公開サーフェスから最終状態を採点します。
• アップグレード軸 — リリース済みバージョンごとに 80 のチェックを、10 種類のリポジトリ 形状にわたって実行します。公開された各リリースは自身のバイナリでリポジトリをビルドおよびオーサリングし、 その後テスト対象のバイナリがアイデンティティを移動させたり、スコープ変更を要求したり、正式なアセットを 書き換えたりすることなくそれを統治しなければならず、さらにそれがオーサリングする内容は別パスの チェックアウトを整合したまま保たなければなりません。10 番目の形状では役割が反転し、 公開された各リリースはテスト対象のバイナリが書き込んだリポジトリを、クラッシュや書き換えなしに 読み取らなければなりません。他の 3 つのスイートはすべてのフィクスチャをテスト対象のバイナリで 生成するため、バージョン間で変化したプリイメージは構造上それらには見えません。

これらはビルド済みバイナリに加えて Python 3 と git のみを必要とします (MySQL スイートには Docker、モデルトラックには OpenCode とご自身のモデルサブスクリプション)。したがって リポジトリのクローンは自身のビルド、プラットフォーム移植、またはフォークを検証でき、 AOCI_BIN は適合性スイートとシナリオスイートを、spec/public/ の公開契約を主張する任意の代替 バイナリに向けることができます。これらのスイートはリポジトリのクローン内に存在し、バイナリリリースアーカイブには含まれません。コマンドと 結果の解釈については scripts/blackbox/README.md を参照してください。

リサーチ、知的財産、およびライセンス

AOCI-CODE の研究論文および成果物は、公開された手法、実験プロトコル、および結果を公に記述することがあります。特許出願、付与された範囲、法的地位、所有者、および領土的効力は法的な事実であり、内部 README、過去のバージョン番号、または未検証の伝聞に基づいて製品説明に追加すべきではありません。

将来、特定の特許番号、付与日、または範囲を開示する必要が生じた場合、権利者および法務顧問は公式の公開記録に対してそれを検証し、専用の IP、NOTICE、または法的文書に記載すべきです。この README はその権威あるファイルへのリンクのみを行うべきであり、特許の範囲を自ら拡張したり、特許の状況をソフトウェアライセンスとして提示したりすべきではありません。

コミュニティ

WeChat または WeCom (企業微信) でコードをスキャンして AOCI プロジェクトグループに参加し、メンテナーや他のユーザーと話してください。バグレポートと機能リクエストは検索可能な状態を保つために GitHub issues として提出し、疑わしい脆弱性は SECURITY.md に記載されているとおりに非公開で報告してください。グループ内では決して報告しないでください。

AOCI-CODE は、エージェントにさらに多くのコードを見せることではありません。それは、あらゆる行動の前に、エージェントにシステムについての最新で、構造化され、追跡可能で、統治された理解を与えます。Git はコードをバージョン管理し、データベースマイグレーションはデータ構造をバージョン管理し、AOCI-CODE はエージェントがシステムについて知っていることを、その知識がどのように進化するかの追跡可能性、統治の一貫性、およびリカバリ境界とともにバージョン管理します。