なぜドキュメントがメモリとして機能しないのか
文書は「これは何か」に答え、メモリは「何をすべきか」に答える
ほとんどすべての社内ドキュメントは「記述的」です。システムを説明し、設計を順に追い、検討された選択肢をリストアップします。これはチームに新しく加わった人間にとっては適切なトーンです。人間は前後の段落を読み、そこからルールを推測できるからです。
エージェントには、明文化されたルールが必要です。12ページの設計書の中で本当に価値のある一文は、往々にして「アップストリームがタイムアウト時に重複を発生させるため、リトライロジックは冪等でなければならない」といった、別のセクションの真ん中に埋もれた1行だけだったりします。検索（Retrieval）はそのページを返すかもしれませんが、必ずしもその行をピンポイントで返すとは限りません。仮に返したとしても、モデルはその段落が現在の制約なのか、それとも過去の検討事項なのかを推測しなければなりません。
検索が返すのは「一節」であり、一節には曖昧さが残る
十分に調整された検索セットアップであっても、文書化された限界があります。OpenAI自身によるインデックス化された知識ソースの説明では、「当初はQ&Aや検索関連のクエリに最適に機能するように設計されている」とされており、「クエリの意図に基づいて最も関連性の高いデータがモデルに送信されるため、多数 of ソースからの集約や非常に複雑なクエリを必要とするシナリオではパフォーマンスが制限される」と述べられています。
これは、ドキュメント検索の用途に関する率直な説明です。「Xについて何を決めたか？」という質問は、通常、ミーティングメモ、ドキュメントの改訂履歴、PR（プルリクエスト）のコメントなどに分散した情報を集約する質問です。検索はドキュメントを見つけ出しますが、結論を導き出すわけではありません。この違いこそが、why RAG isn't memory（なぜRAGはメモリではないのか）のテーマそのものです。
文書のどこにも、それが「今でも正しいか」は書かれていない
ページには「最終編集日時」のタイムスタンプがありますが、これは誰かがいつ触ったかを示すだけで、その内容が今も有効かどうかは教えてくれません。ドキュメントは主張単位で劣化していきます。3つの段落は正しいままですが、移行作業の後に1つの段落が静かに真実ではなくなり、誰もページ全体を読み直さないため、編集されることもありません。
人間であれば、古くなったドキュメントのトーンからそれを察知して対処できます。しかし、エージェントにとっては現在の事実と区別がつかず、そのまま実行してしまいます。これが、ドキュメントよりもメモリにおいてプロベナンス（来歴・根拠）が重要である理由です。この点については、memory provenance explained（メモリのプロベナンス解説）で詳しく説明しています。
ドキュメントをコンテキストに読み込ませても解決しない
明らかな回避策として、ドキュメントを常に有効な指示ファイルに含める方法がありますが、これはすべてのベンダーが公開しているガイドラインと衝突します。Claude Codeは、CLAUDE.mdを1ファイルあたり200行未満に抑えることを推奨しており、ファイルが長くなると「より多くのコンテキストを消費し、指示への準拠度が低下する」と指摘しています。Cursorはルールを500行未満に抑えることを推奨しています。さらに、Claude Codeは、コンテンツを@pathインポートに分割することは「整理には役立つが、インポートされたファイルは起動時にロードされるため、コンテキストを削減することにはならない」と明記しています。つまり、インポートのトリックを使っても容量の節約にはなりません。
サイズ以外にも、もう一つのコストがあります。Claude Codeのドキュメントは、「2つのルールが矛盾している場合、Claudeは任意に一方を選択する可能性がある」と警告しています。異なる時期に書かれた5つのドキュメントを1つのコンテキストに放り込むことは、矛盾を確実に作り出す方法と言えます。
よく試されるアプローチ
エージェントにドキュメントフォルダを指し示す。 答えが1つのファイルにあり、それがどのファイルか分かっている場合には機能します。しかし、本当に知りたい質問（答えが複数のファイルに分散している、あるいはそもそも書き残されていない質問）では確実に失敗します。
1つの巨大な `CONTEXT.md`。 最もよくある試みです。800行にまで膨れ上がり、リクエストのたびにロードされ、3つの矛盾を含み、重要なルールへの準拠度が低下します。なぜなら、それらのルールが参照資料と競合してしまうからです。
すべてをベクトルストアにインデックス化する。 ソース資料を見つけるのには役立ちますが、結論の代わりにはなりません。設計書は返ってきますが、その設計が破棄されたという事実を知ることはできません。
エージェントにドキュメントの要約を依頼する。 魅力的ですが、もっともらしい要約が生成されるだけで、本当に必要な区別（現在と過去、決定事項と検討事項、ルールと例）がすべて平坦化されてしまいます。
ドキュメントをアシスタントのメモリにコピーする。 方向性としては良いですが、粒度が間違っています。貼り付けられたページは1つの巨大なメモリ・エントリとなり、あらゆるものに対して検索に引っかかるものの、何の役にも立たなくなります。
何もしないで、その都度説明し直す。 現状維持ですが、そのコストは過小評価されがちです。すべてのメッセージで、トークンと注意力の両方において、永遠にコストを支払い続けることになります。これこそが、stopping re-explaining context to your AI（AIへのコンテキストの再説明をやめる）が解決しようとしている悪習慣です。
解決策：ドキュメントではなく「主張」を抽出する
この変換はインポート作業ではありません。特定の出力フォーマットを持つ「読み込み作業」です。すなわち、1つのエントリにつき1つの主張とし、指示または事実として記述し、その理由を付記します。 主要なドキュメントに対してこれを一度行えば、あとは作業を進める中で自然と蓄積されていきます。
具体的な手順の前に、仕分け（トリアージ）を行います。ドキュメント内のすべてを以下の4つの山に分類してください。
メモリに昇格させる。 決定事項とその理由。外部からは恣意的に見える制約。ツールのデフォルトとは異なる規約。痛い目を見て学んだ注意点。却下された事項（試したものの断念したこと、およびその理由）。これらは短く、永続的であり、エージェントがコードベースから推測できないまさにその情報です。
文書として残し、参照する。 長い手順、参照テーブル、API仕様の記述など、数ステップ以上あるもの。これらはファイルに属します。お使いのツールがオンデマンド・パッケージ（現在の多くのツールにおける「スキル」など）をサポートしている場合は、そこが最適な置き場所となり、常にロードされるのではなく、関連する時だけロードされるようになります。
削除する。 すでに稼働していないシステムを説明しているものすべて。これはほとんどのドキュメントフォルダの3分の1を占めており、最もリスクの高い3分の1でもあります。なぜなら、それらは一見すると信頼できるように読めてしまうからです。
人に尋ねる。 この作業中、誰も書き残していなかった決定事項という「ギャップ」を発見するでしょう。気づいた今のうちに、それらを書き留めておきましょう。
次に、3つのステップからなるセットアップを行います。
ステップ 1: APIキーを作成する
MemoryLake にサインインし、APIキーを作成します。これは、使用するアシスタントに関係なく、エージェントがメモリを読み書きするために使用する単一の認証情報です。そのため、この変換は次のツール変更時にもそのまま引き継がれます。
ステップ 2: 最初のメモリをアップロードする
「昇格させる」山を処理し、各項目を独立したエントリとして書き出します。以下の4つのルールが、メモリレイヤーと「第2のドキュメントフォルダ」を分ける決定的な違いとなります。
1つのエントリにつき1つの主張。 2つのアイデアが含まれている場合は分割します。1つのアイデアに絞られたエントリは正確に検索され、古くなった際にも一目で分かります。
ルールを述べ、次にその理由を述べる。 「リトライは冪等でなければならない — アップストリームがタイムアウト時に重複を発生させるため」。理由が書かれていることで、人間であれモデルであれ、少し不都合が生じたからといってルールを勝手に上書きしてしまうのを防ぐことができます。
検証可能にする。 「APIハンドラーは src/api/handlers/ に配置する」は、「コードを整理された状態に保つ」よりも優れています。モデルは前者に従って行動できますが、後者では行動できません。
却下された事項を明示的に記録する。 「検討の上却下：キューベースの順序保証、2026年3月 — リトライ時に順序保証が崩れたため」。これがないと、新しいエージェントが来るたびに熱心にそれを再提案し、あなたはまた一から説明し直すことになります。
変換効率の高さに驚くかもしれません。12ページのアーキテクチャ設計書から得られるのは、通常6〜10個のエントリです。これは情報の損失ではありません。残りの11ページは、モデルには不要な説明か、あるいはすでに真実ではなくなった過去の経緯です。
ステップ 3: AIとエージェントを接続する
ツールを接続します。MemoryLakeはMCPおよびAPI経由でアクセス可能です。そのため、Claude Code、Codex、OpenClawなどのMCPネイティブなエージェントはMCPサーバーを指定するだけで接続でき、その他のアシスタントはAPIを介して同じメモリを読み取ることができます。指示ファイルは短く保たれ、その限定された役割を果たします。抽出された主張はクエリ可能になるため、エージェントは12ページの文書や何も得られない状態の代わりに、関連する4つのエントリだけを的確に取得できます。
ここで、2つの率直な限界があります。この仕組みは、あなたの代わりにドキュメントを読んでくれるわけではありません。抽出は、どの主張が今も有効かを知っている人間が一度だけ行う「判断作業」です。また、これは強制力を持つレイヤーではありません。モデルの決定に関わらず必ず守らなければならないルールは、メモリではなく、フックやCIチェックに記述すべきです。
実務で何が変わるのか
質問に対して、情報源ではなく「答え」が返ってくる。 「台帳スキーマについて何を決めたか？」と尋ねると、スキーマに言及している3つのドキュメントではなく、決定事項そのものが返ってきます。
古くなった知識が可視化される。 日付の入った短い主張のリストであれば、レビューが可能です。しかし、ドキュメントのフォルダはレビューできません。第9段落を確認するために12ページのドキュメントを読み直す人などいないからです。
リクエストごとのトークンコストが低下する。 指示ファイルが縮小し、貼り付けられたコンテキストがなくなり、検索によって送信されるトークンは数千から数百へと減少します。その計算ロジックは、how memory cuts token cost（メモリがトークンコストを削減する仕組み）で解説しています。
ドキュメントがドキュメントとしてより洗練される。 主張が別の場所に保管されれば、ドキュメントはルール集のふりをする必要がなくなり、ストーリー性のある徹底した記述が可能になります。競合しなくなることで、両方の成果物の質が向上します。
新しいエージェントが最初から知識を持った状態でスタートできる。 これこそが、この取り組みの目的です。次にどのようなツールを導入したとしても、試行錯誤しながらプロジェクトを学び直す必要はなく、初日から抽出された主張を読み取ることができます。
ベストプラクティス：今週から実行できる変換レシピ
最もよく引用される3つのドキュメントから始める。 最も大きなドキュメントではなく、新人が質問したときに誰かがSlackでリンクを貼るようなドキュメントです。それらには、最も高密度で重要な主張が含まれています。
読みながら抽出する（読んだ後ではない）。 スクラッチファイルを開いておき、主張を見つけた瞬間にエントリを書き留めます。ドキュメント全体を読んでから要約しようとすると、平坦で曖昧さを残した文章になってしまいます。
曖昧な表現は決定事項に変換するか、捨てる。 「現在はXに傾いている」はメモリのエントリではありません。それが決定事項であるなら決定事項として書き、そうでないなら歴史（過去の経緯）であり、歴史はドキュメントに残すべきです。
時間経過に左右されるものには日付を入れる。 主張がベンダーの現在の挙動や特定のバージョンに依存している場合は、エントリにその旨を明記します。これが、事実となるか、半年後の罠となるかの分かれ目です。
「常に有効な」レイヤーの上限を意図的に制限する。 指示ファイルに残すものは、1画面で読み切れる長さに抑えるべきです。それ以外はすべて検索可能（retrievable）にします。ベンダーのガイドラインがこの結論に収束しているのには理由があります。
ドキュメントだけでなく、抽出したデータもバージョン管理する。 差分（diff）や変更履歴（change log）など、レビュー可能な形で主張を管理することが、乖離を防ぐ鍵となります。これが、git for AI memory（AIメモリのためのgit）の背景にある考え方です。
エージェントを2回修正するたびに、エントリを1つ追加する。 これが唯一にして最善のメンテナンス習慣です。同じ修正を繰り返すということは、必要なエントリが不足していることを示しています。
結論
ドキュメント化されたプロジェクトが、エージェントにとって依然としてドキュメント化されていないように感じられる理由は、ドキュメントとメモリが異なる読者のための異なるフォーマットだからです。文書は説明し、メモリは指示します。文書は曖昧さを許容しますが、メモリは決定事項を必要とします。文書は設計上長くなりますが、エージェントがリクエストごとにロードするレイヤーは必然的に短くなければなりません。
したがって、この変換はインポートではなく「抽出」です。実際に引用しているドキュメントを読み、今も有効な主張を抜き出し、理由を付記し、却下された事項を記録し、すでに稼働していないシステムを説明している3分の1を削除します。ほとんどのプロジェクトにおいて、これは半日（午後だけ）で終わる作業です。その結果得られるのは、すでに持っていると思っていたもの、すなわち、人間であれシステムであれ、それに取り組むすべての存在が利用できるプロジェクトの知識です。まず概念的な基礎を理解したい場合は、what persistent memory actually is（永続メモリの真の意味）でこの違いを詳しく解説しています。