手动恢复指南¶

概述¶

Claude-mem 的手动恢复系统可帮助您在 worker 崩溃、系统重启或意外关闭后，恢复在处理队列中卡住的观测记录。

v5.x 的关键变更：worker 启动时的自动恢复现已禁用。这使您可以明确控制何时重新处理，避免产生意外的重复观测记录。

何时需要手动恢复？¶

在以下情况下，您应触发手动恢复：

Worker 崩溃或重启 - 观测记录已入队，但 worker 在处理前停止了
没有新的摘要生成 - 观测记录已保存，但未处理成摘要
检测到卡住的消息 - 消息显示为 "processing" 状态超过 5 分钟
系统崩溃 - 意外关闭导致消息停留在不完整状态

快速开始¶

使用 CLI 工具（推荐）¶

交互式 CLI 工具是恢复卡住观测记录的最安全、最简单的方式：

# Check status and prompt for recovery
bun scripts/check-pending-queue.ts

该工具将：

检查 worker 健康状态
显示队列摘要（pending、processing、failed、stuck 数量）
显示有待处理工作的 session
提示您确认恢复
显示最近处理的消息以供反馈

无提示自动处理¶

适用于脚本场景，或当您确信需要恢复时：

# Auto-process without prompting
bun scripts/check-pending-queue.ts --process

# Limit to 5 sessions
bun scripts/check-pending-queue.ts --process --limit 5

理解队列状态¶

消息会经历以下生命周期状态：

pending → 已入队，等待处理
processing → 正在由 SDK agent 处理
processed → 已成功完成
failed → 3 次重试后仍失败

卡住检测¶

处于 processing 状态超过 5 分钟 的消息被视为卡住：

worker 启动时，它们会被自动重置为 pending
它们不会被自动重新处理（需要手动触发）
检查队列状态时，它们会出现在 stuckCount 字段中

恢复方法¶

方法一：交互式 CLI 工具¶

适用场景：普通用户、交互式会话，或当您希望清楚地了解正在发生什么时

bun scripts/check-pending-queue.ts

输出示例：

Checking worker health...
Worker is healthy ✓

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

Would you like to process these pending queues? (y/n)

功能特性：

✅ 预检健康状态（验证 worker 是否在运行）
✅ 按 session 细分的队列详情
✅ 用于卡住检测的时长追踪
✅ 确认提示（防止意外重新处理）
✅ 通过 --process 标志支持非交互模式
✅ 通过 --limit N 控制 session 数量上限

方法二：HTTP API¶

适用场景：自动化、脚本编写、与监控系统集成

检查队列状态¶

WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl http://127.0.0.1:$WORKER_PORT/api/pending-queue

响应：

{
  "queue": {
    "messages": [
      {
        "id": 123,
        "session_db_id": 45,
        "claude_session_id": "abc123",
        "message_type": "observation",
        "status": "pending",
        "retry_count": 0,
        "created_at_epoch": 1730886600000
      }
    ],
    "totalPending": 12,
    "totalProcessing": 2,
    "totalFailed": 0,
    "stuckCount": 1
  },
  "recentlyProcessed": [...],
  "sessionsWithPendingWork": [44, 45, 46]
}

关键字段：

totalPending - 等待处理的消息
totalProcessing - 正在处理的消息
stuckCount - 处理时间超过 5 分钟的消息
sessionsWithPendingWork - 需要恢复的 Session ID

触发恢复¶

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

响应：

{
  "success": true,
  "totalPendingSessions": 15,
  "sessionsStarted": 10,
  "sessionsSkipped": 2,
  "startedSessionIds": [44, 45, 46, 47, 48, 49, 50, 51, 52, 53]
}

响应字段：

totalPendingSessions - 数据库中含待处理消息的 session 总数
sessionsStarted - 本次请求中已开始处理的 session 数量
sessionsSkipped - 已在处理中的 session 数量（避免重复 agent）
startedSessionIds - 已开始处理的 session 的数据库 ID

最佳实践¶

1. 恢复前务必先检查¶

# Check queue status first
curl http://127.0.0.1:$WORKER_PORT/api/pending-queue

# Or use CLI tool which checks automatically
bun scripts/check-pending-queue.ts

2. 从较小的 Session 数量限制开始¶

# Process only 5 sessions at a time
bun scripts/check-pending-queue.ts --process --limit 5

这可以避免过多的并发 SDK agent 压垮 worker。

3. 恢复期间进行监控¶

在恢复运行期间查看 worker 日志：

npm run worker:logs

关注以下日志：

SDK agent 启动：Starting SDK agent for session...
处理完成：Processed observation...
错误：ERROR 或 Failed to process...

4. 验证恢复是否成功¶

检查最近处理的消息：

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

或使用 CLI 工具，它会自动显示这些信息。

5. 处理失败的消息¶

失败 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;
"

如有需要，您可以手动重置它们：

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

故障排除¶

恢复不工作¶

症状：已触发恢复，但消息仍处于待处理状态。

解决方案：

检查 worker 健康状态：

curl http://127.0.0.1:$WORKER_PORT/health

检查 worker 日志中的错误：
```
npm run worker:logs | grep -i error
```
重启 worker：
```
npm run worker:restart
```

检查数据库完整性：

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

消息永远卡住¶

症状：消息显示为“processing”状态持续数小时。

解决方案：强制重置卡住的消息

# Reset all stuck messages to pending
sqlite3 ~/.claude-mem/claude-mem.db "
  UPDATE pending_messages
  SET status = 'pending', started_processing_at_epoch = NULL
  WHERE status = 'processing';
"

# Then trigger recovery
bun scripts/check-pending-queue.ts --process

恢复期间 Worker 崩溃¶

症状：worker 在处理已恢复消息时停止。

解决方案：

检查可用内存：
```
npm run worker:status
```

降低会话限制：

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

检查日志中的 SDK 错误：
```
npm run worker:logs | grep -i "sdk"
```

增加 worker 内存（如果使用自定义 runner）：

export NODE_OPTIONS="--max-old-space-size=4096"
npm run worker:restart

高级用法¶

直接数据库检查¶

查看所有待处理消息：

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    id,
    session_db_id,
    message_type,
    status,
    retry_count,
    datetime(created_at_epoch/1000, 'unixepoch') as created_at,
    datetime(started_processing_at_epoch/1000, 'unixepoch') as started_at,
    CAST((strftime('%s', 'now') * 1000 - started_processing_at_epoch) / 60000 AS INTEGER) as age_minutes
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  ORDER BY created_at_epoch;
"

按状态统计消息¶

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT status, COUNT(*) as count
  FROM pending_messages
  GROUP BY status;
"

查找有待处理工作的会话¶

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    session_db_id,
    COUNT(*) as pending_count,
    GROUP_CONCAT(message_type) as message_types
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  GROUP BY session_db_id;
"

查看最近失败¶

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT
    id,
    session_db_id,
    message_type,
    retry_count,
    datetime(completed_at_epoch/1000, 'unixepoch') as failed_at
  FROM pending_messages
  WHERE status = 'failed'
  ORDER BY completed_at_epoch DESC
  LIMIT 10;
"

集成示例¶

自动恢复的 Cron 任务¶

#!/bin/bash
# Run every hour to process stuck queues

WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)

# Check if worker is healthy
if curl -f http://127.0.0.1:$WORKER_PORT/health > /dev/null 2>&1; then
  # Auto-process up to 5 sessions
  bun scripts/check-pending-queue.ts --process --limit 5
else
  echo "Worker not healthy, skipping recovery"
  exit 1
fi

监控脚本¶

#!/bin/bash
# Alert if stuck count exceeds threshold

WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
STUCK_COUNT=$(curl -s http://127.0.0.1:$WORKER_PORT/api/pending-queue | jq '.queue.stuckCount')

if [ "$STUCK_COUNT" -gt 5 ]; then
  echo "WARNING: $STUCK_COUNT stuck messages detected"
  # Send alert (email, Slack, etc.)
fi

关闭前恢复¶

#!/bin/bash
# Process pending queues before system shutdown

echo "Processing pending queues before shutdown..."
bun scripts/check-pending-queue.ts --process --limit 20

echo "Waiting for processing to complete..."
sleep 10

echo "Stopping worker..."
claude-mem stop

迁移说明¶

如果你正在从 v4.x 升级到 v5.x：

v4.x 行为（自动恢复）： - Worker 会在启动时自动恢复卡住的消息 - 用户无法控制重新处理的时间

v5.x 行为（手动恢复）： - 检测到卡住的消息，但不会自动重新处理 - 用户必须通过 CLI 或 API 明确触发恢复 - 防止意外的重复观察 - 提供对处理时机的明确控制

迁移步骤： 1. 升级到 v5.x 2. 检查是否有卡住的消息：bun scripts/check-pending-queue.ts 3. 如需要则处理：bun scripts/check-pending-queue.ts --process 4. 将恢复添加到你的工作流程中（cron 任务、关闭前脚本等）

另请参阅¶

Worker Service 架构 - 队列处理的技术细节
故障排除 - 手动恢复 - 常见问题与解决方案
数据库模式 - 待处理消息表结构

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem