AIコーディングエージェントを1つだけ使っているうちは、指示や覚えたことをそのツールの設定に閉じておけば済む。ところが Codex、Gemini CLI、Antigravity を併用し、しかも Windows / Linux / macOS の複数マシンを行き来するようになると、話が変わってくる。あるエージェントに教えた規約を、別のエージェントは知らない。あるマシンで直したルールが、別のマシンでは古いまま残る。

agent-cortex は、このずれをなくすための個人的なリポジトリだ。README には「エージェントの自律学習データ、コーディング規約、カスタムスキル、およびツール実行の自動承認許可リストを複数マシン間で自動同期するリポジトリ」とある。いわば、エージェント個別の記憶ではなく、エージェントの外側に置いた共通の脳である。

この記事では、公開できる範囲でその設計の考え方を整理する。設定ファイルの原文や運用の詳細ではなく、構造と思想の部分だけを取り上げる。

入口は薄く保つ

各エージェントには、それぞれが最初に読む入口ファイルがある。Codex 向けは AGENTS.md、Antigravity 向けは GEMINI.md で、どちらも 1KB 程度の小さなファイルだ。

中身はルールの本文ではなく、索引に徹している。「常時適用ルールは rules/global_rules.md を読むこと」「プロジェクト作業では現在のワークスペース側の指示を優先すること」「バックアップは必要箇所だけ参照すること」といった、読み込み方そのものの指定が中心になる。

入口を厚くしない理由は単純で、起動時に毎回読み込むものは、コンテキストをそのまま消費するからだ。本文を入口に詰め込むのではなく、入口は入口として分離し、実体は必要になったときに辿る。この割り切りが全体を通して貫かれている。

常時適用ルールは1ファイルに絞る

共通ルールの実体は rules/global_rules.md の1ファイルだけに集約されている。ここに入るのは、どのマシン・どのプロジェクトでも常に効かせたい行動原則だけだ。

たとえば、質問や相談と編集の許可を区別すること、破壊的な操作を避けて事前に影響と復旧手段を確認すること、推測で機能や抽象化を足さず単純な解法を優先すること、再利用できる訂正だけを記録し履歴を積み上げないこと。いずれも「毎回効いていないと困る」性質のものに限られる。

逆に、過去の技術レシピや詳細な作法は常時適用から外し、旧版ルールのアーカイブとして knowledge/archive/ に退避している。アーカイブは参考資料であって強制標準ではない、という位置づけも明記されている。ルールを増やすことよりも、常時読み込む量を増やさないことの方を優先する設計だ。

skills / knowledge / projects の3層構造

入口とルールの先は、性質の違う3つの置き場に分かれている。

1つ目は skills/。再利用できる作業手順をスキル単位で収めた場所で、現在は90を超えるフォルダがある。重要なのは、スキルは起動時に全部読むものではないという点で、使うスキルの SKILL.md だけを、そのときに開く。

2つ目は knowledge/。技術的な知識やトラブルシュートの記録をトピック別に分けたもので、archive、network、oci、projects、proxmox、vrchat といったフォルダ構成になっている。障害対応の経緯や具体的なレシピは、常時ルールではなくこちらに置く。解決済みの事象をルールに混ぜないための受け皿である。

3つ目は projects/。各ワークスペースの指示ファイルを自動収集したバックアップ置き場だ。ここは特に扱いが明確で、同期バックアップであり、起動時に読み込むためのものではない。ファイルによっては非常に大きくなるため、まず projects/INDEX.md で章別の索引を引き、該当プロジェクトの必要な passage だけを確認する運用になっている。「Never load all project backups」という注意書きが入口ファイル側にもあるくらい、この点は徹底している。

つまり、常時読むもの(rules)、必要時に引くもの(knowledge / skills)、非常時の参照用バックアップ(projects)という、読み込み頻度と寿命で層を分けている。

同期は Git とスケジューラで回す

共有の仕組み自体は凝ったものではなく、Git が土台になっている。各マシンでは Windows ならタスクスケジューラ、Linux / macOS なら Cron が定期的に同期スクリプトを回し、ルールや知識やスキルをリモートと揃える。手動で同期したいときのために、同期そのものを担当するスキルも用意されていて、「同期して」「並列化して」といった依頼でスクリプト実行と結果確認までを担う。

Codex 向けには接続用の仕組みもあり、各マシンの Codex 用指示ファイルに、共有 AGENTS.md を参照するブロックを冪等に追加する。既存の指示は保持され、再実行してもブロックは増えない。入口を各ツールに合わせて薄く用意し、実体は1か所に寄せるための配線である。

なお、同期されるものの中には権限設定も含まれるが、これはエージェント間で自動的に流用されるわけではない。Antigravity の許可リストが Codex のツール実行を許可するものではない、という線引きも入口に書かれている。共有することと、権限まで共有することとは別だという意識がうかがえる。

タスク終了時に知識を棚卸しする

もう1つの柱が、タスク終了時の知識レビューである。Codex の Stop フック、Gemini CLI の AfterAgent フック、Antigravity の Stop フックから、共通スキル knowledge-maintainer をタスクごとに一度だけ呼び出す構成になっている。

このレビューでやるのは、新しく得た知見のうち「持続するもの」だけを選別することだ。新しい事実、誤っていた前提の訂正、長く効くプロジェクト判断、再利用できる障害対応策が候補になる。一時的なログや時刻、未確認の主張、秘密情報や個人データは捨てる。既存のルールや知識を先に検索して重複を避け、置き場所は性質で振り分ける。横断的な行動原則は共通ルールへ(ただし稀)、プロジェクト固有の現行方針はワークスペースの指示へ、詳細な技術や事象はトピック別の knowledge へ、という具合だ。

大事なのは、学ぶことがなければ何も保存しないのが正常な結果とされている点と、レビュー自体は読み取り専用で、書き込みは既存の承認ルールの範囲でしか行わない点だ。学習のために勝手にコミットや Push や同期をしてはいけない。知識を増やす仕組みが暴走しないよう、出口にブレーキが付いている。

まとめ

agent-cortex の設計を一言でまとめると、「全部覚えさせる」のではなく「読む量を制御する」ための仕組みだと思う。

入口は薄く、常時ルールは1ファイルに絞り、知識とスキルは必要時にだけ引き、巨大なバックアップは索引経由で部分参照する。そしてタスクの終わりに一度だけ棚卸しをして、残す価値のあるものだけを適切な層へ戻す。

エージェントの性能が上がるほど、与える情報の量よりも、どの情報をいつ渡すかの設計の方が効いてくる。このリポジトリは、その制御を Git とファイル構成という素朴な手段で実現しようとした試みである。