Claude-Mem 从入门到实践

适用 claude-mem 版本：6.x

Claude-Mem —— 一个让 AI 编程助手拥有”长期记忆”的开源插件。

第 1 章为什么需要 Claude-Mem

1.1 你是否遇到过这个场景？

Day 1:
  你：" 帮我用 React 搭一个待办事项应用，要支持拖拽排序和本地存储。"
  Claude：（完美地完成了任务，代码运行良好）
  你：（开心地关闭了终端）

Day 2:
  你：" 把昨天的待办应用加一个分类标签功能。"
  Claude：" 请问你的项目使用什么框架？目录结构是怎样的？有哪些现有组件？"
  你：？？？昨天不是刚说完吗？

这就是 AI 编程助手的 **”失忆症”**：每次会话都是全新的，之前讨论过的架构决策、代码风格、项目结构全部丢失。你需要反复”喂背景”，浪费大量时间和 Token。

1.2 Claude-Mem 是什么？

Claude-Mem 是一个为 Claude Code（Anthropic 的命令行 AI 编程工具）设计的开源插件，它能：

功能	说明
自动记忆	捕获 Claude 每一次工具调用（读文件、写代码、执行命令等）
智能压缩	用 AI 将海量操作记录压缩成精炼摘要
跨会话恢复	下次启动时自动注入相关历史上下文
语义搜索	用自然语言搜索过去的所有工作记录

1.3 核心价值

零干预：安装后全自动工作，不需要手动操作
本地存储：所有数据存在你的电脑上（SQLite 数据库），不上传云端
Token 节省：通过”渐进式披露”机制，常规使用可节省约 90% 的 Token 消耗
隐私可控：支持 <private> 标签排除敏感内容

第 2 章工作原理速览

这一章用最通俗的语言和图示，帮你理解 Claude-Mem 在幕后做了什么。不需要编程基础就能看懂。

2.1 全景架构图

┌─────────────────────────────────────────────────────────────────┐
│                     Claude-Mem 系统架构                          │
│                                                                 │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────────────┐  │
│  │ Claude   │    │ 5 个生命周期  │    │    Worker 服务        │  │
│  │ Code     │◄──►│ Hooks        │◄──►│    (端口 37777)       │  │
│  │ 会话     │    │              │    │                      │  │
│  └──────────┘    │ · SessionStart│    │  ┌──────────────┐   │  │
│                  │ · UserPrompt  │    │  │ SQLite 数据库 │   │  │
│                  │ · PostToolUse │    │  │ (本地存储)    │   │  │
│                  │ · Stop        │    │  └──────────────┘   │  │
│                  │ · SessionEnd  │    │                      │  │
│                  └──────────────┘    │  ┌──────────────┐   │  │
│                                      │  │ AI 压缩引擎  │   │  │
│                  ┌──────────────┐    │  │ (Agent SDK)  │   │  │
│                  │ MCP 搜索工具  │    │  └──────────────┘   │  │
│                  │ · search     │    │                      │  │
│                  │ · timeline   │    │  ┌──────────────┐   │  │
│                  │ · get_observations │ │ Web 查看器    │   │  │
│                  └──────────────┘    │  │ localhost     │   │  │
│                                      │  │ :37777        │   │  │
│                                      │  └──────────────┘   │  │
│                                      └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

2.2 数据流：从捕获到注入

 会话中                             会话结束                        下次会话 
────────                          ──────────                     ──────────

Claude 使用工具                   自动生成摘要
┌──────────┐                     ┌──────────┐
│ Read     │                     │          │
│ Write    │──► 捕获观察记录 ──► │ AI 压缩  │──► 存入 SQLite
│ Edit     │    (观察)           │          │
│ Bash     │                     └──────────┘
│ Grep     │                          │
└──────────┘                          │
                                      ▼
 下次启动 Claude Code ◄── 智能检索 ◄── 索引 + 摘要
(自动注入最近上下文)      (语义匹配)

2.3 什么是”渐进式披露”？

想象你在图书馆查资料：

先看目录（search）：快速浏览有哪些相关记录，每条只显示标题和摘要
翻到相关章节（timeline）：查看某条记录前后的来龙去脉
精读具体页面（get_observations）：只在需要时才加载完整内容

这种分层策略让你在常规使用下 节省约 90% 的 Token 消耗，因为大部分查询在第一层就能找到答案，不需要加载完整内容。

2.4 五个生命周期 Hook

Hook	触发时机	做什么
SessionStart	新会话启动时	从数据库检索最近上下文并注入
UserPromptSubmit	用户发送消息时	捕获用户意图，优化检索策略
PostToolUse	Claude 每次使用工具后	记录工具调用的详细信息
Stop	Claude 完成回复时	生成会话摘要
SessionEnd	会话结束时	清理资源，确保数据持久化

第 3 章环境准备

在安装 Claude-Mem 之前，你需要先确保系统已安装 Node.js 和 Claude Code。本章为三大平台分别提供详细步骤。

3.1 什么是 Node.js？

Node.js 是一个 JavaScript 运行环境，Claude Code 和 Claude-Mem 都依赖它运行。你可以把它理解为”Claude Code 的运行基础”。

3.2 Windows 环境

步骤 1：安装 Node.js

访问 https://nodejs.org
下载 LTS（长期支持版） 安装包（.msi 文件）
双击安装，** 一路点”Next”**，确保勾选了”Add to PATH”
安装完成后，重新打开终端（这一步很重要！）

验证安装：

node --version
# 应该显示 v18.x.x 或更高版本

npm --version
# 应该显示版本号

常见问题：如果提示 npm 不是内部或外部命令，说明 PATH 未生效。请重启电脑或重新打开终端。

步骤 2：安装 Claude Code

1	npm install -g @anthropic-ai/claude-code

验证：

1 2	claude --version # 显示版本号即可

步骤 3：登录 Claude Code

1	claude login

按提示完成认证（使用 Anthropic 账号登录）。

步骤 4：验证 Claude Code 可用

claude

如果能进入交互模式（出现提示符），说明一切就绪。输入 /exit 退出。

3.3 macOS 环境

步骤 1：安装 Node.js

方式 A：使用 Homebrew（推荐）

# 如果没有 Homebrew，先安装它：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node

方式 B：官方安装包

访问 https://nodejs.org
下载 macOS LTS 安装包（.pkg）
双击安装

验证：

1 2	node --version # v18.x.x 或更高 npm --version # 显示版本号

步骤 2：安装 Claude Code

1 2	npm install -g @anthropic-ai/claude-code claude login

步骤 3：验证

1 2	claude --version claude # 进入交互模式，/exit 退出

3.4 Linux 环境

步骤 1：安装 Node.js

Ubuntu / Debian：

1
2
3

# 使用 NodeSource 仓库安装 Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora / RHEL：

1	sudo dnf install nodejs npm

Arch Linux：

1	sudo pacman -S nodejs npm

验证：

1 2	node --version # v18.x.x 或更高 npm --version

步骤 2：安装 Claude Code

1 2	npm install -g @anthropic-ai/claude-code claude login

步骤 3：验证

1 2	claude --version claude

3.5 环境准备检查清单

在继续下一章之前，请确认以下项目全部通过：

node --version      # ✅ v18.0.0 或更高
npm --version       # ✅ 显示版本号
claude --version    # ✅ 显示版本号
claude              # ✅ 能进入交互模式

全部通过？恭喜，环境准备完成！

第 4 章安装 Claude-Mem

Claude-Mem 提供两种安装方式。推荐使用”插件市场”方式，最简单可靠。

4.1 方式一：插件市场一键安装（推荐）

这是最简单的方式，只需两条命令：

步骤流程：

启动 Claude Code
       │
       ▼
  /plugin marketplace add thedotmack/claude-mem
       │
       ▼
  /plugin install claude-mem
       │
       ▼
  /exit（退出并重启 Claude Code）
       │
       ▼
  ✅ 安装完成！

详细步骤

第 1 步：启动 Claude Code

在终端中输入：

claude

第 2 步：添加插件市场来源

在 Claude Code 的交互环境中输入：

1	/plugin marketplace add thedotmack/claude-mem

第 3 步：安装插件

1	/plugin install claude-mem

安装过程会自动完成以下操作：

下载预编译二进制文件（无需手动编译）
安装依赖（包含 SQLite、Bun 等）
配置生命周期 Hooks
首次会话时自动启动 Worker 服务

第 4 步：重启 Claude Code

/exit

然后重新启动：

claude

4.2 方式二：npx 命令安装

如果你更喜欢命令行操作：

1	npx claude-mem install

这条命令会自动完成所有配置。安装完成后重启 Claude Code 即可。

注意：不要使用 npm install -g claude-mem，这只会安装 SDK 库，不会注册插件 Hooks 和 Worker 服务。

4.3 验证安装成功

重启 Claude Code 后，观察是否出现以下迹象：

迹象 1：启动时显示上下文注入

如果这不是你的第一次会话，启动时可能看到类似信息：

1	# [UsageGuide] recent context, 2026-04-30 3:48pm GMT+8

这表示 Claude-Mem 正在注入历史上下文。

迹象 2：Web Viewer 可访问

打开浏览器访问：

1	http://localhost:37777

如果能看到 Claude-Mem 的 Web 界面，说明 Worker 服务已正常启动。

迹象 3：检查数据目录

# Windows (PowerShell)
ls ~/.claude-mem/

# macOS / Linux
ls ~/.claude-mem/

如果看到以下文件 / 目录，说明一切正常：

1
2
3

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

4.4 依赖项说明

Claude-Mem 会自动处理以下依赖，通常不需要你手动安装：

依赖	用途	是否自动安装
Node.js 18+	运行时环境	❌ 需手动安装（第 3 章）
Claude Code	AI 编程工具	❌ 需手动安装（第 3 章）
Bun	Worker 服务的 JavaScript 运行时	✅ 自动安装
uv	向量搜索的 Python 包管理器	✅ 自动安装
SQLite 3	本地数据存储	✅ 内置

第 5 章基础配置

Claude-Mem 开箱即用，默认配置已能满足大多数需求。本章介绍最常用的几项配置。

5.1 配置文件位置

1	~/.claude-mem/settings.json

平台	实际路径
Windows	`C:\Users\ 你的用户名 \.claude-mem\settings.json`
macOS	`/Users/ 你的用户名 /.claude-mem/settings.json`
Linux	`/home/ 你的用户名 /.claude-mem/settings.json`

该文件在首次运行时自动生成，包含默认值。

5.2 中文模式设置

默认情况下，Claude-Mem 使用英文生成观察记录和摘要。如果你希望使用中文，需要修改模式设置。

编辑 ~/.claude-mem/settings.json：

1
2
3

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

可用的语言模式：

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

其他语言模式遵循 code--[语言代码] 格式，其中语言代码为 ISO 639-1 标准（如 es 西班牙语、ko 韩语）。

修改后需要重启 Claude Code 才能生效。

5.3 自定义数据目录

如果你想把数据存到特定位置（比如 SSD 硬盘或为不同项目隔离记忆），可以设置环境变量：

Windows（PowerShell）：

1 2	$env:CLAUDE_MEM_DATA_DIR="D:\claude-mem-data" claude

macOS / Linux：

1 2	export CLAUDE_MEM_DATA_DIR=/data/claude-mem-data claude

如果想永久生效，将环境变量添加到你的 shell 配置文件（如 .bashrc、.zshrc）或 Windows 系统环境变量中。

5.4 Worker 服务管理

Worker 服务是 Claude-Mem 的后台引擎，处理数据存储和 AI 压缩。通常它会自动启动和管理，但有时你可能需要手动操作：

# 进入 claude-mem 安装目录
cd ~/.claude/plugins/marketplaces/thedotmack

# 常用管理命令
npm run worker:start      # 启动 Worker
npm run worker:stop       # 停止 Worker
npm run worker:status     # 查看运行状态
npm run worker:logs       # 查看日志（排查问题时很有用）
npm run worker:restart    # 重启 Worker
npm run worker:kill       # 强制终止（仅在卡死时使用）

5.5 配置速查

~/.claude-mem/
├── settings.json         ← 主配置文件（编辑此文件）
├── claude-mem.db         ← SQLite 数据库（不要手动删除！）
├── .worker.pid           ← Worker 进程 ID（自动管理）
├── .worker.port          ← Worker 端口（默认 37777）
└── logs/
    └── worker-YYYY-MM-DD.log  ← 每日日志文件

第 6 章日常使用实战

本章通过一个完整的实战案例，演示 Claude-Mem 如何在日常开发中发挥作用。

6.1 最佳实践：完全当它不存在

Claude-Mem 的设计理念是 零干预——你只需要正常使用 Claude Code 编码，记忆系统在后台自动工作。

你的日常工作流（和没装 Claude-Mem 完全一样）：

  1. 启动 claude
  2. 告诉 Claude 你要做什么
  3. Claude 读文件、写代码、跑测试……
  4. Claude-Mem 自动记录每一步
  5. 会话结束，Claude-Mem 自动生成摘要
  6. 下次启动，自动恢复上下文

6.2 实战案例：跨会话项目开发

下面演示一个完整的多日开发场景，展示 Claude-Mem 如何在会话间保持记忆连续性。

Day 1：搭建项目基础

启动 Claude Code：

1
2
3

cd ~/projects
mkdir my-task-app && cd my-task-app
claude

与 Claude 的对话：

你：帮我创建一个简单的 Node.js 命令行任务管理工具。支持添加任务、列出任务、
    标记完成这三个功能。数据存储在 JSON 文件中。

Claude：[开始创建项目……]
        - 创建 package.json
        - 创建 src/task-manager.js
        - 创建 src/storage.js
        - 创建 index.js
        - 编写测试……

你：测试都通过了吗？

Claude：是的，3 个测试套件全部通过。

此时 Claude-Mem 已经在后台自动记录了：

你创建的项目类型和技术栈
Claude 读取和创建了哪些文件
测试结果和关键决策

关闭会话：

1
2
3

你：今天就到这里，明天继续。
Claude：好的，明天见！
/exit

Claude-Mem 自动生成 Day 1 的会话摘要：

会话摘要：创建了 Node.js 命令行任务管理工具，支持添加、列出、标记完成功能，
数据存储在 JSON 文件中。包含 task-manager.js、storage.js、index.js，
3 个测试套件全部通过。

Day 2：跨会话恢复

第二天，启动新会话：

1 2	cd ~/projects/my-task-app claude

Claude-Mem 自动注入 Day 1 的上下文，Claude 已经”记得”你的项目。

你：继续昨天的项目，加一个删除任务的功能，然后给每个任务加上创建时间。

Claude：（不需要你重新解释项目结构，直接开始工作）
        我记得昨天我们创建了一个 Node.js 任务管理工具，使用 JSON 存储。
        现在来添加删除功能和创建时间……

        - 修改 src/task-manager.js，添加 deleteTask 方法 
        - 修改 task 对象结构，增加 createdAt 字段
        - 更新测试……

 你：帮我检查一下昨天写的代码有没有潜在问题。

Claude：（基于记忆中的上下文进行分析）
        我注意到 storage.js 的写入操作没有错误处理……

关键点：你完全不需要重复说明项目背景。Claude-Mem 让 Claude 在新会话中”记住”了：

项目的技术栈（Node.js + JSON 存储）
项目结构（哪些文件、各文件职责）
已完成的功能（添加、列出、标记完成）
测试状态（全部通过）

Day 3：主动搜索历史记忆

1 2	cd ~/projects/my-task-app claude

你：我们之前在讨论 storage.js 时遇到过什么问题吗？

Claude：（通过 mem-search 技能搜索历史记忆）
        在 Day 2 的会话中，我们发现 storage.js 的写入操作缺少错误处理，
        后来添加了 try-catch 和文件权限检查……

你：把这几天的改动整理成一个 CHANGELOG。

Claude：（检索所有历史记录，生成完整的变更日志）

6.3 Web Viewer：可视化查看记忆

Claude-Mem 提供了一个 Web 界面，让你可以直观地查看所有记忆记录。

打开浏览器访问：

1	http://localhost:37777

你能看到：

功能	说明
记忆流	按时间线查看所有观察记录
搜索	用关键词搜索历史记录
设置	切换稳定版 /Beta 版、调整配置
观察详情	点击任意记录查看完整内容

每条观察记录都有一个唯一 ID，你可以通过以下方式访问特定记录：

1	http://localhost:37777/api/observation/{ID}

6.4 隐私控制

如果你不希望某些敏感内容被记录，可以在对话中使用 <private> 标签：

你：数据库密码是 <private>my-secret-password-123</private>，
    帮我配置数据库连接。

Claude：（正常工作，但密码不会被 Claude-Mem 记录）

第 7 章进阶技巧

掌握了基础用法后，本章介绍 Claude-Mem 的高级搜索和知识库功能。

7.1 MCP 搜索工具：三层工作流

Claude-Mem 提供了 3 个 MCP 搜索工具，遵循 **”先索引、后详情”** 的三层工作流，大幅节省 Token。

三层工作流：

第 1 层：search（搜索索引）
  输入：" 认证相关的 bug 修复 "
  输出：~10 条结果，每条约 50-100 Token（只有标题和摘要）
  ──────────────────────────────────────────
  ID #123 | 修复了 JWT token 过期处理的问题 
  ID #124 | 添加了 refresh token 逻辑
  ID #125 | 重构了认证中间件
                    │
                    ▼  选择相关的 ID

 第 2 层：timeline（时间线上下文）
  输入：anchor=#124
  输出：#124 前后的来龙去脉（上下文）
                    │
                    ▼  确认需要查看的 ID

第 3 层：get_observations（完整详情）
  输入：ids=[123, 124]
  输出：完整的观察记录（每条 500-1000 Token）

使用示例

在 Claude Code 中，你可以直接用自然语言触发搜索，Claude 会自动调用 MCP 工具：

你：我们之前修复过一个 JWT 认证的 bug，能帮我找到吗？

Claude：（自动调用 search 工具）
        我找到了以下相关记录：
        - #123 修复了 JWT token 过期处理 
        - #124 添加了 refresh token 逻辑

 你：#123 具体改了什么？

Claude：（自动调用 get_observations 工具）
        在 #123 中，我们修改了 auth/middleware.js 的第 45-52 行……

手动使用搜索工具

如果你想要更精确的控制，可以使用 /mem-search 技能：

1
2
3

你：/mem-search

（Claude 将启动 mem-search 技能，提供结构化的搜索界面）

搜索参数

search 工具支持的筛选条件：

参数	说明	示例
`query`	搜索关键词	`"authentication bug"`
`type`	记录类型	`decision`、`bugfix`、`feature`、`refactor`
`project`	项目名称	`"my-task-app"`
`dateStart`	起始日期	`"2026-04-01"`
`dateEnd`	结束日期	`"2026-04-30"`
`limit`	结果数量	`10`（默认 20）

7.2 知识库：从记忆到知识

Claude-Mem 的知识库功能可以将散落的观察记录组织成可查询的知识集合。

1
2
3

记忆 ──────► 知识库 ──────► 智能问答

(散落的观察)   (结构化知识)    (自然语言查询)

创建知识库

 你：帮我构建一个关于 " 认证系统 " 的知识库。

Claude：（调用 build_corpus 工具）
        已创建知识库 "auth-system"，包含 23 条相关观察记录。

实际上，Claude 会调用以下工具：

build_corpus(
  name="auth-system",
  description=" 认证系统相关知识 ",
  query="authentication JWT token",
  types="decision,bugfix,feature"
)

查询知识库

 你：我们的认证系统支持哪些登录方式？

Claude：（先调用 prime_corpus 加载知识库，再调用 query_corpus 查询）
        根据知识库记录，我们目前支持：
        1. 用户名 / 密码登录
        2. JWT Token 认证
        3. Refresh Token 自动续期

知识库管理命令

命令	说明
`build_corpus`	创建新知识库
`list_corpora`	列出所有知识库
`prime_corpus`	加载知识库（查询前必须先加载）
`query_corpus`	向知识库提问
`rebuild_corpus`	重建知识库（刷新内容）
`reprime_corpus`	重置知识库会话（清除对话历史）

7.3 智能代码分析工具

Claude-Mem 还提供了基于 AST（抽象语法树）的代码分析工具，比全文件读取更高效：

工具	说明	适用场景
`smart_outline`	查看文件的函数 / 类 / 方法结构	快速了解文件内容
`smart_search`	搜索代码中的符号（函数名、类名等）	查找特定函数的位置
`smart_unfold`	展开特定符号的完整代码	只看某个函数的实现

7.4 实用技能（Skills）

Claude-Mem 安装后会在 Claude Code 中注册以下技能：

技能	触发方式	说明
`/mem-search`	手动触发	搜索持久化记忆
`/make-plan`	手动触发	创建详细的实施计划
`/do`	手动触发	执行已有的实施计划
`/knowledge-agent`	手动触发	构建和查询知识库
`/smart-explore`	手动触发	Token 优化的结构化代码搜索
`/pathfinder`	手动触发	生成代码库的功能分组流程图
`/timeline-report`	手动触发	生成项目开发历程报告

7.5 Beta 功能：Endless Mode

Claude-Mem 提供了 Beta 频道，包含实验性功能如 Endless Mode（无尽模式）——一种仿生记忆架构，支持超长会话。

开启方法：

访问 Web Viewer：http://localhost:37777
进入 Settings 页面
切换到 Beta 版本

注意：Beta 功能可能不稳定，建议在非关键项目中试用。

第 8 章常见问题与排错

8.1 FAQ 速查表

问题	原因	解决方案
`npm 不是内部或外部命令`	Node.js 未安装或 PATH 未配置	重新安装 Node.js，确保勾选”Add to PATH”，重启终端
安装时网络超时	npm 下载慢	设置国内镜像：`npm config set registry https://registry.npmmirror.com`
Worker 启动失败	端口 37777 被占用	终止占用进程或修改端口配置
记忆未被注入	Worker 未运行	手动启动：`cd ~/.claude/plugins/marketplaces/thedotmack && npm run worker:start`
Web Viewer 无法访问	Worker 未启动或端口错误	检查 `~/.claude-mem/.worker.port` 文件中的实际端口
中文模式下仍显示英文	修改后未重启	修改 `settings.json` 后必须重启 Claude Code
`Bun` 安装失败	网络问题或权限不足	手动安装 Bun：`powershell -c "irm bun.sh/install.ps1 \| iex"`（Windows）
向量搜索不工作	`uv` 未安装	Claude-Mem 会自动安装，检查网络连接后重试

8.2 详细排查步骤

问题：安装后看不到任何效果

排查步骤：

确认安装成功：

1 2	ls ~/.claude/plugins/marketplaces/thedotmack/ # 应该能看到插件文件

确认 Worker 正在运行：

1 2	curl http://localhost:37777/api/health # 应该返回 {"status":"ok"} 或类似响应

查看日志：

1 2	cat ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log # 查看是否有错误信息

尝试手动启动 Worker：

1 2	cd ~/.claude/plugins/marketplaces/thedotmack npm run worker:start

问题：Windows 上路径相关错误

Windows 用户可能遇到路径分隔符问题（\ vs /）。建议：

在 PowerShell 中使用反引号（`）转义路径
确保用户目录路径中没有中文字符
使用完整路径而非相对路径

问题：如何完全卸载

# 1. 卸载插件（在 Claude Code 中）
/plugin uninstall claude-mem

# 2. 删除所有记忆数据（谨慎！会删除所有历史记录）
rm -rf ~/.claude-mem

# 3. 删除插件文件
rm -rf ~/.claude/plugins/marketplaces/thedotmack

8.3 获取帮助

如果以上方法都无法解决你的问题：

向 Claude 描述问题：Claude-Mem 内置了 troubleshoot 技能，描述问题后 Claude 会自动诊断

生成 Bug 报告：

1 2	cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report

提交 Issue：GitHub Issues
加入社区：Discord

附录

A. 命令速查表

安装与管理

命令	说明
`/plugin marketplace add thedotmack/claude-mem`	添加插件市场来源
`/plugin install claude-mem`	安装插件
`/plugin uninstall claude-mem`	卸载插件
`npx claude-mem install`	命令行方式安装

Worker 管理

命令	说明
`npm run worker:start`	启动 Worker 服务
`npm run worker:stop`	停止 Worker 服务
`npm run worker:status`	查看运行状态
`npm run worker:logs`	查看日志
`npm run worker:restart`	重启 Worker 服务
`npm run worker:kill`	强制终止 Worker

日常操作

命令 / 操作	说明
正常使用 Claude Code	Claude-Mem 自动记录一切
`http://localhost:37777`	打开 Web Viewer
`<private>...</private>`	标记隐私内容，不被记录
`/mem-search`	手动触发记忆搜索

B. 配置项参考

~/.claude-mem/settings.json 中的主要配置项：

配置项	默认值	说明
`CLAUDE_MEM_MODE`	`"code"`	工作模式和语言（中文用 `"code--zh"`）
`CLAUDE_MEM_DATA_DIR`	`~/.claude-mem/`	数据存储目录
Worker 端口	`37777`	Worker 服务监听端口

环境变量：

变量	说明
`CLAUDE_MEM_DATA_DIR`	自定义数据目录
`CLAUDE_MEM_MODE`	工作模式

C. 参考资源

资源	链接
GitHub 仓库	github.com/thedotmack/claude-mem
官方文档	GitHub README 中的文档链接
Claude Code 官方	docs.anthropic.com
Bug 报告	[GitHub Issues

D. 卸载与重新安装

如果遇到无法解决的问题，可以尝试完全重新安装：

# 第 1 步：卸载插件（在 Claude Code 中执行）
/plugin uninstall claude-mem

# 第 2 步：清理数据（可选，会删除所有记忆）
rm -rf ~/.claude-mem

# 第 3 步：清理插件文件
rm -rf ~/.claude/plugins/marketplaces/thedotmack

# 第 4 步：重新安装
# 在 Claude Code 中执行：
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

# 第 5 步：重启 Claude Code
/exit
claude

许可证：Claude-Mem 使用 GNU Affero General Public License v3.0 (AGPL-3.0) 开源协议。

本指南基于 claude-mem v6.x 编写，功能可能随版本更新而变化，请以官方文档为准。

Claude-Mem 从入门到实践

目录

第 1 章 为什么需要 Claude-Mem

1.1 你是否遇到过这个场景？

1.2 Claude-Mem 是什么？

1.3 核心价值

第 2 章 工作原理速览

2.1 全景架构图

2.2 数据流：从捕获到注入

2.3 什么是”渐进式披露”？

2.4 五个生命周期 Hook

第 3 章 环境准备

3.1 什么是 Node.js？

3.2 Windows 环境

步骤 1：安装 Node.js

步骤 2：安装 Claude Code

步骤 3：登录 Claude Code

步骤 4：验证 Claude Code 可用

3.3 macOS 环境

步骤 1：安装 Node.js

步骤 2：安装 Claude Code

步骤 3：验证

3.4 Linux 环境

步骤 1：安装 Node.js

步骤 2：安装 Claude Code

步骤 3：验证

3.5 环境准备检查清单

第 4 章 安装 Claude-Mem

4.1 方式一：插件市场一键安装（推荐）

详细步骤

4.2 方式二：npx 命令安装

4.3 验证安装成功

4.4 依赖项说明

第 5 章 基础配置

5.1 配置文件位置

5.2 中文模式设置

5.3 自定义数据目录

5.4 Worker 服务管理

5.5 配置速查

第 6 章 日常使用实战

6.1 最佳实践：完全当它不存在

6.2 实战案例：跨会话项目开发

Day 1：搭建项目基础

Day 2：跨会话恢复

Day 3：主动搜索历史记忆

6.3 Web Viewer：可视化查看记忆

6.4 隐私控制

第 7 章 进阶技巧

7.1 MCP 搜索工具：三层工作流

使用示例

手动使用搜索工具

搜索参数

7.2 知识库：从记忆到知识

创建知识库

查询知识库

知识库管理命令

7.3 智能代码分析工具

7.4 实用技能（Skills）

7.5 Beta 功能：Endless Mode

第 8 章 常见问题与排错

8.1 FAQ 速查表

8.2 详细排查步骤

问题：安装后看不到任何效果

问题：Windows 上路径相关错误

问题：如何完全卸载

8.3 获取帮助

附录

A. 命令速查表

安装与管理

Worker 管理

日常操作

B. 配置项参考

C. 参考资源

D. 卸载与重新安装

第 1 章为什么需要 Claude-Mem

第 2 章工作原理速览

第 3 章环境准备

第 4 章安装 Claude-Mem

第 5 章基础配置

第 6 章日常使用实战

第 7 章进阶技巧

第 8 章常见问题与排错