# 評価と機能比較 アーキテクチャ評価基準、ベンダーニュートラルなメモリ層チェックリスト、ユースケース別選定指針、再現可能なベンチマーク、および移行手順。 - Canonical: https://docs.xmemo.dev/ja/docs/guides/evaluate - Locale: ja-JP - Content-Locale: ja-JP - Canonical-Content-Digest: 0069e449eaa8f028d7308cb779002505a54942410f60a2fededb0cfff578c724 - Edition-Digest: ef85be99d01433d00ea8ac19d70aac702caab0c27b348949b7e135df9bc41c39 - Source-Revision: sha256:a21dd7bbdb6629dd16a471cb65bb89a3850e15a29b88ca1f457ab66fcf565701 ## アーキテクチャ評価の主要次元 エージェントメモリシステムの評価では、表面的なベクトル検索だけでなく、本番運用のコアアーキテクチャ（データモデル、テナント分離境界、整合性保証、プロトコル適合性、レイテンシ、機械可読性）を精査する必要があります。 - ストレージモデル：ハイブリッドなリレーショナルメタデータ＋ベクトル埋め込みと、フラットなベクトル専用ストアの比較。リレーショナル基盤により、正確なフィルタプッシュダウン、不変の監査ログ、決定論的スコープ分離が保証されます。 - マルチテナント分離：ハードウェアまたはサーバー強制のテナント分離と、アプリケーション層メタデータフィルタリングの比較。エージェント共有空間には暗号署名付きスペースバインディングが必要です。 - 整合性保証：分散ツール呼び出しにおける書き込み後読み取り（Read-your-writes）整合性と、連続エージェントループでハルシネーションを招く結果整合性ウィンドウの比較。 - プロトコル適合性：ネイティブな Model Context Protocol (MCP) Streamable HTTP エンドポイントと、フレームワーク毎の SDK アダプタを要する独自ラッパーの比較。 - 機械可読性：ツールのスキーマ定義に厳密に準拠し、雑談や自然言語の余計なラッパーを含まない構造化された確定的な JSON 応答。 ## あらゆるメモリ層で評価すべき重要項目 スコープ分離、呼び出し元帰属、ライフサイクル削除、プロトコル統合、並行レート制限、再現可能なベンチマーク、プラン依存機能の7つの基盤的な本番次元であらゆるエージェントメモリシステムを評価します。 - スコープ分離：ユーザー、セッション、エージェント、ワークスペースの各メモリがどのように分離されているかを各ベンダーに確認してください。XMemo はストレージ境界で4階層の直交スコープ（user、session、agent、team/space）とファーストクラスのプロジェクト分離を強制します（/docs/concepts/scopes および /docs/concepts/projects を参照）。 - 帰属と出所：すべてのメモリ書き込みおよび変更が検証済みの呼び出し元識別情報および発生イベントまで追跡可能か各ベンダーに確認してください。XMemo は呼び出し元帰属、エージェントインスタンス指紋、出所メタデータを監査ログに記録し、更新 DAG によりバージョン履歴（superseded バージョン）を保持します（/docs/concepts/agent-instance-identity および /docs/concepts/memory-model を参照）。 - 削除とエクスポート：トゥームストーン論理削除、確実なデータ墨消し、一括データエクスポートにプラットフォームがどのように対応しているか各ベンダーに確認してください。XMemo は管理されたライフサイクル状態（active、archived、deleted）、復元可能な論理削除、恒久的な墨消し、構造化 JSON エクスポートを提供します（/docs/concepts/memory-deletion および /docs/api/memory を参照）。 - MCP と REST 統合：標準の REST エンドポイントに加えてネイティブな Model Context Protocol (MCP) をサポートしているか各ベンダーに確認してください。XMemo は凍結された標準ツールカタログを公開するネイティブ Streamable HTTP MCP サーバーと、/v1/ 配下の認証済み REST エンドポイントを提供します（/docs/mcp/overview および /docs/api/authentication を参照）。 - レート制限：リクエストスループットと並行制限がどのように適用され、クライアントに通知されるか各ベンダーに確認してください。XMemo は公開された静的クォータではなく api-authentication 層によるランタイムレート制限を適用しており、クライアントでクォータをハードコードしてはなりません（/docs/api/authentication を参照）。 - 再現可能なベンチマーク：検索精度やレイテンシの主張がオープンなテストハーネスと決定論的データセットで独立検証可能か各ベンダーに確認してください。XMemo は決定論的 Golden Set データセット（recall_golden_set.jsonl）と不変の実行記録を備えたリポジトリ所有のベンチマーク契約を公開し、インメモリ評価とネットワーク I/O を明確に区別しています（/docs/guides/evaluate#reproducible-benchmark-methodology を参照）。 - プラン依存機能：どのバックグラウンド処理や高度な機能が基本ランタイムに含まれ、どの機能が商用ティアで制限されているかを各ベンダーに確認してください。XMemo はコアメモリストレージ、検索、想起、および5つのアクションを持つ reflect ツールを基本ランタイムに含み、定期的なバックグラウンド Dream 内省は機能フラグおよびプラン／エンタイトルメント依存（プリセット：manual、daily、weekly；/docs/concepts/how-xmemo-works および /docs/concepts/dream-reflection を参照）です。 ```json { "evaluation_checklist": { "dimensions": [ { "dimension": "Scope isolation", "question": "How are user, session, agent, and workspace memories segregated?", "xmemo_answer": "4-tier orthogonal scope hierarchy (user, session, agent, team/space) enforced at storage boundary (/docs/concepts/scopes)" }, { "dimension": "Attribution and provenance", "question": "Can every memory mutation be traced to a specific caller and event?", "xmemo_answer": "Caller attribution and agent instance fingerprints recorded in audit logs with version history (/docs/concepts/agent-instance-identity)" }, { "dimension": "Deletion and export", "question": "Does the system support soft deletion, hard redaction, and data export?", "xmemo_answer": "Tombstone soft-deletion with restoration, hard redaction, and structured export (/docs/concepts/memory-deletion)" }, { "dimension": "MCP and REST integration", "question": "Is the memory layer accessible via native MCP as well as HTTP REST?", "xmemo_answer": "Native Streamable HTTP MCP server with frozen tool catalog and authenticated REST endpoints (/docs/mcp/overview)" }, { "dimension": "Rate limits", "question": "How are request quotas communicated and enforced?", "xmemo_answer": "Runtime rate limiting governed by api-authentication without hard-coded client quotas (/docs/api/authentication)" }, { "dimension": "Reproducible benchmarks", "question": "Are retrieval accuracy and performance metrics independently verifiable?", "xmemo_answer": "Open repository-owned benchmark harness with deterministic golden set datasets and run traces (/docs/guides/evaluate#reproducible-benchmark-methodology)" }, { "dimension": "Plan-dependent features", "question": "Which features are core runtime versus gated by tier entitlements?", "xmemo_answer": "Core operations and 5-action reflect tool in base runtime; background Dream reflection is plan/entitlement-dependent (/docs/concepts/dream-reflection)" } ] } } ``` ## シナリオ別選定ガイド ワークロードのトポロジー、チーム構造、ガバナンス要件を評価し、最適なメモリアーキテクチャパターンを選択してください。 - 複数環境に跨るマルチエージェントワークフロー：Claude Code、Cursor、ChatGPT、Codex、Gemini CLI に跨るエージェントを調整する場合は、ネイティブ MCP サポート、共有プロジェクトスコープ、クロス環境同期を備えたメモリ層を選択してください。 - 規制対象およびエンタープライズワークスペース：直交スコープ階層（user、session、agent、team/space）、呼び出し元帰属の監査ログ、ハードウェアまたはサーバー強制のテナント境界を提供するアーキテクチャを優先してください。 - 高並行自律ループ：競合する更新や古いメモリによるハルシネーションを防ぐため、バージョン管理された更新ツリー、楽観的ロック、書き込み後読み取り（read-your-writes）整合性を備えたアーキテクチャを選択してください。 ## 再現可能なベンチマーク手法 XMemo は、制御された環境下で検索精度とガバナンス制約を評価するための、リポジトリ組み込み型のオープンなベンチマークハーネスを提供します。評価体系は、内部合成評価、実際の商用本番レイテンシ、検証済みの公開性能声明の3つを厳密に区別しています。 - 評価手法コントラクト：ベンチマークは、決定論的なゴールデンデータセットと記録された検証トレースを備えた、凍結された再現可能な手法コントラクトに準拠します。 - 内部合成ベンチマーク：tests/data/recall_golden_set.jsonl（SHA-256 7533FBDC...）を用い、scripts/benchmark_runner.py を介して完全オフラインで実行されます。ネットワークやデータベース I/O を伴わない純粋なインメモリ検索アルゴリズム品質とランキングロジックを測定します。 - 実際の商用本番レイテンシ：エンドツーエンドのレイテンシには、TLS ハンドシェイク、ネットワーク往復、データベーストランザクション、マルチテナント分離判定のオーバーヘッドが含まれます。デプロイ構成（クラウド SaaS か自己ホスト Docker か）や地理的距離に左右され、インメモリ合成評価の数値とは本質的に異なります。 - 公開性能声明：公表されるすべての指標は、不変の benchmark_run_id および検証実行からの未加工検証レポートを引用する必要があります。ベンダーによる未検証の主張や合成ショートカットはベースライン表明から除外されます。 - 障害モード分析：2つの異なるプロジェクト空間に存在する同名エンティティ（'config.py'）に対して明示的なプロジェクトスコープ修飾がない場合に検索競合が発生するエッジケースを記録；プロジェクトスコープ制約を追加することで解消されました。 ```bash # Execute reproducible retrieval benchmark against golden set python scripts/benchmark_runner.py \ --track standard \ --dataset tests/data/recall_golden_set.jsonl \ --cache-state COLD_CACHE \ --output reports/custom_run_raw.json ``` ## XMemo への移行手順 従来の Key-Value、ベクトル専用ストア、または外部メモリサービスから XMemo への移行は、4 つの段階に従って実施します。 - フェーズ 1：レガシーメモリ項目を text、user_id、session_id、created_at タイムスタンプを含む JSON Lines としてエクスポートします。 - フェーズ 2：識別子を XMemo のスコープ階層にマッピングします（user_id を owner、session_id を agent_instance_id または project_id にマッピングし、永続性に応じて事実を分類）。 - フェーズ 3：適切なスコープおよび出所属性を指定して、一括 remember ツールまたは REST API（/v1/memories）経由で取り込みます。 - フェーズ 4：エージェントの書き込み権限を有効化する前に、recall_context を使用して検索精度とテナント分離境界を検証します。 ```python import requests def migrate_legacy_record(legacy_item, api_key): payload = { "content": legacy_item["content"], "path": f"migration/{legacy_item.get('id', 'item')}", "scope": "project" if legacy_item.get("project_id") else "user", "metadata": {"source": "legacy_migration", "original_id": legacy_item.get("id")} } response = requests.post( "https://xmemo.dev/v1/memories", headers={"Authorization": f"Bearer {api_key}"}, json=payload ) response.raise_for_status() return response.json() ``` ## 既知の制限と運用境界 システムの誤用を防止するため、XMemo の運用境界と設計上のトレードオフを正確に把握してください。 - 汎用リレーショナルデータベースではありません：XMemo はエージェントの事実、状態、スキルの定着に特化しており、任意の SQL トランザクションを処理する基幹データベースを置き換えるものではありません。 - 非構造化大容量ファイルのダンプ先ではありません：32 KB を超えるドキュメントは、単一のインラインメモリとしてではなく、ナレッジベース（Knowledge Bases）にインデックス付けする必要があります。 - Dream 内省の周期性：reflect API および MCP ツールサーフェスはスケジューラを公開しません。バックグラウンド Dream スケジューリングは機能フラグおよびプラン／エンタイトルメント依存（プリセット：manual［デフォルト］、所有者ローカル 03:00 の daily、または weekly）であり、統合は書き込みと同期しません。 - レート制限：ホスト型エンドポイントは公開された固定クォータではなく api-authentication に基づくランタイムレート制限を適用します。クライアントでクォータをハードコードしないでください。 ## ChatGPT ユーザー bearer token をチャットに貼り付けずに、ChatGPT が XMemo の設定、プロジェクト事実、意思決定、TODO に永続的にアクセスできるようにします。 ChatGPT/OpenAI app の OAuth フローで hosted XMemo MCP server に接続し、XMemo アカウントに memory:read と memory:write の許可を承認します。 合成の設定またはプロジェクトメモを保存し、新しいチャットを開始してから、作業を続ける前に ChatGPT に XMemo 経由でそれを呼び出させます。 OAuth が失敗する、またはツールが表示されない場合は、direct token を作成する前に、ホストアプリで MCP server からサインアウトし、XMemo server URL を再接続して再試行します。 ## Copilot / Codex 開発者 リポジトリの判断、コーディング規約、バグ修正メモ、タスク履歴を IDE と CLI エージェント間で持ち運べます。 利用可能な場合は、VS Code / GitHub Copilot および Gemini CLI に OAuth を使用してください。Copilot CLI、Codex、Cursor、またはその他の直接 MCP クライアントの場合は、XMEMO_KEY をローカル環境またはシークレットストアに保持し、安定した XMEMO_AGENT_INSTANCE_ID を設定してください。 コードベースの判断またはバグ修正を記録し、次の IDE または CLI エージェントに、編集前に関連する XMemo コンテキストを呼び出させます。 呼び出し結果が空の場合は、選択した MCP 設定パス、direct client 用の XMEMO_KEY 環境変数、ホストアプリ内の古い OAuth 認証情報を確認します。 ## チーム / エンタープライズ pilot owner アカウント制御、ソース attribution、エクスポート/削除ワークフロー、レビュー担当者向けに安全な設定証跡で共有メモリを評価します。 保護された XMemo workspace を作成または開き、承認済みユーザーを招待してから、readiness badges に従って OAuth またはスコープ付き direct credential で各クライアントを接続します。 pilot メンバーに合成のチームメモリを保存してもらい、XMemo でソース attribution を確認し、削除/エクスポートとサポート経路をレビューします。 メンバーが接続できない場合は、新しい token を発行する前に、ロール権限、OAuth 承認、クライアント readiness 状態、サポートガイダンスを確認します。 ## 自律エージェント operator headless またはスケジュール済みエージェントが進捗を記録し、過去の判断を取得し、安定した非秘密のインスタンス ID を保持できるようにします。 /api/v1/mcp/config/autonomous-agent を取得します。runner が OAuth + custom headers をサポートする場合は auth_modes.oauth を優先し、完全 headless runner の場合のみ secret store の XMEMO_KEY で auth_modes.xmemo_key を使います。 XMemo に進捗を書き込む合成タスクを 1 つ実行し、runner を再起動して、同じ XMEMO_AGENT_INSTANCE_ID でその進捗を呼び出せることを確認します。 attribution が変わる、または呼び出し結果がインスタンス間で分かれる場合は、XMEMO_AGENT_INSTANCE_ID を git の外に永続化し、runner が起動ごとに再生成していないことを確認します。