1. 为什么 Claude Code 需要 Claude-MemClaude Code 是 Anthropic 推出的命令行编码工具用起来很顺手但它有个天然短板会话之间是无状态的。你昨天跟它聊了半小时把项目架构、数据库表结构、踩过的坑都交代清楚了今天重新打开终端它又是一张白纸你得从头再讲一遍背景。项目越大这种重复喂上下文的成本越高。Claude-Mem 就是冲着这个痛点来的。它是一个给 Claude Code 增加跨会话持久记忆的开源插件核心机制是把 Claude Code 每次工具调用读文件、写文件、改代码、跑命令、搜索都捕获成结构化的“观察记录”存进本地 SQLite 数据库然后在会话结束时自动生成摘要。下次你启动新会话它会自动把最近的工作以“索引 摘要”的形式注入初始上下文让 Claude 一上来就知道你昨天干了什么、做到哪一步、下一步该干嘛。它适合谁适合长期用 Claude Code 做同一项目的开发者尤其是那种项目周期长、模块多、需要反复切换任务的人。如果你只是偶尔跑个一次性脚本Claude-Mem 的价值不大但如果你每天都在同一个代码库里推进它能明显减少你重复解释背景的时间。这篇指南聚焦落地流程从安装、settings.json 配置到 IDE 集成和日常使用给出可复制的配置骨架、TaoToken 统一 Key/API 通道的接入方式以及验证命令和常见报错排查步骤。你可以跟着一步步操作。2. 前置准备Claude Code 与 TaoToken 通道在装 Claude-Mem 之前得先确保 Claude Code 本身能正常跑起来。Claude-Mem 是挂在 Claude Code 上的插件宿主环境不通插件也无从谈起。Claude Code 的安装方式通常是全局 npm 包npm install -g anthropic-ai/claude-code claude --version能打印出版本号说明装好了。接下来是登录和 API 通道的问题。Claude Code 默认走 Anthropic 官方通道但很多国内开发者在网络和计费上会遇到麻烦。这时候可以用 TaoToken 作为统一的 API 通道把 Key 和 Base URL 配好Claude Code 和后续的 Claude-Mem 都走这条通道省去反复切换的麻烦。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要在控制台创建一个 API Key然后把它写进 Claude Code 的环境变量或配置文件里。具体来说Claude Code 读取的是ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这两个环境变量。你可以这样设置export ANTHROPIC_API_KEY你的TaoToken Key export ANTHROPIC_BASE_URLhttps://taotoken.net/apiWindows PowerShell 下$env:ANTHROPIC_API_KEY你的TaoToken Key $env:ANTHROPIC_BASE_URLhttps://taotoken.net/api设置完之后运行claude进入交互模式随便问一句“你好”能正常回复就说明通道通了。这一步很关键因为 Claude-Mem 的摘要生成和记忆检索也会调用模型通道不通的话插件装了也是白装。如果你还没有 Key可以去 TaoToken 控制台的 API Keys 页面创建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建后复制保存后面配置里要用。3. 安装 Claude-Mem插件市场与源码两种方式Claude-Mem 的安装有两种路径插件市场一键安装和从源码构建。前者适合绝大多数用户后者适合想改代码或做测试的人。3.1 插件市场一键安装这是官方推荐的 Quick Start 方式零配置。先启动 Claude Codeclaude进入交互提示符后输入添加插件市场来源的命令/plugin marketplace add thedotmack/claude-mem然后安装插件/plugin install claude-mem安装过程通常几秒到十几秒期间会自动下载预编译二进制、安装依赖包括 SQLite 相关库、配置会话生命周期 hooksSessionStart 和 Stop并在首次会话时自动启动 worker 服务。安装完成后输入/exit退出再重新运行claude启动新会话。这时候 Claude-Mem 应该已经生效了。你可以通过查看数据目录来确认ls ~/.claude-mem/如果看到claude-mem.db、settings.json、logs/等文件说明安装成功。3.2 源码安装如果你需要自己改代码或参与开发可以从源码构建。前置要求是 Git、Node.js 18、npm 或 yarn。git clone https://github.com/thedotmack/claude-mem.git cd claude-mem npm install npm run build构建完成后worker 服务通常会在第一次 Claude Code 会话时自动启动。你也可以手动启动npm run worker:start npm run worker:status npm run worker:logs源码方式的好处是你可以直接看 worker 的实现逻辑调整摘要生成的提示词或者改数据库 schema。但日常使用没必要走这条路插件市场方式更省心。3.3 卸载与重装如果配置搞乱了想重来先卸载插件/plugin uninstall claude-mem如果要彻底清空本地记忆数据谨慎操作会删除所有观察记录和摘要rm -rf ~/.claude-mem然后重新走一遍安装流程即可。4. settings.json 配置骨架与 TaoToken 接入Claude-Mem 安装后会在~/.claude-mem/下生成settings.json。这个文件控制注入规模、日志级别、数据目录等行为。下面给出一份可复制的配置骨架你可以根据自己的项目情况调整。{ dataDir: ~/.claude-mem, injection: { maxObservations: 50, showFullSummary: true, indexMode: timeline }, logging: { level: info }, worker: { port: 37777, autoStart: true }, api: { baseUrl: https://taotoken.net/api, apiKeyEnv: ANTHROPIC_API_KEY } }几个关键字段说明一下。injection.maxObservations控制新会话启动时注入的观察记录条数默认 50。如果你的项目历史很长开局上下文占用太大可以降到 20 或 30。injection.showFullSummary决定是否展示摘要的完整细节Investigated/Learned/Completed/Next Steps当摘要生成时间晚于最后一条观察记录时才展示避免过期信息误导。logging.level排障时可以调成debug或trace平时用info就行。api这一段是接入 TaoToken 的关键。baseUrl指向 https://taotoken.net/api apiKeyEnv指定从哪个环境变量读取 Key。这样 Claude-Mem 在生成摘要和检索记忆时走的就是 TaoToken 通道和 Claude Code 主流程保持一致。如果你有多个项目需要严格隔离记忆可以为每个项目设置不同的CLAUDE_MEM_DATA_DIRexport CLAUDE_MEM_DATA_DIR/path/to/project-a/.claude-mem claudeWindows PowerShell$env:CLAUDE_MEM_DATA_DIRC:\projects\project-a\.claude-mem claude这样项目 A 和项目 B 的记忆互不干扰切换项目时不会串上下文。Hooks 配置由 Claude Code 管理Claude-Mem 安装时自动写入。你可以查看已配置的 hookscat ~/.claude-code/plugin/hooks/hooks.json通常不需要手动改。如果你有特殊需求比如想禁用 SessionStop 的自动摘要生成建议先看官方文档或提 Issue不要直接改 hooks 文件否则升级时可能被覆盖。5. 验证请求与成功结果配置写完后得验证一下整条链路是否通。分三步验证 Claude Code 通道、验证 Claude-Mem worker、验证记忆注入。第一步验证 Claude Code 走 TaoToken 通道能正常对话claude -p 用一句话说明什么是持久化记忆如果返回了合理的回答说明 API 通道没问题。如果报 401 或 403检查ANTHROPIC_API_KEY是否设置正确以及 Key 是否有余额。第二步验证 Claude-Mem worker 状态npm run worker:status正常输出会显示 worker 正在运行、监听端口默认 37777、PID 等信息。你也可以直接访问本地 Web UIhttp://localhost:37777打开后能看到记忆流和摘要内容。如果页面打不开说明 worker 没起来用npm run worker:logs看日志。第三步验证记忆注入。启动一个新会话随便做点操作比如让 Claude 读一个文件claude在交互模式里输入“读一下 package.json 并告诉我项目名”。Claude 执行 Read 工具后Claude-Mem 会捕获这条观察记录。退出会话再重新启动claude新会话启动时Claude-Mem 应该自动注入了刚才的上下文。你可以问“我上一个会话做了什么”如果它能说出“你读了 package.json”说明记忆注入生效了。成功的结果是新会话开局就带着最近工作的索引和摘要你不需要重复交代背景直接说“继续昨天的任务”就能接上。6. 常见报错排查实际用下来Claude-Mem 的坑主要集中在几个地方。下面按现象列排查步骤。现象一安装后新会话没有记忆注入。先确认插件是否真的装上了在 Claude Code 里输入/plugin list看有没有 claude-mem。然后检查~/.claude-mem/claude-mem.db是否存在如果数据库文件没生成说明 worker 没正常初始化。看日志npm run worker:logs常见原因是 Node.js 版本低于 18或者 SQLite 库没装好。升级 Node.js 后重装插件。现象二worker 启动失败端口被占用。默认端口 37777 可能被其他进程占了。改settings.json里的worker.port为其他端口比如 37778然后重启 workernpm run worker:restart现象三摘要生成报 API 错误。如果日志里出现 401、429 或连接超时说明 TaoToken 通道配置有问题。检查环境变量是否在当前 shell 生效echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果为空说明 export 没生效或者你是在另一个终端窗口运行的 claude。把 export 写进~/.bashrc或~/.zshrc里持久化。429 通常是频率限制等一会儿再试或者去 TaoToken 控制台看配额。现象四记忆串项目。如果你在多个项目间切换发现 Claude 把项目 A 的记忆带到了项目 B说明没有做数据目录隔离。给每个项目设置独立的CLAUDE_MEM_DATA_DIR或者在settings.json里配置项目级的数据路径。现象五升级后配置丢失。Claude-Mem 升级时可能会重写settings.json。建议升级前备份cp ~/.claude-mem/settings.json ~/.claude-mem/settings.json.bak升级后对比一下把自定义字段补回去。现象六Web UI 打不开但 worker 在跑。检查防火墙是否拦了本地端口或者浏览器代理设置是否把 localhost 也代理了。把 localhost 加入代理例外即可。排障的核心思路是先看 worker 日志再看 Claude Code 的 hooks 是否触发最后看 API 通道是否通。三层逐一确认大部分问题都能定位。7. 日常使用与 IDE 集成Claude-Mem 最推荐的使用方式就是完全当它不存在。你正常用 Claude Code 写代码它在后台自动捕获工具调用、处理数据、会话结束时生成摘要。典型的工作流是这样的第一天你启动 claude告诉它“我要实现用户认证模块”。Claude 读文件、写代码、跑测试Claude-Mem 自动记录这些操作和决策。关闭会话时摘要自动生成。第二天你启动 claude它自动注入昨天的上下文一上来就知道“你昨天实现了认证模块的 JWT 部分”。你直接说“继续昨天的任务”它就能基于记忆快速恢复进度。当你需要调取历史细节时用明确的自然语言提示会更准确比如“上个会话我们修了哪些 bug”“认证模块是怎么实现的”。Claude-Mem 会按需检索并加载相关记忆片段先概览、后细节。IDE 集成方面Claude Code 本身可以在 VS Code、JetBrains 系列等编辑器的终端里运行Claude-Mem 作为插件跟随宿主不需要额外配置。如果你在 VS Code 里用集成终端跑 claude确保环境变量在 VS Code 的终端里也生效。可以在 VS Code 的settings.json里配置终端环境变量或者用.env文件配合 dotenv 加载。对于长期编码和 Agent 场景如果你需要更稳定的配额和更低的单位成本可以了解 TaoToken 的 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它适合那种每天大量调用、需要长期跑 Agent 任务的开发者。日常使用中我建议定期清理过期的记忆数据。SQLite 数据库会随着时间增长如果某个项目的记忆已经不再需要直接删掉对应的数据目录即可。另外摘要的完整细节只在“摘要新于最后观察”时展示如果你发现注入的摘要总是过期的说明 worker 处理有延迟检查一下日志里有没有处理失败的记录。最后如果你在配置过程中需要对照模型的实际响应来验证通道可以用 TaoToken 的模型对话页面快速测试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的调用示例配合 Claude-Mem 的 settings.json 一起看能少走不少弯路。