memory-systems

メモリシステムの設計

このスキルを使用して、検索、永続性、推論の要件を満たす最もシンプルな永続メモリレイヤーを選択し、実装します。

有効化するタイミング

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

他のスキルが担当する関連作業では、このスキルを有効化しないでください。

• 1つの軌跡内でのトークン予算、検索範囲の指定、またはプレフィックスキャッシュ：context-optimization。
• コンテキストポイズニングとしての古くなったメモリや競合するメモリ：context-optimization（診断モード、references/degradation.md）。

コアコンセプト

揮発性コンテキストから永続ストレージまで、メモリ要件を分類します。 ベンチマークの結果から、一部のメモリワークロードではツールの複雑さよりも信頼性の高い検索のほうが重要であることが示唆されているため、要件を満たす最もシンプルなレイヤーをデフォルトとします（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. 埋め込みモデルの不一致：ある埋め込みモデルでメモリを書き込み、別のモデルで読み取ると、ベクトル空間に互換性がないため、検索品質が低下します。各メモリストアで使用する埋め込みモデルを1つに固定し、モデルを変更した場合はすべてのエントリーを再埋め込みします。
6. グラフスキーマの硬直性：構造化しすぎたグラフスキーマ（固定されたノードタイプや関係ラベル）は、ドメインの変化に対応できなくなります。新しい種類のエンティティを追加するたびにスキーマ移行が必要にならないよう、汎用的な関係タイプと柔軟なプロパティの集合を優先します。
7. 古いメモリによる汚染：現在の状態と矛盾する古いメモリは、気付かないうちにエージェントの動作を損ないます。古くなった事実の優先度をエージェントが下げられるよう、有効期限ポリシーや確信度の減衰を実装します。また、矛盾を検出した場合は明示的に提示します。
8. メモリとコンテキストの不一致：話題としては関連していても、文脈にはそぐわないメモリを取得する場合があります（例：エージェントがプログラミング言語の Python について話しているときに、ヘビの「Python」に関するメモリが取得される）。メモリエントリーにセッションまたはドメインのメタデータを含め、検索時にその情報で絞り込むことで対処します。

統合

このスキルは永続的なセマンティックメモリを管理します。隣接するスキルは、スクラッチストレージ、コンパクション、コンテキスト戦略を管理します。

• context-optimization：アクティブなコンテキスト予算内でのジャストインタイムのメモリ読み込みと検索範囲の設定を扱います。その診断モード（references/degradation.md）では、古くなったメモリや矛盾するメモリを、コンテキストの汚染または衝突として扱います。
• multi-agent-patterns：エージェント間の共有メモリを扱います。
• evaluation：メモリの品質、検索の正確性、ベンチマークの選定を扱います。

参考資料

内部参考資料：

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

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

• context-optimization（基礎リファレンス） - 対象：メモリが情報を供給するコンテキストレイヤーを設計する場合
• 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 間のグラフ構造を比較する場合