# 评估与选型对比

架构评估维度、中立的记忆层评估清单、场景选型指南、可复现基准测试与迁移方案。

- Canonical: https://docs.xmemo.dev/zh/docs/guides/evaluate
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 0069e449eaa8f028d7308cb779002505a54942410f60a2fededb0cfff578c724
- Edition-Digest: 7897a0339272378794bf0286e084e5cbece9a35bba584d98acec38cd077ffd4d
- Source-Revision: sha256:a21dd7bbdb6629dd16a471cb65bb89a3850e15a29b88ca1f457ab66fcf565701

## 架构评估维度

评估 Agent 记忆系统不能仅停留在表层的向量检索，而必须深入核心生产架构：数据存储模型、多租户边界、一致性保证、协议合规性、延迟指标与机器可读性。

- 存储模型：混合关系型元数据与向量嵌入对比纯向量扁平存储。关系型底层保证精确过滤下推、不可变审计日志与确定性作用域分区。
- 多租户隔离：硬件或服务端强制的租户物理分区对比应用层元数据软过滤。共享 Agent 空间需通过密码学签名的空间绑定来保障。
- 一致性保证：分布式工具调用间的“写后读（read-your-writes）”一致性对比导致连续 Agent 循环产生幻觉的最终一致性窗口。
- 协议合规：原生 Model Context Protocol (MCP) Streamable HTTP 端点对比需要各框架 SDK 适配器的专有封装。
- 机器可读性：结构化、确定性 JSON 响应，严格遵守工具模式定义，无多余闲聊包装或自然语言尾缀。

## 评估任何记忆层的核心要素

从七个生产基础维度评估任何 Agent 记忆系统：作用域隔离、调用方归因、生命周期删除、协议集成、并发速率限制、可复现基准测试以及方案相关特性。

- 作用域隔离：询问任何厂商如何对用户、会话、Agent 和工作区记忆进行分区隔离。XMemo 在存储边界强制实施 4 级正交作用域层次（user、session、agent、team/space）并提供一等公民项目隔离（参见 /docs/concepts/scopes 与 /docs/concepts/projects）。
- 归因与来源追溯：询问任何厂商每次记忆写入和变更是否能追溯至经过验证的调用方身份与来源事件。XMemo 在审计日志中记录调用方归属、Agent 实例指纹以及来源元数据，并保留版本历史（superseded 版本）与更新 DAG（参见 /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)"      }
    ]
  }
}
```

## 场景选型指南

根据您的工作负载拓扑、团队结构与治理要求，选择适宜的记忆架构模式。

- 多环境多 Agent 工作流：在跨 Claude Code、Cursor、ChatGPT、Codex 和 Gemini CLI 编排 Agent 时，选择具备原生 MCP 支持、共享项目作用域和跨客户端同步能力的记忆层。
- 受监管与企业级工作区：优先选择提供正交作用域层次（user、session、agent、team/space）、调用方归因审计日志以及硬件或服务端强制租户边界的架构。
- 高并发自主循环：选择具备版本化更新树、乐观锁和写后读（read-your-writes）一致性的架构，以避免相互冲突的更新与过期记忆引起的幻觉。

## 可复现基准测试方法论

XMemo 提供开源且仓库内建的基准测试套件，用于在受控条件下评估检索准确率与治理约束。评测体系严格区分内部合成评测、真实生产延迟与对外性能声明三者界限。

- 评测方法契约：基准测试遵循冻结且可复现的方法契约，采用确定性 Golden 数据集与记录的验证追踪。
- 内部合成评测：通过 scripts/benchmark_runner.py 基于 tests/data/recall_golden_set.jsonl（SHA-256 7533FBDC...）离线运行，用于评估纯内存检索算法质量与排序逻辑，不包含网络与数据库 I/O 开销。
- 真实生产延迟：端到端延迟包含 TLS 握手、网络传输、数据库事务与多租户隔离判定开销；其实际表现取决于部署拓扑（托管 SaaS 或自建 Docker）与网络物理距离，绝不能以纯内存合成评测数据代指。
- 对外性能声明：任何公开引用的性能指标均须引用不可变 benchmark_run_id 与验证运行产生的原始验证报告。未经独立验证的供应商声明和合成快捷方式均排除在基线断言之外。
- 边界失败案例分析：记录了一起极端冲突案例——当两个不同项目空间中存在同名实体（'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 指南

从传统键值库、纯向量数据库或外部记忆服务平滑迁移至 XMemo 遵循四阶段流程。

- 阶段 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：在开启 Agent 写入权限前，使用 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 专为 Agent 事实、状态与技能沉淀设计，无法替代承载任意复杂 SQL 事务的主业务数据库。
- 非非结构化大文件存储：超过 32 KB 的完整文档应索引至知识库（Knowledge Bases），而非作为单条内联记忆节点存放。
- Dream 反思周期性：reflect API 与 MCP 工具表面不暴露调度器；后台 Dream 调度受特性开关与方案/权益控制（预设包括 manual［默认］、所有者本地 03:00 的 daily 或 weekly），整合过程与写入并非同步。
- 速率限制：托管端点实行由 api-authentication 管理的运行时速率限制，而非公开发布的静态配额；客户端严禁硬编码配额假设。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。