跳转至

故障排查指南

快速诊断工具

向 Claude 描述你遇到的任何问题，故障排查技能将自动激活并提供诊断和修复。

该技能将： - ✅ 检查 worker 状态和健康情况 - ✅ 验证数据库是否存在且完整 - ✅ 测试 worker 服务的连通性 - ✅ 验证依赖项是否已安装 - ✅ 检查端口配置和可用性 - ✅ 为常见问题提供自动修复

该技能包含全面的诊断、自动修复序列，以及针对所有常见问题的详细排查工作流。只需自然地描述问题即可调用它。

常见问题

对于下面的 worker API 命令，请先设置 PORT：

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

查看器 UI 无法加载

症状：无法访问查看器 URL，页面无法加载，或浏览器显示连接错误。

解决方法：

  1. 查找 worker 端口。默认值为 37700 + (uid % 100)。配置的端口是 ~/.claude-mem/settings.json 中 CLAUDE_MEM_WORKER_PORT 的值；运行中的 worker 也会在 /api/health 上报告该端口： 

    PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
lsof -i :$PORT
npm run worker:status

  2. 验证 worker 是否健康： 

    curl http://127.0.0.1:$PORT/health

  3. 检查 worker 日志中的错误： 

    npm run worker:logs

  4. 重启 worker 服务： 

    npm run worker:restart

  5. 如果自动分配的端口冲突，请固定端口： 

    export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

Provider 超时后 Observer 暂停

如果某个 observer 请求超时，Claude-Mem 会保留其排队中的观察记录，并在一段时间后安排另一次尝试。延迟从配置的 CLAUDE_MEM_LLM_TIMEOUT_MS 附近开始，并在连续尝试超时时增大。一次成功的排队观察记录会重置该退避。即使原始会话已结束，也不需要新的 Claude Code 钩子。

在 worker 日志中查找 Transport pause: scheduled buffered-work resume，然后查找 Generator auto-starting (transport-resume)。如果 provider 仍不可用，worker 会以较慢的频率继续探测，并一次只允许一次无人值守的 transport resume。在 cmem.ai 记忆网关上，那些背后没有 Claude Code 活动的重试——超时后、限流等待后、或记忆转入你的 Anthropic 套餐后——如果连续三次没有得到应答就会停止，以免消耗你的套餐；排队中的观察记录随后会等待你的下一次 Claude Code 活动（日志会显示 Unattended resumes stopped on the cmem gateway）。身份验证和配额暂停仍需走现有的恢复路径。

此路径中的排队观察记录保存在 worker 内存中。如果在它们被处理前重启 worker，仍可能丢失它们；相关独立的持久化工作请参阅 issue #4068。

主题切换无法持久化

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

解决方法：

  1. 检查浏览器是否启用了 localStorage： 

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

  2. 验证 settings 端点是否正常工作： 

    curl http://127.0.0.1:$PORT/api/settings

  3. 清除 localStorage 并重试： 

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

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

SSE 连接问题

症状：查看器显示 “Disconnected” 状态，更新无法实时显示。

解决方法：

  1. 检查 SSE 端点是否可访问： 

    curl -N http://127.0.0.1:$PORT/stream

  2. 检查浏览器控制台中的错误：

  3. 打开开发者工具 (F12)
  4. 查找 EventSource 错误

  5. 在 Network 标签页中检查失败的 /stream 请求

  6. 验证 worker 是否在运行： 

    npm run worker:status

  7. 检查是否有网络/代理问题阻止 SSE

  8. 企业防火墙可能会阻止 SSE

  9. 尝试暂时禁用 VPN

  10. 重启 worker 并刷新浏览器： 

    npm run worker:restart

Chroma/Python 依赖问题（v5.0.0+）

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

解决方法：

  1. 验证是否已安装 Python 3.8+： 

    python --version
# or
python3 --version

  2. 手动安装 chromadb： 

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

  3. 检查 chromadb 健康状态： 

    npm run chroma:health

  4. Windows 专用：确保 Python 在 PATH 中： 

    where python
# Should show Python installation path

  5. 如果 Chroma 仍然失败，混合搜索将优雅地降级为仅使用 SQLite FTS5

关闭工具钩子捕获（PreToolUse / PostToolUse）

何时使用：你希望 claude-mem 停止捕获工具调用（PostToolUse observation）或在 Read 之前注入文件历史（PreToolUse file-context），例如因为每个工具调用的钩子成本在你的机器上过高。不要改为在 hooks.json 中重命名这些键：Claude Code 会拒绝未知的钩子键，并丢弃整个插件的钩子集。

选择退出（SessionStart 上下文、UserPromptSubmit 和 Stop 摘要仍可正常工作）：

{
  "env": {
    "CLAUDE_MEM_DISABLE_TOOL_HOOKS": "1"
  }
}

将上述内容添加到 ~/.claude/settings.json（或在 shell 中导出该变量）。如果只关闭两个钩子中的一个，请使用 CLAUDE_MEM_DISABLE_OBSERVATION=1 或 CLAUDE_MEM_DISABLE_FILE_CONTEXT=1。请参阅 配置。

Windows 控制台窗口：旧版本在每次工具调用时闪现的控制台窗口不需要此开关。Claude Code 现在直接将每个钩子作为 claude-mem 启动器运行，中间没有 bash（#3605）。该开关仍然只是让每个工具钩子立即退出；Claude Code 仍会启动 claude-mem 进程。

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

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

解决方案：

  1. 清除安装缓存： 

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

  2. 强制重新安装： 

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

  3. 检查版本标记： 

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

  4. 手动安装后重启 Claude Code

Worker Service 问题

Worker Service 无法启动

症状：Worker 未启动，或 Worker 状态显示其未运行。

解决方案：

  1. 检查 Worker 状态： 

    npm run worker:status

  2. 尝试手动启动： 

    npm run worker:start

  3. 检查 Worker 日志中的错误： 

    npm run worker:logs

  4. 完全重置： 

    npm run worker:stop
npm run worker:start

  5. 确认已安装 Bun： 

    which bun
bun --version

端口分配失败

症状：Worker 因“端口已被占用”错误而无法启动。

解决方案：

  1. 检查配置的端口是否被占用： 

    lsof -i :$PORT

  2. 终止占用端口的进程： 

    kill -9 $(lsof -t -i:$PORT)

  3. 或使用其他端口： 

    export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:restart

  4. 验证新端口： 

    curl -s http://127.0.0.1:$CLAUDE_MEM_WORKER_PORT/api/health | jq .port

Worker 反复崩溃

症状：Worker 反复重启，或无法保持运行。

解决方案：

  1. 检查错误日志： 

    npm run worker:logs

  2. 检查 Worker 状态： 

    npm run worker:status

  3. 检查数据库是否损坏： 

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

  4. 验证 Bun 安装： 

    bun --version

Worker 未处理观察记录

症状：观察记录已保存但未被处理，未生成任何摘要。

解决方案：

  1. 检查 Worker 是否在运行： 

    npm run worker:status

  2. 检查 Worker 日志： 

    npm run worker:logs

  3. 确认数据库中有观察记录： 

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

  4. 重启 Worker： 

    npm run worker:restart

卡住的观察记录的手动恢复

症状：Worker 崩溃或重启后，观察记录卡在处理队列中；尽管 Worker 在运行，却没有新的摘要生成。

背景：自 v5.x 起，Worker 启动时的自动队列恢复已禁用。用户必须手动触发恢复，以保持对重新处理的显式控制，并防止出现意外的重复观察记录。

解决方案：

交互式 CLI 工具提供了最安全且最友好的恢复体验：

# 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

适用于自动化或脚本编写场景：

  1. 检查队列状态： 
    curl http://127.0.0.1:$PORT/api/pending-queue

响应包含： - queue.totalPending：等待处理的消息 - queue.totalProcessing：当前正在处理的消息 - queue.stuckCount：处理时间超过 5 分钟的消息 - sessionsWithPendingWork：需要恢复的会话 ID

  1. 触发手动恢复： 
    curl -X POST http://127.0.0.1:$PORT/api/pending-queue/process \
  -H "Content-Type: application/json" \
  -d '{"sessionLimit": 10}'

响应包含： - totalPendingSessions：有待处理消息的会话总数 - sessionsStarted：我们开始处理的会话数 - sessionsSkipped：已在处理中的会话（未重启） - startedSessionIds：已开始处理的会话的数据库 ID

理解队列状态

消息依次经历以下状态：

  1. pending - 已排队，等待处理
  2. processing - 正在由 SDK agent 处理
  3. processed - 已成功完成
  4. failed - 重试 3 次后失败

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

恢复策略

何时使用手动恢复： - Worker 崩溃或意外重启后 - 观察记录显示已保存但未生成摘要时 - 队列状态显示有卡住的消息（处理时间超过 5 分钟）时 - 系统崩溃或强制关机后

最佳实践： 1. 在触发恢复前始终检查队列状态 2. 对交互式会话使用 CLI 工具（可提供反馈） 3. 对自动化/脚本编写使用 HTTP API 4. 从较低的会话限制（5-10）开始，避免让 Worker 过载 5. 在恢复期间监控 Worker 日志：npm run worker:logs 6. 检查最近处理的消息，确认恢复成功

排查恢复问题

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

  1. 验证 worker 是否健康： 

    curl http://127.0.0.1:$PORT/health
# Should return: {"status":"ok","uptime":12345,"port":...}

  2. 检查数据库是否损坏： 

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

  3. 直接查看卡住的消息： 

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

  4. 强制重置卡住的消息（核选项）： 

    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

  1. 查看 worker 日志中的 SDK 错误： 
    npm run worker:logs | grep -i error

了解队列表

pending_messages 表通过以下关键字段跟踪所有消息：

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
)

查询示例：

# 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;
"

Hook 问题

claude-mem：在 hooks 中找不到命令

症状：每个 hook 都会报告非阻塞错误，且不会出现上下文或观察结果。在转录或 claude --debug 输出中：

Error occurred while executing hook command: Executable not found in $PATH: "claude-mem"

或者，对于启动自愈条目：

Error occurred while executing hook command: Executable not found in $PATH: "node"

会话启动时可能还会显示：

claude-mem: memory hooks are not active: <reason>. Fix: run `npx claude-mem install`, then restart Claude Code.

原因：Claude Code 以 claude-mem hook claude-code <event> 的形式运行每个 hook，且不通过 shell。因此它需要 claude-mem 启动器位于其启动时继承的 PATH 中。该启动器位于 ~/.local/bin/claude-mem（macOS/Linux）或 %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe（Windows）。node 错误意味着 Node.js 也不在该 PATH 中，因此自愈条目（node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs）无法运行来放置启动器。

解决方案：

  1. 安装或刷新启动器： 

    npx claude-mem install
    它会编译启动器、将其放置到位，并将其目录添加到 PATH（macOS/Linux 上为 shell rc 文件，Windows 上为用户 Path）。对于 node 错误，请先安装 Node.js 20+。

  2. 重启终端或 IDE，然后重启 Claude Code。正在运行的 Claude Code（或启动它的 IDE）会保留其启动时的 PATH，因此不会看到该更改。

  3. 检查 Hook 启动器 行： 

    npx claude-mem doctor

  4. ok — <path> (protocol N, --version N ms)：启动器可解析；请从新终端重启 Claude Code。
  5. installed at <path> but its directory is not on PATH — 打开新终端，或重新运行 npx claude-mem install。
  6. claude-mem not on PATH — 运行 npx claude-mem install。
  7. <path> is not the claude-mem hook launcher — 另一个 claude-mem 在 PATH 中排在前面（见下一步）。

  8. speaks protocol N, expected M（警告）— 启动器来自另一个版本；请运行 npx claude-mem install。

  9. 检查是否存在遮蔽 PATH 的 npm 全局 claude-mem。npm install -g claude-mem 会将 npm CLI 安装为 claude-mem；如果其目录在 PATH 中排在启动器之前，hook 将运行错误的程序： 

    which -a claude-mem      # macOS/Linux
where.exe claude-mem     # Windows
    使用 npm uninstall -g claude-mem 将其移除，或者将 ~/.local/bin（或 %LOCALAPPDATA%\claude-mem\bin）在 PATH 中排在它前面。安装程序不会覆盖它未放置的 claude-mem。

  10. 使用 claude --version 检查你的 Claude Code 版本。exec 形式的 hook 需要 Claude Code 2.1.139 或更高版本；较旧的 Claude Code 会忽略 hook 的 args 并直接运行裸 claude-mem，这只会打印用法信息且不会捕获任何内容，也不会显示错误。npx claude-mem doctor 会在 Claude Code 版本 行发出警告。使用 claude update 进行更新。

  11. 更新后可能会有一个间隙。在仅通过市场安装的情况下，如果启动器缺失或过时，启动自愈会在会话启动期间编译启动器。更新后的第一个会话在编译期间可能会缺少内存上下文；下一个会话则会包含。改为运行 npx claude-mem update 可以避免这个间隙。

Hook 未触发

症状：没有上下文出现，观察结果未保存。

解决方案：

  1. 验证 hook 是否已配置： 

    cat plugin/hooks/hooks.json

  2. 手动测试 hook： 

    # Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | claude-mem hook claude-code context

  3. 检查启动器是否在 PATH 中： 

    command -v claude-mem && claude-mem --version   # prints the launcher protocol number
    如果缺失，请参阅 claude-mem：在钩子中找不到命令。

  4. 验证 hooks.json 是否为有效的 JSON： 

    cat plugin/hooks/hooks.json | jq .

上下文未出现

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

解决方案：

  1. 检查摘要是否存在： 

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

  2. 查看最近的会话： 

    npm run test:context:verbose

  3. 检查数据库完整性： 

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

  4. 手动测试上下文钩子： 

    npm run test:context

钩子超时

症状：钩子执行超时，在 Claude Code 中报错。

解决方案：

  1. 增加 plugin/hooks/hooks.json 中的超时时间： 

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

  2. 检查 worker 是否在运行（防止等待 worker 时超时）： 

    npm run worker:status

  3. 检查数据库大小（数据库过大 = 查询缓慢）： 

    ls -lh ~/.claude-mem/claude-mem.db

  4. 优化数据库： 

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

Windows："bun" is not recognized 钩子错误

症状：在 Windows 上，每个钩子都会失败，并出现以下错误：

SessionStart:startup hook error
Failed with non-blocking status code: ""bun"" is not recognized as an internal or external command

（或本地化等效提示），即使 bun --version 在任何终端中都能正常工作，并且 where bun 也能正确解析。

原因：cmd.exe 会静默丢弃长度超过约 8,191 个字符的环境变量。旧版基于 bash 的钩子会将登录 shell 的 PATH 前置到继承的 PATH 之前，这可能会使其翻倍并超过该限制——在 cmd.exe 内部，PATH 随后变为空，因此即使 where.exe（使用 Win32 API，没有此类限制）能找到 bun，裸的 bun 命令也无法被解析。只有组合后的 PATH 超过该限制时才会复现此问题，这就是为什么同样的设置在 PATH 较短的机器上可以正常工作。

解决方案：

  1. 使用 npx claude-mem install 更新 claude-mem。现在钩子直接运行 claude-mem 启动器，不需要 bash 或 cmd.exe，它会解析出 bun.exe 的绝对路径并直接启动它。运行时钩子不再需要 Git Bash。

  2. 检查你的 PATH 长度；如果接近或超过约 4,000 个字符，一旦翻倍就会超过 cmd.exe 的限制： 

    $env:Path.Length

  3. 删除重复或失效的 PATH 条目（Windows 会合并机器和用户的 PATH，而且许多安装程序会同时添加两者）。

依赖项未安装

症状：SessionStart 钩子因“module not found”错误而失败。

解决方案：

  1. 手动安装依赖： 

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

  2. 检查 npm 是否可用： 

    which npm
npm --version

  3. 检查 package.json 是否存在： 

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

数据库问题

数据库被锁定

症状：日志中出现“database is locked”错误。

解决方案：

  1. 关闭所有连接： 

    npm run worker:stop

  2. 检查是否存在过期的锁： 

    lsof ~/.claude-mem/claude-mem.db

  3. 终止持有锁的进程： 

    kill -9 <PID>

  4. 重启 worker： 

    npm run worker:start

数据库损坏

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

解决方案：

  1. 检查数据库完整性： 

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

  2. 备份数据库： 

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

  3. 尝试修复： 

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

  4. 终极手段——重建数据库： 

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

FTS5 搜索无法工作

症状：搜索无结果，出现 FTS5 错误。

解决方案：

  1. 检查 FTS5 表是否存在： 

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

  2. 重建 FTS5 表： 

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

  3. 检查触发器是否存在： 

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

数据库过大

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

解决方案：

  1. 检查数据库大小： 

    ls -lh ~/.claude-mem/claude-mem.db

  2. 对数据库执行 VACUUM： 

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

  3. 删除旧会话： 

    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);
"

  4. 删除后重建 FTS5： 

    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 搜索工具。

解决方案：

  1. 检查 MCP 配置： 

    cat plugin/.mcp.json

  2. 确认搜索服务器已构建： 

    ls -l plugin/scripts/mcp-server.cjs

  3. 如有需要，重新构建： 

    npm run build

  4. 重启 Claude Code

搜索无结果

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

解决方案：

  1. 检查数据库是否有数据： 

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

  2. 验证 FTS5 表是否已填充： 

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

  3. 测试简单查询： 

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

  4. 检查查询语法： 

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

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

Token 限制错误

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

解决方案：

  1. 遵循三层工作流（不要跳过前面的步骤直接使用 get_observations）： 

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

# Review the index and inspect context around a relevant ID
timeline(anchor=<relevant_id>, depth_before=2, depth_after=2)

# Review that context, then fetch only the selected records
get_observations(ids=[<2-3 relevant IDs>])

  2. 降低 search 中的 limit： 

    search(query="...", limit=3)

  3. 使用过滤器缩小结果范围： 

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

  4. 对结果进行分页： 

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

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

  5. 在 get_observations 中批量传入 ID： 

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

# Don't make separate calls per ID

性能问题

上下文注入缓慢

症状：SessionStart 钩子耗时过长。

解决方案：

  1. 减少上下文会话数： 

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

  2. 优化数据库： 

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

  3. 添加索引（如果缺失）： 

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

搜索查询缓慢

症状：MCP 搜索工具耗时过长。

解决方案：

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

内存占用过高

症状：Worker 占用过多内存。

解决方案：

  1. 检查当前使用情况： 

    npm run worker:status

  2. 重启 worker： 

    npm run worker:restart

  3. 清理旧数据（参见上文“数据库过大”）

安装问题

插件未找到

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

解决方案：

  1. 先添加市场： 

    /plugin marketplace add thedotmack/claude-mem

  2. 然后安装： 

    /plugin install claude-mem

  3. 验证安装： 

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

构建失败

症状：npm run build 失败。

解决方案：

  1. 清理并重新安装： 

    rm -rf node_modules package-lock.json
npm install

  2. 检查 Node.js 版本： 

    node --version  # Should be >= 20.0.0

  3. 检查 TypeScript 错误： 

    npx tsc --noEmit

缺少依赖

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

解决方案：

  1. 安装依赖： 

    npm install

  2. 检查 package.json： 

    cat package.json

  3. 验证 node_modules 是否存在： 

    ls -la node_modules/

调试

启用详细日志

export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs

检查关联 ID

追踪整个流水线中的观测记录：

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

检查 Worker 状态

# Check if worker is running
npm run worker:status

# View logs
npm run worker:logs

# Check configured port (per-user default = 37700 + uid % 100)
jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json

# Test worker health (substitute PORT for the value above)
curl "http://127.0.0.1:$PORT/health"

数据库检查

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 服务无响应”

原因：Worker 未运行或端口不匹配。

解决方法：使用 npm run worker:restart 重启 worker。

“数据库被锁定”

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

解决方法：停止 worker，终止残留进程，然后重新启动。

“FTS5：语法错误”

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

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

“SQLITE_CANTOPEN”

原因：数据库文件权限问题或目录缺失。

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

“找不到模块”

原因：缺少依赖。

解决方法：运行 npm install。

获取帮助

如果上述解决方案均无效：

  1. 检查日志： 

    npm run worker:logs

  2. 创建 Issue：GitHub Issues

  3. 包含错误消息
  4. 包含相关日志

  5. 包含复现步骤

  6. 查看现有 Issue：可能已经有人解决了你的问题

下一步

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