AIコーディングエージェントを使っていて、こんな経験はないだろうか。
昨日決めたアーキテクチャの方針を、今日のセッションでもう一度説明し直す。先週のバグ修正の経緯を、一から伝え直す。自分の中では「もう共有済み」のはずの情報が、毎回リセットされる。
Claude CodeやCursor、GitHub Copilotといったコーディングエージェントは、セッション内では驚くほど賢い。でもセッションが切れた瞬間、全部忘れる。まさに金魚。
この「記憶がない問題」にどう向き合うかで、AIエージェントの生産性は大きく変わる。
・Claude Codeに毎朝同じ説明をしている
・CLAUDE.mdが肥大化して管理しきれない
・AIが過去の決定を覚えていなくてイライラする
・記憶を持たせたいけど、何から始めればいいか分からない
ここで止まってる人ほど見てほしい。
CLAUDE.mdが「3000行の巨大ファイル」になる問題
Claude CodeにはCLAUDE.mdというプロジェクト設定ファイルがある。ここにアーキテクチャの方針やコーディング規約を書いておけば、セッション開始時にAIが読み込んでくれる仕組みだ。
最初はこれで十分だと思う。自分もそう思ってた。
でも運用を続けていくと、決定事項が増えるたびにCLAUDE.mdは膨らんでいく。設計方針、NG集、デプロイ手順、過去のバグ対応の経緯……。気づけば数千行の巨大ファイルになる。
問題はサイズだけじゃない。Claude Codeにはコンテキストウィンドウという「一度に読める情報量の上限」がある。CLAUDE.mdが大きくなりすぎると、コンテキスト圧縮によってファイルの後半が静かに切り捨てられる。「後半に書いてあった大事な方針が、AIに読まれていなかった」という事態が起きる。警告もなく、だ。
海外の開発者コミュニティでも、この問題は頻繁に話題になっている。元記事の著者は「CLAUDE.mdが3000行以上に膨らみ、コンテキスト圧縮で下3分の1が警告なしに消えた」と報告している。
自分の場合は、CLAUDE.mdの肥大化に気づいてからは「索引＋外部参照」方式に切り替えた。CLAUDE.md本体は要点だけにして、詳細は別の場所から引っ張ってくる形にしている。ただ、この構造を作り込むのに結構な時間がかかったのも事実だ。
「AIに記憶を持たせる」4つのアプローチと、それぞれの落とし穴
CLAUDE.mdの限界が見えたとき、次に考えるのは「もっとちゃんとした記憶の仕組み」だ。現時点で主に4つのアプローチがある。
1. クラウドメモリサービス
AIエージェント向けの記憶をクラウドで管理してくれるサービスがいくつか登場している。手軽だが、自分のコードや設計判断を外部に送ることになる。セキュリティを気にするプロジェクトでは使いづらい。料金もトークン従量制で、月額約20〜50ドル程度かかるものが多い。
2. ベクトルデータベース
類似検索には強い。「このエラーメッセージに似た過去の対処法」を探すのは得意だ。でも「2週間前の認証方式の決定理由」のような、特定の意思決定を正確に引っ張ってくるのは苦手。検索用のコードを自分で書く必要があり、運用のハードルが高い。
3. プロンプトスタッフィング（情報の詰め込み）
毎回のプロンプトに過去の決定事項を全部詰め込む方法。小規模なうちは動く。でも情報量が増えると、古い決定が新しい文脈を汚染し始める。「3ヶ月前に決めたけどもう撤回した方針」がAIの判断に影響を与える、みたいなことが起きる。
4. ローカルファイル＋SQLiteベースの記憶
ここが今一番ホットな領域だ。ローカルにSQLiteファイルを1つ置いて、そこに事実・決定・セッション履歴を溜めていく。外部サービスへの依存がなく、自分のマシンだけで完結する。
最近公開されたWaypathというツールは、まさにこのアプローチだ。~/.waypath/waypath.dbというSQLiteファイル1つに、4つの独立したモジュール（構造化された事実、全文検索つきアーカイブ、エンティティのグラフ構造、人間によるレビューゲート）を載せている。MCPサーバーとして動くので、Claude CodeやCursorなどMCP対応のエージェントから直接呼び出せる。
自分もAIエージェントの記憶管理にSQLiteを使っている。実際、複数のAIプロセスが同時にDBを読み書きする場面で「DB locked」エラーにハマったことがある。WALモード（Write-Ahead Logging）を有効にしてbusy_timeoutを設定することで解決したが、こういう泥臭い部分はドキュメントに書いてないことが多い。ローカルファイルベースの記憶は手軽に始められる反面、並行アクセスの制御は自前でやる必要がある。
一番怖いのは「AIが嘘の記憶を書き込むこと」
ここまでの話は「AIに情報を覚えさせる仕組み」だった。でも本当に怖いのは、その先にある。
AIに記憶を書き込む権限を与えると、AIが「決定していないことを決定事項として記録する」リスクがある。
たとえば、AIと議論の途中で「PostgreSQLをイベントストアに使うのはどうか」と聞いただけなのに、AIが「PostgreSQL 16をイベントストアに採用することが決定された」と記憶に書き込んでしまう。次のセッションでは、その「決定」が前提として使われる。
これはハルシネーション（AIの事実誤認）の一種だが、通常のハルシネーションよりたちが悪い。なぜなら、嘘が「永続化された事実」として残り続けるからだ。セッション内のハルシネーションはセッション終了で消える。でも記憶に書き込まれたハルシネーションは、消さない限りずっとそこにある。
元記事の著者は、AIエージェントが自信満々に「自分が決めていない決定」を記憶として書き込んだのを目撃し、人間による承認なしには記憶を確定させない仕組みを入れたと述べている。
この「人間のレビューゲート」という考え方は、記憶を持たせる上で最も重要なポイントだと思う。AIが書き込んだ情報は「下書き」状態で止めておき、人間が確認して初めて「正式な記憶」に昇格させる。毎日30秒程度のレビューで、記憶の品質が担保される。
自分のシステムでも似た仕組みを入れている。AIが生成した内容を人間が確認するステップを挟むことで、「いつの間にか嘘が事実になっていた」という事故を防いでいる。面倒に感じるのは最初の2日だけで、そこを超えると「これがないと怖い」に変わる。
MCP（Model Context Protocol）が記憶の標準規格になりつつある
AIエージェントに記憶を持たせる仕組みとして、MCP（Model Context Protocol）の存在感が急速に高まっている。
MCPは、AIエージェントと外部ツールをつなぐための共通規格だ。従来はツールごとに独自の接続方法を作る必要があったが、MCPに対応していれば、1つの規格でどのツールにもつながる。
WaypathもMCPサーバーとして動作する。Claude Codeの設定ファイルにMCPサーバーとして登録すれば、AIエージェントが直接「過去の記憶を検索」「新しい事実を下書きとして保存」「エンティティ間の関係を辿る」といった操作を行える。
MCP対応の記憶ツールが増えてきたことで、「どのツールをどう組み合わせるか」が新しい設計判断になってきている。記憶サーバーを1つ入れるだけで解決するほど単純ではなく、何を記憶させて・何を忘れさせて・誰が承認するかの設計が必要だ。
ただし、MCPサーバーを増やしすぎるとClaude Codeの起動が遅くなるという実測もある。記憶用のMCPサーバーは「本当に毎セッションで必要なもの」に絞るのが現実的だ。
SQLiteが「AI記憶のデファクト」になりそうな理由
Waypathに限らず、AIエージェントの記憶管理にSQLiteを選ぶツールが増えている。その理由は明快だ。
まず、インストールが不要に近い。SQLiteはファイル1つで動くデータベースで、別途サーバーを立てる必要がない。ローカルのファイルシステムに置くだけで使える。
次に、全文検索が標準装備されている。SQLiteのFTS5（Full-Text Search 5）を使えば、コード中の関数名やエラーメッセージもキーワード検索できる。ベクトルDBのようなセマンティック検索ほど賢くはないが、「あの関数名、なんだっけ」を探すには十分すぎる。GPUも外部APIも不要だ。
さらに、グラフ構造もSQLiteだけで表現できる。再帰CTE（Common Table Expression）という機能を使えば、「この人が関わっているプロジェクトの、関連技術」のような多段の関係を辿れる。Neo4jのようなグラフデータベースを別途立てる必要がない。
元記事のWaypathでは、MacBook Airで120件以上のセッションエントリに対して、検索のp95（95パーセンタイル、つまり100回中95回はこの時間以内に収まるという指標）が40ミリ秒以下だったと報告されている。ローカルファイルならではの速さだ。
自分がSQLiteで記憶管理を運用していて実感するのは、「バックアップが楽」という地味な利点だ。ファイルを1つコピーするだけで完全なバックアップが取れる。データベースサーバーのダンプとリストアに比べると、圧倒的にシンプル。
結局、AIの記憶で一番大事なのは「仕組み」じゃなくて「運用」
ここまで技術的なアプローチを紹介してきたが、正直に言うと、ツール選びよりも大事なことがある。
それは「何を覚えさせて、何を忘れさせるか」の判断を、人間がサボらないことだ。
どんなに優れた記憶システムを入れても、放置すれば古い情報が溜まってAIの判断を歪める。かといって毎回全部確認するのは現実的じゃない。
自分がたどり着いた運用は、こんな感じだ。
- 設計判断や方針は「なぜそう決めたか」もセットで記録する
- 古くなった情報は定期的にアーカイブする（削除ではなく、検索対象から外す）
- AIが書き込んだ記憶は、人間が確認してから正式採用する
- 記憶の索引（目次）を薄く保ち、詳細は参照先に置く
この「薄い索引＋外部参照」パターンは、CLAUDE.mdの肥大化問題への対策として自然にたどり着いたものだ。結局、コードを書く時間よりも「AIに何を伝えて何を伝えないか」を設計する時間の方が、生産性に効いてくる。
気づいたんですよ。遅すぎたけど。
まとめ
- AIコーディングエージェントはセッション間で記憶を失う。CLAUDE.mdの肥大化は多くの開発者が直面する壁
- SQLiteベースのローカル記憶（Waypathなど）は、クラウド依存なし・コスト0で始められる現実的な選択肢
- 最も重要なのは「AIが嘘を記憶に書き込まない仕組み」。人間によるレビューゲートが記憶の品質を守る
AIツールの進化は速いが、記憶の管理は結局「人間の設計力」にかかっている。ツールに振り回されるのではなく、自分の運用に合った記憶の仕組みを育てていく。それが、AIエージェントを本当の相棒にする近道だと思うよ。すごく。
【PR】フリーランスエンジニアにおすすめのツール
AI開発環境を自前で構築するなら、安定したサーバーが必須。エスツーサーバは困ったときにすぐ相談できるサポート体制が強みです。
独自ドメインで技術ブログを始めるなら、お名前.com プレミアムドメインで信頼感のあるドメインを押さえておくのがおすすめです。
【PR】おすすめの書籍
記事の内容に関連する書籍を紹介させてほしい。
「マンガでわかる！Claude Code超入門: プログラミング知識ゼロでも使える！ AIに「相談」する時代から「お任せ」する時代へ Claude Code シリーズ (NaoTsu Production)」は、AIの仕組みと実践的な活用法を学べる一冊。技術の裏側を知ると使い方が変わる。
リファクタリング (アジャイルソフトウェア開発技術シリーズ・応用編)
「リファクタリング (アジャイルソフトウェア開発技術シリーズ・応用編)」は、ソフトウェア設計の考え方を体系的に学べる一冊だ。
コメント