Claude-Mem 详细安装教程(Claude Code 全平台通用)

Claude-Mem 是专为 Claude Code 打造的开源持久化记忆插件，可实现跨会话上下文自动留存、智能检索，大幅减少重复上下文输入与 Token 消耗。以下是全场景可落地的详细安装步骤，优先推荐一键安装方案。

一、安装前必备前置条件

1. 已完成 Claude Code 安装与账号登录

官方 CLI 版本：macOS/Linux/WSL 执行 curl -fsSL

VS Code 扩展版本：打开 VS Code 扩展面板（快捷键 Ctrl+Shift+X / Cmd+Shift+X ），搜索「Claude Code」（发布者为 Anthropic），完成安装并登录你的 Claude 账号。
必须升级到支持插件系统的最新版 Claude Code，避免插件不兼容。

2. 基础环境要求

Node.js 18.0.0 及以上版本（终端执行 node --version 可检查版本，无则前往 nodejs.org 官网下载安装）。
网络可正常访问 GitHub、Claude 相关服务。
系统兼容：Windows 10/11、macOS、Linux（含 WSL 环境）。

3. 关键避坑提示

直接执行 npm install -g claude-mem 仅会安装 SDK 工具库，不会注册插件钩子、无法启动核心服务，不能正常使用插件功能，请勿使用该方式安装。

二、【最推荐】全平台一键安装（npx 方案）

该方案全程自动化，自动检测你的 Claude Code 环境、安装缺失依赖（Bun、uv 等）、注册插件钩子、启动后台服务，无需手动配置，新手首选。

1. 打开终端（Windows 用 PowerShell，macOS/Linux 用系统终端），或直接打开 Claude Code 内置终端。

2. 执行一键安装命令：

bashnpx claude-mem install

3. 等待安装程序执行完成，全程无需手动操作，安装器会自动完成以下操作：

检测你已安装的 Claude Code（含 CLI 版本、VS Code 扩展版本）
复制插件文件到系统对应目录
向 Claude Code 注册插件与生命周期钩子
自动安装缺失的运行时依赖（Bun、uv 等）
后台启动 worker 核心服务，实现记忆持久化

4. 安装完成后，重启 Claude Code（CLI 版本新开终端会话，VS Code 版本重载窗口），即可生效。

三、Claude Code 内置插件市场安装（CLI 命令方案）

适合习惯使用 Claude Code 原生插件命令的用户，全程在 Claude Code 会话内完成。

1. 终端执行 claude 命令，启动 Claude Code 会话。

2. 在 Claude Code 输入框中，先执行添加插件市场命令：

bash/plugin marketplace add thedotmack/claude-mem

3. 等待市场源添加完成，再执行插件安装命令：

bash/plugin install claude-mem

4. 安装程序会自动完成：下载预编译二进制文件、安装全部依赖、配置会话生命周期钩子、首次会话自动启动 worker 服务。

5. 执行完成后，重启 Claude Code 会话，插件即可正常运行。

四、VS Code 图形界面安装方案

如果你使用的是 VS Code 中的 Claude Code 扩展，可通过图形化界面完成安装，无需输入命令。

1. 打开 VS Code，点击左侧侧边栏的 Claude Code 图标，启动 Claude Code 面板。

2. 在 Claude Code 对话输入框中，输入 /plugins 命令，回车打开「插件管理」界面。

3. 切换到「Marketplaces（市场）」标签页，在输入框中填入插件源地址：

plaintextthedotmack/claude-mem

4. 点击添加，完成插件市场源的配置，点击刷新按钮同步插件列表。

5. 切回「Plugins（插件）」标签页，在可用插件列表中找到 claude-mem ，点击「Install」。

6. 选择安装范围（推荐「Install for you」，全项目生效），等待安装完成。

7. 按下 Ctrl+Shift+P / Cmd+Shift+P ，执行「Developer: Reload Window」重载 VS Code 窗口，插件即可生效。

五、高级源码安装方案（适合开发/自定义场景）

适合需要二次开发、修改插件源码的用户，需手动完成编译与配置。

1. 终端执行以下命令，克隆源码仓库并进入目录：

bashgit clone

claude-mem

2. 安装项目依赖：

bashnpm install

3. 编译构建钩子脚本与 worker 服务：

bashnpm run build

4. 服务启动配置：

自动启动：首次打开 Claude Code 会话时，worker 服务会自动启动
手动启动：终端执行 npm run worker:start 可手动启动服务
运行状态检查：执行 npm run worker:status 可查看服务运行状态

5. 完成后重启 Claude Code，即可加载自定义编译的插件。

六、安装成功验证步骤

执行以下任意操作，可确认插件安装与运行正常：

1. 钩子注册验证

终端执行以下命令，查看 Claude Code 配置中是否已注册 claude-mem 钩子，有对应输出即为注册成功：

bashcat /.claude/settings.json | grep claude-mem

2. 服务运行状态检查

进入插件目录，执行 npm run worker:status ，若显示 worker 服务运行中，即为正常。

3. 功能实测验证

重启 Claude Code 后，开启一个新会话，询问 Claude「你还记得我上一个会话的内容吗？」，若能正常召回历史上下文，说明记忆功能已正常生效。

4. 数据目录检查

插件所有记忆数据、日志、配置均存储在 /.claude-mem/ 目录下，可查看该目录是否正常生成，包含数据库文件、日志文件夹等。

七、常见安装问题排查

1. 安装后无记忆效果、新会话无法召回历史

优先重启 Claude Code 或重载 VS Code 窗口，确保钩子配置生效
检查 worker 服务是否正常运行，执行 npm run worker:start 手动重启服务
确认 Claude Code 版本为最新版，旧版本不支持插件钩子系统

2. 依赖安装失败，提示 Bun/uv 缺失

一键安装方案会自动安装 Bun，若失败可手动安装： curl -fsSL

手动安装 uv： curl -Lssf

3. Windows 环境权限报错

以管理员身份运行 PowerShell 或终端，重新执行安装命令
确保已安装 Git for Windows，否则无法拉取插件源与源码

4. 插件安装后不显示、无法找到

执行 /plugin marketplace refresh 刷新插件市场列表
检查网络是否可正常访问 GitHub，确保插件源添加成功