1. 为什么 Claude Code 需要一套持久记忆压缩系统
用 Claude Code 写项目的人，大概率都遇到过同一个尴尬：昨天刚跟它讲清楚目录结构、命名规范、某个接口为什么这么设计，今天开个新会话，它又像第一次进这个仓库一样，从零开始问东问西。项目结构、历史决策、已经修过的 Bug，全都在会话结束时蒸发了。
Claude-Mem 就是冲着这个痛点来的。它是一个专为 Claude Code 设计的持久记忆压缩系统，通过生命周期 Hook 自动捕获工具调用和会话内容，再经 AI 语义压缩后写入本地 SQLite + ChromaDB 向量数据库，为后续会话提供智能上下文注入。简单说，它让 Claude Code 拥有了"跨会话的长期记忆"，而且这套记忆是压缩过的，不是把历史对话原样塞回去。
它适合谁？三类人最值得装：一是长期维护同一个仓库、每天都要跟 Claude Code 打交道的开发者；二是用 Cursor、Gemini CLI 等多工具切换、希望记忆能共享的人；三是被 Token 账单教育过、想靠"渐进式检索"把上下文成本压下来的人。实测下来，三层渐进检索相比全量拉取，Token 节省能到 50%–75%。
这篇不讲空话，直接给你可复制的settings.json与config.toml骨架、TaoToken 统一 Key 配置片段，以及安装后验证记忆压缩是否真的生效的具体命令。架构部分我会拆到你能自己改 Hook 的程度。
2. TaoToken 前置：给 Claude-Mem 一条统一的 Key/API 通道
Claude-Mem 本身是本地优先的，数据不出机器，但它的 AI 语义压缩环节需要调用模型。如果你同时用 Claude Code、Cursor、Gemini CLI，每个工具各配一套 Key，管理起来很烦，额度也分散。TaoToken 在这里的角色就是"统一 Key/API 通道"——一个 Key 覆盖多个模型入口，Claude-Mem 的压缩调用、Claude Code 的对话调用都走同一条通道。
先把入口准备好。官网注册与总览在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=，API 基址是https://taotoken.net/api（这个地址不加 UTM，配置里直接写它）。
拿到 Key 的路径是：登录后进控制台，在 API Keys 页面创建一个新 Key。建议按用途分 Key，比如claude-mem-compress专门给记忆压缩用，claude-code-main给日常编码用，这样后面排查额度消耗时能一眼看出是谁在花钱。
注意：Claude-Mem 的压缩调用是后台异步的，频率不低。如果你把压缩和主对话混用同一个 Key，额度曲线会很难看。分 Key 是省心的第一步。
创建完 Key 后，先别急着写进 Claude-Mem，用一条 curl 确认通道是通的：
curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer $TAOTOKEN_API_KEY"返回模型列表就说明 Key 和通道都正常。这一步很重要，因为 Claude-Mem 的报错经常被 Hook 的静默执行吞掉，先在通道层确认，能省掉后面一半的排查时间。
3. 可复制配置：settings.json 与 config.toml 骨架
Claude-Mem 的配置分两块：一块是 Claude Code 侧的 Hook 注册（~/.claude/settings.json），一块是 Claude-Mem 自身的运行配置（~/.claude-mem/config.toml）。下面两份骨架你可以直接抄，改掉 Key 和路径即可。
3.1 settings.json：Hook 注册与 TaoToken 环境变量
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-your-taotoken-key", "CLAUDE_MEM_WORKER_PORT": "37777", "CLAUDE_MEM_WORKER_HOST": "localhost", "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "50" }, "hooks": { "SessionStart": [ { "matcher": "startup|clear|compact", "hooks": [ { "type": "command", "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/worker-service.cjs start", "timeout": 60 }, { "type": "command", "command": "bun ${CLAUDE_PLUGIN_ROOT}/scripts/context-hook.js", "timeout": 60 } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/new-hook.js", "timeout": 120 } ] } ], "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/save-hook.js", "timeout": 120 } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/summary-hook.js", "timeout": 120 } ] } ], "SessionEnd": [ { "hooks": [ { "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup-hook.js", "timeout": 120 } ] } ] } }这里的关键是env段：ANTHROPIC_BASE_URL指向 TaoToken 的 API 基址，ANTHROPIC_API_KEY填你刚创建的 Key。Claude-Mem 的压缩调用会继承这套环境变量，所以它走的就是同一条通道，不需要在 Claude-Mem 里再单独配一遍。
3.2 config.toml：Claude-Mem 运行参数
[worker] port = 37777 host = "localhost" auto_start = true [compression] enabled = true model = "claude-sonnet-4-20250514" max_observations_per_session = 200 summary_timeout_seconds = 120 [context] inject_observations = 50 inject_timeout_seconds = 60 progressive_retrieval = true [storage] db_path = "~/.claude-mem/claude-mem.db" chroma_path = "~/.claude-mem/chroma" [privacy] strip_api_keys = true strip_jwt = true private_tag = "<private>" [api] base_url = "https://taotoken.net/api" api_key_env = "ANTHROPIC_API_KEY"[compression]段控制 AI 语义压缩的行为，model填你要用的模型名；[context]段的progressive_retrieval = true就是开启三层渐进检索，这是省 Token 的核心开关；[privacy]段负责自动剥离 API Key、JWT 这类敏感串，写入前就过滤掉。
提示：
api_key_env写的是环境变量名而不是 Key 本身，这样 Key 只存在settings.json一处，改起来不会漏。
4. 安装与验证：确认记忆压缩真的生效
配置写好了，接下来是安装和验证。安装本身不复杂，难的是"怎么知道它真的在工作"。
4.1 安装 Worker
在终端执行（用 npx，不要全局安装，避免版本锁死）：
npx claude-mem install这条命令会自动完成四件事：创建~/.claude-mem目录、生成 SQLite 数据库和 ChromaDB 向量存储、在 Claude Code 中注册 5 个生命周期 Hook、启动 Worker 后台服务（端口 37777）。
装完先看 Worker 状态：
npx claude-mem worker:status预期输出是running。如果不是，手动拉起来：
npx claude-mem worker:start4.2 验证记忆压缩生效
这是全文最关键的一步。开一个 Claude Code 会话，随便让它读几个文件、改一处代码，然后退出。接着检查数据库里有没有产生 Observation：
sqlite3 ~/.claude-mem/claude-mem.db \ "SELECT id, title, type, created_at FROM observations ORDER BY id DESC LIMIT 5;"如果能看到记录，说明 PostToolUse Hook 捕获成功。再看压缩摘要有没有生成：
sqlite3 ~/.claude-mem/claude-mem.db \ "SELECT request, completed, next_steps FROM session_summaries ORDER BY id DESC LIMIT 1;"completed和next_steps字段有内容，就证明 AI 语义压缩跑通了，而且走的是你配的 TaoToken 通道。
最后验证上下文注入：重新开一个会话，问一个跟上次项目相关的问题，观察 Claude Code 是否"记得"之前的决策。你也可以直接查注入接口：
curl "http://localhost:37777/api/context/inject?project=your-project-name"返回的 JSON 里additionalContext字段有内容，说明 SessionStart Hook 的上下文注入链路完整。
4.3 三层渐进检索的验证
Claude-Mem 的检索是"先索引、再时间线、最后详情"的三层结构，强制 Token 高效使用。你可以在会话里让它调用search工具，观察返回的是紧凑索引（ID、标题、日期、类型，每条约 50–100 tokens），而不是完整内容。确认这一点，就说明渐进式检索在按设计工作。
5. 本篇常见错排查
装 Claude-Mem 踩坑的概率不低，因为它的 Hook 是静默执行的，报错经常不显示。下面是我整理的高频问题和对应解法。
Worker 起不来。先npx claude-mem worker:status，如果不是 running，执行npx claude-mem worker:start。如果端口 37777 被占用，先npx claude-mem worker:kill杀掉旧进程再重启。Windows 上偶尔会遇到进程残留，任务管理器里搜bun或node手动结束也行。
上下文没注入。检查 Worker 是否 running，然后看context-hook.js的执行日志。常见原因是CLAUDE_MEM_CONTEXT_OBSERVATIONS设得太大导致超时，先降到 20 试试。另外 Claude Code 2.1.0+ 之后不再显示用户可见的注入消息，别以为没生效，去查接口返回。
Claude Code 退出时卡住。这是老版本的已知问题，Stop Hook 早期是同步阻塞的，会卡约 110 秒。升级到 v12.3.9+ 后改成了 Fire-and-Forget，退出就顺畅了。升级命令：npx claude-mem@latest install。
记忆搜索无结果。确认 Worker 在运行，再检查是否积累了足够的会话历史。刚装完是空的，得先跑几个会话让它有东西可压缩。如果跑了几轮还是空，查observations表有没有数据，没有就是 PostToolUse Hook 没触发。
FTS5 查询报错。全文检索对特殊字符敏感，Claude-Mem 内部有escapeFTS5Query()做转义，但如果你手动查库，记得自己转义引号和布尔操作符，别直接拼未处理的字符串。
压缩调用报 401/403。基本是 Key 或通道问题。回到第 2 节的 curl 命令，确认https://taotoken.net/api通道正常、Key 有效。如果 curl 通但 Claude-Mem 报错，检查settings.json的env段有没有被其他配置覆盖。
SessionStart Hook 偶发报错。这是已知问题，冷启动时 Worker 进程可能被误杀，重试即可。如果频繁出现，把worker-service.cjs start的 timeout 从 60 提到 90。
6. 把记忆通道和编码通道统一起来
Claude-Mem 装好之后，你其实得到了两条链路：一条是记忆压缩链路（Hook → Worker → SQLite/ChromaDB），一条是模型调用链路（Claude Code / 压缩调用 → TaoToken 通道）。这两条链路共用同一个 Key 体系，管理成本才压得下来。
如果你主要是排障和接入阶段，先把 API Keys 和接入文档过一遍，确认通道稳定：API Keys ｜ 接入文档。
如果你想先验证模型在记忆压缩场景下的表现，可以直接在模型对话里试几轮，看压缩摘要的质量：模型对话。
如果你打算长期用 Claude Code 做编码、甚至跑 Agent 任务，记忆系统会持续产生压缩调用，这时候按用量规划更划算：Coding Plan。
最后给一个实操建议：装完 Claude-Mem 的第一周，每天花一分钟看一眼observations表的增长曲线。如果某天突然暴涨，说明有 Hook 在重复捕获，回去检查PostToolUse的 matcher 是不是配成了*又没排除TodoWrite、AskUserQuestion这类低价值工具。把排除名单加上，数据库和 Token 都会清爽很多。
