不写入 memory 也能验证连接
下面每条故障排查路径都会以 verification 步骤结束。先从读取开始：它可以在不改变任何内容的情况下证明 credential 和 transport。
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'X-API-Key: <your-assigned-api-key>' \
'https://xmemo.dev/v1/memories/search?query=connection%20check&limit=1'读取 status code
Status 可以区分 credential 问题和空的 memory store。
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 响应，避免数据分块被截断。
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。
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'Authorization: Bearer <your-token>' \
'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，而非软删除或已废弃。
curl -s -H 'Authorization: Bearer <your-token>' \
'https://xmemo.dev/v1/memories/search?query=test&limit=5&scope=project:demo'写锁超时
来自多个运行器的并发写入或并行的工具调用可能会触发共享 memory path 上的写锁争用。
- 当写入请求返回写锁争用时，在客户端实现带有随机抖动的指数退避重试策略。
- 在重试写入时附带客户端幂等键（idempotency key），防止生成重复的 memory 记录。
- 对于高频写入工作流，使用任务队列或批量 API 对 memory 变更操作进行排队处理。
curl -s -X POST 'https://xmemo.dev/v1/memories' \
-H 'Authorization: Bearer <your-token>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: <generate-a-uuid-v4>' \
-d '{"content":"Durable convention fact","path":"projects/demo/conventions"}'FAQ / 故障排查
先查看 AI assistant 用户的答案，再使用 developer 和 integrator 的答案处理连接及运营细节。每个答案都包含 action 步骤和 safety 边界。
AI assistant 用户
面向不自行配置 connection、而是通过 AI assistant 使用 XMemo 的用户的日常答案。
为什么我的 AI assistant 不记得我之前告诉它的事情？
- 现象
- 我保存了重要偏好或细节，但在后续对话中，AI assistant 像从未见过它一样。
- 原因
- Assistant 可能连接到了不同的 XMemo account、project 或 device context，或者原始 memory 没有保存成功。
- 操作：
- 让 assistant 保存一条小型、非敏感的测试细节，然后打开 Memory Console，检查它是否出现在你使用的 account 和 project 下。
- 验证
- 用同一个 assistant 开启新对话并询问这条测试细节；完成后删除测试条目。
- 安全：
- 使用虚构的测试细节；不要使用他人的私人信息。
为什么我的 AI assistant 把不同的 project 或对话混在一起？
- 现象
- 一个 project 的细节出现在另一个 project 中，或者 assistant 回答时仿佛两段对话属于同一处。
- 原因
- Assistant 可能使用了与保存 memory 时不同的 project 或 account context。
- 操作：
- 在 assistant 中选择预期的 XMemo account 和 project，必要时重新连接，然后用清楚标记的测试细节重试。
- 验证
- 在 Memory Console 中检查 memory 的 project 和 source，然后确认无关 project 无法看到这条测试细节。
- 安全：
- 不要为了让信息出现而在 project 之间移动私人信息。
怎样才能让我的 AI assistant 完全忘记某件事？
- 现象
- 我想删除一条 memory，并需要知道它是否已经消失。
- 原因
- 查看、可恢复移除、永久删除和导出 memory 是不同的 account 操作。
- 操作：
- 打开 Memory Console，找到这条 memory 并使用 delete 或 forget 控件；如果找不到控件，请带上 memory reference 联系 Support。
- 验证
- 再次搜索这条 memory，确认 Memory Console 显示的状态；检查任何 export 只包含你的 account 数据。
- 安全：
- 只删除预期的 memory，绝不要在 Support 消息中包含私人内容。
我更换了电脑或 AI assistant，XMemo 还会记得我吗？
- 现象
- 更换设备、重启 assistant 或切换 host 后，我的旧 memory 似乎与新 memory 分开了。
- 原因
- 新的 assistant connection 可能把设备或 assistant 标识为新 source，或者它登录了不同的 account。
- 操作：
- 在想要使用的 assistant 中重新连接 XMemo，登录同一个 account，并在应用提供该选项时保持 connection 的 device label 稳定。
- 验证
- 保存一条虚构的测试细节，在同一个 assistant 中开启新对话，确认它出现且 account 没有改变。
- 安全：
- 在共享电脑上保存任何个人信息前，先检查 account。
为什么我的 AI assistant 把同一件事保存了两次？
- 现象
- retry 或 reconnect 后，我看到两条看起来相同的 memory。
- 原因
- 第一次保存可能已经成功，只是 assistant 没有显示结果；重复请求又创建了一份副本。
- 操作：
- 打开 Memory Console，比较两条记录，确认日期和 source 后只移除重复项。
- 验证
- 让 assistant 保存一条清楚标记的新测试细节一次，确认只出现一条新记录。
- 安全：
- 在确认要保留的副本前，不要删除所有匹配的 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，并确认它被拒绝后再使用新 connection。
- 安全：
- 只撤销预期移除的 connection，不要分享 account 登录详情。
为什么我的 AI assistant 不能再使用 XMemo？
- 现象
- XMemo 以前在 assistant 中可用，但 memory 操作不再出现，或 assistant 说无法使用它们。
- 原因
- Assistant 可能需要刷新 XMemo connection，或者登录了不同的 account。
- 操作：
- 打开 assistant 的 connected-app settings，断开并重新连接 XMemo，然后开启新对话。
- 验证
- 让 assistant 显示 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。
- 验证
- 保存个人细节前，确认页面使用的是预期的 XMemo account 和 hosted service。
- 安全：
- 不要使用本地开发地址，也不要把私人 credential 粘贴到公共 chat。
如果我的 AI assistant 仍无法连接 XMemo，该怎么办？
- 现象
- 我重试了 connection 步骤，但 assistant 仍然无法使用 XMemo。
- 原因
- 问题可能属于 assistant 应用、我的 account，或 public instructions 无法检查的过期 connection。
- 操作：
- 联系 Support，提供 assistant 名称、大致时间和所见情况的简短描述；只包含已脱敏的细节。
- 验证
- 确认这份报告无需发送私人 memory 或 account secret 也能复现。
- 安全：
- 绝不要发送登录详情、一次性代码、cookies 或私人 memory 文本。
Developer 与 integrator
面向集成 XMemo 的人员，涵盖 connection、account boundary、client 和运营问题的答案。
OAuth 失败，或者同意窗口无法完成。
- 现象
- Client 显示 401、OAuth 浏览器没有打开，或者同意后返回 client 却没有可用 connection。
- 原因
- Hosted grant 可能已过期，浏览器交接可能被阻止，或者 client 使用了旧的 server registration。
- 操作：
- 在 host app 中退出 XMemo MCP server，重新连接 hosted MCP URL，并再次批准 memory:read 和 memory:write。
- 验证
- 重新连接直到 client 报告 active authorization，然后先执行无害的 recall，再写入 memory。
- 安全：
- 不要仅为绕过过期 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 地重试相同操作。
- 验证
- 确认预期 project 中的只读请求成功后，再重试 write 或 delete 操作。
- 安全：
- 不要扩大 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。
- 验证
- 开始写入或 marketplace 演示前，确认至少出现 remember、recall 和 search_memory。
- 安全：
- 不要把 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 稳定。
- 验证
- 只检查变量存在的 metadata，重启 client 并确认无害的 authenticated recall；绝不要打印 token value。
- 安全：
- 把真实 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 中发送。
- 验证
- 重启 runner 两次，确认 source attribution 中的 instance label 相同且没有暴露 credential。
- 安全：
- 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。
- 验证
- 用相同 project 和 scope 读回新建的 synthetic record，然后通过预期 delete path 移除它。
- 安全：
- 使用 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 重复操作。
- 验证
- 在 Memory Console 中确认 record 的 project 和 source attribution，再确认无关 project 无法读取它。
- 安全：
- 绝不要通过授予更宽 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 后重新写入。
- 验证
- 重复一次相同的 controlled capture，确认只有一条新 record 和一次 readback，而不是两条新 record。
- 安全：
- 确认目标 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 与目标问题对比，确认每条包含的 record 都已授权且有用。
- 安全：
- 不要为了填满 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 内。
- 验证
- Forget 或 delete 后按 record reference 搜索，确认预期的 recoverable 或 permanent state；验证 export 只包含 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 已暴露或不再可信，则轮换它。
- 验证
- 用旧 connection 重试 authenticated read，确认被拒绝后，再只通过预期的 consent 或 secret-store path 重新连接。
- 安全：
- 只撤销预期的 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。
- 验证
- 发布 status claim 前，检查 canonical client capability matrix 和指定的 approval artifact。
- 安全：
- 不要仅凭可用 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 开始。
- 验证
- 连接前确认 host URL、authentication mode 和 account boundary 与预期的 hosted 或 self-hosted deployment 一致。
- 安全：
- 不要把 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，而不是重新生成它。
- 验证
- 从预期 runner 写入一条 synthetic record，确认 reconnect 后 source attribution 仍然稳定。
- 安全：
- 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。
- 验证
- 确认 Support report 包含可复现的 symptom 和脱敏 metadata，然后等待 account-scoped diagnosis。
- 安全：
- 只分享脱敏 diagnostic；绝不要发送 bearer token、OAuth code、cookie 或 customer memory content。
来源: FAQ / 故障排查