Claude-Mem 完整指南：深入详解、安装、配置、使用与 IDE 集成

1. Claude-Mem 核心原理与能力

1.1 是什么

Claude-Mem 是一个为 Claude Code（Anthropic 的命令行编码工具）增加"跨会话持久记忆"的开源插件。它的核心价值在于：Claude Code 的会话通常是独立的（无状态），关闭后上下文会丢失；Claude-Mem 通过本地数据库存储与智能检索机制，让新会话可以自动"回忆"起项目背景与关键决策，从而减少重复喂背景的成本。

1.2 全自动工作生命周期

会话启动（SessionStart）：Claude-Mem 自动从本地数据库取出最近的会话上下文（通常是最近 50 条观察记录），并以时间线方式注入到新会话的初始上下文中。
工作过程中（During Session）：每当 Claude 使用 Claude Code 的工具（Read 读文件、Write 新建文件、Edit 修改文件、Bash 执行命令、Glob 按模式找文件、Grep 内容搜索等），Claude-Mem 都会自动捕获这些"观察记录"，记录工具名、参数、结果等结构化信息。
会话结束（SessionStop）：当 Claude 完成响应触发 Stop hook 时，Claude-Mem 会自动生成并保存本次会话的摘要，包含：你的请求、调查/探索内容、学到的知识、完成的工作、建议的下一步。
下次会话：再次启动时，自动把最近工作以"索引 + 摘要"方式注入。

1.3 捕获与处理的数据范围

Claude-Mem 会捕获 Claude Code 工具的所有执行，包括：

文件操作：Read（哪个文件、读了多少行）、Write（新建了什么文件）、Edit（修改了哪些文件、改了什么内容）
命令执行：Bash（执行了什么命令、输出是什么）
搜索操作：Glob（按模式查找的文件）、Grep（搜索关键词的结果）
其他工具：所有 Claude Code 支持的工具调用都会被记录

1.4 智能压缩与"渐进式披露"

结构化处理：Worker 服务会把观察记录处理成结构化字段，包括标题、叙述、事实要点、概念标签、类型（决策/修复/功能等）、涉及文件等。
摘要完整度判断：摘要是否完整展示有逻辑------只有当"摘要生成时间晚于最后一条观察记录"时，才会把摘要的完整细节（Investigated/Learned/Completed/Next Steps）放在上下文末尾；如果摘要已经落后于最新观察，则隐藏完整摘要细节避免过期信息误导。
按需加载：启动新会话时先注入高层概览，当你提问更多细节时，再检索并加载更相关的记忆片段（"先概览、后细节"）。

1.5 本地存储与隐私

所有记忆存储在本地的 SQLite 数据库中（不上传到云端）
提供本地 Web UI 来查看记忆流与摘要内容（通常地址为 http://localhost:37777）
完整的数据所有权与控制权在用户手中

2. 系统要求与前置条件

2.1 硬件与操作系统要求

支持的系统：macOS（Intel 和 Apple Silicon）、Windows（7 及更高）、Linux（主流发行版）
磁盘空间：至少 200MB 用于安装与初始数据库
内存：建议最少 2GB RAM（通常不是瓶颈）

2.2 软件依赖

Node.js 18.0.0 或更高：运行时环境
Claude Code 最新版本：支持插件的版本（你应该能正常使用 Claude Code）
Bun：JavaScript runtime 与进程管理器。安装 Claude-Mem 时如果缺失会自动下载并安装。
SQLite 3：用于持久化存储。通常预装在系统中，Claude-Mem 也会捆绑相关库。

2.3 网络要求

首次安装时需要网络下载预编译二进制与依赖
正常工作时无需外网连接（完全离线可用）

2.4 Claude Code 的前置安装

在安装 Claude-Mem 前，你需要确保 Claude Code 已安装并可用。

常见安装方式：

bash 复制代码

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

验证 Claude Code 可用：

bash 复制代码

claude --version
claude
# 能进入交互模式即可

3. 安装方法

3.1 推荐方式：插件市场一键安装

这是官方"Quick Start"方式，最简单且零配置。

步骤 1：启动 Claude Code

bash 复制代码

claude

此时你应该看到 Claude Code 的交互提示符。

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

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

复制代码

/plugin marketplace add thedotmack/claude-mem

步骤 3：安装插件

继续输入：

复制代码

/plugin install claude-mem

安装过程通常持续几秒到十几秒，期间会自动：

下载预编译二进制（无需手动编译）
安装依赖（包含 SQLite 相关库）
配置会话生命周期 hooks（SessionStart/Stop）
首次会话时自动启动 worker 服务

步骤 4：重启并验证

安装完成后输入 /exit 退出，然后重新运行 claude 启动新会话。此时 Claude-Mem 应该已生效。

3.2 进阶方式：从源码安装（开发与测试）

如果你希望自己改代码、参与开发、或做测试，可以从源码安装。

前置要求：

Git 客户端
Node.js 18+
npm 或 yarn

步骤 1：克隆仓库

bash 复制代码

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

步骤 2：安装依赖并构建

bash 复制代码

npm install
npm run build

步骤 3：手动启动 Worker

Worker 服务通常会在第一次 Claude Code 会话时自动启动；你也可以手动启动：

bash 复制代码

npm run worker:start

查看 Worker 状态：

bash 复制代码

npm run worker:status

查看 Worker 日志：

bash 复制代码

npm run worker:logs

3.3 卸载与重新安装

如果你希望重新安装或完全卸载：

卸载插件：

复制代码

/plugin uninstall claude-mem

完全清空本地数据（谨慎！会删除所有记忆）：

bash 复制代码

rm -rf ~/.claude-mem

4. 配置详解

4.1 数据与文件位置

官方文档给出的默认数据目录在：~/.claude-mem/

在该目录下常见文件包括：

claude-mem.db：SQLite 数据库，存储所有观察记录与摘要
.worker.pid：Worker 进程 ID 文件
.worker.port：Worker 监听的端口号
logs/ 目录：Worker 服务的日志文件（命名为 worker-YYYY-MM-DD.log）
settings.json：配置文件（首次运行时自动生成）

4.2 自定义数据目录

如果你想把数据放到特定磁盘路径（例如 SSD、网络存储、或多项目隔离），可以设置环境变量：

Linux / macOS：

bash 复制代码

export CLAUDE_MEM_DATA_DIR=/custom/path/to/data
claude

Windows（PowerShell）：

powershell 复制代码

$env:CLAUDE_MEM_DATA_DIR="C:\custom\path\to\data"
claude

Windows（cmd.exe）：

cmd 复制代码

set CLAUDE_MEM_DATA_DIR=C:\custom\path\to\data
claude

4.3 Settings.json 配置项

Claude-Mem 安装后会在 ~/.claude-mem/ 生成 settings.json。具体配置字段会随版本变化，但常见调整方向包括：

注入规模控制：

控制新会话注入的观察记录条数（默认通常为 50）
控制摘要完整细节是否展示（在"摘要新于最后观察"时显示全部细节）
调整索引展示策略（例如哪些摘要在启动时主动显示）

这些控制能帮助你权衡"上下文长度"与"信息完整性"。例如若你的项目非常大且历史很长，可能希望只注入最近 20 条观察而不是 50 条，以减少开局上下文占用。

日志级别：

可调整为 debug 或 trace 以获得更详细的日志，便于排障

多项目隔离：

如果你有多个项目并希望记忆严格隔离，可以为每个项目设置不同的 CLAUDE_MEM_DATA_DIR

4.4 Hooks 配置

Claude-Mem 通过会话生命周期 hooks 实现 SessionStart/Stop 行为。这些 hooks 由 Claude Code 管理，Claude-Mem 安装时会自动配置。

你可以查看已配置的 hooks：

bash 复制代码

cat ~/.claude-code/plugin/hooks/hooks.json

通常不需要手动修改 hooks；如果你有特殊需求（例如想禁用 SessionStop 的自动摘要生成），应参考官方文档或提 Issue 反馈需求。

4.5 Worker 服务管理

Claude-Mem 会启动一个后台 Worker 服务来处理数据库操作与摘要生成。

手动管理 Worker：

bash 复制代码

npm run worker:start      # 启动
npm run worker:stop       # 停止
npm run worker:status     # 查看状态
npm run worker:logs       # 查看日志
npm run worker:restart    # 重启

如果 Worker 进程崩溃或卡死，你可以手动重启：

bash 复制代码

npm run worker:kill       # 强制杀死（会清理 PID 文件）
npm run worker:start      # 重新启动

5. 日常使用方法

5.1 最推荐的使用方式：完全当它不存在

你正常使用 Claude Code 写代码即可；Claude-Mem 会在后台自动捕获每次工具调用、处理数据、并在会话结束时生成摘要。

典型工作流：

复制代码

Day 1:
  - 启动 claude，告诉它"我要实现用户认证模块"
  - Claude 读文件、写代码、执行测试等
  - Claude-Mem 自动记录这些操作与决策
  - 关闭会话，Claude-Mem 自动生成摘要

Day 2:
  - 启动 claude，它自动注入昨天的上下文（"你昨天实现了认证模块的 JWT 部分......"）
  - 你直接说"继续昨天的任务"
  - Claude 基于记忆快速恢复进度

5.2 主动"回忆"触发检索

当你需要它把历史细节拿出来时，用更明确的自然语言提示会更准确：

例如：

"What bugs did we fix last session?"
"How did we implement authentication?"
"