第 5 期：Worker Service — Claude-Mem 的心脏 — Claude-Mem 完全实战指南

本期场景：Hooks 只负责捕获数据并扔给 Worker，真正的脏活累活 —— 数据压缩、存储、搜索、Web UI 推送 —— 全部由 Worker Service 完成。

5.1 Worker Service 的角色

Worker Service 是一个运行在后台的 HTTP 服务，监听 localhost:37777。它是 Claude-Mem 架构中的枢纽：

graph TB
    subgraph "数据输入"
        H1["SessionStart Hook"]
        H2["PostToolUse Hook"]
        H3["SessionEnd Hook"]
    end

    subgraph "Worker Service (port 37777)"
        API["Express.js Router"]
        Compress["AI 压缩引擎
(Claude Agent SDK)"]
        SSE["SSE 事件流"]
    end

    subgraph "数据输出"
        DB["SQLite + FTS5"]
        Vec["ChromaDB 向量库"]
        UI["Web Viewer UI"]
    end

    H1 --> API
    H2 --> API
    H3 --> API
    API --> Compress
    Compress --> DB
    Compress --> Vec
    API --> SSE
    SSE --> UI

    style API fill:#f59e0b,color:#000
    style Compress fill:#6366f1,color:#fff

5.2 为什么用 Bun 而不是 Node.js？

Claude-Mem 从 v5 开始完全迁移到 Bun 运行时，原因有三：

特性	Node.js	Bun
SQLite 驱动	需要安装 `better-sqlite3`（C++ 编译）	内置 `bun:sqlite`（开箱即用）
进程管理	需要 PM2 等额外工具	Bun 自己管理子进程
启动速度	~200ms	~30ms
安装体积	较大	较小（单个二进制）

你不需要手动安装 Bun，npx claude-mem install 会自动搞定。但了解它存在有助于排障。

5.3 Worker 的核心 API 端点

Worker 对外暴露了约 10 个 HTTP 端点。以下是最重要的几个：

健康检查

curl http://localhost:37777/api/health
# → {"status":"ok"}

这是最基础的排障手段 —— 如果这个端点不通，说明 Worker 没在运行。

上下文获取（SessionStart 调用）

curl http://localhost:37777/api/context?project=my-blog

返回最近几个会话的 Observations 和 Summaries，Hook 将其注入 Claude 的初始上下文。

接收新 Observation（PostToolUse 调用）

# Hook 发送的请求类似这样
POST http://localhost:37777/api/observation
Content-Type: application/json

{
  "session_id": "sess_abc123",
  "tool_name": "Write",
  "tool_input": { "file": "src/api/comments.ts", "content": "..." },
  "tool_output": "File written successfully"
}

Worker 收到后的内部处理流程：

graph TD
    A["收到原始工具数据"] --> B["Claude Agent SDK
开始压缩"]
    B --> C["提取关键信息"]
    C --> D["生成结构化数据"]
    D --> D1["title: 修复评论外键约束"]
    D --> D2["narrative: 开发者发现..."]
    D --> D3["facts: 使用了级联删除..."]
    D --> D4["type: bugfix"]
    D --> D5["concepts: Prisma, 外键, 级联"]

    D1 --> E["SQLite INSERT"]
    D2 --> E
    D3 --> E
    D4 --> E
    D5 --> E
    E --> F["FTS5 索引更新"]

    D1 --> G["ChromaDB 向量化"]
    D2 --> G
    G --> H["向量索引更新"]

    E --> I["SSE 推送到 Web UI"]
    H --> I

    style A fill:#6366f1,color:#fff
    style B fill:#f59e0b,color:#000
    style I fill:#10b981,color:#fff

搜索端点

# 全文搜索
curl "http://localhost:37777/api/search?q=评论+bug&type=bugfix"

# 时间线
curl "http://localhost:37777/api/timeline?observation_id=42"

# 获取完整 Observation
curl "http://localhost:37777/api/observation/42"

Web Viewer UI

访问 http://localhost:37777（不带 /api 路径），你会看到一个漂亮的 Web 界面，提供：

🔴 实时 Observation 流（通过 SSE 推送，不需要刷新页面）
🔍 搜索功能
⚙️ 配置管理
📊 统计信息
🔄 版本切换（稳定版 / Beta）

5.4 AI 压缩的内部逻辑

Worker 收到原始工具输出后，不是直接存储，而是用 Claude Agent SDK 进行一轮 AI 压缩。这一步至关重要，因为原始数据往往又长又杂：

原始数据	Token 量	压缩后	Token 量	压缩比
读取一个 500 行文件的完整内容	~8,000	"读取了 auth.ts 的 JWT 验证逻辑" + facts 列表	~200	40x
`npm test` 输出的 200 行日志	~3,000	"运行测试，15 个通过，1 个失败（评论 API 超时）"	~100	30x
写入一个大文件的完整 diff	~5,000	"修改了评论 API，添加了输入验证逻辑" + concepts	~150	33x

这种压缩让 Claude-Mem 能在不消耗过多 Token 的情况下，注入大量历史上下文。

5.5 常见 Worker 问题排查

Worker 没有启动

# 检查进程
ps aux | grep bun | grep claude-mem

# 如果看不到进程，手动启动
cd ~/.claude/plugins/marketplaces/thedotmack
bun run plugin/worker/index.ts

端口被占用

# 查看谁占用了 37777
lsof -i :37777

# 如果需要换端口，编辑 settings.json
vim ~/.claude-mem/settings.json
# 修改 "WORKER_PORT": 37778

Worker 日志在哪？

# 查看实时日志
tail -f ~/.claude-mem/logs/worker.log

# 常见的健康日志
# [INFO] Worker started on port 37777
# [INFO] Processing observation for session sess_abc123
# [INFO] Compression complete: "修复评论外键约束" (bugfix)

Worker 意外退出

# 重装通常能解决
npx claude-mem install

实操练习

验证 Worker 正在运行：

curl http://localhost:37777/api/health

在博客项目中用 Claude Code 做一些操作
在另一个终端实时监控 Worker 日志：

tail -f ~/.claude-mem/logs/worker.log

打开 Web Viewer UI (http://localhost:37777)，观察实时 SSE 流
手动调用搜索 API 测试：

curl "http://localhost:37777/api/search?q=blog"

下期预告

Worker 负责存数据，但怎么读数据才高效？直接把所有记忆塞给 Claude 会消耗巨量 Token。下一期我们学习 Claude-Mem 最精妙的设计 —— 三层渐进式检索（Progressive Disclosure），这是它的「省钱秘诀」。

➡️ 第 6 期：三层渐进式检索 — Claude-Mem 的省钱秘诀