bonza The backend development engineers

Claude-Mem：Claude Code 持久化记忆系统，让 AI 拥有跨会话记忆能力

2026-02-12
来财
ai
           
本文 6558 字，阅读全文约需 19 分钟

🧠 持久化记忆，跨越会话的智能延续

Claude-Mem 是一个专为 Claude Code 设计的持久化记忆压缩系统。它能够自动捕获 Claude 在编码会话中的所有工具使用观察，使用 AI（Claude 的 agent-sdk）进行语义总结，并将相关上下文注入到未来的会话中。这使得 Claude 能够在会话结束或重新连接后仍然保持对项目的连续性知识。

🚀 核心特性

🧠 持久化记忆

  • 跨会话保持：上下文在不同会话间持续存在
  • 自动捕获：无需手动干预，自动记录所有工具使用
  • 语义总结：使用 AI 进行智能内容压缩和总结
  • 上下文注入：在相关会话中自动注入历史上下文

📊 渐进式披露

  • 分层检索：通过多层记忆检索机制优化 token 使用
  • 成本可视化：清晰显示每次检索的 token 成本
  • 智能过滤：只加载最相关的上下文信息
  • 性能优化：避免不必要的数据传输

🔍 基于技能的搜索

  • 自然语言查询：使用 mem-search 技能查询项目历史
  • 语义搜索：基于 Chroma 向量数据库的智能搜索
  • 关键词搜索：SQLite FTS5 全文搜索支持
  • 混合搜索：语义搜索与关键词搜索的完美结合

🖥️ Web 查看器界面

  • 实时监控：在 http://localhost:37777 查看记忆流
  • 可视化界面：直观的 Web UI 管理界面
  • 实时更新：实时显示记忆捕获和检索状态
  • 配置管理：通过 Web 界面管理系统设置

💻 Claude Desktop 技能

  • 跨平台支持：支持 Claude Desktop 客户端
  • 统一体验：在 Claude Desktop 中搜索历史记忆
  • 无缝集成：与 Claude Code 完美配合
  • 多端同步：多个客户端之间的记忆同步

🔒 隐私控制

  • 标签过滤：使用标签排除敏感内容的存储
  • 选择性存储：精确控制哪些内容被记录
  • 数据安全：本地存储，数据不会上传到云端
  • 权限管理：细粒度的数据访问控制

⚙️ 上下文配置

  • 精细控制：对上下文注入进行精细化管理
  • 自定义规则：根据项目需求定制上下文规则
  • 动态调整：根据使用情况动态优化配置
  • 性能调优：平衡记忆完整性和性能

🤖 自动化操作

  • 零干预：无需手动操作，全自动运行
  • 智能触发：根据会话状态智能触发记忆操作
  • 后台处理：在后台静默处理记忆任务
  • 实时响应：实时响应用户操作和系统事件

🔗 引用系统

  • ID 引用：通过 ID 引用历史观察记录
  • API 访问：通过 http://localhost:37777/api/observation/{id} 访问
  • 完整记录：在 Web 查看器中查看所有记录
  • 追溯能力：完整的操作历史追溯

🧪 Beta 版本

  • 实验性功能：尝试 Endless Mode 等实验性功能
  • 版本切换：通过 Web 界面在稳定版和 Beta 版之间切换
  • 前沿特性：体验最新的记忆架构和技术
  • 反馈渠道：为实验性功能提供反馈

📋 快速开始

🚀 安装步骤

第一步：安装插件

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

第二步：重启 Claude Code

重启 Claude Code 后，之前会话的上下文将自动出现在新会话中。

第三步：访问 Web 界面

打开 http://localhost:37777 查看实时记忆流和管理界面。

🎯 核心组件

生命周期钩子 (5个)

  • SessionStart：会话开始时的钩子
  • UserPromptSubmit：用户提交提示时的钩子
  • PostToolUse：工具使用后的钩子
  • Stop：会话停止时的钩子
  • SessionEnd：会话结束时的钩子

智能安装

  • 缓存依赖检查器：预钩子脚本，检查依赖项
  • 自动安装：自动安装缺失的依赖项
  • 版本管理：管理依赖项版本兼容性

工作服务

  • HTTP API：在端口 37777 上提供 API 服务
  • Web 查看器：提供可视化的管理界面
  • 搜索端点：10 个搜索端点支持不同查询需求
  • Bun 管理：使用 Bun 进行进程管理

数据库系统

  • SQLite 数据库：存储会话、观察和摘要
  • 会话管理：完整的会话生命周期管理
  • 观察记录：详细的观察记录存储
  • 摘要生成：自动生成语义摘要

记忆搜索技能

  • 自然语言查询：支持自然语言查询
  • 渐进式披露：分层记忆检索策略
  • 智能过滤：智能过滤相关结果
  • 上下文感知：感知当前会话上下文

向量数据库

  • Chroma 向量数据库：支持语义搜索
  • 混合搜索：语义搜索与关键词搜索结合
  • 智能检索：基于相关性的智能检索
  • 性能优化：优化搜索性能和准确性

🔍 MCP 搜索工具

📊 3 层工作流模式

Claude-Mem 通过 5 个 MCP 工具提供智能记忆搜索，采用 token 高效的 3 层工作流模式：

第一层：搜索索引

  • search：获取紧凑索引（约 50-100 tokens/结果）
  • 快速概览：快速获取相关结果的概览
  • ID 获取：获取感兴趣结果的 ID
  • 类型过滤：按类型、日期、项目过滤

第二层：时间线上下文

  • timeline：获取特定观察周围的按时间顺序的上下文
  • 环境理解：理解观察发生时的环境
  • 关联分析：分析相关观察之间的关联
  • 上下文重建：重建观察发生时的完整上下文

第三层：详细获取

  • get_observations：仅获取过滤后 ID 的完整详情（约 500-1,000 tokens/结果）
  • 批量操作：批量获取多个观察的详细信息
  • 完整内容：获取观察的完整内容和元数据
  • 深度分析：支持对观察的深度分析

🛠️ 可用 MCP 工具

search - 搜索记忆索引

# 基础搜索
search(query="authentication bug", type="bugfix", limit=10)

# 按日期搜索
search(query="API changes", date="2024-01-01", limit=20)

# 按项目搜索
search(query="database migration", project="myproject", limit=15)

timeline - 时间线上下文

# 获取特定观察的上下文
timeline(observation_id=123)

# 获取查询结果的时间线上下文
timeline(query="user authentication", time_range="1h")

get_observations - 获取详细观察

# 批量获取观察详情
get_observations(ids=[123, 456, 789])

# 获取特定类型的观察
get_observations(ids=[123, 456], include_metadata=true)

save_memory - 手动保存记忆

# 保存重要信息
save_memory(text="API requires auth header X-API-Key", title="API Auth")

# 保存项目配置
save_memory(text="Database connection string: postgresql://localhost/mydb", title="DB Config")

__IMPORTANT - 工作流文档

  • 始终可见：工作流文档始终对 Claude 可见
  • 使用指南：提供详细的使用指南和最佳实践
  • 示例代码：包含丰富的示例代码和用例
  • 性能提示：提供性能优化建议

💡 使用示例

完整工作流示例

// 步骤 1：搜索索引
search(query="authentication bug", type="bugfix", limit=10)

// 步骤 2：审查索引，识别相关 ID（例如 #123, #456）

// 步骤 3：获取完整详情
get_observations(ids=[123, 456])

// 手动保存重要信息
save_memory(text="API requires auth header X-API-Key", title="API Auth")

实际应用场景

// 搜索历史 bug 修复
search(query="memory leak", type="bugfix", limit=5)

// 查看相关时间线
timeline(observation_id=789)

// 获取详细信息
get_observations(ids=[789, 790, 791])

// 保存新发现
save_memory(text="Fixed memory leak in image processing module", title="Bug Fix")

🧪 Beta 功能

🔄 Endless Mode

  • 生物拟态记忆架构：模拟生物记忆系统的持久性
  • 扩展会话支持：支持长时间运行的会话
  • 智能记忆管理：智能管理长期记忆
  • 性能优化：针对长时间运行的性能优化

📊 版本切换

  • Web 界面切换：通过 http://localhost:37777 → Settings 切换版本
  • 稳定版优先：生产环境推荐使用稳定版
  • Beta 版体验：开发环境可以尝试 Beta 版功能
  • 回滚机制：支持版本回滚和切换

🔧 系统要求

💻 基础要求

  • Node.js：18.0.0 或更高版本
  • Claude Code：支持插件的最新版本
  • Bun：JavaScript 运行时和进程管理器（如缺失会自动安装）
  • uv：Python 包管理器，用于向量搜索（如缺失会自动安装）
  • SQLite 3：持久化存储（内置）

🪟 Windows 设置注意

如果在 Windows 上遇到类似于以下错误：

npm : The term 'npm' is not recognized as the name of a cmdlet

请确保已安装 Node.js 和 npm 并将其添加到 PATH 中。从 https://nodejs.org 下载最新的 Node.js 安装程序，安装后重启终端。

⚙️ 配置管理

📁 配置文件位置

设置管理在 ~/.claude-mem/settings.json 中（首次运行时自动创建并使用默认值）。

🎯 可配置项

  • AI 模型配置：选择使用的 AI 模型和参数
  • 工作端口：配置 HTTP API 服务端口（默认 37777）
  • 数据目录：指定数据存储目录
  • 日志级别：配置日志输出详细程度
  • 上下文注入设置：精细控制上下文注入行为

📋 配置示例

{
  "aiModel": "claude-3-sonnet",
  "workerPort": 37777,
  "dataDirectory": "~/.claude-mem/data",
  "logLevel": "info",
  "contextInjection": {
    "maxTokens": 4000,
    "relevanceThreshold": 0.7,
    "excludeTags": ["sensitive", "private"]
  }
}

🏗️ 架构概览

🎯 系统组件

  • 生命周期钩子：5 个钩子脚本管理会话生命周期
  • 工作服务：HTTP API 和 Web 界面服务
  • 数据库层：SQLite 存储和 Chroma 向量搜索
  • 搜索系统：混合语义和关键词搜索
  • 记忆技能：自然语言查询和渐进式披露

🔄 数据流

  1. 会话开始 → SessionStart 钩子触发
  2. 用户输入 → UserPromptSubmit 钩子记录
  3. 工具使用 → PostToolUse 钩子捕获观察
  4. 语义处理 → AI 生成摘要和索引
  5. 存储 → SQLite 和 Chroma 存储
  6. 检索 → 搜索工具查询历史记忆
  7. 注入 → 相关上下文注入新会话

📈 性能优化

🚀 Token 效率

  • 分层检索：通过过滤减少 10 倍 token 使用
  • 智能过滤：只加载最相关的上下文
  • 渐进式披露：按需加载详细信息
  • 缓存机制：智能缓存常用查询结果

📊 存储优化

  • 压缩存储：智能压缩存储历史记录
  • 索引优化：优化搜索索引结构
  • 清理策略：自动清理过期和无关数据
  • 备份机制：定期备份重要数据

🛠️ 开发与贡献

🔧 开发环境

  • TypeScript：主要开发语言
  • Node.js：运行时环境
  • Bun：进程管理器
  • SQLite：数据存储
  • Chroma：向量数据库

📝 贡献流程

  1. Fork 仓库
  2. 创建功能分支
  3. 进行更改并添加测试
  4. 更新文档
  5. 提交 Pull Request

🐛 错误报告

使用自动化生成器创建全面的错误报告：

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

📄 许可证

📜 AGPL-3.0 许可证

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。

版权所有 © 2025 Alex Newman (@thedotmack)。保留所有权利。

📋 许可证含义

  • 自由使用：可以自由使用、修改和分发本软件
  • 网络部署：如果在网络服务器上修改和部署，必须提供源代码
  • 衍生作品：衍生作品也必须采用 AGPL-3.0 许可证
  • 无担保：本软件不提供任何担保

🔒 Ragtime 许可证

ragtime/ 目录单独采用 PolyForm Noncommercial License 1.0.0 许可证。详见 ragtime/LICENSE 文件。

🆘 支持与社区

📚 文档资源

  • 完整文档：https://docs.claude-mem.ai/
  • 安装指南：快速开始和高级安装说明
  • 使用指南：Claude-Mem 自动工作原理
  • 搜索工具：使用自然语言查询项目历史
  • Beta 功能：尝试 Endless Mode 等实验性功能

🌐 社区支持

  • GitHub Issues：报告问题和功能请求
  • 官方 X 账号：@Claude_Memory
  • 官方 Discord：https://discord.com/invite/J4wttp9vDu
  • 作者：Alex Newman (@thedotmack)

📖 最佳实践

  • 上下文工程：AI 代理上下文优化原则
  • 渐进式披露：Claude-Mem 上下文注入策略哲学
  • 架构指南：系统组件和数据流详解
  • 配置指南：环境变量和设置详解

🎯 应用场景

👨‍💻 个人开发者

  • 项目记忆：保持对长期项目的上下文理解
  • 学习记录：记录学习过程中的重要发现
  • 问题解决：快速回顾类似问题的解决方案
  • 代码复用：找到类似的代码实现和模式

👥 团队协作

  • 知识共享：团队成员间共享项目知识
  • 经验传承：保留有价值的开发经验
  • 问题追溯：快速定位和解决历史问题
  • 最佳实践：记录和推广最佳实践

🏢 企业应用

  • 知识管理：企业级知识库建设
  • 培训支持：新员工培训和支持
  • 质量保证：提高代码质量和一致性
  • 效率提升：减少重复工作和错误

🚀 未来发展

📈 功能路线图

  • 更多 AI 模型支持：支持更多 AI 服务提供商
  • 高级搜索功能：更智能的搜索和过滤选项
  • 可视化增强：更丰富的数据可视化功能
  • 集成扩展：与更多开发工具集成

🔮 技术演进

  • 记忆架构优化：更高效的记忆存储和检索
  • 性能提升：持续优化系统性能
  • 用户体验：改进用户界面和交互体验
  • 生态系统：构建完整的开发工具生态

🎉 总结

Claude-Mem 通过其创新的持久化记忆系统，彻底改变了 Claude Code 的使用体验。它不仅解决了 AI 会话间上下文丢失的问题，还通过智能的记忆管理和搜索功能，大大提升了开发效率和代码质量。

🎯 核心价值

  1. 连续性：跨越会话的知识连续性
  2. 智能化：AI 驱动的记忆压缩和检索
  3. 效率性：显著减少重复工作和时间浪费
  4. 可扩展性：支持大型项目和长期开发
  5. 用户友好：简单易用的界面和操作

🚀 技术优势

  • 自动化：全自动的记忆捕获和管理
  • 智能化：基于 AI 的语义理解和总结
  • 高效性：优化的 token 使用和性能表现
  • 可靠性：稳定的数据存储和检索机制
  • 灵活性：丰富的配置选项和自定义能力

Claude-Mem 代表了 AI 辅助开发工具的未来方向，让 AI 真正成为开发者的长期合作伙伴，而不仅仅是临时的助手。

本文基于 Claude-Mem 项目的官方 README 文件整理，更多详细信息请参考项目 GitHub 仓库和官方文档。

原文地址 https://blog.bonza.cn/2026/02/12/claude-mem-persistent-memory-system/

Similar Posts

上一篇 Lingti Bot：极简至上的 AI 机器人平台，零依赖部署方案

下一篇 Prompt Optimizer：强大的AI提示词优化工具，助力编写高质量提示词

Comments

Content