Claude-Mem Worker 重启后观察队列卡住不生成摘要，怎么触发手动恢复

Claude-Mem Worker 重启后观察队列卡住不生成摘要，怎么触发手动恢复

【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem

Worker 崩溃或重启后，Claude-Mem 的观察（observation）会滞留在处理队列里：数据库里 observation 正常写入，但一直不生成新的摘要。从 v5.x 开始，Claude-Mem 关闭了 worker 启动时的自动队列恢复，以避免产生意外的重复观察，所以卡住的消息只会被检测、被重置回pending，但不会被自动重新处理——必须手动触发一次恢复。

本文覆盖的操作路径：检查 worker 与队列状态 → 用 CLI 或 HTTP API 触发手动恢复 → 观察日志并验证处理结果。文档依据是 Manual Recovery Guide 和 Troubleshooting 两篇文档。

出现以下现象之一时应该触发手动恢复：

• Worker 崩溃或重启过，期间有观察排队但未被处理；
• 观察在保存，但没有新的摘要出现；
• 有消息在processing状态停留超过 5 分钟（文档中判定为 stuck）。

第一步：确认 Worker 存活并读取队列状态

所有 worker 命令都依赖端口变量PORT，先从用户配置里取出来（Troubleshooting 给出的写法）：

PORT=${CLAUDE_MEM_WORKER_PORT:-$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)}

如果环境变量CLAUDE_MEM_WORKER_PORT未设置，就读取~/.claude-mem/settings.json里的CLAUDE_MEM_WORKER_PORT。未显式配置时，默认端口是37700 + (uid % 100)。

确认 worker 健康：

curl http://127.0.0.1:$PORT/health

文档示例的健康返回为{"status":"ok","uptime":12345,"port":...}（示例结果，uptime等数值以实际为准）。如果 worker 没在运行，先按 Worker Service Not Starting 一节处理：npm run worker:status查看状态，npm run worker:start手动启动。

worker 健康后，读队列状态。两种方式二选一：

方式 A：HTTP API

curl http://127.0.0.1:$PORT/api/pending-queue

响应中与本场景相关的字段：

• queue.totalPending：等待处理的消息数；
• queue.totalProcessing：正在处理的消息数；
• queue.stuckCount：处于processing超过 5 分钟的消息数；
• sessionsWithPendingWork：需要恢复的 session 数据库 ID 列表；
• recentlyProcessed：最近已处理的消息（恢复后用来验证）。

方式 B：CLI 工具

CLI 脚本是 scripts/check-pending-queue.ts。在插件安装目录~/.claude/plugins/marketplaces/thedotmack下运行：

cd ~/.claude/plugins/marketplaces/thedotmack bun scripts/check-pending-queue.ts

不带参数时，脚本会先检查 worker 健康（对应 worker 的/api/health），再打印队列汇总，最后提示是否触发处理，需要手动回答y。非交互环境（无 TTY）下脚本会提示改用--process。脚本会自己解析CLAUDE_MEM_WORKER_HOST/CLAUDE_MEM_WORKER_PORT环境变量或~/.claude-mem/settings.json中的配置来定位 worker。

文档中给出的交互式示例输出（文档示例，数值以实际为准）：

Queue Summary: Pending: 12 messages Processing: 2 messages (1 stuck) Failed: 0 messages Recently Processed: 5 messages in last 30 minutes Sessions with pending work: 3 Session 44: 5 pending, 1 processing (age: 2m) Session 45: 4 pending, 1 processing (age: 7m - STUCK) Session 46: 2 pending

判断下一步：totalPending/stuckCount大于 0、或sessionsWithPendingWork非空，说明存在积压，进入下一步触发恢复；全部为 0 则说明队列已清空，无需恢复。

第二步：触发手动恢复

主路径：CLI 的--process标志

跳过确认提示直接处理积压：

bun scripts/check-pending-queue.ts --process

脚本会调用 worker 的/api/processing端点触发处理，并打印处理状态、队列深度与活跃 session 数，然后提示过几分钟再查一次状态。

一个需要注意的版本差异：Manual Recovery 文档提到了--limit N参数（例如--process --limit 5，用于限制同时恢复的 session 数），但仓库里该脚本的--help文本只列出了--help和--process。如果本机脚本版本不认识--limit，请改用下面 HTTP API 的sessionLimit字段来控制 session 数，两者在文档中是同一个目的——避免一次性并发过多 SDK agent 压垮 worker。

替代路径：HTTP API 直接触发

适合脚本化或监控系统集成。先查状态，再发 POST：

curl -X POST http://127.0.0.1:$PORT/api/pending-queue/process \ -H "Content-Type: application/json" \ -d '{"sessionLimit": 10}'

sessionLimit控制本次最多启动多少个 session 的处理。响应字段：

• totalPendingSessions：数据库中带有 pending 消息的 session 总数；
• sessionsStarted：本次请求启动了处理的 session 数；
• sessionsSkipped：已经在处理中、被跳过的 session 数（防止重复 agent）；
• startedSessionIds：本次启动的 session 数据库 ID 列表。

文档建议从较低的 session 上限（5–10）开始，防止 worker 被过多并发 SDK agent 压垮。

第三步：监控处理过程并验证结果

恢复触发后，处理由 worker 内的 SDK agent 执行。开一个终端看日志：

npm run worker:logs

Manual Recovery 文档指出应关注这几类日志行：

• Starting SDK agent for session...：SDK agent 已开始处理某个 session；
• Processed observation...：有处理完成；
• ERROR或Failed to process...：处理失败。

处理完成后验证。两种方式：

1. 查最近已处理的消息：

curl http://127.0.0.1:$PORT/api/pending-queue | jq '.recentlyProcessed'

2. 确认数据库里确实生成了摘要：

sqlite3 ~/.claude-mem/claude-mem.db "SELECT COUNT(*) FROM session_summaries;"

recentlyProcessed有新增记录、session_summaries计数增长，说明卡住的观察已经走完了摘要生成。

恢复没生效时的检查项

按 Troubleshooting 与 Manual Recovery 两篇文档给出的顺序：

1. 确认 worker 健康：curl http://127.0.0.1:$PORT/health。
2. 看日志里的错误：npm run worker:logs | grep -i error。
3. 检查数据库完整性：

sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"

4. 重启 worker：npm run worker:restart。

消息长期卡在 processing 的强制重置

如果消息显示processing已持续数小时，文档提供了"核选项"：直接把processing全部重置回pending，再触发恢复。该命令会修改~/.claude-mem/claude-mem.db中所有pending_messages记录的状态，属于对数据库的写操作，建议先备份（Database Corruption 一节给出的备份方式）：

cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup

然后执行重置：

sqlite3 ~/.claude-mem/claude-mem.db " UPDATE pending_messages SET status = 'pending', started_processing_at_epoch = NULL WHERE status = 'processing'; "

再触发一次恢复：

bun scripts/check-pending-queue.ts --process

处理失败的（failed）消息

消息重试 3 次后会标记为failed，不会自动重试。先查看失败记录：

sqlite3 ~/.claude-mem/claude-mem.db " SELECT id, session_db_id, message_type, retry_count FROM pending_messages WHERE status = 'failed' ORDER BY completed_at_epoch DESC; "

确认可以重放后，手动把它们重置回pending并清零重试计数，再走第二步触发恢复：

sqlite3 ~/.claude-mem/claude-mem.db " UPDATE pending_messages SET status = 'pending', retry_count = 0 WHERE status = 'failed'; "

队列状态与限制

pending_messages表中消息的生命周期状态为：pending（排队等待）→processing（SDK agent 处理中）→processed（成功）或failed（重试 3 次后失败）。processing超过 5 分钟的消息判定为 stuck：worker 启动时会被自动重置回pending，但不会自动重跑——这正是 v5.x 的行为，与 v4.x 的启动自动恢复不同。

文档明确的相关边界：

• 触发恢复后如果 worker 中途崩溃，文档建议先用npm run worker:status查看可用内存，降低 session 数（文档示例为--process --limit 3，若脚本不支持该参数则用 API 的sessionLimit: 3），再用npm run worker:logs | grep -i "sdk"查 SDK 错误；
• API 响应中的sessionsSkipped表示这些 session 已在处理中，本次未重复启动，这是预期行为，不是失败；
• 若需要恢复在定时任务中自动执行，Manual Recovery 文档给出了先探活/health、再--process的 cron 脚本示例，见 docs/public/usage/manual-recovery.mdx 的 Integration Examples 一节。

更深入的队列处理机制可以参阅 Worker Service Architecture，pending_messages的表结构见 Troubleshooting 的 Queue Table 小节。

【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem