Codexで過去の記憶や会話、作業内容を、忘れてしまうって面倒ですが実は
第2の「脳みそ」を追加して、話が途切れても文脈を完全に理解し、記憶を残せる様にする仕組みがあります。その名もAgentmemory
AIエージェントの活用が広がる中で、多くのユーザーが共通して直面する課題があります。それは、AIが過去の会話や作業内容を「忘れてしまう」という問題です。特に、Claude CodeやCodexのようなエージェントを日常的に利用していると、「セッションを新しく開くたびに、また同じ前提から説明し直さなければならない」という状況に頻繁に遭遇します。
例えば、昨日合意した設計判断や、一週間前に決定した機能の要件など、本来であれば継続して記憶しておくべき情報が、セッションを跨ぐと失われてしまいます。これはまるで、AIが「健忘症」にかかっているかのようです。この「記憶の欠如」は、作業効率を著しく低下させ、AIとの対話においてフラストレーションの原因となります。
このような課題を解決するために登場したのが、「Agentmemory」というツールです。Agentmemoryは、AIエージェントに永続的な記憶を後付けすることを可能にし、AIが過去の文脈を保持したまま、より賢く、より効率的に作業を進められるように設計されています。
本記事では、このAgentmemoryの導入方法から設定、そして実際の運用における注意点までを詳細に解説します。Agentmemoryを導入することで、AIエージェントが「昨日の続きから」作業を開始できるようになり、あなたのAI活用体験は大きく向上するでしょう。AIの「健忘症」を克服し、よりスムーズな協業を実現するための具体的なステップを、これからご紹介します。
【緊急企画開催】
あなた専用に働く
AI社員を1on1で構築します。
Codex / Claude Code を使って、
今あなたが使っている環境で
実際に動くAI社員を一緒に作成します。
・作業を自動で進めたい
・毎回の指示出しを減らしたい
・AIにタスクを任せられる状態を作りたい
・自分専用のAIチームを持ちたい
そんな方は、今がチャンスです。
期間限定で受付中なので、
興味がある方はお早めに。
希望される方は、下記から
「AI社員構築」
と送信してください
🔻🔻🔻🔻🔻🔻🔻🔻
🔺🔺🔺🔺🔺🔺🔺🔺
CLAUDE.md（AGENTS.md）の限界
AIエージェント、特にClaude CodeやCodexには、プロジェクト直下にある特定のMarkdownファイル（Claude CodeではCLAUDE.md、CodexではAGENTS.md）を起動時に読み込む機能があります。この機能は、プロジェクト固有のルールや制約、例えば「この言語でコードを書いてほしい」「このフォルダは変更しないでほしい」「テストは特定のフレームワークを使ってほしい」といった指示をAIに伝える上で非常に有効です。
しかし、この仕組みでカバーできるのは、あくまで「不変のプロジェクト規約」に限られます。つまり、プロジェクトの根幹に関わる、頻繁には変わらないルールを伝えるのに適しています。一方で、以下のような「不変ではないが、セッションを跨いで記憶しておきたい情報」は、CLAUDE.mdに含めるには不向きです。
•過去の作業履歴: 例えば、「昨日の作業でデータベースのマイグレーション順序で問題が発生した」といった具体的な失敗ログや、その解決策。
•意思決定の経緯: 一週間前にチームで合意した「この機能はリリースしない」という決定や、その理由。
•技術的な比較検討: 月曜日に試したライブラリAと火曜日に試したライブラリBの比較結果や、それぞれのメリット・デメリット。
•進行中のタスクの状態: 現在取り組んでいるTODOリストの中で、どこまでが完了し、何が残っているかといった進捗情報。
これらの情報をすべてCLAUDE.mdに詰め込もうとすると、ファイルはあっという間に肥大化し、数千行にも及ぶ可能性があります。その結果、AIエージェントがセッションごとに読み込むコンテキストの量が増大し、肝心のコード生成や推論の精度が低下する現象が起こり得ます。これは、コンテキスト長が長くなるほどAIの推論精度が下がるという研究結果が示す通り、無限に情報を詰め込めば良いというわけではありません。
CLAUDE.mdは「会社の就業規則」のようなもので、普遍的なルールを定める場所です。しかし、日々の業務で発生する「個人の業務日報」や「机の上の付箋」のような一時的かつ変動的な情報は、別の場所で管理する必要があります。Agentmemoryは、まさにこの「不変ではないが、セッションを跨いで残したい情報」の置き場所問題に対する効果的な解決策を提供します。
Agentmemoryの仕組みと正体
Agentmemory（npmではmyagentmemory、CLIコマンドはagent-memory）の核心は、非常にシンプルかつ強力な組み合わせにあります。それは、「ローカルのMarkdownディレクトリ」と「qmdによる検索」、そして「Skillを介した自動コンテキスト注入」です。
agent-memory initコマンドを実行すると、ユーザーのホームディレクトリ配下（通常は~/.agent-memory/）に、以下のような構造のディレクトリが作成されます。これは、Agentmemoryが情報をどのように管理しているかを示しています。
1~/.agent-memory/2 MEMORY.md # 長期記憶（ユーザーが整理する主要な記憶領域）3 SCRATCHPAD.md # 短期的なタスクや覚えておきたいことのチェックリスト4 daily/5 2026-05-29.md # 日ごとの作業ログやメモ（追記専用）6 2026-05-28.md7 ...8 topics/9 auth.md # 特定のテーマに関するログや情報（dailyから逆引き可能）
この構造からわかるように、Agentmemoryは特別なデータベースを使用していません。すべての情報は、プレーンなMarkdownファイルとしてローカルに保存されます。この「プレーンテキストでの管理」には、想像以上に多くのメリットがあります。
1.高い可読性: catコマンドなどでファイルの中身を直接読み込むことができ、AIがどのような情報を参照しているかを簡単に確認できます。
2.容易な履歴管理: Gitなどのバージョン管理システムを使って、記憶の変更履歴を追跡・管理できます。これにより、いつ、どのような情報が追加・変更されたかを把握し、必要に応じて過去の状態に戻すことが可能です。
3.高い堅牢性: 万が一Agentmemoryツール自体に問題が発生しても、データは単なるMarkdownファイルとして残るため、資産が失われる心配がありません。手動での修正や移行も容易です。
4.ツールへの依存度の低減: 特定のツールにロックインされることなく、柔軟に情報を活用できます。
そして、このローカルに蓄積されたMarkdownファイルを「検索可能な形でAIセッションに注入する」役割を担うのが、qmdという強力な検索エンジンです。
qmd：Shopify CEOが開発したローカル検索エンジン
tobi/qmdは、Agentmemoryとは独立したオープンソースプロジェクトであり、ShopifyのCEOであるTobi Lütke氏自身が開発に深く関わっています。これは単なる簡易的な検索ツールではなく、「ローカルで動作するハイブリッド検索エンジン」として設計されており、3つの異なる検索モードを提供します。
qmdは、埋め込みモデルやリランクモデル、クエリ拡張モデルをHuggingFaceから自動的にダウンロードし、GGUF（量子化済みのローカルLLM形式）として~/.cache/qmd/models/に保存します。これらのモデルは合計で約2GB程度のサイズですが、すべてローカルで完結するため、外部にデータが送信されることはありません。
特に注目すべきは、qmd queryモードにおけるハイブリッド検索の高度なパイプラインです。このモードでは、RRF（Reciprocal Rank Fusion）という複数の検索結果を統合する手法や、Qwen3-Reranker-0.6Bのようなリランカーモデルが活用されています。具体的には、元のクエリをLLMで2つの異なるクエリに拡張し、それぞれをBM25とベクトル検索で実行します。その後、得られた結果をRRFで統合し、位置情報に基づいた重み付けで再ランク付けするという、非常に洗練されたプロセスが1つのコマンドの裏側で実行されています。
Agentmemoryは、このqmdの強力な検索機能の上に、コーディングエージェント向けの使いやすいガイド（SKILL.md）を載せた構造と言えます。つまり、技術的な複雑さの大部分はqmdが引き受けており、ユーザーはMarkdownファイルとqmdコマンドさえあれば、同様の記憶システムを自前で構築することも可能です。
最速セットアップ手順
ここからは、Agentmemoryを実際に動かすための具体的な手順を、最小限のステップで解説します。MacユーザーであればHomebrew経由でのインストールが最も簡単ですが、npm経由でも導入可能です。
- Agentmemory本体のインストール
まず、Agentmemoryの本体をシステムにインストールします。Homebrewを使用する場合とnpmを使用する場合の2つの方法があります。
Homebrewを使用する場合:
1# 1. agentmemoryのリポジトリをタップ brew tap jayzeng/agentmemory https://github.com/jayzeng/agentmemory # 2. agent-memoryコマンドをインストール brew install jayzeng/agentmemory/agent-memory
npmを使用する場合:
1npm install -g myagentmemory
どちらかの方法でAgentmemory本体をインストールしてください 。
- 記憶ディレクトリの作成
次に、Agentmemoryが記憶を保存するためのディレクトリを作成します。このコマンドを実行すると、ユーザーのホームディレクトリ（~/.agent-memory/）に、MEMORY.mdやdaily/などの記憶管理に必要なファイルとフォルダが自動的に生成されます。
Bash
agent-memory init
- qmdのインストールと初期設定
セマンティック検索機能を利用するためには、qmdのインストールが必須です。qmdはAgentmemoryの強力な検索エンジンとして機能します。
Bash
1npm install -g @tobilu/qmd
インストール後、初回のみ埋め込みモデルのダウンロードと初期設定が必要です。qmd embedコマンドを実行すると、必要なGGUFモデルがダウンロードされ、セマンティック検索の準備が整います。このプロセスには2〜3分かかる場合があります。
Bash
1qmd embed # 初回はGGUFモデルをダウンロードするため、数分かかります
日本語環境への最適化:
qmdのデフォルトの埋め込みモデルは英語に最適化されているため、日本語でのセマンティック検索精度を向上させるには、モデルの切り替えを推奨します。Qwen3-Embeddingモデルを使用することで、日本語の検索精度が大幅に向上します。以下のコマンドを実行し、環境変数を設定してからqmd embed -fで再埋め込みを行ってください。
Bash
1export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf" qmd embed -f # -fオプションで全件再埋め込みを実行します
-fオプションを付けないと、古いモデルのベクトル情報が残ってしまうため、必ず指定してください。
- AIエージェントへのSkill適用
最後に、Claude Code、Codex、CursorなどのAIエージェントがAgentmemoryを利用できるように、必要なSKILL.mdファイルを配置します。このコマンドを実行すると、各エージェントがAgentmemoryの機能を使えるようになります。
Bash
1agent-memory install-skills
これらのステップを完了することで、あなたのAIエージェントは永続的な記憶を持つ準備が整います。次のセクションでは、Agentmemoryを最大限に活用するための実践的な運用テクニックについて解説します。
実践的な運用テクニック
Agentmemoryの導入が完了したら、次に重要なのはその機能を最大限に引き出すための実践的な運用方法です。ここでは、AIエージェントがどのように記憶を活用し、あなたがどのように記憶を管理していくべきかについて解説します。
効果的な書き込みコマンドの使い方
Agentmemoryは、あなたの記憶を効率的に記録・管理するためのいくつかのコマンドを提供します。これらを使いこなすことで、AIエージェントの記憶をより豊かにし、あなたの作業フローにシームレスに統合できます。
- 日次ログ（daily）への追記
daily/ディレクトリには、日付ごとのログが自動的に作成されます。その日の作業内容や気づき、発生した問題などを記録するのに最適です。特に、その日に行った具体的な作業や、一時的な判断、遭遇したエラーとその解決策などを記録しておくと、後でAIが参照する際に非常に役立ちます。
例えば、以下のようにコマンドを実行します。
Bash
1agent-memory write --target daily --content "今日の作業でAPI認証の新しいフローを実装。テストは後回し #auth"
このコマンドを実行すると、~/.agent-memory/daily/YYYY-MM-DD.mdのようなファイルに、指定した内容が追記されます。#authのようなハッシュタグを含めることで、後述するテーマ別ログとの連携も容易になります。
- テーマ別ログ（topic）への追記
topics/ディレクトリは、特定のテーマやプロジェクトに関する情報を集約するのに便利です。例えば、認証システムに関するメモや、特定の機能開発に関する詳細、特定の技術スタックに関する調査結果などを記録できます。dailyへの追記時にハッシュタグ（例：#auth）を含めることで、自動的に関連するtopicファイルへの逆リンクが張られるため、情報の整理が容易になります。
例えば、認証システムに関する新しい知見を得た場合、以下のように記録します。
Bash
1# topic に追記（daily への逆リンクも自動で張られる） agent-memory write --target topic --topic auth --content "JWT refresh をエッジに展開する際のセキュリティ考慮事項を調査。CSRF対策が必要 #auth"
このコマンドは、~/.agent-memory/topics/auth.mdファイルに内容を追記します。もしauth.mdが存在しない場合は自動的に作成されます。このようにテーマごとに情報を集約することで、AIが特定の領域に関する深い知識を効率的に参照できるようになります。
- スクラッチパッド（scratchpad）の活用
SCRATCHPAD.mdは、短期的なTODOリストや、一時的に覚えておきたいことのチェックリストとして機能します。これは、まるで机の上の付箋のように、すぐに参照できて、完了したら消せるような情報を管理するのに適しています。例えば、以下のような使い方があります。
Bash
1# スクラッチパッドにTODOを追加 agent-memory scratchpad add --text "rate limit の単体テスト書く"
これにより、SCRATCHPAD.mdに「- [ ] rate limit の単体テスト書く」のような形でタスクが追加されます。タスクが完了したら、以下のコマンドでマークできます。
Bash
1# TODOが完了したらマーク agent-memory scratchpad done --text "rate limit"
このコマンドは、指定したテキストを含む行のチェックボックスを「- [x]」に変更します。完了したタスクは定期的に削除するなどして、スクラッチパッドを常に最新の状態に保つことが重要です。
ハッシュタグとWikiリンクによるナレッジ管理
AgentmemoryのMarkdownファイル内で、#authのようなハッシュタグや[[wiki-link]]のようなWikiリンクを使用すると、qmdの全文検索機能がそれらを自動的に拾い上げます。これは、Obsidianなどのノートツールに慣れているユーザーにとっては非常に馴染みやすい運用方法です。関連する情報をタグ付けしたり、相互にリンクさせたりすることで、知識ベースとしての価値を高めることができます。
例えば、[[プロジェクトXの設計]]というリンクを貼ることで、AIは「プロジェクトXの設計」に関する情報がどこにあるかを把握し、必要に応じてその情報を参照できるようになります。これにより、記憶が単なるテキストの羅列ではなく、相互に関連付けられたナレッジグラフとして機能するようになります。
記憶の整理術：MEMORY.mdのメンテナンス
MEMORY.mdは、あなたのAIエージェントの「長期記憶」を司る重要なファイルです。しかし、このファイルを無計画に肥大化させると、AIがコンテキストを処理する際のトークン消費量が増え、パフォーマンスが低下する可能性があります。Agentmemoryは、優先度の低い情報から自動的にコンテキストから除外する設計になっていますが、それでも定期的なメンテナンスは不可欠です。
長期記憶は、MEMORY.mdに「決定事項だけ」を3〜5行程度の簡潔な記述でまとめるのが理想的です。詳細な情報や経緯は、topics/ディレクトリ内の関連ファイルに記録し、MEMORY.mdからはそれらへの参照を記述するようにしましょう。これにより、MEMORY.mdは常に重要な情報のみを保持し、AIが効率的に長期記憶を参照できるようになります。
例えば、プロジェクトの重要な決定事項をMEMORY.mdに以下のように記述します。
Markdown
1# プロジェクトAの主要決定事項23* 2026-06-01: 認証システムにJWTを採用することを決定。詳細は[[auth_system_design]]を参照。4* 2026-06-05: データベースはPostgreSQLを使用。理由はスケーラビリティと既存システムとの互換性。5* 2026-06-10: フロントエンドフレームワークはReactを選択。開発者の習熟度とエコシステムを考慮。
このように、MEMORY.mdには要点のみを記述し、詳細な情報は[[auth_system_design]]のようなWikiリンクでtopics/auth_system_design.mdなどのファイルに誘導することで、AIは必要に応じて深掘りした情報を参照できます。これにより、トークン消費を抑えつつ、AIが必要な情報にアクセスできる状態を維持できます。
導入前に知っておくべき注意点とFAQ
AgentmemoryはAIエージェントの記憶問題を解決する強力なツールですが、導入前にいくつかの注意点とよくある質問を理解しておくことが重要です。これにより、よりスムーズな運用と期待通りの効果を得ることができます。
OSSとしての成熟度とポータビリティ
Agentmemoryはオープンソースプロジェクトであり、活発に開発が進められています。そのため、機能の追加や改善が頻繁に行われる一方で、破壊的な変更や予期せぬ挙動が発生する可能性もゼロではありません。しかし、すべての記憶データがプレーンなMarkdownファイルとしてローカルに保存されるため、特定のツールにロックインされるリスクは低く、将来的に別のツールへ移行する際のポータビリティは非常に高いと言えます。
トークン消費量と16Kの上限問題
Agentmemoryは、AIエージェントのセッション開始時に関連する記憶をコンテキストとして注入します。この際、注入される記憶の量が増えれば増えるほど、AIが消費するトークン量も増加します。特に、Claude 3 Haikuのような16Kトークンという上限があるモデルを使用している場合、記憶が肥大化しすぎると、本来の指示に使えるトークンが圧迫され、パフォーマンスに影響が出る可能性があります。
Agentmemoryは関連性の低い記憶を自動的に除外する仕組みを持っていますが、それでもMEMORY.mdの適切なメンテナンスや、dailyやtopicファイルの定期的な整理は重要です。本当に必要な情報だけを長期記憶に残し、不要な情報は削除するか、別のアーカイブとして管理することを検討しましょう。
他のメモリ系ツールとの違い
AIエージェントの記憶を扱うツールはAgentmemory以外にもいくつか存在します。例えば、mem0やLettaなどが挙げられます。これらのツールはそれぞれ異なるアプローチや特徴を持っていますが、Agentmemoryは特に以下の点で優位性があります。
•プレーンテキストベース: すべての記憶がMarkdownファイルとしてローカルに保存されるため、透明性が高く、Gitでのバージョン管理が容易です。
•qmdによる強力な検索: Shopify CEOが開発に関わるqmdエンジンをバックエンドに持つことで、キーワード検索とセマンティック検索を組み合わせた高精度な情報抽出が可能です。
•エージェントへのSkill注入: SKILL.mdを通じて、Claude CodeやCodexなどの主要なAIエージェントにシームレスに記憶機能を統合できます。
自前で再実装する場合の見通し
Agentmemoryの仕組みは、ローカルのMarkdownファイルとqmd検索エンジン、そしてエージェントへのコンテキスト注入というシンプルな構成です。そのため、もしあなたがPythonやNode.jsに慣れているのであれば、同様の記憶システムを自前で再実装することも不可能ではありません。実際、qmd自体が独立したライブラリとして提供されているため、これを活用すれば比較的容易にカスタマイズされた記憶システムを構築できるでしょう。
しかし、Agentmemoryはすでに多くのエージェントに対応し、使いやすいCLIとSKILL.mdを提供しています。ゼロから開発する手間を考えると、まずはAgentmemoryを試してみて、必要に応じてカスタマイズを検討するのが現実的なアプローチと言えます。
<!-- 画像挿入位置：Agentmemoryのメリット・デメリットをまとめた表、または他のメモリ系ツールとの比較表 -->
まとめとアクションプラン
本記事では、AIエージェントが抱える「健忘症」という記憶の課題に対し、Agentmemoryがいかに効果的な解決策となるかを解説しました。AIとの対話において、毎回同じ前提を説明し直す手間は、想像以上に大きな負担となります。Agentmemoryを導入することで、この「説明し直し」の時間を大幅に削減し、AIとの協業をよりスムーズで生産的なものに変えることができます。
Agentmemoryは、ローカルのMarkdownファイルと強力なqmd検索エンジンを組み合わせることで、AIエージェントに永続的な記憶を後付けします。これにより、AIは過去の文脈を理解し、より的確なアウトプットを生成できるようになります。また、すべての記憶がプレーンテキストとして管理されるため、透明性が高く、Gitによるバージョン管理も容易です。
あなたのアクションプラン
1.Agentmemoryの導入: 本記事の「最速セットアップ手順」を参考に、Agentmemoryをあなたの開発環境に導入してみましょう。
2.日々の記録: agent-memory write --target dailyコマンドを活用し、日々の作業ログや気づきを積極的に記録してください。
3.テーマ別整理: 特定のテーマに関する情報は--target topicで整理し、ハッシュタグやWikiリンクを積極的に活用して知識ベースを構築しましょう。
4.長期記憶のメンテナンス: MEMORY.mdには重要な決定事項のみを簡潔にまとめ、定期的に見直すことで、AIが常に最適な記憶を参照できるようにします。
AIエージェントは、適切に記憶を管理することで、その真価を発揮します。Agentmemoryは、そのための強力な基盤を提供してくれるでしょう。ぜひ、あなたのAI活用体験を次のレベルへと引き上げるために、Agentmemoryの導入を検討してみてください。
codex 研究ラボでは、これからもAIの最先端技術を分かりやすく解説し、皆さんの開発や業務に役立つ情報を提供していきます。AIとのより良い未来を共に築いていきましょう。
「いいね」「リポスト」「引用」「リプ」
すごく嬉しいので是非！
