Claude-Mem 持久记忆压缩系统：安装、架构与深度使用指南（TaoToken 配置版）

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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址是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.jsonHook 注册与 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.tomlClaude-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 会话随便让它读几个文件、改一处代码然后退出。接着检查数据库里有没有产生 Observationsqlite3 ~/.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?projectyour-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-memlatest 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 都会清爽很多。