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 给每个长期项目建一个 profile，Key 和通道地址统一走 TaoToken，这样换项目时一键切换，不会把 A 项目的记忆策略带到 B 项目。settings.json 里的 skipTools 按自己的工具使用习惯调整，把那些高频但无意义的元操作排除掉，记忆库会干净很多。
如果你还想进一步验证模型通道的稳定性，可以到模型对话页面手动发几条请求，确认 Key 和 base_url 在交互场景下也正常。需要新建或轮换 Key 时，直接进 API Keys 管理页操作。接入细节和参数说明都在接入文档里，遇到不确定的字段先查文档再改配置，比反复试错快。
记忆这件事，配好一次就能长期受益。把 settings.json、CC Switch 和统一通道这三层理顺，claude-mem 就能稳定地在后台帮你攒下项目的「工作记忆」，下次开会话时不用再从头解释一遍。
