Claude Code 持久化记忆插件 claude-mem 完全指南：从 settings.json 到 CC Switch 配置落地

1. 为什么 Claude Code 需要 claude-mem 这类持久化记忆插件如果你用 Claude Code 写过稍大一点的项目大概率经历过这个场景昨天和它一起把用户认证模块从头到尾捋了一遍改了七八个文件今天打开终端想接着做权限校验它却像第一次见到这个仓库一样问你「这个项目是做什么的」。这不是它笨而是大语言模型的原生限制——上下文窗口再大也有边界会话一关工作记忆就清零了。Claude Code 本身提供了 CLAUDE.md 这类静态上下文文件但它是「手写文档」的思路你得自己维护写的是宏观约定记不住「上周三我们为什么把 JWT 换成了 Session」这种动态过程。claude-mem 补的正是这块——它是一个为 Claude Code 打造的持久化记忆压缩系统通过生命周期钩子自动捕获会话中的关键观察压缩成语义摘要存进本地数据库下次开会话时再把相关记忆注入进去。它适合谁适合长期维护同一批项目、经常做跨天重构、或者同时推进多个模块的开发者。如果你只是偶尔写个一次性脚本它的价值有限但如果你每天都在和同一个代码库打交道claude-mem 能明显减少「重新解释背景」的重复劳动。下面我从配置链路讲起把 settings.json、CC Switch 和统一 API 通道一次跑通。2. 前置准备TaoToken 统一 Key 与 API 通道claude-mem 的 Worker 服务在后台调用模型来生成摘要和做语义提取这一步需要一个稳定的模型通道。我实测下来用 TaoToken 做统一入口比较省心一个 Key 覆盖多种模型接入文档也写得清楚不用在多个平台之间来回切换配置。你需要先拿到两样东西API Key 和接入地址。访问控制台创建 Key地址是 https://taotoken.net/api 注意这个 API 地址不带任何查询参数直接作为 base_url 使用。如果你还没建过 Key进控制台按提示新建一个即可权限选默认的对话调用就够 claude-mem 用了。这里要说明一点claude-mem 默认会复用 Claude Code 的登录态但当你把 provider 指向自定义通道时就需要显式配置 base_url 和 api_key。TaoToken 在这里扮演的是统一模型网关的角色让 claude-mem 的摘要生成和语义检索走同一条稳定链路避免因为某个上游波动导致记忆写入失败。配置前建议先确认版本Node.js 18 以上Claude Code 为较新版本。可以用node --version和claude --version各查一次。另外 Worker 默认监听 37777 端口确认它没被别的进程占用不然后面验证会卡住。3. 可复制配置settings.json 与 CC Switch 骨架claude-mem 的主配置文件在~/.claude-mem/settings.json首次运行会自动生成默认值。我们要改的核心是 provider、model 和通道地址。下面这份是我跑通后的骨架你可以直接抄把 api_key 换成自己的{ provider: openai-compatible, model: claude-sonnet-4-5-20250929, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, workerPort: 37777, dataDir: ~/.claude-mem, logLevel: info, contextObservations: 10, skipTools: [ListMcpResourcesTool, SlashCommand] }几个参数值得展开说。provider设为openai-compatible是因为 TaoToken 走的是兼容接口这样 claude-mem 的 Worker 就能用标准方式调用。contextObservations控制每次会话开始时注入多少条历史观察默认 10 条项目记忆多的时候可以调到 15但别太大否则会挤占当前会话的上下文预算。skipTools里排除掉那些不需要记录的元操作能减少噪音。如果你用 CC Switch 管理多套配置可以在它的配置目录里为 claude-mem 单独建一个 profile。CC Switch 的作用是让你在不同项目、不同 Key 之间快速切换避免手动改 settings.json。骨架大致是这样{ profiles: { claude-mem-default: { env: { CLAUDE_MEM_PROVIDER: openai-compatible, CLAUDE_MEM_BASE_URL: https://taotoken.net/api, CLAUDE_MEM_API_KEY: sk-你的TaoToken密钥, CLAUDE_MEM_WORKER_PORT: 37777, CLAUDE_MEM_CONTEXT_OBSERVATIONS: 10 } } } }环境变量的优先级高于 settings.json所以用 CC Switch 切换 profile 时实际生效的是 env 里的值。这样你在做不同项目时可以给每个项目配不同的记忆策略比如重构项目把 contextObservations 调高实验性项目调低。注意api_key 不要提交到 Git 仓库settings.json 和 CC Switch 的 profile 文件都建议加进 .gitignore。claude-mem 的数据目录~/.claude-mem里存的是本地记忆同样不要外传。配置写完后重启 Claude Code 让钩子重新加载。如果你是从插件市场装的可以用/plugin命令确认 claude-mem 在列表里且状态正常。4. 验证请求确认记忆跨会话生效配置对不对跑一次跨会话测试就知道。我试过的流程分三步你照着做能快速判断链路通不通。第一步开一个新会话让 Claude 做一件有明确痕迹的事。比如请在这个项目里创建一个 utils/date.ts导出一个 formatDate 函数把时间戳格式化成 YYYY-MM-DD。等它写完文件、会话结束后claude-mem 的 Stop 钩子会触发Worker 在后台生成摘要并写入 SQLite 和 ChromaDB。这时候打开浏览器访问http://localhost:37777在记忆流里应该能看到一条类型为 feature 的观察记录涉及文件是 utils/date.ts。第二步完全关掉终端重新开一个 Claude Code 会话。这一步很关键必须是真的新进程不能只是清空对话。然后问它我们之前是不是创建过一个日期格式化工具在哪个文件里如果配置生效Claude 会通过 SessionStart 钩子拿到注入的历史观察回答出 utils/date.ts 和 formatDate。这就说明记忆跨会话生效了。第三步验证语义搜索。问一个不带具体文件名的模糊问题我们最近对工具函数做过哪些改动claude-mem 会用 ChromaDB 做向量匹配把相关的观察捞出来。如果它能答出日期工具那条记录说明语义检索链路也是通的。命令行侧也可以辅助验证。Worker 状态用npm run worker:status查日志在~/.claude-mem/logs/worker-日期.log。数据库文件~/.claude-mem/claude-mem.db存在且体积在增长基本就能确认写入正常。5. 本篇常见错排查配置过程中最容易卡在几个地方我按出现频率排一下。Worker 起不来37777 端口被占。先用lsof -i :37777看是谁占着。如果是残留的旧 Worker 进程杀掉后重启 Claude Code。如果确实有别的服务在用这个端口改 settings.json 里的 workerPort同时把 CC Switch profile 里的CLAUDE_MEM_WORKER_PORT一起改掉两边不一致会导致钩子连不上 Worker。记忆没保存下次会话还是失忆。先确认 Worker 在跑再看日志里有没有报错。常见原因是 api_key 无效或 base_url 写错导致 Worker 调用模型生成摘要时失败观察记录进了队列但没被处理。检查https://taotoken.net/api是否拼写正确Key 是否有余额。另外确认~/.claude-mem/claude-mem.db有写权限。上下文注入太多会话一开始就很卡。这是 contextObservations 设太大了。默认 10 条比较稳项目历史特别多的时候也别超过 20。可以在 CC Switch 里给不同项目配不同值重构类项目适当调高日常小改动调低。依赖安装失败。多半是 Node 版本不够。node --version确认在 18 以上。如果是从源码装的进插件目录手动npm install一次看具体报错。Bun 运行时一般会自动装装不上时检查网络和权限。摘要生成很慢。Worker 调用模型本身有延迟单条观察 5 到 30 秒都算正常因为它是后台异步跑的不阻塞你的会话。如果你开了 Endless Mode 这类实验功能延迟会更高每个工具操作可能到 60 秒以上这个阶段不建议在生产项目里开。排查时有个通用思路先看 Web 界面http://localhost:37777有没有记录进来有记录说明钩子正常问题在 Worker 处理没记录说明钩子没触发回去检查插件是否启用、settings.json 是否被正确加载。6. 把记忆链路固定下来的几个习惯跑通之后建议把配置固化下来别每次手动改。用 CC Switch 给每个长期项目建一个 profileKey 和通道地址统一走 TaoToken这样换项目时一键切换不会把 A 项目的记忆策略带到 B 项目。settings.json 里的 skipTools 按自己的工具使用习惯调整把那些高频但无意义的元操作排除掉记忆库会干净很多。如果你还想进一步验证模型通道的稳定性可以到模型对话页面手动发几条请求确认 Key 和 base_url 在交互场景下也正常。需要新建或轮换 Key 时直接进 API Keys 管理页操作。接入细节和参数说明都在接入文档里遇到不确定的字段先查文档再改配置比反复试错快。记忆这件事配好一次就能长期受益。把 settings.json、CC Switch 和统一通道这三层理顺claude-mem 就能稳定地在后台帮你攒下项目的「工作记忆」下次开会话时不用再从头解释一遍。