错误码
记忆服务不可用或请求被拒绝时，记忆工具返回一段带错误码的文本，会话照常进行，推送跳过这一步。
工具返回的文本#
| 情况 | 返回 |
|---|---|
| 记忆服务不可用 | 记忆暂不可用 (memory temporarily unavailable: <错误码>). Continue without it. |
| 会话不归本插件管，或已结束 | 记忆暂不可用 (memory is not available for this session: <错误码>). |
| 请求被拒绝 | memory request refused (<错误码>): <原因> |
错误码#
| 错误码 | 描述 |
|---|---|
endpoint_unavailable | 原因：读不到 endpoint.json。记忆服务没有运行，或文件路径不对解决方法：运行 crowdmemory-runtime start；装在其他目录时检查 CROWDMEMORY_ENDPOINT_FILE |
runtime_unavailable | 原因：本会话还没连上记忆服务 解决方法：启动记忆服务。插件会自动重试，间隔从 5 秒开始翻倍，最长 60 秒 |
endpoint_untrusted | 原因：endpoint.json 不安全：相对路径、符号链接、属主不是当前用户、组或其他用户可写解决方法：使用记忆服务写出的原文件，不要软链接或放宽权限 |
token_unavailable | 原因：令牌文件 adapter-token 读不到或为空解决方法：检查 <state>/adapter-token 是否存在、属主是否为运行 DSH 的用户 |
token_untrusted | 原因：令牌文件权限不是 0600、是符号链接，或不在 endpoint.json 所在目录解决方法：删除令牌文件后重启记忆服务，会重新生成 |
unauthorized | 原因：记忆服务拒绝了令牌 解决方法：确认 DSH 和记忆服务以同一个用户运行 |
transport_error | 原因：连不上套接字 解决方法：检查记忆服务是否在运行 |
timeout | 原因：请求超时 解决方法：检查记忆服务负载；必要时调大 timeoutMs |
protocol_incompatible | 原因：插件与记忆服务的协议版本不一致 解决方法：升级到同一个大版本 |
session_unbound | 原因：会话不归本插件管（配置了 sessionId），或会话句柄已失效解决方法：新开会话 |
session_ended | 原因：会话已结束 解决方法：新开会话 |
budget_exhausted | 原因：本会话读取的字数达到上限（默认 20000 字符） 解决方法：新开会话，或在记忆服务的本机配置中调高 read_chars |
note_rejected | 原因：笔记被拒绝：必填项为空、超出长度、topic_key 格式不对，或内容命中提示注入规则解决方法：按返回的原因修改后重新记录 |
unavailable | 原因：记忆服务内部出错。memory_note 遇到时，笔记已经保存为原始记录解决方法：稍后重试；问题持续时查看 crowdmemory-runtime status |
常见问题#
| 现象 | 原因 | 处理 |
|---|---|---|
| 会话里没有记忆工具 | 插件没加载，或既没设置 CROWDMEMORY_ENDPOINT_FILE，进程也没有 HOME | 用 dsh --dump-config 检查插件；设置环境变量 |
| 启动时报套接字路径过长 | macOS 上套接字路径不能超过约 103 字节 | 用 --socket 指定更短的路径 |
| 第二个记忆服务启动失败 | 同一个状态目录已有一个在运行 | 只保留一个 |