核心能力#

1. 自动记录 — 通过 6 个生命周期钩子，自动捕获每次工具调用，生成语义摘要存入 SQLite
2. 自动注入 — 新会话启动时，自动把跟当前项目相关的记忆加载到 system prompt
3. 主动查询 — 自然语言提问即可搜索历史，如”上次修了什么 bug？“

与 CLAUDE.md 的关系#

自动化联动：Folder Context Files#

claude-mem 不仅是本地数据库存储，还能自动为项目文件夹生成 CLAUDE.md，实现与手动维护文件的联动。

工作机制：每次 observation 保存后，claude-mem 自动识别被修改文件所在的文件夹，查询近期相关 observation，生成活动时间线，写入该文件夹下的 CLAUDE.md（包裹在 <claude-mem-context> 标签中）。

生成内容示例：

1
# Authentication Module
2

3
这里是手动写的模块说明，会被保留。
4

5
<claude-mem-context>
6
### Jan 4, 2026
7
| ID | Time | T | Title | Read |
8
| #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 |
9
| #1235 | " | 🔴 | Fixed login redirect bug | ~180 |
10
</claude-mem-context>

关键设计：

• <claude-mem-context> 标签外的手动内容始终保留，再生时只替换标签内部分
• 项目根目录（含 .git 的目录）不自动生成，避免覆盖根 CLAUDE.md
• 默认关闭，通过 CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED: "true" 开启

闭环价值：团队中即使没有安装 claude-mem 的成员，拉取代码后也能通过自动生成的文件夹级 CLAUDE.md 看到活动时间线，快速了解最近做了什么。可通过 --clean 模式在 PR 合并前清理自动生成的内容。

2.1 架构总览#

5 大核心组件：

1
钩子收集 → SQLite 存储 → Worker 处理 → AI 压缩 → 下次会话注入

技术栈：TypeScript / Node.js 20+ + Bun / SQLite 3 + Express.js 5 / SSE / React / @anthropic-ai/claude-agent-sdk

两条数据管线：

• 记忆管线（写入）：Hook (stdin) → SQLite → Worker → Claude Agent SDK 压缩 → 写回数据库 → 下次注入
• 搜索管线（读取）：用户自然语言提问 → mem-search 触发 → HTTP API → FTS5 查询 → 返回结果

2.2 Hook Lifecycle — 6 个生命周期钩子#

每次 Claude Code 运行，按此顺序触发：

PostToolUse 一次会话可能触发 100+ 次，每次读文件、改代码、跑命令都会被记录。

2.3 Claude Agent SDK 的角色#

为什么需要它：PostToolUse 钩子捕获的是原始工具调用数据（如 {"tool": "Edit", "file": "src/auth.ts"}），本身没有语义价值。SDK 的作用是把原始记录变成结构化洞察（如 {"type": "bugfix", "title": "修复 JWT token 验证"}）。

工作流程：原始观察堆积 → 批量发给 Claude Agent SDK → 调用配置的模型（默认 claude-haiku，我们实际配置为 qwen3.6-plus） → 解析 XML 响应 → 结构化数据写回 SQLite

可配置模型（通过 CLAUDE_MEM_MODEL 指定，由 Claude Agent SDK 调用）：

2.4 Worker Service#

端口分配：默认 37700 + (uid % 100)（多用户不冲突），可用 CLAUDE_MEM_WORKER_PORT 覆盖

主要 HTTP 端点：

数据存储：

1
~/.claude-mem/
2
├── claude-mem.db           # SQLite 数据库
3
├── .env                    # gateway 凭证（BASE_URL + AUTH_TOKEN）
4
├── .install-version        # 版本标记
5
├── settings.json           # 用户配置
6
├── supervisor.json         # 进程管理
7
├── worker.pid              # PID 文件
8
├── chroma/                 # 可选向量索引
9
├── corpora/                # Knowledge Agent 语料库
10
└── logs/
11
    ├── worker-out.log      # 输出日志
12
    └── worker-error.log    # 错误日志

管理命令：npm run worker:start / stop / restart / logs / status

3.1 Observation（观察记录）#

最小信息单元——每次 Claude 调用工具后，被 AI 压缩提取的一条”工作记录”。

完整结构：

1
{
2
  "id": 123,
3
  "type": "bugfix",
4
  "title": "修复 JWT token 验证中的竞态条件",
5
  "subtitle": "高并发下读取过期 session",
6
  "narrative": "用户反馈登录后偶发 401...",
7
  "facts": ["401 是竞态条件导致的", "同步验证方案有效"],
8
  "concepts": ["authentication", "concurrency", "jwt"],
9
  "files_read": ["src/auth.ts", "src/session.ts"],
10
  "files_modified": ["src/auth.ts"],
11
  "created_at": "2026-06-04T10:30:00Z",
12
  "project": "claudecode"
13
}

6 种类型：

与 Session、Summary 的关系：

1
Session（会话容器）
2
  ├── 包含多个 Observation（工作记录条目）
3
  └── 结束时生成一条 Summary（会话总结）

3.2 Context Injection — 上下文注入#

SessionStart 钩子干 4 件事： 核心问题：每次新会话启动都无脑灌入历史数据，会不会是 Token 刺客？

1. 查数据库，拉取当前项目最近的 observation（默认 50 条）
2. 拉取最近的 session summaries
3. 按时间线展示，带会话标记
4. 智能显示摘要：只有当摘要是在最后一条观察之后生成的，才显示完整详情

核心问题：每次新会话启动都无脑灌入历史数据，会不会是 Token 刺客？

答案：不会。实际开销不到传统 RAG 的 1/10。

1
### Oct 26, 2025
2
| ID | Time | T | Title | Tokens |
3
| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
4
| #2592 | 1:16 AM | 🟡 | Web UI strategy redesigned | ~193 |

3.3 Memory Search — 三层搜索工作流#

不一次性灌入所有历史，而是分三层，按需展开：

1
Layer 1: search()           → 轻量索引（ID + 标题 + 分类，~50-100 tokens/条）
2
Layer 2: timeline()         → 某条记录前后的时间线上下文（~100-200 tokens/条）
3
Layer 3: get_observations() → 只对筛选后的 ID 拉完整详情（500-1,000 tokens/条）

Token 对比：传统 RAG 一次拉 20 条 = 10,000-20,000 tokens（10% 有用）vs 三层搜索 = 2,500-4,000 tokens（接近 100% 有用）。省了约 10 倍 token。

三个搜索工具：

• search — 全文搜索，支持 AND/OR/NOT/短语，按 type/project/date 过滤
• timeline — 按 ID 或关键词定位锚点，展开前后 N 条上下文
• get_observations — 批量拉取完整详情（必须传数组 ids=[123, 456, 789]）

6 个常见场景：

3.4 Knowledge Agents — 知识代理#

把 observation 历史编译成一个可对话的”大脑”——不是返回原始搜索结果，而是综合回答。

核心流程：Build → Prime → Query：

1
BUILD（编译语料库）──>  PRIME（加载到 Claude 会话）──>  QUERY（对话提问）

1. Build — 从 observation 历史中按条件筛选，保存为 corpus 文件（~/.claude-mem/corpora/*.corpus.json）
2. Prime — 把整个 corpus 加载到 Claude Agent SDK 的会话中，返回 session_id 就是 agent
3. Query — 对话提问，每次追问自然累加到会话中
4. Rebuild/Reprime — 新 observation 加入后重新编译和加载

vs Mem-Search：

经验法则：要找到具体的某件事用 mem-search；要理解全局用 knowledge-agent。

大白话类比：

3.5 Progressive Disclosure — 渐进式披露#

核心原则：先展示存在什么 + 获取成本。让 agent 自己决定要不要拉取。

传统 RAG 启动注入 35,000 tokens 历史（6% 有用），claude-mem 只注入 ~800 tokens 索引（100% 有用）。

索引格式：

1
### Oct 26, 2025
2
**src/hooks/context-hook.ts**
3
| ID | Time | T | Title | Tokens |
4
| #2591 | 1:15 AM | ⚖️ | Stderr messaging abandoned | ~155 |
5
| #2592 | 1:16 AM | 🟡 | Web UI strategy redesigned | ~193 |

Legend 图标：🔴 gotcha | 🟡 problem-solution | 🔵 how-it-works | 🟢 what-changed | 🟣 discovery | 🟠 why-it-exists | 🟤 decision | ⚖️ trade-off

4.1 核心配置项#

配置文件：~/.claude-mem/settings.json（首次运行自动创建）

4.2 Gateway 配置（ANTHROPIC_BASE_URL）#

当使用非 Anthropic 模型（如 qwen3.6-plus 通过 DashScope gateway）时，需要配置 gateway：

~/.claude-mem/.env：

1
ANTHROPIC_BASE_URL=https://coding.dashscope.aliyuncs.com/apps/anthropic
2
ANTHROPIC_AUTH_TOKEN=sk-sp-xxxxx

~/.claude-mem/settings.json：

1
{
2
  "CLAUDE_MEM_PROVIDER": "claude",
3
  "CLAUDE_MEM_CLAUDE_AUTH_METHOD": "gateway",
4
  "CLAUDE_MEM_MODEL": "qwen3.6-plus"
5
}

关键点：

• CLAUDE_MEM_MODEL 原样传给 SDK，gateway 必须认识这个名字
• 凭证必须在 ~/.claude-mem/.env，shell export 不可靠
• claude-mem 不自动检测 Claude Code 本身的 ANTHROPIC_BASE_URL，必须镜像到 .env

4.3 Modes & Languages#

Mode 定义了 Observer Role、Observation Types、Concepts、Language。通过 CLAUDE_MEM_MODE 配置：

4.4 Hook 超时时间#

5.1 Context Engineering（上下文工程）#

核心原则：找到最小的、信号最强的 token 集合，最大化期望结果的概率。

与 Prompt Engineering 的区别：

Context Rot：LLM 有”注意力预算”，上下文增长时会消耗殆尽。每个 token attend 所有其他 token（n² 关系），上下文越长准确率越低。

System Prompt 正确高度：足够具体引导行为 + 足够灵活提供启发式 + 最小信息集完整描述期望行为。从最小 prompt 开始，根据失败模式逐步补充。

长任务三技术：

1. Compaction — 压缩对话历史，保留关键决策
2. 结构化笔记（Agentic Memory） — Agent 写 NOTES.md 等外部文件
3. Sub-Agent 架构 — 主 agent 管高层计划，子 agent 返回 1000-2000 token 压缩摘要

5.2 Progressive Disclosure（渐进式披露）#

核心原则：先展示存在什么 + 获取成本。让 agent 自己决定要不要拉取。

四层设计原则：

1. 让成本可见 — 每条显示 token 数（~50 便宜直接拉，~500 要慎重）
2. 语义压缩 — 标题用 ~10 字说清楚
3. 按上下文分组 — 按日期、文件路径、项目分组
4. 提供检索工具 — 索引 + search → timeline → get_observations

成功指标：

• ✅ 有用 token / 总上下文 > 80%
• ✅ 显示 50 条索引，只拉 2-3 条详情
• ✅ 有索引 30 秒找到相关内容，无索引 90 秒扫描

5.3 两篇最佳实践的关系#

Context Engineering 是指导思想——怎么管理有限注意力预算。 Progressive Disclosure 是具体实现——claude-mem 把上下文工程原则落地为三层搜索架构。

共同核心：上下文是货币，要省着花。

5.4 记忆垃圾回收（Memory GC）#

长期使用后（1000+ 会话），SQLite 的 FTS5 索引和 Chroma 向量库会膨胀，且早期的某些观察认知会在后续重构中被废弃，导致 Context Rot（上下文腐化）——新会话被过时的历史数据干扰。

常见腐化场景：

• “发现 A 库版本不兼容” → 后续升级后已不再适用
• “选用了方案 X” → 后续重构中已切换为方案 Y
• 早期临时方案被当作”决策”持久化，误导新会话

对策：

• 定期审查：用 search(type="decision", orderBy="date_asc") 按时间线扫描早期决策，确认哪些已固化到 CLAUDE.md 或文档中
• 标记归档：利用 Knowledge Agent 的 Build 机制，定期把已固化的内容从活跃数据中标记为 archived
• 控制注入量：CLAUDE_MEM_CONTEXT_OBSERVATIONS 不要设太高（默认 50 足够），避免注入过多陈旧上下文
• 按类型过滤：注入时只保留高价值类型（decision、gotcha、discovery），跳过 change 类琐碎记录

经验法则：每 3-6 个月做一次记忆审查，把已写入文档的内容从 SQLite 中剥离。记忆系统不是越多越好，相关性 > 完整性。

sync-mem-model.sh — 模型同步 + Worker 重启#

位置：~/.claude/hooks/sync-mem-model.sh

做 3 件事：

1. 读取 Claude Code 当前模型（~/.claude/settings.json）
2. 写入 ~/.claude-mem/settings.json 的 CLAUDE_MEM_MODEL
3. 重启 worker 进程

1
Claude Code settings.json ──读──▶ 当前模型
2
                                    │
3
                                    ▼
4
                            ──写──▶ claude-mem/settings.json
5
                                    │
6
                                    ▼
7
                            ──重启──▶ worker 进程

check-claude-mem.sh — 深度健康检查#

位置：~/.claude/hooks/check-claude-mem.sh

switch-model.sh 自动同步 .env#

每次切换 provider 时，~/.claude/switch-model.sh 自动把新 gateway 的 URL 和 key 写入 ~/.claude-mem/.env，避免 worker 自动重启后丢失凭证。

最终配置#

.env 凭证持久化#

问题：之前 gateway 凭证（ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN）只存在于 ~/.claude/settings.json 中，由 sync-mem-model.sh 临时 export 给 worker。脆弱性：Worker 崩溃后 Bun 自动重启、系统重启、手动 restart 都可能导致变量丢失。

解决：创建 ~/.claude-mem/.env（权限 0600），Worker 每次启动时 EnvManager.loadClaudeMemEnv() 自动读取。

职责分工：

.env 修的是路，settings.json 选的是车。换车型不用重新修路。

为什么保留 sync-mem-model.sh：即使有了 .env 兜底凭证，模型名的同步和 worker 重启仍然需要它。除了 switch-model.sh，用户还可能通过 /model 命令切模型——那时 sync 脚本是唯一的同步路径。

8.1 代码考古：取代无意义的 git log#

痛点：接手半年前的旧模块，看到一行诡异的兼容代码，git blame 显示是自己写的，但完全想不起来当时遇到了什么坑。

玩法：直接搜索文件名或模块名：

1
# 通过 HTTP API 搜索
2
curl -s "http://localhost:37700/api/observations?limit=100" | jq '.[] | select(.files_modified[] | contains("auth"))'
3

4
# 或通过 mem-search 技能
5
search("worker-service.ts")

你能看到什么：完整的 Observation 链路——“发现 API 高并发下偶发 401（事实） → 判定为 JWT 验证中的竞态条件（技术决策） → 提取并重构了 useAuth 组件（重构事实）”。

价值：相当于一个自动生成的 “代码心理活动日志”，比 git log 多了一层 “为什么这么改”。

8.2 自动化生成周报 / Release Notes#

痛点：每周五花半小时凭记忆写周报、交付文档。

玩法：用 HTTP API 拉取本周 observation，喂给任意大模型润色：

1
const res = await fetch("http://localhost:37700/api/observations?limit=100");
2
const data = await res.json();
3
// 筛选出本周的 type === 'feature' 或 'bugfix'
4
// 喂给大模型："帮我把这些开发事实润色成一份本周的周报交付文档"

价值：由于 observation 精准记录了改了哪些文件（files_modified）、解决了什么 Bug，生成的周报比凭记忆写的要精准、详实得多。

8.3 跨项目技术决策库（ADR）#

痛点：在 A 项目封装了大文件分片上传的 Hooks，三个月后在 B 项目又遇到了，只记得”我以前做过”，但不记得细节。

玩法：claude-mem 的 SQLite 数据库是 跨项目共享 的（带 project 字段），直接在终端搜索：

1
search("slice upload", type="decision")

一秒钟找回三个月前在另一个项目里做出的架构决策和核心思路。

8.4 打通桌面工具链（MCP 集成）#

claude-mem 原生支持 Claude Desktop MCP。这意味着它的记忆不仅能给终端的 Claude Code 用，还能赋能整个桌面生态：

• Cursor / VS Code：接入本地 claude-mem MCP 服务后，编辑器内的 AI 辅助面板可以直接调用 search 和 timeline 工具，读取你在终端用 Claude Code 调试出来的排错历史。
• 个人 RAG 知识库：将 ~/.claude-mem/corpora/ 下的 .corpus.json 语料库导入 Obsidian 或 Notion，作为个人的 AI 辅助编程知识库。

8.5 团队新人的项目上下文#

传统做法：丢一个过时的 README.md，花两小时口述项目架构。

优雅做法：开启 Folder Context Files 自动化后，claude-mem 自动为每个模块文件夹增量生成 CLAUDE.md，连同代码一起推送到 Git。新人拉下代码后，不需要装任何工具，光是读这个实时更新的 CLAUDE.md 里的活动时间线，就能摸清项目过去两周都在发生什么、怎么提交、规避了哪些坑。

常用维护命令#

1
# 查看 worker 状态
2
curl -s http://localhost:37700/api/stats | jq '.'
3

4
# 查看待处理队列
5
curl -s http://localhost:37700/api/pending-queue | jq '.'
6

7
# 手动触发队列处理
8
curl -s -X POST http://localhost:37700/api/pending-queue/process
9

10
# 查看最近的 observation
11
curl -s "http://localhost:37700/api/observations?limit=5" | jq '.'
12

13
# 健康检查
14
bash ~/.claude/hooks/check-claude-mem.sh
15

16
# 同步模型 + 重启 worker
17
bash ~/.claude/hooks/sync-mem-model.sh
18

19
# 修复 claude-mem（版本不匹配、端口冲突）
20
npx claude-mem repair