第 15 期：排障指南 + 最佳实践 + 全书总结

本期场景：你已经掌握了 Claude-Mem 的所有核心功能。最后这一期，我们整理排障手册、分享日常最佳实践，并用博客项目做全书回顾。

15.1 常见问题排障清单

🔴 Worker 未启动

症状：http://localhost:37777 打不开

# Step 1: 检查进程
ps aux | grep claude-mem

# Step 2: 手动检查端口
lsof -i :37777

# Step 3: 尝试重装
npx claude-mem install

# Step 4: 查看日志
cat ~/.claude-mem/logs/worker.log

🔴 Observations 不出现

症状：Web UI 中没有新数据

可能原因	解决方案
Hook 未注册	`npx claude-mem install` 重装
Claude Code 版本太旧	更新到最新版
Worker 崩溃了	检查日志，重启 Worker
磁盘空间不足	清理 `~/.claude-mem/` 中的旧日志

🔴 搜索结果不准确

症状：搜索关键词返回无关结果

# 检查 ChromaDB 状态
ls -la ~/.claude-mem/chroma/

# 如果向量索引损坏，重建
npx claude-mem rebuild-index

🔴 MCP 在 Claude Desktop 中不工作

症状：Claude Desktop 说没有可用的 MCP 工具

检查项	操作
配置文件路径是否正确	检查 `claude_desktop_config.json`
MCP Server 脚本是否存在	`ls ~/.claude/plugins/marketplaces/thedotmack/plugin/scripts/mcp-server.cjs`
是否完全重启了 Claude Desktop	退出应用再打开（不是退出对话）
Node.js 是否可用	`node -v`

🔴 安装时报错

# 清除缓存后重试
rm -rf ~/.claude-mem
npx claude-mem install

15.2 日常最佳实践

实践 1：控制会话长度

不要让单次会话超过 300 个工具调用。

超长会话会导致：

Worker 压缩质量下降（太多数据需要处理）
Session Summary 变得笼统
上下文窗口被填满

建议：完成一个功能模块后，有意识地结束会话。让 SessionEnd 生成高质量摘要后，再开新会话继续。

实践 2：利用 File Read Gate

File Read Gate 是一种高级模式 —— 让 Claude 在读取文件之前先搜索记忆：

常规模式:
  用户: "修复评论 Bug"
  Claude → read_file("comments.ts")  → 8,000 tokens
  Claude → 分析并修复

File Read Gate 模式:
  用户: "修复评论 Bug"
  Claude → search("评论 Bug")  → 找到 Observation #67
  Claude → get_observations([67])  → 1,000 tokens
  Claude → 已知问题和修复方向 → 精准 read_file 所需的行
  → 总消耗更少

File Read Gate 让 Claude 先"回忆"再"行动"，避免盲目读取大文件。

实践 3：定期构建 Corpus

为项目的重要模块维护专题知识库：

每月维护一次:
  build_corpus("auth_system", tags=["认证","JWT","登录"])
  build_corpus("database", tags=["Prisma","Schema","迁移"])
  build_corpus("deployment", tags=["部署","CI/CD","环境"])

实践 4：善用 `<private>` 标签

养成习惯：涉及密钥、密码、内部 URL 时，用 <private> 包裹。

实践 5：检查 Web UI

每周花 2 分钟浏览 http://localhost:37777，了解 Claude-Mem 记录了什么。这有助于发现异常（比如 Observations 突然不更新了）。

15.3 博客项目的完整回顾

让我们用全书的视角，回顾博客项目在 Claude-Mem 加持下的开发历程：

graph TB
    subgraph "第 1-2 期"
        A1["安装 Claude-Mem"] --> A2["初始化博客项目"]
    end

    subgraph "第 3-5 期: 理解底层"
        A2 --> B1["观察数据如何存入 SQLite"]
        B1 --> B2["理解 Hook 自动捕获机制"]
        B2 --> B3["了解 Worker 压缩流程"]
    end

    subgraph "第 6 期: 省 Token"
        B3 --> C1["学会三层渐进式检索"]
    end

    subgraph "第 7-12 期: 掌握 7 Skills"
        C1 --> D1["Memory Search: 搜索记忆"]
        D1 --> D2["Smart Explore: 读代码"]
        D2 --> D3["Knowledge Agent: 知识库"]
        D3 --> D4["Make Plan + Do: 规划执行"]
        D4 --> D5["Timeline Report: 回顾"]
        D5 --> D6["Plugin Release: 版本管理"]
    end

    subgraph "第 13-15 期: 进阶"
        D6 --> E1["MCP: Claude Desktop 集成"]
        E1 --> E2["高级配置: 中文/隐私/导出"]
        E2 --> E3["排障 + 最佳实践"]
    end

    style A1 fill:#6366f1,color:#fff
    style E3 fill:#10b981,color:#fff

如果没有 Claude-Mem...

场景	没有 Claude-Mem	有 Claude-Mem
新会话继续开发	花 10 分钟重新解释项目	自动注入历史上下文
回忆上次做了什么	翻聊天记录、Git log	`search("上次的修改")`
理解代码结构	读取大量文件（$$$）	Smart Explore（省 93%）
规划复杂功能	手动一步步指挥	Make Plan + Do 自动规划执行
向同事解释架构	凭记忆口述	Knowledge Agent 生成报告
找到 3 个月前的 Bug 修复	几乎不可能	`search(type="bugfix", date_from=...)`

15.4 全书架构总览

最后放一张全景图，这就是 Claude-Mem 的完整架构：

graph TB
    subgraph "用户界面层"
        CC["Claude Code"]
        CD["Claude Desktop"]
        WebUI["Web Viewer
(localhost:37777)"]
    end

    subgraph "7 个 Skills"
        S1["Memory Search"]
        S2["Smart Explore"]
        S3["Knowledge Agent"]
        S4["Make Plan"]
        S5["Do"]
        S6["Timeline Report"]
        S7["Plugin Release"]
    end

    subgraph "协议层"
        MCP["MCP Protocol"]
        Hooks["5 Lifecycle Hooks
SessionStart / UserPromptSubmit
PostToolUse / Stop / SessionEnd"]
    end

    subgraph "服务层"
        Worker["Worker Service
(Bun + Express, port 37777)"]
        SDK["Claude Agent SDK
(AI 压缩引擎)"]
        SSE["SSE 事件流"]
    end

    subgraph "存储层"
        SQLite["SQLite
+ FTS5 全文搜索"]
        Chroma["ChromaDB
向量语义搜索"]
    end

    CC --> Hooks
    CC --> S1 & S2 & S3 & S4 & S5 & S6 & S7
    CD -->|MCP| MCP
    MCP --> Worker
    Hooks --> Worker
    Worker --> SDK
    SDK --> SQLite & Chroma
    Worker --> SSE
    SSE --> WebUI

    style CC fill:#6366f1,color:#fff
    style CD fill:#6366f1,color:#fff
    style Worker fill:#f59e0b,color:#000
    style SQLite fill:#10b981,color:#fff
    style Chroma fill:#10b981,color:#fff

15.5 进阶学习资源

资源	链接
官方文档	docs.claude-mem.ai
GitHub 仓库	github.com/thedotmack/claude-mem
架构演进文档	docs.claude-mem.ai/architecture-evolution
Context Engineering	docs.claude-mem.ai/context-engineering
Progressive Disclosure	docs.claude-mem.ai/progressive-disclosure
Troubleshooting	docs.claude-mem.ai/troubleshooting

全文完

从第 1 期的"为什么 AI 需要记忆"到现在，你已经掌握了 Claude-Mem 的完整知识体系：

✅ 理解了双数据库架构（SQLite + ChromaDB）
✅ 掌握了 5 个生命周期钩子的触发时机和数据流
✅ 学会了三层渐进式检索的省 Token 原理
✅ 实操了 7 个 Skills 的具体使用场景
✅ 配置了 MCP 让 Claude Desktop 共享记忆
✅ 定制了语言、隐私和上下文控制

去构建有记忆的 AI 工作流吧。