claude-mem 插件，这是一个专为 Claude Code 设计的持久化记忆系统。它通过生命周期钩子自动捕获对话上下文，利用 SQLite 和 ChromaDB 双数据库存储记忆，支持语义搜索和渐进式披露。文章涵盖了工作原理、安装配置（含插件市场和源码方式）、实战演示、Web 管理界面使用、隐私保护及故障排除等内容，帮助开发者解决 AI 编程助手上下文遗忘的问题，实现跨会话的连续工作。
相信每一位使用过 Claude Code 的开发者都有过这样的体验：
你和 Claude 协作了一整天，它帮你写了几千行代码，修复了十几个 Bug，你们配合得天衣无缝。然后你关掉终端，第二天满怀期待地打开 Claude Code，准备继续昨天的工作——
"抱歉，我不知道你在说什么。"
所有的上下文、所有的讨论、所有的项目背景——全部被清零了。就好像你在和一个失忆症患者合作写代码，每天早上都需要从头解释一遍：这个项目是干什么的、我们昨天做到哪里了、哪些问题还没解决......
这不是 Claude 的问题，而是大语言模型天生的局限性。Claude Code 的上下文窗口大约是 20 万 Token，说实话，对于复杂项目来说这点容量少得可怜。很多时候让它运行十几二十分钟，上下文就直接用满了。
这个痛点，正是 claude-mem 项目要解决的核心问题。
claude-mem 是一个专门为 Claude Code 打造的持久化记忆压缩系统。它能够自动捕获你和 Claude 的对话上下文，让 AI 拥有真正的长期记忆能力。
简单来说，它的工作方式类似于给 Claude 配备了一个"私人秘书"——这个秘书会默默记录每次对话中发生的重要事情，当你下次开始新对话时，秘书会把相关的历史信息重新告诉 Claude，让它能够"记起"之前的工作内容。
| 属性 | 信息 |
|---|---|
| 项目名称 | claude-mem |
| GitHub 仓库 | https://github.com/thedotmack/claude-mem |
| 官方网站 | https://claude-mem.ai/ |
| 官方文档 | https://docs.claude-mem.ai/ |
| 开源协议 | AGPL-3.0 |
| 系统支持 | Windows、macOS、Linux |
1. 持久化记忆
上下文会在会话之间自动保存，不需要手动操作。每次你结束一个编程会话，claude-mem 都会自动生成语义摘要，为下次会话做好准备。
2. 渐进式披露（Progressive Disclosure）
这是 claude-mem 的核心设计哲学。它采用分层记忆检索策略，模拟人类的记忆模式：
3. 智能搜索
可以通过自然语言搜索项目历史。比如你可以直接问 Claude：
4. 可视化管理界面
claude-mem 提供一个实时 Web 界面（运行在 http://localhost:37777/），你可以：
5. 隐私控制
你可以排除敏感内容，完全掌控哪些信息被存储。通过 <private> 标签包裹的内容不会被记录。
6. 全自动运行
无需手动干预，后台透明运行，自动完成所有记忆管理工作。
要真正理解 claude-mem 的价值，我们需要深入了解它的技术架构。这一部分内容稍微偏技术向，但我会尽量用通俗的语言来解释。
claude-mem 的核心设计理念是：它不会中断或修改 Claude Code 的行为，而是从外部观察，通过生命周期钩子提供价值。
整个系统由以下几个核心组件构成：
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 会话 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 生命周期钩子 (Lifecycle Hooks) │
│ SessionStart → UserPromptSubmit → PostToolUse → Stop │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Worker 服务 (后台处理) │
│ 通过 Claude Agent SDK 提取学习内容 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 双数据库存储系统 │
│ SQLite (结构化) + ChromaDB (向量化) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 下次会话开始时自动注入相关上下文 │
└─────────────────────────────────────────────────────────────┘
claude-mem 使用 5 个生命周期钩子来捕获和处理会话信息。这些钩子会在 Claude Code 的关键时刻自动触发。
触发时机： Claude Code 启动时（包括 startup、clear 或 compact 操作）
执行内容：
这是最关键的钩子之一，它确保每次你开始新会话时，Claude 都能"记起"之前的工作内容。
触发时机： 用户发送消息给 Claude 时
执行内容：
触发时机： Claude 执行任何工具操作后
执行内容：
这个钩子会捕获几乎所有的工具执行记录，包括：
触发时机： Claude 停止当前任务时
执行内容：
摘要的格式如下：
<summary>
<request>用户的原始请求</request>
<investigated>检查了什么</investigated>
<learned>关键发现</learned>
<completed>已完成的工作</completed>
<next_steps>剩余任务</next_steps>
<files_read>
<file>path/to/file1.ts</file>
</files_read>
<files_modified>
<file>path/to/file2.ts</file>
</files_modified>
<notes>额外上下文</notes>
</summary>
触发时机： Claude Code 会话完全结束时
执行内容：
claude-mem 采用了一个巧妙的架构设计来确保不影响 Claude Code 的响应速度：
前端钩子（快速）：
┌─────────────────────────────────────────────────────────────┐
│ HOOK (快速层) │
│ 1. 读取 stdin (< 1ms) │
│ 2. 插入队列 (< 10ms) │
│ 3. 返回成功 (总计 < 20ms) │
└─────────────────────────────────────────────────────────────┘
↓ (队列)
后台 Worker（慢速但不阻塞）：
┌─────────────────────────────────────────────────────────────┐
│ WORKER (慢速层) │
│ 1. 每秒轮询队列 │
│ 2. 通过 Claude SDK 处理观察 (5-30 秒) │
│ 3. 解析并存储结果 │
│ 4. 标记观察已处理 │
└─────────────────────────────────────────────────────────────┘
这种设计的好处是：
claude-mem 使用两个数据库来存储记忆：
1. SQLite 数据库（结构化存储）
位置：~/.claude-mem/claude-mem.db
用途：
2. ChromaDB（向量数据库）
位置：~/.claude-mem/chroma/
用途：
这种双数据库架构使得 claude-mem 既能进行精确的关键词搜索，也能进行"模糊"的语义搜索。
claude-mem 会自动将每个观察分类为以下类型之一：
| 类型 | 英文 | 说明 |
|---|---|---|
| 决策 | decision | 架构选择、技术决策 |
| Bug 修复 | bugfix | 问题诊断和修复 |
| 功能实现 | feature | 新功能开发 |
| 重构 | refactor | 代码重构 |
| 发现 | discovery | 关于代码库的发现 |
这种分类使得后续搜索更加精准。比如你可以问："上周我们修复了哪些 Bug？"
本文将带你一步步完成 claude-mem 的安装和配置。
在安装之前，请确保你的系统满足以下要求：
| 要求 | 说明 |
|---|---|
| Node.js | 18.0.0 或更高版本 |
| Claude Code | 最新版本（需支持插件功能） |
| Bun | JavaScript 运行时（会自动安装） |
| SQLite 3 | 用于持久化存储（已打包） |
| 内存 | 至少 4GB RAM |
| 磁盘空间 | 至少 100MB 可用空间 |
这是最简单的安装方式，只需要两行命令：
第一步：启动 Claude Code
在终端中启动 Claude Code。
第二步：添加插件市场并安装
在 Claude Code 中输入以下命令：
/plugin marketplace add thedotmack/claude-mem
等待命令执行完成，然后输入：
/plugin install claude-mem
安装程序会询问你安装范围，有以下选项：
建议选择第一个选项进行全局安装。
第三步：重启 Claude Code
安装完成后，重启 Claude Code 让配置生效。
第四步：验证安装
重启后，输入以下命令查看已安装的插件：
/plugin
按 Tab 键切换，你应该能看到 claude-mem 插件已经出现在列表中。
如果你需要进行开发测试，或者想要修改源码，可以选择从源码安装：
# 克隆仓库
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
# 安装依赖
npm install
# 构建钩子和 Worker 服务
npm run build
# 手动启动 Worker 服务（可选，首次会话会自动启动）
npm run worker:start
# 验证 Worker 运行状态
npm run worker:status
claude-mem 的配置文件位于 ~/.claude-mem/settings.json，首次运行时会自动创建默认配置。
以下是主要配置项说明：
{
"provider": "claude",
"model": "claude-sonnet-4-5-20250929",
"workerPort": 37777,
"dataDir": "~/.claude-mem",
"logLevel": "info",
"contextObservations": 10
}
配置项解释：
| 配置项 | 说明 | 默认值 |
|---|---|---|
| provider | AI 提供商 | claude |
| model | 使用的模型 | claude-sonnet-4-5-20250929 |
| workerPort | Worker 服务端口 | 37777 |
| dataDir | 数据存储目录 | ~/.claude-mem |
| logLevel | 日志级别 | info |
| contextObservations | 注入上下文的观察数量 | 10 |
关于模型配置的说明：
这里可能有人会疑惑：为什么要在配置中设置模型？需要配置 API Key 吗？
答案是：不需要配置 API Key！
claude-mem 会作为 Claude Code 的子进程运行，它会复用 Claude Code 的登录认证，通过 Claude Code 来调用 AI 模型。所以只要你能正常启动 Claude Code，claude-mem 就能正常工作。
如果你需要自定义某些配置，可以通过环境变量来覆盖：
# 自定义数据目录
export CLAUDE_MEM_DATA_DIR=/custom/path
# 自定义 Worker 端口
export CLAUDE_MEM_WORKER_PORT=8080
# 设置上下文观察数量
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=15
# 设置跳过的工具（不记录这些工具的使用）
export CLAUDE_MEM_SKIP_TOOLS="ListMcpResourcesTool,SlashCommand"
安装完成后，你可以通过以下方式验证：
1. 访问 Web 界面
打开浏览器，访问 http://localhost:37777/，你应该能看到 claude-mem 的管理界面。
2. 检查 Worker 日志
npm run worker:logs
或者查看日志文件：~/.claude-mem/logs/worker-YYYY-MM-DD.log
3. 测试上下文检索
npm run test:context
4. 检查数据目录
确认以下文件存在：
~/.claude-mem/claude-mem.db - 数据库文件~/.claude-mem/.worker.pid - Worker 进程 ID 文件~/.claude-mem/.worker.port - Worker 端口文件~/.claude-mem/settings.json - 配置文件现在让我们通过一个完整的实战案例来体验 claude-mem 的强大功能。
步骤 1：启动新的 Claude Code 会话
claude
步骤 2：让 Claude 创建一个项目
向 Claude 发送请求：
请帮我创建一个美发预约网站，需要包含以下功能：
1. 用户注册和登录
2. 服务项目展示
3. 在线预约功能
4. 个人中心
步骤 3：观察 claude-mem 的工作
在 Claude 开始工作的同时，打开浏览器访问 http://localhost:37777/，你会看到 Web 界面开始记录各种信息：
步骤 4：完成项目并退出
等 Claude 完成项目后，你可以结束会话。此时 claude-mem 会：
步骤 1：开启全新的 Claude Code 会话
完全关闭之前的终端，打开一个新的终端，启动 Claude Code：
claude
步骤 2：询问之前的工作
在这个全新的对话中（没有任何上下文），问 Claude：
上次我们做了一个什么项目？都实现了哪些功能？
步骤 3：见证奇迹
你会看到 Claude 开始查找之前的项目记录。它会回答类似这样的内容：
"根据历史记录，我们上次一起做了一个美发预约网站，实现了以下功能：
整个网站使用了 [具体技术栈]，项目结构如下......"
这就是 claude-mem 的神奇之处——新的对话中，Claude 依然能够"记住"之前的工作！
场景一：继续之前的工作
继续完善我们之前做的美发网站，添加一个评价系统
Claude 会直接知道你说的是哪个项目，无需重新解释。
场景二：排查历史 Bug
之前我们在用户登录功能上遇到过什么问题？是怎么解决的？
claude-mem 会搜索历史记录，找出相关的 Bug 修复记录。
场景三：查看决策历史
我们为什么选择使用 JWT 而不是 Session？
如果之前有过相关讨论，Claude 能够找到当时的决策记录。
claude-mem 的 Web 界面是一个强大的管理工具，让我们详细了解它的功能。
打开浏览器，访问：http://localhost:37777/
1. 记忆流（Memory Stream）
这是主界面，显示所有的观察记录。每条记录包含：
2. 项目切换
如果你有多个项目，可以在界面中切换不同项目的记忆。
3. 过滤功能
可以按照以下维度过滤记忆：
4. 设置面板
点击设置图标，可以配置：
5. 事实叙述（Fact Narrative）
点击某条记忆的"事实叙述"按钮，可以看到更详细的记录，包括：
claude-mem 提供了一个实验性功能叫 Endless Mode（无尽模式），这是一种仿生记忆架构，用于大幅延长会话长度。
问题背景：
标准的 Claude Code 会话在大约 50 次工具使用后就会触及上下文限制。每个工具添加 1-10k+ Token，而且 Claude 在每次响应时都会重新合成所有之前的输出（O(N²) 复杂度）。
Endless Mode 的解决方案：
启用方式：
在 Web 界面的 Settings 中切换到 Beta 版本即可尝试。
注意事项：
claude-mem 的搜索功能是其核心价值之一，让我们深入了解如何充分利用它。
最简单的方式是直接用自然语言提问：
上次会话我们修复了什么 Bug？
我们是怎么实现用户认证的？
最近对 worker-service.ts 做了什么修改？
claude-mem 支持一个三层工作流模式来进行高效搜索：
第一步：搜索索引
search(query="authentication bug", type="bugfix", limit=10)
这会返回一个轻量级的索引，包含标题、类型和时间戳。
第二步：识别相关条目
查看返回的索引，找到相关的记录 ID（比如 #123、#456）。
第三步：获取完整详情
get_observations(ids=[123, 456])
获取特定记录的完整内容。
可以使用以下过滤条件：
按类型过滤：
type:decision file:auth.ts
按文件过滤：
"What decisions affected index.ts?"
语义搜索：
"What do we know about auth?"
两种搜索方式都能工作：关键词搜索使用 SQLite 的 FTS5 引擎，语义搜索使用 ChromaDB 的向量匹配。
对于涉及敏感信息的项目，claude-mem 提供了完善的隐私保护机制。
在你的代码或对话中，使用 <private> 标签包裹不想被记录的内容：
<private> 这里的内容不会被 claude-mem 记录
API_KEY="sk-xxxxx"
</private>
可以通过配置跳过某些工具的记录：
export CLAUDE_MEM_SKIP_TOOLS="ListMcpResourcesTool,SlashCommand,AskUserQuestion"
如果需要，你可以手动删除某些记忆记录：
症状： 安装后 Worker 服务无法在端口 37777 启动
解决方案：
lsof -i :37777
export CLAUDE_MEM_WORKER_PORT=8080
bun plugin/scripts/worker-service.cjs
症状： 完成会话后，下次对话 Claude 依然不记得
排查步骤：
npm run worker:status
ls -la ~/.claude-mem/claude-mem.db
npm run worker:logs
症状： 安装过程中提示依赖错误
解决方案：
node --version
cd ~/.claude/plugins/marketplaces/thedotmack npm install
症状： 每次会话开始时注入的历史信息太多或太少
解决方案：
调整上下文观察数量配置：
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=5 # 减少
# 或
export CLAUDE_MEM_CONTEXT_OBSERVATIONS=20 # 增加
claude-mem 内置了自动诊断功能。如果遇到问题，可以直接向 Claude 描述问题，troubleshoot skill 会自动激活并提供修复建议。
你也可以生成详细的 Bug 报告：
cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report
除了默认的 Claude，claude-mem 还支持其他 AI 提供商：
使用 OpenRouter：
export CLAUDE_MEM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your-api-key
使用 Gemini：
export CLAUDE_MEM_PROVIDER=gemini
export GEMINI_API_KEY=your-api-key
claude-mem 支持自定义模式文件，位于 ~/.claude-mem/modes/。可以为不同的编程语言或工作模式配置不同的提示词。
如果需要在不同机器间迁移记忆，可以使用导出/导入功能。详细说明请参考官方文档的 Memory Export/Import 页面。
claude-mem 不仅支持 Claude Code，还支持 Cursor IDE。配置方式略有不同，请参考官方文档的 Cursor Integration 页面。
为了帮助读者更直观地理解 claude-mem 的工作方式，这里提供几张关键的架构图解。
用户输入 ↓
Claude Code 处理 ↓
PostToolUse 钩子触发 ↓
观察数据发送到 Worker ↓
Worker 调用 AI 提取语义 ↓
双数据库存储
├── SQLite (结构化索引)
└── ChromaDB (向量嵌入)
↓
下次会话 SessionStart 时检索 ↓
相关上下文注入新会话
┌─────────────────────────────────────────────────────────────┐
│ Claude Code IDE │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Lifecycle Hooks │ │
│ │ SessionStart → UserPrompt → PostToolUse → Stop → End │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓ HTTP
┌─────────────────────────────────────────────────────────────┐
│ Worker Service (:37777) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ SessionRoutes│ │ ObservationAPI│ │ ContextBuilder │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ AI Providers │
│ ┌──────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ SDKAgent │ │ GeminiAgent │ │ OpenRouterAgent │ │
│ │ (Claude) │ │ │ │ │ │
│ └──────────┘ └──────────────┘ └────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Database Layer │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ SQLite │ │ ChromaDB │ │
│ │ (Structured + FTS) │ │ (Vector Search) │ │
│ └─────────────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Claude Code 本身支持通过 CLAUDE.md 文件来存储项目上下文。但这种方式有几个局限性：
| 特性 | CLAUDE.md | claude-mem |
|---|---|---|
| 自动化程度 | 需要手动维护 | 全自动 |
| 记忆粒度 | 宏观概述 | 精细观察 |
| 搜索能力 | 无 | 全文 + 语义搜索 |
| 历史追溯 | 无版本历史 | 完整时间线 |
| 适用场景 | 静态项目知识 | 动态工作记忆 |
最佳实践是将两者结合使用：
CLAUDE.md 存储稳定的项目约定、架构决策claude-mem 处理动态的工作记忆和历史追溯市面上有一些其他的 AI 记忆解决方案，但 claude-mem 有几个独特优势：
1. 长期重构项目
在进行跨越多天的复杂重构时，持久化记忆能帮助 Claude 记住：
2. 多模块大型项目
当项目涉及多个模块时，Claude 能够记住：
3. 团队协作项目
虽然 claude-mem 主要是个人工具，但在团队项目中：
4. 学习和探索性开发
在学习新技术时，claude-mem 能帮你记住：
1. 一次性脚本任务
如果只是写一个简单的一次性脚本，记忆功能的价值有限。
2. 高度机密项目
尽管有隐私保护机制，但对于极度敏感的项目，任何形式的持久化存储都需要谨慎评估。
3. 资源受限环境
claude-mem 需要运行后台 Worker 服务，会占用一定的系统资源。在资源极度受限的环境中可能不太合适。
通过插件市场安装的 claude-mem 会自动升级。当有新版本可用时，SessionStart 钩子会自动检测并更新。
如果需要手动升级，可以执行：
/plugin update claude-mem
v9.0.0：
v8.2.0：
v7.1.0：
v5.4.0+：
完整的更新日志请参考：https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md
claude-mem 使用 AGPL-3.0 开源协议。这意味着：
你可以：
但你需要：
对于普通开发者来说，直接使用没有任何限制。但如果你是企业用户，想要将 claude-mem 集成到内部平台并提供给第三方使用，建议进行法律评估。
claude-mem 解决了 AI 编程助手的一个根本性问题：上下文遗忘。
通过这个项目，你可以：
根据项目的发展趋势，claude-mem 可能会在以下方向继续进化：
| 资源 | 链接 |
|---|---|
| GitHub 仓库 | https://github.com/thedotmack/claude-mem |
| 官方网站 | https://claude-mem.ai/ |
| 官方文档 | https://docs.claude-mem.ai/ |
| 问题反馈 | https://github.com/thedotmack/claude-mem/issues |
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online