Claude Codeで4時間かけてアーキテクチャを議論したとします。
「ここはRedisじゃなくNATSにしよう」「ライブラリXのバグを踏んだから使わない」という判断が積み重なって、ようやく方針が固まった。
そして翌日、新しいセッションを開く。
エージェントはその4時間を一切知りません。
これはClaude Codeの設計上の問題というより、LLMのコンテキストウィンドウという構造的な制約です。
セッションが終わればウィンドウの中身は消える。
作業机の上の書類が、退勤と同時に全部シュレッダーにかけられるようなものです。
Rust製CLIツール ai-memory がこの問題にどう向き合っているかを、データ構造・コマンド体系・エージェント連携パターンの順に実装レベルで追っていきます。
自分のワークフローに組み込む価値があるか判断できるところまで持っていくのがゴールです。
セッションが終わるたびに記憶が消える、という地味な消耗
現状の回避策として多くのエンジニアがやっているのが、CLAUDE.mdに手書きでメモを残す方法です。
これはこれで有効ですが、限界もはっきりしています。
書くのが手動なので、忙しいときは書き忘れる。
属人的なので、フォーマットがバラバラになる。
そして何より、Claude CodeのCLAUDE.mdはCodexやOpenCodeには届きません。
エージェントを切り替えた瞬間に、引き継ぎがゼロになります。
既存のアプローチとして Mem0 のようなクラウドDB前提のソリューションもあります。
Mem0はフック経由でセッション情報をクラウドに送り、次のセッションで引き出す設計です。
精度は高いですが、外部インフラへの依存・トークンコスト・プライバシーの懸念がセットでついてきます。
ai-memoryが採った答えは、発想の向きが少し違います。
エージェントのライフサイクルイベント（セッション開始・終了・ツール呼び出しなど）を観察し、その観察記録から wikiページを自動生成する というアプローチです。
「メモを書く」のではなく「作業を見ていて、後でまとめる」というイメージに近い。
そして生成されたwikiはローカルのMarkdownファイルとして残るので、外付けインフラは一切不要です。
メモリの実体はMarkdownファイル：データ構造を読み解く
ai-memoryのストレージの実体は、ローカルのMarkdownファイル群です。
Gitリポジトリとして管理されるので、grepで検索できるし、Obsidianで開けるし、rsyncでバックアップできます。
ベクトルDBのプロセスを別途立ち上げる必要はありません。
実際のメモリエントリはおおよそこんな形をしています（以下はARCHITECTURE.mdの記述をもとにした構造例です。実際のスキーマはリポジトリのドキュメントで確認してください）。
---
title: Queue choice entities nats jetstream delivery guarantees
entities:
- nats
- jetstream
- queue
tags:
- architecture
- decision
---
NATSのJetStreamを採用する判断をした。
RedisのPub/Subはat-most-once配信のため、ジョブのロストが許容できないユースケースには不適切と判断。
JetStreamはat-least-once配信を保証し、consumerグループによる並列処理も扱いやすい。
frontmatterの構造がポイントです。
title はエントリの識別子を兼ねた自然言語のフレーズで、 entities はそのエントリに登場する技術・コンポーネント・ドメイン名詞の正規リストです。
ARCHITECTURE.mdの「Entity retrieval」節によれば、consolidation（後述）がツールの入出力から技術名・ファイル名・ドメイン名詞を抽出してこのフィールドに格納します。
このentitiesフィールドが、検索インデックスの精度に直結します。
ディレクトリ構成の詳細な名称はARCHITECTURE.mdで確認するのが確実ですが、概念的には3層に分かれています。
生成・蓄積されたwikiページ群がメモリの本体で、セッション中に溜まった観察の一時置き場（spoolに相当する領域）が別に存在します。
そしてSQLiteのデータベースファイルが検索インデックスを担います。
検索インデックスはSQLiteのFTS5（全文検索）と sqlite-vec（ベクトル検索）を組み合わせて構築されます。
ai-memoryのissues-agentmemory.mdには、インデックスのコミットをwikiファイルの書き込みと同一トランザクション内で行う設計方針が明記されています。
インデックスだけが先に更新されてファイルと乖離する、あるいはクラッシュ時にインデックスだけが壊れる、といった問題を構造的に防ぐ意図です。
LLMによる圧縮・要約はデフォルトではオフです。
デフォルトの動作は「ゼロLLM合成圧縮」と呼ばれていて、ツールの入出力からtitle・ファイルパス・ナラティブを機械的に抽出してwikiページを生成します。
wikiを生成するためだけにトークンを消費しない、という設計判断です。
LLMによる高品質な要約が欲しい場合はオプトインで有効化できますが、デフォルトではコストゼロで動きます。
CLIコマンドの実際：読み書きから検索・ハンドオフまで
READMEとARCHITECTURE.mdで明確に確認できるコマンドは、大きく「整理する」と「セットアップする」の2系統が核になっています。
まずセットアップから見てみます。
# CLAUDE.md（またはAGENTS.md）にルーティングスニペットを書き込む
ai-memory install-instructions
これを実行すると、CLAUDE.mdにルーティングスニペットが追記されます。
このスニペットがエージェントに「どんなときにai-memoryのMCPツールを呼び出すか」を教える役割を担います。
READMEには「idempotent」と明記されているので、何度実行しても同じ結果になります。
既存のCLAUDE.mdを壊す心配はありません。
次に、観察ログをwikiページに昇格させるconsolidateです。
# spoolに溜まった観察ログをwikiページとして生成する
ai-memory consolidate
セッション中にエージェントが行ったツール呼び出しの観察記録が一時領域に蓄積されていて、consolidateを実行するとそれが処理されてwikiページになります。
セッション終了時に自動で走る構成にもできますし、手動で実行することもできます。
検索・追加・削除などその他のサブコマンドについては、具体的なフラグやシグネチャが検索結果から確認できなかったため、ここでは断定的に示しません。
usage.md にハンドオフ例・コマンド一覧・生wikiの検査コマンドが記載されているので、実際に使う前に一読することをおすすめします。
自動観察が機能しているときは、consolidateを実行するだけでspoolの内容がwikiページになります。
ただし自動観察はあくまでツール呼び出しのイベントを見ているので、「会話の中で決まったこと」は拾えません。
アーキテクチャ判断・ライブラリの採否・チームの合意事項など、会話レベルの意思決定は別途手動で記録する必要があります。
ここが自動観察の限界で、手動操作との補完関係が生まれる理由です。
Claude Code / Codex 間のハンドオフはこう動く
ai-memoryのハンドオフの仕組みを理解するには、CLAUDE.mdに書き込まれるルーティングスニペットの役割から入るのがわかりやすいです。
install-instructionsを実行すると、CLAUDE.mdにはざっくり「セッション開始時にmemory_searchを呼んで関連コンテキストを取得せよ」「セッション終了時にconsolidateを走らせよ」という指示が追記されます。
エージェントはこの指示を読んで、MCPツール経由でai-memoryのサーバーと通信します。
初回セットアップはエージェントに「ai-memoryのルーティングをこのプロジェクトにインストールして」と頼むだけで、エージェントが memory_install_self_routing MCPツールを呼び出し、スニペットを自分でCLAUDE.mdに書き込みます。
具体的なハンドオフシナリオで流れを追ってみます。
Claude Codeで4時間作業したとします。
NATSの採用を決め、ライブラリXのバグを踏み、認証フローの設計を固めた。
セッション終了時、Claude CodeはSessionEndイベントを検知し、spoolに溜まった観察ログをai-memoryに送ります。
consolidateが走り、wikiページが生成される。
次に同じディレクトリでCodexを開きます。
CodexはAGENTS.mdに書かれたルーティングスニペットを読み、セッション開始時にmemory_searchを呼び出します。
「このプロジェクトで何が決まっているか」をwikiから引き出し、コンテキストとして受け取る。
CodexはClaude Codeが4時間かけて積み上げた判断を知った状態でスタートできます。
このハンドオフが成立する理由は、wikiが 特定エージェントに依存しないローカルファイル だからです。
Claude CodeもCodexも、同じディレクトリの同じMarkdownファイルを参照します。
エージェントが変わっても、wikiは変わらない。
READMEのSupport MatrixにはClaude Code・Codex・OpenCode・Cursor・Gemini・OMPなど複数のエージェントCLIが列挙されており、それぞれに対応するルーティングファイル（CLAUDE.mdまたはAGENTS.md）へのスニペット書き込みが行われます。
エージェントごとのライフサイクルイベントへの対応も、設計上の工夫が見えます。
たとえばAntigravity CLIはネイティブのSessionStartイベントを持っていません。
その代わりにPreInvocationフックがすべてのモデル呼び出し前に発火するので、ai-memoryはinvocationNum=0のペイロードだけをsession-startとしてマッピングし、それ以降の呼び出しは無視します。
エージェントごとの差異を吸収するアダプター層が、ai-memoryの内部に存在しているわけです。
このツールが解決する範囲と、解決しない範囲
正直なところ、万能ではありません。
使う前に、何を解決して何を解決しないかを把握しておく方が後悔が少ない。
検索精度から話すと、FTS5はキーワードマッチが得意ですが、「あの判断の背景にあった制約」みたいな意味的に遠い検索には弱さが出ます。
sqlite-vecによるベクトル検索が補完しますが、商用のベクトルDBと比べると精度の天井は低い。
wikiページが数十〜数百程度の規模なら実用的ですが、大規模なモノレポで何年も使い続けた場合のスケール感は未知数です。
セキュリティ面では、メモリの実体が 平文のMarkdownファイル であることを忘れないでください。
エージェントが観察したツール呼び出しの内容がそのままspoolに入るので、APIキー・パスワード・個人情報を含むファイルを操作したセッションでは、その情報がwikiに紛れ込むリスクがあります。
ai-memoryにはignore_pathsによるキャプチャ除外設定があるので、機密情報を含むパスは事前に除外ポリシーを設定しておく必要があります。
実用上おさえておきたい注意点をまとめます。
- ignore_pathsの設定は必須に近い。.envファイル・シークレット管理ディレクトリ・認証情報を含むパスは最初に除外ポリシーを書いておく。
- 会話レベルの意思決定は手動で補う。自動観察はツール呼び出しを見ているので、「話し合いで決まったこと」は自動では拾えない。重要な判断はその場で記録しておく習慣が必要。
- チーム共有・クラウド同期はスコープ外。wikiはローカルのGitリポジトリなので、チームで共有したければ自分でGitリモートを設定してpush/pullする運用が必要になる。ai-memory自体はその同期を管理しない。
このツールが輝くのは、「一人のエンジニアが複数のエージェントCLIを使い分けながら、同一プロジェクトを長期間触り続ける」というシナリオです。
ローカル完結・外部インフラ不要・マルチエージェント共有という3点が揃うユースケースでは、セットアップコストに対してリターンが大きい。
逆に、チーム全体でメモリを共有したい・高精度なセマンティック検索が必要・クラウド同期が前提、という要件があるなら、Mem0のようなクラウド前提のソリューションの方が合っています。
ai-memoryはあくまで「ローカルで完結する軽量な記憶層」として設計されています。
その設計判断を理解した上で使えば、AIコーディングの日常的な消耗をかなり減らせるツールだと思います。
株式会社ホコサキは、山口県宇部を拠点にAI活用支援・業務システム開発・DX推進に取り組んでいます。
AIコーディングエージェントの実務導入や、開発ワークフローの改善について相談したい方は、お気軽にご連絡ください。
お問い合わせはこちら