AIエージェントの記憶・知識管理設計（昇格・重複検知・保存ポリシー）

AI エージェントにプロジェクト記憶やナレッジ層（設計判断・手順などの蓄積ドキュメント）を読ませる機能の設計。蓄積データをセッション開始時に全文注入するとトークンコストが蓄積量に比例して増え、既存の常時読み込みファイル（グローバル指示ファイル／システムプロンプト等）との二重管理問題も生む。その改善として「開始時にタイトル+要約のインデックスを全件注入し、本文はオンデマンド取得」という階層化を採っても、蓄積が増えると同じ形で破綻する。数十件規模の実運用で、インデックスだけが毎セッション数千トークンを占め、しかも活用されないことを確認した。

インデックス注入の破綻の症状

• インデックスは件数に比例して単調増加し、常時注入コストが頭打ちにならない。
• 蓄積の大半は決着済み・再発しない案件になり、将来セッションの文脈価値がない項目が active な項目と同列に並ぶ。
• 「常時適用の少量指示」用の器が空のまま、目次のはずのインデックスが事実上の常時注入コンテンツになる逆転が起きる。
• 開始時に一覧を見せても、数週間後の関連する判断の瞬間にエージェントがそれを想起する保証がない。読ませているのに使われない。

実測による方針更新: 主経路は検索ではなく昇格

当初は「常時層は最小に保ち、取得層＝判断の瞬間のセマンティック検索」を主経路とした。数百件規模まで蓄積が育った時点で実測したところ、この主経路は機能していなかった。

• 横断的な蓄積（数百件規模）は、検索ツールが用意されていても日常の作業でほぼ引かれない。実際に引かれるのは重複判定など書き込み側の処理だけになり、蓄積層の唯一の読者が重複判定器になる。
• 同じ期間に実際へ効いていたのは、蓄積から常時適用される規約ファイルへ転記された少数だけだった。運用ルールとして毎ターン効いている項目を遡ると、いずれも元は蓄積メモで、人手で規約へ昇格させたものだった。
• したがって「昇格」は当初考えたような参照カウントの副次的な観測結果ではなく、設計すべき主経路である。蓄積システムには capture（会話→記録）の対になる promote（記録→常駐規約）の段を明示的に置く。

検索経路が成立する3条件

検索が無効なのではなく、成立条件が厳しい。次の3つが揃うスコープでのみ機能する。

1. 母集団が小さい（数十〜百件台）。数百件規模の横断集合では候補がぼやけて引く価値が落ちる。
2. 発火点が具体的で頻繁（「設計判断を書く前」など、ワークフローの手順自体に埋め込める瞬間）。
3. 引かなかったときの失敗が即座に可視（却下済み案の再提案、過去の決定との矛盾など）。

単一プロジェクトの設計判断記録はこの3条件を満たし、実運用でも機能している。横断的な原則層は 1 と 3 を満たさないため、検索ではなく昇格で届ける。

階層化の設計（改訂版）

• 常時読み込み層: 毎セッション必ず適用すべき少量の恒常指示のみ。昇格の着地点であり、意図的に小さく保つ（実質10〜20行が上限）。応答トークン量を蓄積件数に非依存にする。
• 昇格層: 蓄積から常時層へ持ち上げる工程。人手でも定期バッチでもよいが、経路として明示的に存在させる（下記の設計要件を参照）。
• 取得層: 上記3条件を満たすスコープに限ってセマンティック検索ツールを提供し、取得の引き金は計画起草・設計検討のワークフロー側へ埋め込む。ルールで「読め」と言うより、発火点が明確な手順に検索を組み込む方が確実に効く。
• 本文層: ID 指定の取得ツールでオンデマンドに読む。
• ライフサイクル: archived 相当の状態を入れ、決着済み・上書き済みの記録をデフォルト検索対象から外す。検索では明示オプトインで引ける形にし、監査証跡としては残す。

昇格の設計要件

• 転記ではなく圧縮。蓄積側の数百字を規約側の1〜3行に畳む工程が本体。原文のコピーは常時層をすぐ食い潰す。
• 1件1行ではなくクラスタ1行。似た原則を束ねてから畳む。
• 既存規約本文との重複排除。突き合わせないと既に書いてある内容を繰り返し提案する。
• ゼロサム運用。追加提案と同時に「畳める／もう不要」も出す。常時層が膨らむとモデルが規約全体を守らなくなるため、枠は実質固定と扱う。
• 選抜基準は「破ると実害が出る」×「モデルが素の状態では守らない」の2条件。片方だけの項目を入れると常時層が薄まる。
• 昇格はプル型（定期バッチ）でよい。毎タスク発火が要る検索と違い、常時効いてほしいのは出力物である規約の側で、そちらは自動的に文脈へ載る。

昇格運用の落とし穴

• 昇格先が他システムの管理ブロック内だと、更新で消える。規約ファイルをツールが版管理付きで書き換える方式を採っている場合、昇格した項目は管理ブロックの外か、別マーカーの専用ブロックに置く。
• 「昇格済み」の状態を蓄積側が持たないと、同じ項目を毎回提案する。昇格先が外部ファイルで書き込み確認が取れない構成ほど、この状態管理が要る。
• 状態管理の構造化は、提案品質を確認してから入れる。最初は状態を持たないスキル1本で出し、実際に採用された項目の傾向を見てから構造を決める。

却下した代替案

• 縮小 push（直近 N 件だけインデックス注入）: N の恣意性が残り、古いが関連の深い判断に届かず、線形成長の根治にならない。
• 常時層の全廃: 恒常指示や承認待ち提案など「毎セッション配達すべき少量」の経路は維持する。むしろここが主経路。
• 横断蓄積に対する全タスク想起検索の常設: 上記3条件を満たさないため引かれず、習慣の維持コストだけが残る。

二重管理の回避

既存の常時読み込みファイルとの住み分けルールを先に明文化する。「リポジトリから導出可能・チーム共有可・コミット可な内容は既存ファイル、コミットできない個人文脈・リポジトリ横断の判断・却下案の履歴は新しい層」のように、置き場を内容の性質で機械的に決められる基準にする。

検証

• 蓄積ドキュメントが数十件ある状態でセッションを開始し、初期注入トークン量が蓄積件数に依存しないことを確認する。
• 計画起草ワークフローで検索が実際に発火し、過去の却下案・決定が起草に反映されるかを次の実案件で観測する。発火しないなら上記3条件のどれが欠けているかで診断する。
• 昇格経路の効きは、「現在の規約に載っている項目のうち、蓄積から昇格したものが何件あるか」と「昇格後に実際の作業でその規約が参照・適用されたか」で確認する。蓄積件数の伸びは活用の指標にならない。

AI エージェントが永続データ（指示・記録・ドキュメント）を自動保存する仕組みでは、保存の摩擦を一律にせず誤保存時の影響範囲（blast radius）で非対称にすると、低摩擦と安全性を両立できる。

判断基準:

• 毎セッション自動適用されるデータ（恒常的な指示・ポリシー）→ 提案 + ユーザー承認制。一度入ると以後の全セッションに影響するため。承認は会話内で同期的に取れば永続キューは不要。
• 事後に閲覧・編集・削除できる蓄積データ（設計記録・調査結果・手続きメモ）→ 自動保存 + 事後報告。誤保存しても直せるので、確認で会話を止めるコストの方が高い。

状態管理の置き場: 承認待ち・却下・退役などのワークフロー状態は、ローカルキャッシュではなくサーバ側の status カラム（例: active / proposed / retired / discarded）で一元管理する。理由: (1) UI から提案中の状態まで見え、エージェントの動きがブラックボックスにならない、(2) マシン間で状態が分岐しない、(3) キャッシュと DB の突き合わせという恒久的な運用問題を持たずに済む。

重要な落とし穴 — 状態を残すなら類似検索は status で分割する: 却下・退役レコードを保存時の重複チェックと同じ検索空間に無差別に残すと、「過去に却下されたものに似ている」というだけで新規保存が重複扱いで静かにスキップされ、蓄積が却下履歴に汚染されて機能停止する。重複チェックは active のみを対象にし、discarded への照合は「提案を出すか」のゲート判定として分離する（保存処理には影響させない）。フィルタなしの類似検索をリポジトリ層のインターフェースとして公開しないと型で強制できる。

却下の扱い: 却下は物理削除せず discarded 状態 + 却下理由で残すと、同じ提案の再発防止と採用基準改善の材料に転用できる。ただし永久ブロックにはせず、状況が変わったら再提案できる条件（却下時点のシグナル量を記録しておき、大幅に増えたら再点火等）を持たせる。

トレードオフ: サーバ管理はオフライン時に蓄積できないが、エージェント利用はほぼオンラインなので「失敗したら会話内で報告・再試行」で始め、必要になってから送信バッファを足すのが可逆性の高い順番。

「同じ手続きを繰り返している → 自動化・スキル化を提案する」という手続き的メモリ機能を作る場合、セッションログの常時バックグラウンド解析から始めるとコストと誤検出の割に価値検証が遅い。先に保存フローへの相乗り検出で成立させるのが安い。検出コストは保存時の類似検索に収まり、「また記録しようとした瞬間」がトリガーなので反復のシグナルとして偽陽性が少ない。

最重要の設計点 — 目的別に検索空間を分ける: 保存時の類似検索には目的の違う 3 判定が相乗りしており、ヒット時の正しい挙動が逆方向なので、status / kind フィルタで別クエリに分割する。

判定	検索対象	ヒット時の挙動
重複チェック	active の同種ドキュメント	保存スキップ / 既存更新
反復検出	active の手続き記録	むしろ保存してカウント、閾値超え（例: 類似度 0.8 以上が 2 件 = 通算 3 回目）でスキル化提案
再提案防止	discarded の提案候補	提案のみ抑止（保存は妨げない）

無差別の 1 本検索にすると、却下済み提案に似ているというだけで重複チェックが新規保存を止め、反復カウントも増えなくなって機能全体が静かに停止する。

その他の設計点:

• 検出対象を識別できるよう、記録に kind（手続き / 設計判断 / 調査など）を最初から持たせる。後付けだと過去分の再分類が必要になる。
• 再提案防止は永久ブロックにしない。却下レコードに却下時点の類似件数（または対象 ID 群）を記録し、そこから大幅に増えたら（例: 3 件で却下 → 6 件到達）再提案する。
• 提案が承認されたら複数回分の記録を統合して自動化定義（スキル等）のドラフトを生成し、元の記録には昇格先リンク付きの retired 状態を付けて退役させる。
• retired に類似する新規保存が来た場合は、保存でも提案でもなく「この作業は既にスキル X になっています」と案内する（昇格先リンクがここで効く）。

適用条件: 記録が保存フローを必ず通る仕組み（capture ワークフロー等）があること。保存を経由しない反復は拾えないため、価値が確認できてから常時スキャンを追加検討する。