故障排除指南

快速诊断工具

向Claude描述您遇到的任何问题，故障排除技能将自动激活以提供诊断和解决方案。

故障排除技能将会：

✅ 检查 Worker 状态和健康
✅ 验证数据库的存在性和完整性
✅ 测试 Worker 服务连接
✅ 验证依赖项安装
✅ 检查端口配置和可用性
✅ 为常见问题提供自动修复

该技能包括全面的诊断、自动修复序列以及针对所有常见问题的详细故障排除工作流程。只需自然地描述问题即可激活它。

v5.x 特定问题

查看器界面未加载

症状：无法访问 http://localhost:37777, 页面，页面无法加载，或显示连接错误。

解决方案:

检查工作进程是否在端口 37777 上运行：
bash
```
lsof -i :37777
# or
npm run worker:status
```
确认工作人员健康：
bash
```
curl http://localhost:37777/health
```
检查工作日志中的错误：
bash
```
npm run worker:logs
```
重启Worker 服务：
bash
```
npm run worker:restart
```

检查端口冲突：

bash

# If port 37777 is in use by another service

npm run worker:restart

主题切换未保存

症状：浏览器刷新后，主题偏好（浅色/深色模式）会重置。

解决方案:

检查浏览器本地存储是否启用：

javascript

// In browser console
localStorage.getItem('claude-mem-settings')

验证设置端点是否正常工作：
bash
```
curl http://localhost:37777/api/settings
```

清除本地存储并重试：

javascript

// In browser console
localStorage.removeItem('claude-mem-settings')

检查浏览器隐私模式（会阻止 localStorage）

SSE 连接问题

症状：查看器显示“已断开连接”状态，更新未实时显示。

解决方案:

检查 SSE 端点是否可访问：
bash
```
curl -N http://localhost:37777/stream
```
检查浏览器控制台的错误：
- 打开开发者工具 (F12)
- 查找 EventSource 错误
- 检查网络标签以查看失败的 /stream 请求
验证工作进程是否运行：
bash
```
npm run worker:status
```
检查阻止 SSE 的网络/代理问题
- 公司防火墙可能会阻止 SSE
- 尝试暂时禁用 VPN
重新启动 Worker 进程并刷新浏览器：
bash
```
npm run worker:restart
```

Chroma/Python 依赖问题 (v5.0.0 )

症状：安装因 chromadb 或与 Python 相关的错误而失败。

解决方案:

验证是否安装了 Python 3.8：
bash
```
python --version
# or
python3 --version
```

手动安装 chromadb：

bash

cd ~/.claude/plugins/marketplaces/thedotmack
npm install chromadb

检查 chromadb 状态：
bash
```
npm run chroma:health
```

Windows 专用：确保 Python 在 PATH 中：

bash

where python
# Should show Python installation path

如果 Chroma 继续失败，混合搜索将优雅地降级为仅使用 SQLite FTS5

智能安装缓存问题（v5.0.3）

症状：插件更新后依赖项未更新，版本标记过时。

解决方案:

清除安装缓存：

bash

rm ~/.claude/plugins/marketplaces/thedotmack/.install-version

强制重新安装：

bash

cd ~/.claude/plugins/marketplaces/thedotmack
npm install --force

检查版本标记：

bash

cat ~/.claude/plugins/marketplaces/thedotmack/.install-version
cat ~/.claude/plugins/marketplaces/thedotmack/package.json | grep version

手动安装后重启 Claude Code

Worker 服务问题

Worker 服务未启动

症状：工作进程无法启动，或工作进程状态显示未运行。

解决方案:

检查工作状态：
bash
```
npm run worker:status
```
尝试手动启动：
bash
```
npm run worker:start
```
检查工作日志中的错误：
bash
```
npm run worker:logs
```

完全重置：

bash

npm run worker:stop
npm run worker:start

验证是否已安装 Bun：
bash
```
which bun
bun --version
```

端口分配失败

症状：工作进程启动失败，出现“端口已被占用”错误。

解决方案:

检查端口 37777 是否被占用：
bash
```
lsof -i :37777
```
使用该端口的进程杀死：
bash
```
kill -9 $(lsof -t -i:37777)
```
或者使用不同的端口：
bash
```
npm run worker:restart
```
验证新端口：
bash
```
cat ~/.claude-mem/worker.port
```

Worker 进程不断崩溃

症状：Worker 进程反复重启或无法持续运行。

解决方案:

检查错误日志：
bash
```
npm run worker:logs
```
检查工作状态：
bash
```
npm run worker:status
```

检查数据库是否损坏：

bash

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

验证 Bun 安装：
bash
```
bun --version
```

Worker 进程未处理观察结果

症状：观察已保存但未处理，未生成摘要。

解决方案:

检查 Worker 进程是否正在运行：
bash
```
npm run worker:status
```
检查工作日志：
bash
```
npm run worker:logs
```

验证数据库是否有观测数据：

bash

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

重启 Worker 进程：
bash
```
npm run worker:restart
```

卡住观测的手动恢复

症状：在工作进程崩溃或重启后，观察结果卡在处理队列中，尽管工作进程正在运行，但没有出现新的摘要。

背景：从 v5.x 版本开始，工作进程启动时的自动队列恢复已被禁用。用户必须手动触发恢复，以保持对重新处理的明确控制，并防止出现意外的重复观察。

解决方案:

选项 1：使用 CLI 恢复工具（推荐）

交互式命令行工具提供最安全、最用户友好的恢复体验：

bash

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

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

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

它的功能：

✅ 在继续之前检查 Worker 健康
✅ 显示详细的队列摘要（待处理、处理中、失败、卡住）
✅ 按会话对消息进行分组，并显示年龄和状态分解
✅ 提示用户确认处理（除非使用 --process 标志）
✅ 显示最近处理的消息以供反馈

互动示例：

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)

选项2：直接使用HTTP API

用于自动化或脚本场景：

检查队列状态:
bash
```
curl http://localhost:37777/api/pending-queue
```
响应显示：
- queue.totalPending：等待处理的消息
- queue.totalProcessing：当前正在处理的消息
- queue.stuckCount：正在处理超过5分钟的消息
- sessionsWithPendingWork：需要恢复的会话ID
触发手动恢复：
bash
```
curl -X POST http://localhost:37777/api/pending-queue/process \
  -H "Content-Type: application/json" \
  -d '{"sessionLimit": 10}'
```
响应包括：
- totalPendingSessions：有待处理消息的总会话数
- sessionsStarted：我们开始处理的会话数量
- sessionsSkipped：会话正在处理中（未重新启动）
- startedSessionIds：已启动会话的数据库 ID

理解队列状态

消息会经历以下这些状态：

待处理 - 排队中，等待处理
处理中 - 目前正在由 SDK 代理处理
已处理 - 完成成功
失败 - 在重试3次后失败

阻塞检测：处于 processing 状态超过 5 分钟的消息被认为是阻塞的，并在Worker 进程启动时自动重置为 pending（但不会自动重新处理）。

恢复策略

何时使用手动恢复：

在工作进程崩溃或意外重启后
当观察结果显示已保存但未生成摘要时
当队列状态显示消息卡住（处理时间超过5分钟）
在系统崩溃或强制关机之后

最佳实践：

在触发恢复之前始终检查队列状态
使用 CLI 工具进行交互式会话（提供反馈）
使用 HTTP API 进行自动化/脚本编写
从较低的会话限制开始（5-10），以避免让工作人员不堪重负
在恢复期间监控工作日志：npm run worker:logs
检查最近处理的消息以确认恢复是否成功

故障排除恢复问题

如果恢复失败或消息仍然卡住：

确认Worker 健康：

bash

curl http://localhost:37777/health
# Should return: {"status":"ok","uptime":12345,"port":37777}

检查数据库是否损坏：

bash

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

直接查看卡住的消息：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, session_db_id, status, retry_count,
         (strftime('%s', 'now') * 1000 - started_processing_at_epoch) / 60000 as age_minutes
  FROM pending_messages
  WHERE status = 'processing'
  ORDER BY started_processing_at_epoch;
"

强制重置卡住的消息（终极手段）：

bash

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

然后触发恢复：

bash

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

检查工作日志中的 SDK 错误：
bash
```
npm run worker:logs | grep -i error
```

理解队列表

pending_messages 表跟踪所有消息的这些关键字段：

sql

CREATE TABLE pending_messages (
  id INTEGER PRIMARY KEY,
  session_db_id INTEGER,          -- Foreign key to sdk_sessions
  claude_session_id TEXT,          -- Claude session ID
  message_type TEXT,               -- 'observation' | 'summarize'
  status TEXT,                     -- 'pending' | 'processing' | 'processed' | 'failed'
  retry_count INTEGER,             -- Current retry attempt (max: 3)
  created_at_epoch INTEGER,        -- When message was queued
  started_processing_at_epoch INTEGER,  -- When marked 'processing'
  completed_at_epoch INTEGER       -- When completed/failed
)

查询示例：

bash

# Count messages by status
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT status, COUNT(*)
  FROM pending_messages
  GROUP BY status;
"

# Find sessions with pending work
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT session_db_id, COUNT(*) as pending_count
  FROM pending_messages
  WHERE status IN ('pending', 'processing')
  GROUP BY session_db_id;
"

# View recent failures
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;
"

钩子问题

钩子未触发

症状：没有出现背景，观察未保存。

解决方案:

验证钩子是否已配置：
bash
```
cat plugin/hooks/hooks.json
```

手动测试钩子：

bash

# Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js

检查钩子权限：
bash
```
ls -la plugin/scripts/*.js
```
验证 hooks.json 是否为有效的 JSON：
bash
```
cat plugin/hooks/hooks.json | jq .
```

未显示上下文

症状：Claude 启动时没有会话上下文。

解决方案:

检查摘要是否存在：

bash

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

查看最近的会话：
bash
```
npm run test:context:verbose
```

检查数据库完整性：

bash

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

手动测试上下文钩子：
bash
```
npm run test:context
```

钩子超时

症状：Hook 执行超时，Claude Code中出现错误。

解决方案:

增加 plugin/hooks/hooks.json 中的超时:

json

{
  "timeout": 180  // Increase from 120
}

检查工作进程是否正在运行（防止等待工作进程时超时）：
bash
```
npm run worker:status
```
检查数据库大小（大型数据库 = 查询缓慢）:
bash
```
ls -lh ~/.claude-mem/claude-mem.db
```

优化数据库：

bash

sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

依赖项未安装

症状：SessionStart 钩子因“未找到模块”错误而失败。

解决方案:

手动安装依赖项：

bash

cd ~/.claude/plugins/marketplaces/thedotmack
npm install

检查 npm 是否可用：
bash
```
which npm
npm --version
```

检查 package.json 是否存在：

bash

ls -la ~/.claude/plugins/marketplaces/thedotmack/package.json

数据库问题

数据库已锁定

症状：日志中出现“数据库被锁定”错误。

解决方案:

关闭所有连接：
bash
```
npm run worker:stop
```
检查过期锁：
bash
```
lsof ~/.claude-mem/claude-mem.db
```
终止持有锁的进程：
bash
```
kill -9 <PID>
```
重启Worker 进程：
bash
```
npm run worker:start
```

数据库损坏

症状：完整性检查失败，出现奇怪的错误。

解决方案:

检查数据库完整性：

bash

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

备份数据库：

bash

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

尝试修理：

bash

sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

核选项 - 重新创建数据库：

bash

rm ~/.claude-mem/claude-mem.db
npm run worker:start  # Will recreate schema

FTS5 搜索无法工作

症状：搜索未返回结果，FTS5 错误。

解决方案:

检查 FTS5 表是否存在：

bash

sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%_fts';"

重建 FTS5 表：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
  INSERT INTO user_prompts_fts(user_prompts_fts) VALUES('rebuild');
"

检查触发器是否存在：

bash

sqlite3 ~/.claude-mem/claude-mem.db "SELECT name FROM sqlite_master WHERE type='trigger';"

数据库过大

症状：性能缓慢，数据库文件过大。

解决方案:

检查数据库大小：
bash
```
ls -lh ~/.claude-mem/claude-mem.db
```

清理数据库：

bash

sqlite3 ~/.claude-mem/claude-mem.db "VACUUM;"

删除旧会话：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  DELETE FROM observations WHERE created_at_epoch < $(date -v-30d +%s);
  DELETE FROM session_summaries WHERE created_at_epoch < $(date -v-30d +%s);
  DELETE FROM sdk_sessions WHERE created_at_epoch < $(date -v-30d +%s);
"

删除后重建 FTS5：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  INSERT INTO observations_fts(observations_fts) VALUES('rebuild');
  INSERT INTO session_summaries_fts(session_summaries_fts) VALUES('rebuild');
"

MCP 搜索问题

搜索工具不可用

症状：Claude Code 中无法看到 MCP 搜索工具。

解决方案:

检查 MCP 配置：
bash
```
cat plugin/.mcp.json
```
验证搜索服务器是否已构建：
bash
```
ls -l plugin/scripts/mcp-server.cjs
```
如有需要，重建：
bash
```
npm run build
```
重启Claude代码

未找到搜索结果

症状：有效的查询返回空结果。

解决方案:

检查数据库是否有数据：

bash

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

验证 FTS5 表是否已填充：

bash

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

测试简单查询：

bash

# Test MCP search tool
search(query="test", limit=5)

检查查询语法：

bash

# Bad: Special characters may cause issues
search(query="[test]")

# Good: Simple words
search(query="test")

token 限制错误

症状：来自 MCP 的“超出 token 限制”错误。

解决方案:

遵循三层工作流程（不要跳到 get_observations）：

bash

# Start with search to get index
search(query="...", limit=10)

# Review IDs, then fetch only relevant ones
get_observations(ids=[<2-3 relevant IDs>])

减少搜索限制：
bash
```
search(query="...", limit=3)
```

使用筛选器来缩小结果范围：

bash

search(query="...", type="decision", limit=5)

分页显示结果：

bash

# First page
search(query="...", limit=5, offset=0)

# Second page
search(query="...", limit=5, offset=5)

get_observations 中的批次 ID：

bash

# Always batch multiple IDs in one call
get_observations(ids=[123, 456, 789])

# Don't make separate calls per ID

性能问题

慢速上下文注入

症状：SessionStart 钩子耗时过长。

解决方案:

减少上下文会话：

typescript

// In src/hooks/context.ts
const CONTEXT_SESSIONS = 5;  // Reduce from 10

优化数据库：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  ANALYZE;
  VACUUM;
"

添加索引（如果缺失）：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  CREATE INDEX IF NOT EXISTS idx_sessions_project_created ON sdk_sessions(project, created_at_epoch DESC);
"

慢查询

症状：MCP 搜索工具花费的时间太长。

解决方案:

使用更具体的查询
添加日期范围过滤器
添加类型/概念筛选
减少结果限制
使用索引格式而不是完整格式

高内存使用

症状：工作进程使用了过多内存。

解决方案:

检查当前使用情况：
bash
```
npm run worker:status
```
重启Worker 进程：
bash
```
npm run worker:restart
```
清理旧数据（见上文“数据库过大”）

安装问题

未找到插件

症状：/plugin install claude-mem 失败。

解决方案:

先添加市场：

bash

/plugin marketplace add thedotmack/claude-mem

然后安装：
bash
```
/plugin install claude-mem
```

验证安装：

bash

ls -la ~/.claude/plugins/marketplaces/thedotmack/

构建失败

症状：npm run build 失败。

解决方案:

清理并重新安装：

bash

rm -rf node_modules package-lock.json
npm install

检查 Node.js 版本：
bash
```
node --version  # Should be >= 18.0.0
```
检查 TypeScript 错误：
bash
```
npx tsc --noEmit
```

缺少依赖项

症状：出现“找不到模块”错误。

解决方案:

安装依赖项：
bash
```
npm install
```
检查 package.json：
bash
```
cat package.json
```
验证 node_modules 是否存在：
bash
```
ls -la node_modules/
```

调试

启用详细日志记录

bash


npm run worker:restart
npm run worker:logs

检查关联 ID

通过管道跟踪观察：

bash

sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT correlation_id, tool_name, created_at
  FROM observations
  WHERE session_id = 'YOUR_SESSION_ID'
  ORDER BY created_at;
"

检查工作状态

bash

# Check if worker is running
npm run worker:status

# View logs
npm run worker:logs

# Check port file
cat ~/.claude-mem/worker.port

# Test worker health
curl http://localhost:37777/health

数据库检查

bash

sqlite3 ~/.claude-mem/claude-mem.db

# View schema
.schema

# Check table counts
SELECT 'sessions', COUNT(*) FROM sdk_sessions
UNION ALL
SELECT 'observations', COUNT(*) FROM observations
UNION ALL
SELECT 'summaries', COUNT(*) FROM session_summaries
UNION ALL
SELECT 'prompts', COUNT(*) FROM user_prompts;

# View recent activity
SELECT created_at, tool_name FROM observations ORDER BY created_at DESC LIMIT 10;

常见错误信息

Worker 服务无响应

原因：工作进程未运行或端口不匹配。

解决方案：使用 npm run worker:restart 重启 Worker 进程。

数据库被锁定

原因：多个进程访问数据库。

解决方案：停止工作进程，终止陈旧进程，重新启动。

FTS5：语法错误

原因：无效的搜索查询语法。

解决方案：使用更简单的查询，避免特殊字符。

SQLITE_CANTOPEN

原因：数据库文件权限或缺少目录。

解决方案：检查 ~/.claude-mem/ 是否存在且可写。

未找到模块

原因：缺少依赖项。

解决方案：运行 npm install。

获取帮助

如果这些解决方案都不起作用：

检查日志:
bash
```
npm run worker:logs
```
创建问题: GitHub Issues
- 包括错误信息
- 包括相关日志
- 包括重现步骤
检查现有问题：可能已经有人解决了你的问题

下一步

Configuration - 自定义 Claude-Mem
Development - 从源代码构建
Architecture - 了解系统

故障排除指南 ​

快速诊断工具 ​

v5.x 特定问题 ​

查看器界面未加载 ​

主题切换未保存 ​

SSE 连接问题 ​

Chroma/Python 依赖问题 (v5.0.0 ) ​

智能安装缓存问题（v5.0.3） ​

Worker 服务问题 ​

Worker 服务未启动 ​

端口分配失败 ​

Worker 进程不断崩溃 ​

Worker 进程未处理观察结果 ​

卡住观测的手动恢复 ​

选项 1：使用 CLI 恢复工具（推荐） ​

选项2：直接使用HTTP API ​

理解队列状态 ​

恢复策略 ​

故障排除恢复问题 ​

理解队列表 ​

钩子问题 ​

钩子未触发 ​

未显示上下文 ​

钩子超时 ​

依赖项未安装 ​

数据库问题 ​

数据库已锁定 ​

数据库损坏 ​

FTS5 搜索无法工作 ​

数据库过大 ​

MCP 搜索问题 ​

搜索工具不可用 ​

未找到搜索结果 ​

token 限制错误 ​

性能问题 ​

慢速上下文注入 ​

慢查询 ​

高内存使用 ​

安装问题 ​

未找到插件 ​

构建失败 ​

缺少依赖项 ​

调试 ​

启用详细日志记录 ​

检查关联 ID ​

检查工作状态 ​

数据库检查 ​

常见错误信息 ​

Worker 服务无响应 ​

数据库被锁定 ​

FTS5：语法错误 ​

SQLITE_CANTOPEN ​

未找到模块 ​

获取帮助 ​

下一步 ​

故障排除指南

快速诊断工具

v5.x 特定问题

查看器界面未加载

主题切换未保存

SSE 连接问题

Chroma/Python 依赖问题 (v5.0.0 )

智能安装缓存问题（v5.0.3）

Worker 服务问题

Worker 服务未启动

端口分配失败

Worker 进程不断崩溃

Worker 进程未处理观察结果

卡住观测的手动恢复

选项 1：使用 CLI 恢复工具（推荐）

选项2：直接使用HTTP API

理解队列状态

恢复策略

故障排除恢复问题

理解队列表

钩子问题

钩子未触发

未显示上下文

钩子超时

依赖项未安装

数据库问题

数据库已锁定

数据库损坏

FTS5 搜索无法工作

数据库过大

MCP 搜索问题

搜索工具不可用

未找到搜索结果

token 限制错误

性能问题

慢速上下文注入

慢查询

高内存使用

安装问题

未找到插件

构建失败

缺少依赖项

调试

启用详细日志记录

检查关联 ID

检查工作状态

数据库检查

常见错误信息

Worker 服务无响应

数据库被锁定

FTS5：语法错误

SQLITE_CANTOPEN

未找到模块

获取帮助

下一步