# 故障排查 当 OAuth、MCP discovery 或 recall 未按预期工作时，使用 symptom、cause、action 和 safety 指引。 - Canonical: https://docs.xmemo.dev/zh/docs/troubleshooting - Locale: zh-CN - Content-Locale: zh-CN - Canonical-Content-Digest: 78719b9cecfa970434f8f31e363e6e5cca1f6171a945b7c98cd4db05a669dc4b - Edition-Digest: f7e88f22f0834faae22b64fa0da20eae5fc820e706cc5716087d517e1aa786db - Source-Revision: sha256:888cdc62dd33778dae5cd658cec828efa3504abd545d98fc35af9f3fbd35157a ## 不写入 memory 也能验证连接 下面每条故障排查路径都会以 verification 步骤结束。先从读取开始：它可以在不改变任何内容的情况下证明 credential 和 transport。 ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'X-API-Key: ' \ 'https://xmemo.dev/v1/memories/search?query=connection%20check&limit=1' ``` ## 读取 status code Status 可以区分 credential 问题和空的 memory store。 ```text 200 — authorized; an empty results array just means nothing matched. 401 — the credential is missing or not valid. 403 — the credential is valid but lacks the required scope. ``` ## 客户端连接错误 当 AI 客户端或运行器无法连接 MCP 服务器时，在轮换 Token 之前，请先排查传输协议协商与主机路由问题。 - 通过直接向 /health 发起 GET 请求或向 /mcp 发起 OPTIONS 请求验证服务器健康状态。 - 检查传输兼容性：托管客户端使用 Streamable HTTP (/mcp)；本地 CLI 工具使用 stdio。 - 确保企业代理或防火墙允许流式 SSE 响应，避免数据分块被截断。 ```bash curl -I -s 'https://xmemo.dev/mcp' ``` ## 认证失败 认证失败区分了凭据缺失（401 Unauthorized）与权限不足或跨租户边界违规（403 Forbidden）。 - OAuth 客户端：通过宿主应用重新连接并授予 memory:read 与 memory:write 权限。 - Direct MCP 客户端：验证进程环境中是否配置了 XMEMO_KEY，且未在 git 中泄露密钥。 - 403 Forbidden：确认 Token 属于当前激活的租户与 project scope。 ```bash curl -s -o /dev/null -w '%{http_code}\n' \ -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=auth%20check&limit=1' ``` ## 召回结果为空 召回返回零条结果通常表示 scope 范围或查询条件不匹配，而非服务引擎故障。当无匹配数据时，读取请求会正常返回 200 OK。 - Project scope 不匹配：确认查询的 agent 与存储 memory 处于相同的 project 边界下。 - Agent 实例边界：按 XMEMO_AGENT_INSTANCE_ID 过滤的 Direct 客户端无法读取其它实例标识下保存的数据。 - 状态检查：在 Memory Console 中验证 memory 是否已提交且状态为 active，而非软删除或已废弃。 ```bash curl -s -H 'Authorization: Bearer ' \ 'https://xmemo.dev/v1/memories/search?query=test&limit=5&scope=project:demo' ``` ## 写锁超时 来自多个运行器的并发写入或并行的工具调用可能会触发共享 memory path 上的写锁争用。 - 当写入请求返回写锁争用时，在客户端实现带有随机抖动的指数退避重试策略。 - 在重试写入时附带客户端幂等键（idempotency key），防止生成重复的 memory 记录。 - 对于高频写入工作流，使用任务队列或批量 API 对 memory 变更操作进行排队处理。 ```bash curl -s -X POST 'https://xmemo.dev/v1/memories' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{"content":"Durable convention fact","path":"projects/demo/conventions"}' ``` ## 为什么我的 AI assistant 不记得我之前告诉它的事情？ 我保存了重要偏好或细节，但在后续对话中，AI assistant 像从未见过它一样。 Assistant 可能连接到了不同的 XMemo account、project 或 device context，或者原始 memory 没有保存成功。 让 assistant 保存一条小型、非敏感的测试细节，然后打开 Memory Console，检查它是否出现在你使用的 account 和 project 下。 使用虚构的测试细节；不要使用他人的私人信息。 ## 为什么我的 AI assistant 把不同的 project 或对话混在一起？ 一个 project 的细节出现在另一个 project 中，或者 assistant 回答时仿佛两段对话属于同一处。 Assistant 可能使用了与保存 memory 时不同的 project 或 account context。 在 assistant 中选择预期的 XMemo account 和 project，必要时重新连接，然后用清楚标记的测试细节重试。 不要为了让信息出现而在 project 之间移动私人信息。 ## 怎样才能让我的 AI assistant 完全忘记某件事？ 我想删除一条 memory，并需要知道它是否已经消失。 查看、可恢复移除、永久删除和导出 memory 是不同的 account 操作。 打开 Memory Console，找到这条 memory 并使用 delete 或 forget 控件；如果找不到控件，请带上 memory reference 联系 Support。 只删除预期的 memory，绝不要在 Support 消息中包含私人内容。 ## 我更换了电脑或 AI assistant，XMemo 还会记得我吗？ 更换设备、重启 assistant 或切换 host 后，我的旧 memory 似乎与新 memory 分开了。 新的 assistant connection 可能把设备或 assistant 标识为新 source，或者它登录了不同的 account。 在想要使用的 assistant 中重新连接 XMemo，登录同一个 account，并在应用提供该选项时保持 connection 的 device label 稳定。 在共享电脑上保存任何个人信息前，先检查 account。 ## 为什么我的 AI assistant 把同一件事保存了两次？ retry 或 reconnect 后，我看到两条看起来相同的 memory。 第一次保存可能已经成功，只是 assistant 没有显示结果；重复请求又创建了一份副本。 打开 Memory Console，比较两条记录，确认日期和 source 后只移除重复项。 在确认要保留的副本前，不要删除所有匹配的 memory。 ## 为什么我的 AI assistant 给了太多或太少的历史上下文？ Assistant 提起无关细节、遗漏需要的决策，或给出信息过载的回答。 请求覆盖了过宽的主题或时间范围，或者 assistant 试图使用超过当前对话需要的已保存上下文。 要求更窄的主题、project 或时间范围，并告诉 assistant 最重要的决策或细节。 不要为了填满对话而要求 assistant 暴露无关的私人 memory。 ## 我断开了 XMemo，怎样确认旧 assistant 无法再使用它？ 我从 assistant 中移除了 connection，但不确定它是否仍能访问我的 memory。 从应用中移除 connection 可能不会取消 account 的 connection permission。 打开 XMemo account 的 connected-app 或 security controls，撤销旧 assistant connection，只重新连接你信任的对象。 只撤销预期移除的 connection，不要分享 account 登录详情。 ## 为什么我的 AI assistant 不能再使用 XMemo？ XMemo 以前在 assistant 中可用，但 memory 操作不再出现，或 assistant 说无法使用它们。 Assistant 可能需要刷新 XMemo connection，或者登录了不同的 account。 打开 assistant 的 connected-app settings，断开并重新连接 XMemo，然后开启新对话。 绝不要把 secret account details 或私人 memory 粘贴到 chat 或 Support 请求中。 ## 我应该在 AI assistant 中使用哪个 XMemo connection？ 我不确定哪个 XMemo 页面或 connection 应该放进 assistant 的设置。 引导设置页面和 assistant connection 用途不同，hosted 与 self-managed setup 的边界也不同。 对于 hosted service，从 https://xmemo.dev/product/docs 开始，并按照页面为你的 assistant 显示的 connection link 操作；如果组织提供了不同的 setup page，请询问 Support。 不要使用本地开发地址，也不要把私人 credential 粘贴到公共 chat。 ## 如果我的 AI assistant 仍无法连接 XMemo，该怎么办？ 我重试了 connection 步骤，但 assistant 仍然无法使用 XMemo。 问题可能属于 assistant 应用、我的 account，或 public instructions 无法检查的过期 connection。 联系 Support，提供 assistant 名称、大致时间和所见情况的简短描述；只包含已脱敏的细节。 绝不要发送登录详情、一次性代码、cookies 或私人 memory 文本。 ## OAuth 失败，或者同意窗口无法完成。 Client 显示 401、OAuth 浏览器没有打开，或者同意后返回 client 却没有可用 connection。 Hosted grant 可能已过期，浏览器交接可能被阻止，或者 client 使用了旧的 server registration。 在 host app 中退出 XMemo MCP server，重新连接 hosted MCP URL，并再次批准 memory:read 和 memory:write。 不要仅为绕过过期 OAuth session 就在 OAuth client 中改用 XMEMO_KEY。 ## 请求返回 403 Forbidden。 Server 可访问且 credential 已识别，但请求的 project、tool 或 memory 操作被拒绝。 Grant 缺少所需 scope，account 不在选定的 project boundary 内，或 resource 属于其他 tenant。 检查选定的 account 和 project，重新连接 OAuth 或请求预期 scope，然后不改变 resource 地重试相同操作。 不要扩大 scope，也不要复制其他用户的 token 来消除 403。 ## MCP server 已连接，但没有出现 tool。 Host 显示 server 已连接，但 tools/list 为空，或 model 的 tool picker 中缺少 XMemo tools。 Client 尚未刷新 discovery，使用了错误的 MCP profile，或连接到了过期的 URL 或 registration。 重新连接 server，确认 client 使用受支持的 MCP profile，然后再次运行 tool discovery，再考虑修改 credential。 不要把 bearer token 粘贴到截图、Support ticket 或 marketplace review note 中。 ## 直接 MCP client 提示 token 缺失。 Direct client 报告 XMEMO_KEY 未设置、为空或不可用，尽管我已经在机器某处添加了变量。 Client process 没有继承环境变量，变量被添加到了另一个 shell，或者 config 需要 secret-store reference。 在本地 environment 或 secret store 中设置 XMEMO_KEY，重启 client；需要 attribution 时保持 XMEMO_AGENT_INSTANCE_ID 稳定。 把真实 token 放在已提交到 git 的 config 文件之外；公共示例只应引用环境变量。 ## Agent instance ID 每次重启都会改变。 同一个本地 runner 在重启或 redeploy 后看起来像多个 agent，recall 也分散到了不同 instance。 XMEMO_AGENT_INSTANCE_ID 在 process 启动时生成，而不是持久化在 runner 的本地 secret 或 environment configuration 中。 为每个 runner 生成一个非机密 instance label，将它持久化在 git 之外，并在每次 direct MCP connection 中发送。 Instance label 是 attribution metadata，不是 authorization credential；account 和 token boundary 仍决定访问。 ## Recall 返回空 memory。 Recall 或 search 成功，但用户保存 context 后仍没有相关 record。 读取和写入使用了不同的 account、project、scope、agent boundary 或 memory type，或者测试 record 从未提交。 创建一条 synthetic test memory，在 Memory Console 中确认 path 和 memory type，再从相同 account 或 tenant boundary 重试 recall。 使用 synthetic review data；不要把 private customer memory 用作 marketplace demo。 ## Recall 或 write 使用了错误的 project scope。 Record 在一个 project 中可见，在另一个 project 中不可见，或 write 出现在 operator 未预期的 project 下。 Client 复用了其他 environment 的 project identifier，省略了 project boundary，或保留了过期的 account session。 明确选择预期的 account 和 project，刷新 client context，再用 synthetic record 重复操作。 绝不要通过授予更宽 token 或在 project 之间复制 data 来解决 scope mismatch。 ## 同一条 memory 被保存了两次。 Retry 或 reconnect 产生了 duplicate record，而不是一条 durable memory。 Client 在 timeout 后没有 idempotency boundary 就 retry，或者 capture flow 在确认第一次响应前就写入。 先检查现有 record 和 source attribution，再使用 client retry policy 或稳定的 idempotency key 后重新写入。 确认目标 record 和 account scope 前，不要批量删除匹配的 memory。 ## Recall context 太大或太小。 Agent 收到无关 context、遗漏所需 decision，或超过 host 有用的 context budget。 Query 过宽，缺少 scope 或 time window，或者 caller 请求了不适合任务的 result limit。 按 project、agent、time 或 topic boundary 缩小 query，并在扩大 limit 前先请求小而相关的 set。 不要为了填满 context window 而扩大 scope 或导出无关 memory。 ## 如何删除或导出 memory？ Operator 需要移除 record、确认 forget action，或获取 account-scoped export。 Delete、recoverable forget、permanent delete 和 export 是不同的 workflow，具有不同的 confirmation 和 recovery semantics。 先使用 Memory Console 或 account workflow；如果没有 self-service path，请联系 Support，让请求保持在 account scope 内。 Export 和 Support bundle 必须排除 token hash、API key、session secret、provider credential 及无关 tenant data。 ## 断开 client 后如何撤销 access？ Client 已在本地移除，但 operator 需要使其 OAuth grant 失效或轮换 direct credential。 断开 client config 不一定会撤销 server-side grant，也不一定会轮换 direct token。 打开 account security 或 connected-client controls，撤销指定的 OAuth grant；如果 direct credential 已暴露或不再可信，则轮换它。 只撤销预期的 client 或 grant；排查 access 时不要公开旧 token、OAuth code 或 session details。 ## XMemo 是 GA、certified，还是已列入 marketplace？ Listing 或 document 询问一个可用 configuration 是否证明 GA、certification 或 marketplace approval。 Configuration support、OAuth readiness、pilot evidence 和 marketplace approval 是不同的声明。 除非存在具体的 marketplace approval 或 certification artifact，否则将 public wording 视为 beta/config-supported。 不要仅凭可用 configuration 声称 GA、certified、stable 或 listed。 ## 我应该使用哪个 URL？ Hosted user 不确定应该遵循 public quickstart、MCP endpoint，还是 self-hosted developer instructions。 Hosted onboarding 与 self-hosted 或 legacy deployment path 使用不同的 URL、credential 和 data boundary。 Hosted user 应在 MCP client 中使用 https://xmemo.dev/mcp，在 guided setup 中从 https://xmemo.dev/product/docs 开始。 不要把 localhost、Supabase、Docker 或 self-hosted Python instructions 作为 public hosted user 的第一条路径。 ## Memory 出现在错误的 agent 或 device 下。 Client update 或 restart 后，memory 被归因到另一个 runner，或在设备之间看起来分裂。 Client 更改了非机密 agent 或 instance headers，或者多个 runner 共用了同一 credential。 检查非机密 agent/device headers 或 client profile，然后持久化本地 instance ID，而不是重新生成它。 Attribution label 有助于检查 source，但不是 security boundary；访问仍由 account credential 决定。 ## 按步骤操作后仍然无法连接。 重试 client-specific OAuth 或 direct-secret path 后，connection 仍不可用。 剩余问题可能是 client-specific、account-specific，或由 local docs 无法检查的过期 registration 或 environment boundary 引起。 向 Support 提供 client 名称、config path、大致 timestamp，以及 client 使用 OAuth 还是 XMEMO_KEY。 只分享脱敏 diagnostic；绝不要发送 bearer token、OAuth code、cookie 或 customer memory content。