memory-systems

メモリシステムの設計

メモリは、エージェントがセッションをまたいで一貫性を保ち、蓄積された知識をもとに推論できるようにする永続化レイヤーです。シンプルなエージェントはメモリを完全にコンテキストに依存しているため、セッションが終了するとすべての状態が失われます。高度なエージェントでは、直近のコンテキストのニーズと長期的な知識の保持とのバランスを取る、階層化されたメモリアーキテクチャを実装します。ベクトルストアからナレッジグラフ、さらに時間的ナレッジグラフへと進化するにつれて、検索と推論の改善に向けた構造化メモリへの投資が増していきます。

有効化するタイミング

次の場合に、このスキルを有効化します：

• セッションをまたいで知識を保持する必要のあるエージェントを構築する場合
• メモリフレームワーク（Mem0、Zep/Graphiti、Letta、LangMem、Cognee）を選択する場合
• 会話をまたいでエンティティの一貫性を維持する必要がある場合
• 蓄積された知識をもとに推論する機能を実装する場合
• 本番環境でスケールするメモリアーキテクチャを設計する場合
• ベンチマーク（LoCoMo、LongMemEval、DMR）を用いてメモリシステムを評価する場合
• エンティティや関係を自動抽出し、自己改善するメモリを備えた動的メモリを構築する場合（Cognee）

ほかのスキルが担当する、隣接領域の作業ではこのスキルを有効化しないでください：

• ファイルベースのスクラッチパッド、実行ログ、ツール出力の退避：filesystem-context。
• 会話の圧縮や、人が読める形式の引き継ぎ用要約：context-compression。
• 1つの軌跡内でのマスキング、プレフィックスキャッシュ、トークン予算、検索範囲の限定：context-optimization。
• RDF 状態に基づく形式的な信念・欲求・意図のモデル：bdi-mental-states。

コアコンセプト

メモリは、揮発性のコンテキストウィンドウから永続ストレージまでの連続体として捉えてください。ベンチマークのエビデンスによれば、一部のメモリワークロードでは、ツールの複雑さよりも確実な検索のほうが重要です（claim-memory-locomo-filesystem-baseline）。そのため、検索品質が低下するか、エージェントにマルチホップ推論、関係のたどり直し、または時間を遡るクエリが必要になるまでは、検索ニーズを満たす最もシンプルなレイヤーをデフォルトで使用してください。グラフや時間的な有効性などの構造を追加するのは、その後にしてください。

詳細なトピック

本番環境向けフレームワークの概要

エージェントが必要とする主要な検索パターンに基づいて、フレームワークを選択します。この表で候補を絞り込み、以下のベンチマークデータで検証してください。

フレームワーク	アーキテクチャ	最適な用途	トレードオフ
Mem0	ベクトルストア＋グラフメモリ、バックエンドの差し替えが可能	マルチテナントシステム、幅広い連携	マルチエージェント向けの特化度は低め
Zep/Graphiti	時間的ナレッジグラフ、双時制モデル	関係性のモデリングと時間的推論が必要なエンタープライズ	高度な機能はクラウド限定
Letta	階層型ストレージ（コンテキスト内／コア／アーカイブ）を備えた自己編集型メモリ	エージェントの完全な内省、ステートフルなサービス	シンプルなユースケースには複雑
Cognee	カスタマイズ可能な ECL パイプラインと Tasks を介した多層セマンティックグラフ	進化し、適応・学習するエージェントメモリ、複数段階の推論	取り込み時の処理負荷が大きい
LangMem	LangGraph ワークフロー向けのメモリツール	すでに LangGraph を採用しているチーム	LangGraph との結び付きが強い
File-system	命名規則を用いたプレーンファイル	シンプルなエージェント、プロトタイピング	セマンティック検索や関係性に対応しない

エージェントに双時制モデリング（イベントが発生した時点と取り込まれた時点の両方を追跡する機能）が必要な場合は、Zep/Graphiti を選択してください。3 層構造のナレッジグラフ（エピソード、セマンティックエンティティ、コミュニティのサブグラフ）が時間的なクエリに優れています。マネージドインフラストラクチャを使って迅速に本番導入することを優先する場合は、Mem0 を選択してください。Agent Development Environment を通じてエージェントに深い自己内省を求める場合は、Letta を選択してください。エージェントが高密度な多層セマンティックグラフを構築する必要がある場合は、Cognee を選択してください。テキストチャンクとエンティティタイプをノードとして、詳細な関係エッジとともに階層化し、取り込み、エンティティ抽出、後処理、検索というすべての主要な要素をカスタマイズできます。

ベンチマーク性能の比較

期待値を設定する際はこれらのベンチマークを参照してください。ただし、絶対的な順位ではなく、検索の各側面に関する情報源固有の指標として扱ってください。単一のベンチマークだけで決定的な判断はできません。

システム	DMR 正確性	LoCoMo	HotPotQA（複数段階の推論）	レイテンシ
Cognee	—	—	公開済みの高スコア	変動あり
Zep（Temporal KG）	公開済みの高スコア	—	指標全体では中程度	低レイテンシとの報告あり
Letta（filesystem）	—	公開済みのファイルシステム基準値	—	—
Mem0	—	公開済みの特化ツール基準値	ある比較では低め	—
MemGPT	公開済みの高スコア	—	—	変動あり
GraphRAG	公開済みの中～高スコア	—	—	変動あり
Vector RAG baseline	公開済みの低めのスコア	—	—	高速

要点：メモリシステムはブランドではなく、検索の特性で比較してください。ベンチマークの数値は、製品に関する主張を行う前に再確認が必要な、日付付きの証拠として扱います。安定した設計原則は、まずは浅い構成から始め、検索品質を測定し、よりシンプルな層では不十分な場合に限ってセマンティック構造やグラフ構造を追加することです。

Memory Layers（判断ポイント）

永続化要件を満たす最もシンプルなメモリレイヤーを選択してください。レイヤーが深くなるほど、インフラコストと運用の複雑さが増すため、よりシンプルなレイヤーでは検索や耐久性の要件を満たせない場合に限り、段階的に移行してください。

レイヤー	永続性	実装	使用する場面
作業用	コンテキストウィンドウ内のみ	システムプロンプト内のスクラッチパッド	常に使用 — 注意が向きやすい位置を活用して最適化します
短期	セッション単位	ファイルシステム、インメモリキャッシュ	中間的なツール結果、会話状態
長期	セッションをまたぐ	キー値ストア → グラフ DB	ユーザーの好み、ドメイン知識、エンティティレジストリ
エンティティ	セッションをまたぐ	エンティティレジストリ + プロパティ	アイデンティティの維持（「John Doe」が会話をまたいで同一人物であること）
Temporal KG	セッションをまたぐ + 履歴	有効期間を持つグラフ	時間の経過とともに変化する事実、タイムトラベルクエリ、コンテキストの衝突防止

検索戦略

クエリの形式に合った検索戦略を選んでください。セマンティック検索は直接的な事実の検索には適していますが、マルチホップ推論では性能が低下します。エンティティベースのトラバーサルは「X についてのすべて」というクエリに適していますが、グラフ構造が必要です。時間フィルタリングは変化する事実を扱えますが、有効性のメタデータが必要です。正確性が最優先で、インフラ予算に余裕がある場合は、複数の戦略を組み合わせたハイブリッド検索を使用してください。

戦略	使用する場面	制約
セマンティック（埋め込み類似度）	直接的な事実のクエリ	マルチホップ推論では性能が低下します
エンティティベース（グラフトラバーサル）	「X についてのすべてを教えて」	グラフ構造が必要です
時間ベース（有効性フィルター）	事実が時間とともに変化する場合	有効性のメタデータが必要です
ハイブリッド（セマンティック + キーワード + グラフ）	総合的に最も高い正確性	最も多くのインフラが必要です

ハイブリッド方式では、関連するサブグラフやメモリのみを取得することで、アクティブなコンテキストを削減できます。Cognee は、グラフ、ベクトル、リレーショナルストアにまたがる複数の検索モードを通じてハイブリッド検索を実装しています。これにより、エージェントは画一的な方式を使うのではなく、クエリの種類に合った検索戦略を選択できます。

メモリの統合

無制限な増加を防ぐため、定期的に統合処理を実行してください。メモリが無制限に蓄積すると、時間の経過とともに検索品質が低下するためです。無効化しても破棄はしないでください — 過去の状態を再構築する必要がある時間ベースのクエリでは、履歴の保持が重要です。統合処理は、メモリ数のしきい値、検索品質の低下、または定期実行によって開始します。動作する統合コードについては、実装リファレンスを参照してください。

実践的なガイダンス

メモリアーキテクチャの選択

まずは実用可能な最もシンプルなレイヤーから始め、検索品質が低下した場合にのみ複雑さを追加してください。 ほとんどのエージェントは、最初から時間ベースのナレッジグラフを必要としません。以下の段階的な移行手順に従ってください。

1. プロトタイプ：ファイルシステムメモリを使用します。事実をタイムスタンプ付きの構造化 JSON として保存します。これにより、インフラに投資する前にエージェントの動作を検証できます。
2. スケール：エージェントがセマンティック検索とマルチテナント分離を必要とする場合は、Mem0 またはメタデータ付きのベクトルストアに移行します。ファイルベースの検索では類似性クエリを処理できないためです。
3. 複雑な推論：エージェントが関係のトラバーサル、時間的な有効性、またはセッションをまたぐ統合を必要とする場合は、Zep/Graphiti を追加します。Graphiti は汎用的な関係を持つ構造化された結び付きを使用し、シンプルで推論しやすいグラフを維持します。一方、Cognee は詳細な関係エッジを持つ、より密な多層セマンティックグラフを構築します。エージェントに必要なのが時間的な双方向モデリング（Graphiti）か、より豊かで相互接続された知識構造（Cognee）かに応じて選択してください。
4. 完全な制御：エージェントが深い内省を伴って自身のメモリを管理する必要がある場合は、Letta または Cognee を使用します。これらのフレームワークでは、メモリ操作がエージェントの第一級アクションとして公開されているためです。

コンテキストとの統合

すべてを事前に読み込むのではなく、必要なときにメモリを読み込んでください。大きなコンテキストペイロードはコストがかかり、注意の質を低下させるためです。取得したメモリは、生成への影響を最大化できるよう、注意が向きやすいコンテキストの位置（先頭または末尾）に配置してください。

エラーからの復旧

メモリシステムには本質的にノイズがあるため、取得に失敗しても適切に対処してください。次の復旧方法を順番に適用します。

• 取得結果が空の場合：より広い検索に切り替えます（エンティティフィルターを外し、時間範囲を広げます）。それでも結果が空の場合は、ユーザーに確認を求めます。
• 結果が古い場合：valid_until のタイムスタンプを確認します。結果の大半が期限切れの場合は、再試行する前に統合を実行します。
• 事実が矛盾する場合：valid_from が最も新しい事実を優先します。確信度が低い場合は、ユーザーに矛盾を伝えます。
• 保存に失敗した場合：再試行用に書き込みをキューに入れます。メモリへの書き込みによって、エージェントの応答を決してブロックしないでください。

例

例 1：Mem0 との統合

from mem0 import Memory

m = Memory()
m.add("User prefers dark mode and Python 3.12", user_id="alice")
m.add("User switched to light mode", user_id="alice")

# Retrieves current preference (light mode), not outdated one
results = m.search("What theme does the user prefer?", user_id="alice")

例 2：時間的なクエリ

# Track entity with validity periods
graph.create_temporal_relationship(
    source_id=user_node,
    rel_type="LIVES_AT",
    target_id=address_node,
    valid_from=datetime(2024, 1, 15),
    valid_until=datetime(2024, 9, 1),  # moved out
)

# Query: Where did user live on March 1, 2024?
results = graph.query_at_time(
    {"type": "LIVES_AT", "source_label": "User"},
    query_time=datetime(2024, 3, 1)
)

例 3：Cognee によるメモリの取り込みと検索

import cognee
from cognee.modules.search.types import SearchType

# Ingest and build knowledge graph
await cognee.add("./docs/")
await cognee.add("any data")
await cognee.cognify()

# Enrich memory
await cognee.memify()

# Agent retrieves relationship-aware context
results = await cognee.search(
    query_text="Any query for your memory",
    query_type=SearchType.GRAPH_COMPLETION,
)

ガイドライン

1. ファイルシステムを使ったメモリから始め、検索品質の向上に必要な場合にのみ複雑さを加えます
2. 時間の経過とともに変化する可能性のある事実は、時間的な有効性を追跡します
3. 精度を最大化するために、ハイブリッド検索（セマンティック検索＋キーワード検索＋グラフ検索）を使用します
4. メモリを定期的に統合します。無効化しても破棄はしません
5. 検索に失敗する状況に備え、メモリの検索結果がない場合は必ずフォールバックを用意します
6. 永続メモリのプライバシーへの影響（保持ポリシー、削除権など）を考慮します
7. 変更の前後に、LoCoMo または LongMemEval を使ってメモリシステムをベンチマークします
8. 本番環境でのメモリの増加と検索レイテンシーを監視します

注意点

1. すべてをコンテキストに詰め込む：利用可能なメモリをすべてプロンプトに読み込むのはコストがかかり、注意の質を低下させます。代わりに、関連性で絞り込んだうえで、必要なときに検索してください。
2. 時間的な有効性を無視する：事実は古くなります。有効性を追跡しなければ、古い情報がコンテキストを汚染し、エージェントが誤った前提に基づいて動作します。
3. 早い段階で過剰に設計する：単純なファイルシステムベースのメモリは、一部のベンチマークで、より特化したツールを上回ることがあります（claim-memory-locomo-filesystem-baseline）。単純な方法では明らかに不十分な場合にのみ、高度な方法を追加してください。
4. 統合戦略がない：メモリが際限なく増えると、時間とともに検索品質が低下します。統合を実行するためのメモリ件数のしきい値、または定期的な実行間隔を設定してください。
5. 埋め込みモデルの不一致：ある埋め込みモデルでメモリを書き込み、別のモデルで読み取ると、ベクトル空間は相互に置き換えられないため、検索品質が低下します。メモリストアごとに単一の埋め込みモデルを固定し、モデルを変更する場合はすべてのエントリーを再埋め込みしてください。
6. グラフスキーマの硬直性：過度に構造化されたグラフスキーマ（硬直したノード型、固定された関係ラベル）は、ドメインが変化したときに破綻します。新しいエンティティ種別の追加にスキーマの移行が不要となるよう、汎用的な関係型と柔軟なプロパティバッグを優先してください。
7. 古いメモリによる汚染：現在の状態と矛盾する古いメモリは、気づかれないままエージェントの動作を損ないます。有効期限ポリシーや確信度の減衰を実装し、古くなった事実の優先度を下げるとともに、矛盾が検出された場合は明示してください。
8. メモリとコンテキストの不一致：話題としては関連していても、コンテキストに合わないメモリ（例：エージェントが Python 言語について話しているときに、ニシキヘビの「Python」に関するメモリを取得すること）を検索してしまう場合があります。メモリエントリーにセッションまたはドメインのメタデータを含め、検索時にそれらで絞り込むことで軽減できます。

統合

このスキルは、永続的な意味メモリを管理します。隣接するスキルは、スクラッチストレージ、圧縮、コンテキスト戦略を管理します。

• filesystem-context：意味検索が必要になる前の、ファイルベースのスクラッチパッド、ログ、シンプルな実行状態。
• context-compression：セッション状態を文章で保持する要約と引き継ぎ。
• context-optimization：アクティブなコンテキスト予算内でのジャストインタイムのメモリ読み込みと検索範囲の限定。
• context-degradation：古くなった、または矛盾するメモリによるコンテキスト汚染や衝突。
• bdi-mental-states：信念、欲求、意図、来歴の連鎖が重要な場合の、形式的なメンタルステートのモデリング。
• multi-agent-patterns：エージェント間で共有されるメモリ。
• evaluation：メモリ品質、検索の正確性、ベンチマークの選定。

参考資料

内部資料：

• 実装リファレンス - ベクトルストア、プロパティグラフ、時間クエリ、またはメモリ統合ロジックをゼロから実装する場合に参照します。

このコレクションの関連スキル：

• context-fundamentals - メモリが入力されるコンテキストレイヤーを設計する場合に参照します。
• multi-agent-patterns - 複数のエージェントがメモリ状態を共有または調整する必要がある場合に参照します。

外部リソース：

• Zep の時間的ナレッジグラフに関する論文（arXiv:2501.13956） - 双時間モデリングや Graphiti のアーキテクチャを評価する場合に参照します。
• Mem0 の本番環境向けアーキテクチャ論文（arXiv:2504.19413） - マネージドメモリインフラストラクチャのトレードオフを評価する場合に参照します。
• Cognee の最適化されたナレッジグラフと LLM 推論に関する論文（arXiv:2505.24478） - 多層の意味グラフアプローチを比較する場合に参照します。
• LoCoMo ベンチマーク（Snap Research） - 長い会話におけるメモリ保持を評価する場合に参照します。
• MemBench 評価フレームワーク（ACL 2025） - メモリ評価スイートを設計する場合に参照します。
• Graphiti オープンソースの時間的 KG エンジン（github.com/getzep/graphiti） - 時間的ナレッジグラフを実装する場合に参照します。
• Cognee オープンソースのナレッジグラフメモリ（github.com/topoteretes/cognee） - メモリ向けのカスタマイズ可能な ECL パイプラインを構築する場合に参照します。
• Cognee の比較：形式と機能 - Mem0、Graphiti、LightRAG、Cognee のグラフ構造を比較する場合に参照します。

---

スキルのメタデータ

作成日: 2025-12-20 最終更新日: 2026-05-15 作成者: Agent Skills for Context Engineering Contributors バージョン: 4.1.0