给 Claude Code 装上"长期记忆":claude-mem 从安装到实战

本文你能收获什么

✅ 30 分钟让 Claude Code 跨会话"记住"你的项目

✅ 开启中文模式,让记忆用中文存储

✅ 8 个国内开发者最常踩的坑 + 解决方案

✅ 一份能直接抄的 settings.json 配置模板

又要从头给 Claude 讲一遍项目了?

如果你在用 Claude Code 写代码,大概率碰到过这样的场景:

昨天花 1 小时跟它讨论清楚了项目的鉴权逻辑
今天新开一个会话,它又问你:"请告诉我这个项目的技术栈和目录结构"
上周反复强调"这个项目禁止直接操作数据库,必须走 Service 层"
今天它又一次在代码里写了 db.query(...)

每次新会话都像"失忆的朋友",项目背景、代码风格、历史决策全部要重新交代一遍。

有没有一种方式,让 Claude Code 真正记住你的项目?

less 复制代码

**有。它叫 [claude-mem](https://github.com/thedotmack/claude-mem)。** 一个 GitHub 上已经有 **64.6k+ Star** 的 Claude Code 插件,官方基于 Claude Agent SDK 构建,能自动捕获你每次会话的重要信息,压缩成语义摘要,下次新开会话时自动注入相关上下文。

这篇文章我会手把手带你从零装上它,并解决国内开发者最容易踩的坑。

claude-mem 是什么

用一句话概括:一个给 Claude Code 装上"持久化记忆"的插件。

核心能力三件套:

自动捕获 ------ 不需要手动调 API,通过 Claude Code 的生命周期 hooks 在后台默默记录
智能压缩 ------ 用 Claude Agent SDK 把原始会话压缩成语义摘要,省 token 又好检索
自动注入 ------ 新会话开始时,相关历史自动进入上下文,你不需要做任何事

技术架构大概长这样(知道个大概就行,不影响使用):

scss 复制代码

Claude Code 会话
    ↓ (5 个 lifecycle hooks 捕获)
Worker 服务 (Bun + 端口 37777)
    ↓ (AI 压缩)
SQLite (全文索引) + Chroma (向量检索)
    ↓ (新会话时)
自动注入相关上下文

项目主要用 TypeScript 写(占 83%),开源协议 AGPL-3.0,作者是 Alex Newman(@thedotmack),目前处于非常活跃的维护状态------截至 2026 年 4 月,最新版本已经到了 v12.3.8。

安装前准备:别在这里翻车

先做 3 个检查,能帮你省掉 80% 的后续麻烦:

1. Node.js 版本 ≥ 18.0.0

打开终端执行:

复制代码

node -v

如果版本低于 18,去 nodejs.org 下载最新 LTS 版本升级。

2. Claude Code 已安装并能正常使用

确保 Claude Code 能在你的终端里正常启动。如果还没装,先装它。

3. Bun 和 uv(会自动安装,不用管)

claude-mem 依赖 Bun(JS 运行时)和 uv(Python 包管理器),这两个会在首次安装时自动下载,你不用提前装。

⚠️ 国内网络环境特别提醒

claude-mem 安装过程中会从 GitHub、npm 官方源拉取资源。如果你的网络访问 GitHub 不稳定,强烈建议先配好代理或使用镜像,否则安装过程中可能卡在下载 Bun 那一步。

配置 npm 淘宝镜像:

arduino 复制代码

npm config set registry https://registry.npmmirror.com

三种安装方式,选错一个全白搭

这是最容易踩坑的地方,项目 README 专门强调过,我也单独拎出来讲:

安装方式	命令	是否推荐
🟢 npx 一键安装	`npx claude-mem install`	✅ 推荐
🟢 插件市场	`/plugin marketplace add` + `/plugin install`	✅ 推荐
🔴 npm 全局安装	`npm install -g claude-mem`	❌ 别用!

为什么 `npm install -g claude-mem` 不行?

这是很多人第一次装时踩的坑------

npm install -g 只会装 SDK 库本身,不会注册 Claude Code 的 hooks,也不会启动 worker 服务。

换句话说,你装了一个"零件",但没人把它装到机器上。结果就是装完以为 OK,用的时候完全没效果。

所以记住:只用下面两种方式之一。

方式一:npx 一键安装(最简单)

打开终端,执行:

复制代码

npx claude-mem install

然后等它跑完。期间它会:

下载 claude-mem 主程序
自动安装 Bun(如果没有)
自动安装 uv(如果没有)
注册 Claude Code 的 5 个 lifecycle hooks
初始化 SQLite 数据库
启动 worker 服务

全程不需要你输入任何东西,顺利的话 2-5 分钟完成。

方式二:Claude Code 插件市场(官方推荐)

如果你已经在 Claude Code 里,可以直接输入命令:

bash 复制代码

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

两条命令搞定。这种方式的好处是后续升级也能在 Claude Code 里直接管理。

验证安装成功

装完后,重启 Claude Code(这一步别省,不重启 hooks 不生效)。

怎么确认装好了?三个验证方法:

1. 看 worker 是否启动

打开浏览器访问:

arduino 复制代码

http://localhost:37777

如果能看到 claude-mem 的 Web UI 界面,说明 worker 正常运行。

2. 看本地数据目录

bash 复制代码

ls ~/.claude-mem/

应该能看到 settings.json、数据库文件等。

3. 实测跨会话记忆

新开一个 Claude Code 会话
让它做一些操作,比如分析你的项目结构
关掉会话
再新开一个会话,看看开头是否有历史上下文注入

如果有,恭喜你,装好了。

开启中文模式(国内开发者重点)

默认情况下,claude-mem 生成的记忆摘要是英文的。对国内开发者来说不够友好------既不方便自己查看,和项目代码的中文注释、中文变量也对不上。

好消息:v10 之后官方内置了简体中文模式,不需要额外安装。

配置文件位置

javascript 复制代码

~/.claude-mem/settings.json

这个文件在首次运行时会自动创建。

启用中文模式

打开 settings.json,加上这一行:

json 复制代码

{
  "CLAUDE_MEM_MODE": "code--zh"
}

命名规则:code--[ISO 639-1 语言代码]

目前官方内置的语言模式:

模式值	说明
`code`	英文默认
`code--zh`	简体中文 ✅
`code--ja`	日语

查看本地所有可用模式

ruby 复制代码

ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/

⚠️ 切换模式后必须重启 Claude Code

这点容易忘。改完 settings.json 一定要完全退出 Claude Code 再打开,否则新配置不生效。

中文模式实际效果

切换到 code--zh 后,你会在 Web UI(http://localhost:37777)看到记忆摘要直接是中文的,比如:

makefile 复制代码

观察类型: 架构决策
内容: 用户认证模块采用 JWT + Redis 黑名单方案,
     refresh token 有效期 7 天,access token 15 分钟...

读起来比英文摘要顺眼太多。

核心功能实战

装完配完,来看看它到底怎么用。

场景一:让 Claude 记住架构决策

在会话里告诉它:

makefile 复制代码

我们的项目有个约定:所有数据库操作必须走 Service 层,
Controller 里禁止直接调用 ORM。请记住这一点。

claude-mem 会自动把这个决策记下来。下次新会话时,你会在上下文注入里看到这条约定------Claude Code 不会再写出违反规则的代码。

场景二:用自然语言搜索历史

claude-mem 提供了一个叫 mem-search 的 skill,你可以直接问:

复制代码

帮我搜一下上周修过的那个登录 bug

Claude 会通过 MCP 工具查询历史记忆,精准定位到当时的修复方案。

场景三:三层渐进式检索(省 token 利器)

这是 claude-mem 的设计亮点------不一次性把所有相关记忆都塞给 Claude,而是分三步:

步骤	工具	成本	作用
1. 查索引	`search`	~50-100 token/条	只拿 ID 和短摘要
2. 看时间线	`timeline`	中等	看某条记录前后的上下文
3. 取详情	`get_observations`	~500-1000 token/条	按 ID 批量取完整内容

这种"先筛选再取详情"的模式,官方实测可以节省约 10 倍 token。

场景四:保护隐私(重要)

如果你不想让某些敏感内容被记录,用 <private> 标签包起来:

vbnet 复制代码

<private>
数据库密码是 xxx,API key 是 yyy
</private>

被 <private> 包裹的内容不会进入记忆库。

Web UI 导览

访问 http://localhost:37777,你会看到一个完整的 Web 管理界面:

实时记忆流 ------ 看 claude-mem 正在捕获什么
搜索界面 ------ 用自然语言查历史
Settings 页面 ------ 切换 stable / beta 通道(beta 通道能体验仿生物记忆架构 Endless Mode)
按 ID 查询单条记忆 ------ http://localhost:37777/api/observation/{id}

日常用下来,Web UI 是很好的"记忆审计工具"------你可以清楚看到 Claude 记住了什么、漏记了什么。

常见问题与踩坑记录 🕳️

这是全文最有价值的部分。以下所有问题都是我(或社区反馈)实际遇到的:

坑 1:装完新会话没有上下文注入

现象 :用 npm install -g claude-mem 装的,新会话没有任何历史记忆。

原因 :npm install -g 只装 SDK,不注册 hooks。

解决:

复制代码

npm uninstall -g claude-mem
npx claude-mem install

重启 Claude Code。

坑 2:Windows 报 `npm 不是内部或外部命令`

现象 :在 PowerShell 或 CMD 执行 npx claude-mem install 报错。

原因:Node.js 没加入系统 PATH。

解决:

去 nodejs.org 重新下载安装包
安装时勾选 "Add to PATH"
安装完关掉所有终端再重新打开

坑 3:端口 37777 被占用

现象:启动时报端口被占用,Web UI 打不开。

解决 :编辑 ~/.claude-mem/settings.json,加上:

json 复制代码

{
  "CLAUDE_MEM_MODE": "code--zh",
  "WORKER_PORT": 37788
}

改成一个没被占用的端口,重启 Claude Code。

坑 4:Hook 没触发,worker 没起来

现象:Web UI 访问不了,记忆也没被捕获。

排查步骤:

查日志位置:~/.claude-mem/logs/
手动启动 worker:在 Claude Code 里执行 /plugin 看看 claude-mem 是否被正确加载
如果还是不行,重新运行 npx claude-mem install

坑 5:切换中文模式后不生效

现象 :改了 CLAUDE_MEM_MODE 为 code--zh,但记忆还是英文。

原因:没重启 Claude Code。

解决 :完全退出 Claude Code(不是关窗口,是退出进程)再打开。macOS 用户注意 Cmd+Q 才是退出。

坑 6:Bun 自动安装失败(国内网络)

现象 :npx claude-mem install 卡在 "Installing Bun..." 很久,或直接报网络错误。

原因:Bun 官方脚本从 GitHub 拉资源,国内访问不稳定。

解决:手动安装 Bun,再重跑安装命令:

bash 复制代码

# 方式一:用国内镜像
curl -fsSL https://bun.sh/install | bash

# 方式二:如果还是慢,挂代理
export https_proxy=http://127.0.0.1:7890
curl -fsSL https://bun.sh/install | bash

装完 Bun 后再执行 npx claude-mem install。

坑 7:SQLite 数据库存哪了?怎么备份?

数据目录 :~/.claude-mem/

主要文件:

settings.json ------ 配置文件
claude-mem.db ------ SQLite 主数据库
chroma/ ------ 向量数据库目录
logs/ ------ 日志目录

备份 :直接打包整个 ~/.claude-mem/ 目录即可:

javascript 复制代码

tar -czf claude-mem-backup-$(date +%Y%m%d).tar.gz ~/.claude-mem/

换电脑时把这个包解压回去,记忆就恢复了。

坑 8:我的代码会被上传吗?

不会。

claude-mem 所有数据都存在本地的 ~/.claude-mem/ 目录,不会上传到任何服务器。唯一的"外部调用"是压缩摘要时调用 Claude API(走的是你自己的 Claude Code 账号),和你平时用 Claude Code 是一样的。

想要更严格的隐私控制,用前面讲的 <private> 标签即可。

进阶玩法(收藏起来慢慢玩)

装好基础版之后,还有这些值得探索:

1. Beta 通道:体验 Endless Mode

在 Web UI 的 Settings 里可以切换到 beta 通道,体验仿生物记忆架构 Endless Mode------为超长会话设计,借鉴人脑短期/长期记忆的转化机制。

2. 跨 IDE 使用

claude-mem 不只支持 Claude Code,还原生支持:

Gemini CLI :npx claude-mem install --ide gemini-cli
OpenCode :npx claude-mem install --ide opencode
Cursor :仓库里有 cursor-hooks 目录

3. 自定义 Mode

模式文件放在 plugin/modes/ 下,是标准 JSON 格式。你可以照着 code--zh 写一个适合你行业的 mode,比如:

legal--zh:法律行业,记录案件、法条引用
medical--zh:医疗领域,记录病历、诊断思路
teaching--zh:教学场景,记录课程大纲、学生问题

官方也提供了 law-study 模式作为参考,专为法学生设计。

4. OpenClaw 网关集成

如果你是团队场景,想让多人共享记忆,可以集成到 OpenClaw 网关:

arduino 复制代码

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

支持实时同步到 Telegram、Discord、Slack 等。

写在最后

claude-mem 是我用过的 Claude Code 插件里性价比最高的一个------安装简单、零配置可用、中文支持完整、性能损耗基本感知不到。

核心要点回顾:

别用 npm install -g ,用 npx claude-mem install
中文模式一行配置搞定 :"CLAUDE_MEM_MODE": "code--zh"
改完配置一定要重启 Claude Code
Web UI (localhost:37777) 是你的记忆审计台
敏感内容用 <private> 标签包起来

参考资料

claude-mem GitHub 仓库

官方文档

v12.3.8 Release Note

给 Claude Code 装上"长期记忆":claude-mem 从安装到实战

又要从头给 Claude 讲一遍项目了?

claude-mem 是什么

安装前准备:别在这里翻车

1. Node.js 版本 ≥ 18.0.0

2. Claude Code 已安装并能正常使用

3. Bun 和 uv(会自动安装,不用管)

⚠️ 国内网络环境特别提醒

三种安装方式,选错一个全白搭

为什么 npm install -g claude-mem 不行?

方式一:npx 一键安装(最简单)

方式二:Claude Code 插件市场(官方推荐)

验证安装成功

1. 看 worker 是否启动

2. 看本地数据目录

3. 实测跨会话记忆

开启中文模式(国内开发者重点)

配置文件位置

启用中文模式

查看本地所有可用模式

⚠️ 切换模式后必须重启 Claude Code

中文模式实际效果

核心功能实战

场景一:让 Claude 记住架构决策

场景二:用自然语言搜索历史

场景三:三层渐进式检索(省 token 利器)

场景四:保护隐私(重要)

Web UI 导览

常见问题与踩坑记录 🕳️

坑 1:装完新会话没有上下文注入

坑 2:Windows 报 npm 不是内部或外部命令

坑 3:端口 37777 被占用

坑 4:Hook 没触发,worker 没起来

坑 5:切换中文模式后不生效

坑 6:Bun 自动安装失败(国内网络)

坑 7:SQLite 数据库存哪了?怎么备份?

坑 8:我的代码会被上传吗?

进阶玩法(收藏起来慢慢玩)

1. Beta 通道:体验 Endless Mode

2. 跨 IDE 使用

3. 自定义 Mode

4. OpenClaw 网关集成

写在最后

为什么 `npm install -g claude-mem` 不行?

坑 2:Windows 报 `npm 不是内部或外部命令`