一天一个开源项目（第21篇）：Claude-Mem - 为 Claude Code 打造的持久化记忆压缩系统

引言

"记忆是智能的基石------能让 AI 在多次对话后仍记得你的项目，才是真正的助手。"

这是"一天一个开源项目"系列的第21篇文章。今天带你了解的项目是 Claude-Mem （英文名 Claude-Mem）。

使用 Claude Code 写代码时，每次新会话都是一张「白纸」：它不记得你上回改过哪段逻辑、修过哪个 Bug、项目里有哪些约定。Claude-Mem 正是为解决这一问题而生：它自动捕获会话中的工具使用与观察，用 AI 做语义压缩与摘要，并在新会话中按需注入，让 Claude 在多次会话、甚至断线重连后仍能保持对项目的连续认知。

你将学到什么

• Claude-Mem 的核心价值：跨会话持久记忆与渐进式披露
• 5 个生命周期钩子与 Worker 服务、SQLite、Chroma 的协作方式
• MCP 搜索工具的三层工作流（search → timeline → get_observations）与约 10 倍 token 节省
• 如何安装、配置以及在 Claude Code / OpenClaw 中使用
• 与同类「AI 记忆」方案的对比与选型要点

前置知识

• 对 Claude Code（或 Claude Desktop 代码编辑）有基本使用经验
• 了解插件 / 钩子（hooks）的概念
• 对 SQLite、向量检索（RAG）有粗浅认识更佳，非必需

---

项目背景

项目简介

Claude-Mem 是一款面向 Claude Code 的插件，实现「持久化记忆压缩系统」。它会自动记录 Claude 在编码会话中的工具调用与观察结果，经 AI 摘要与压缩后存入本地，并在新会话启动或进行中，将相关上下文按需注入，从而让 Claude 在跨会话、跨设备重连后仍能延续对当前项目的理解。

项目解决的核心问题：

• Claude Code 默认无跨会话记忆，每次新会话都要重新介绍项目
• 长会话的完整历史占用大量 token，成本高且容易超限
• 缺乏「按需加载」的语义检索，无法精准召回与当前任务相关的历史
• 开发者希望 AI 能记住项目约定、已修复的 Bug、API 用法等，而无需每次手动粘贴

面向的用户群体：

• 长期用 Claude Code 做项目开发的开发者
• 需要 AI 记住项目上下文、减少重复说明的团队
• 对 AI 记忆、RAG、上下文工程感兴趣的技术人员
• 使用 OpenClaw 等网关并希望统一记忆能力的用户

作者/团队介绍

• 作者 ：Alex Newman（@thedotmack）
• 版权：Copyright (C) 2025 Alex Newman
• 技术栈：TypeScript 为主（约 81.9%），辅以 JavaScript、Shell、HTML；基于 Claude Agent SDK 构建
• 生态 ：提供官方文档站 docs.claude-mem.ai、Discord、X @Claude_Memory 等

项目数据

• ⭐ GitHub Stars: 27.7k+
• 🍴 Forks: 1.9k+
• 📦 版本: v10.0.6（2026年2月，以 GitHub Releases 为准）
• 📄 License : GNU Affero General Public License v3.0 (AGPL-3.0)；ragtime/ 目录单独采用 PolyForm Noncommercial 1.0.0
• 🌐 官网/文档 : claude-mem.ai / docs.claude-mem.ai
• 💬 社区 : GitHub Issues、Discord、X @Claude_Memory

---

主要功能

核心作用

Claude-Mem 的核心作用是为 Claude Code 提供跨会话的持久记忆与按需上下文注入：

1. 自动捕获：通过生命周期钩子捕获会话中的工具使用与观察（如读文件、执行命令、编辑结果等）
2. AI 压缩与摘要：使用 Claude（通过 agent-sdk）对观察做语义摘要与压缩，控制存储与检索成本
3. 持久存储：将会话、观察、摘要写入 SQLite，并用 Chroma 做向量检索，支持混合搜索
4. 按需注入：在新会话或会话中，根据当前任务将相关记忆注入到 Claude 的上下文中
5. 渐进式披露：先返回轻量索引（如 ID 列表），再按需拉取详情，显著节省 token（约 10 倍量级）

使用场景

1. 多会话连续开发

   • 今天修 Bug、明天加功能，Claude 仍记得之前的改动与约定
   • 换一台机器或重连后，无需重新口述项目结构

2. 项目约定与知识沉淀

   • 记住「API 必须带 X-API-Key」「数据库用 SQLite、表结构在 xxx」
   • 通过 save_memory 主动保存关键信息，供后续会话检索

3. Bug 与变更追溯

   • 用自然语言搜索历史（如「 authentication 相关修复」），结合 timeline 看前后操作
   • 通过观察 ID 在 Web Viewer 或 API 中查看完整内容与引用

4. 团队或网关统一记忆（OpenClaw）

   • 在 OpenClaw 网关上安装 Claude-Mem，为多用户或多会话提供统一的持久记忆能力

5. 上下文工程与成本控制

   • 用渐进式披露策略控制注入的 token 量，在「记得住」和「不爆上下文」之间取得平衡

快速开始

在 Claude Code 新会话中执行：

# 添加插件市场源
/plugin marketplace add thedotmack/claude-mem

# 安装插件
/plugin install claude-mem

安装完成后重启 Claude Code，之后新会话会自动带上过往会话的相关记忆。

OpenClaw 一键安装（在 OpenClaw 网关上）：

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

安装器会处理依赖、插件配置、AI 提供商配置、Worker 启动，以及可选的 Telegram/Discord/Slack 等实时观察流。

核心特性

1. 持久记忆（Persistent Memory）

   • 上下文跨会话保留，新会话自动获得与当前项目/任务相关的历史摘要

2. 渐进式披露（Progressive Disclosure）

   • 分层记忆检索：先拿紧凑索引（约 50--100 tokens/条），再按 ID 拉取完整观察（约 500--1000 tokens/条），显著降低 token 消耗

3. 基于 Skill 的搜索（mem-search）

   • 使用自然语言查询项目历史；支持与 Claude Desktop 对话中直接搜记忆

4. Web Viewer UI

   • 实时记忆流与检索界面：http://localhost:37777，可查看观察、引用与设置

5. 隐私控制

   • 使用 <private> 标签包裹的内容不会进入存储，适合密钥、密码等敏感信息

6. 上下文配置

   • 通过 ~/.claude-mem/settings.json 精细控制注入内容与行为（模型、端口、数据目录、日志级别等）

7. 引用与溯源

   • 观察带 ID，可通过 http://localhost:37777/api/observation/{id} 或 Web Viewer 查看原文与引用

8. Beta 能力

   • 如 Endless Mode（更长会话的生物启发式记忆架构），可在 Web Viewer → Settings 中切换稳定版/ Beta 版

项目优势

对比项	Claude-Mem	纯手贴历史/规则文件	其他记忆类插件（若存在）
跨会话记忆	自动、按需注入	需每次手动粘贴	视实现而定
Token 使用	渐进式披露，约 10 倍节省	整段粘贴，易超限	视实现而定
检索方式	语义 + 关键词混合（Chroma）	无	多为关键词或简单向量
与 Claude Code	深度集成（钩子 + MCP）	无集成	集成深度不一
隐私	<private> 排除	完全本地控制	需看是否本地

为什么选择 Claude-Mem？

• 专为 Claude Code 设计，与会话生命周期和 MCP 工具链深度结合
• 文档与架构清晰（生命周期钩子、Worker、DB、Search 均有说明），便于理解和二次开发
• 开源、活跃（27k+ Stars），社区与迭代可持续
• 支持 OpenClaw 等网关，便于团队或网关级部署

---

项目详细剖析

架构概览

Claude-Mem 由几条主线组成：钩子采集 → Worker 服务 → 存储与检索 → 注入与搜索。

1. 生命周期钩子（5+1）

   在关键时机执行脚本，把「发生了什么」交给 Worker：

   • SessionStart：会话开始，可做初始化或加载上次摘要
   • UserPromptSubmit：用户提交提示前后
   • PostToolUse：每次工具调用之后，提交观察（工具名、输入输出等）
   • Stop：会话被用户停止
   • SessionEnd ：会话正常结束
     另有一个 Smart Install 预检查脚本（依赖等），不属于上述生命周期，但会在安装/启动流程中跑。

2. Worker 服务

   常驻 HTTP 服务，默认端口 37777 ，由 Bun 管理。提供：

   • Web Viewer（记忆流、观察列表、设置）
   • 约 10 个搜索/写入相关 API（如搜索、按 ID 取观察、写记忆等）
   • 与钩子、MCP 工具之间的桥梁

3. SQLite 数据库

   存会话、观察、摘要等结构化数据，并可用 FTS5 做全文检索，支撑关键词路径。

4. Chroma 向量库

   存嵌入，做语义检索；与 SQLite 结合形成混合搜索（关键词 + 语义），提高召回质量。

5. mem-search Skill

   对用户/Claude 暴露「用自然语言搜记忆」的能力，内部走 MCP 工具，并遵循渐进式披露（先索引后详情）。

6. MCP 工具

   供 Claude 在对话中主动查记忆、写记忆，并严格按「search → timeline → get_observations」三层流程，控制 token。

三层检索工作流（MCP Search Tools）

为节省 token，Claude-Mem 把「搜记忆」拆成三步，只对真正需要的观察拉取全文：

1. search

   用自然语言或关键词在记忆索引里搜，返回紧凑列表（含 ID、类型、时间、摘要等），约 50--100 tokens/条。

2. timeline

   围绕某个观察或某次查询，按时间顺序取前后上下文，仍然是相对紧凑的时序视图，便于判断「要不要展开」。

3. get_observations

   根据上两步筛出的 ID 列表 ，批量拉取完整观察内容（约 500--1000 tokens/条）。只在确定相关后才调用，从而在整体上实现约 10 倍 token 节省。

此外：

• save_memory：主动写入一条记忆（如 API 约定、项目决策），参与后续语义检索。
• __IMPORTANT：工作流说明，常驻对 Claude 可见，引导其按三层流程使用，避免一次性拉取大量全文。

示例（逻辑示意，非直接可执行代码）：

// 1. 先搜索引
search(query="authentication bug", type="bugfix", limit=10)

// 2. 看时间线（可选）
timeline(observation_id=123)

// 3. 只取需要的 ID 的全文
get_observations(ids=[123, 456])

// 手动记一条
save_memory(text="API requires auth header X-API-Key", title="API Auth")

配置与扩展

• 配置 ：~/.claude-mem/settings.json，可配置 AI 模型、Worker 端口、数据目录、日志级别、注入策略等。
• 扩展 ：
  • 钩子脚本可自定义，以适配特殊环境或采集需求。
  • 文档中有 Hooks Reference、Architecture Overview、Search Architecture 等，便于做二次开发或与自有系统对接。

系统要求与依赖

• Node.js 18.0.0+
• Claude Code：支持插件的最新版本
• Bun：Worker 与进程管理（缺则自动安装）
• uv：向量搜索相关 Python 依赖（缺则自动安装）
• SQLite 3：本地持久化（通常已内置）

---

项目地址与资源

官方资源

• 🌟 GitHub : github.com/thedotmack/...

相关资源

• OpenClaw 集成指南（网关部署与实时观察流）
• Progressive Disclosure（上下文与 token 优化思路）
• Context Engineering（AI 智能体上下文优化原则）

适用人群

• 日常使用 Claude Code 的开发者：希望减少重复说明、让 AI 记住项目与决策
• 团队或网关管理员：在 OpenClaw 等环境中统一提供持久记忆能力
• 对 AI 记忆、RAG、上下文工程感兴趣的人：可学习其钩子设计、混合检索与渐进式披露实现
• 需要引用与审计的团队：通过观察 ID 与 Web Viewer 追溯「AI 当时看到了什么」

---

欢迎来我中的个人主页找到更多有用的知识和有趣的产品