claude-mem
Claude-Mem 通过自动捕获工具使用观察、生成语义摘要并使其可用于未来会话,无缝保留跨会话的上下文。
这使 Claude 能够在会话结束或重新连接后仍保持对项目的知识连续性。
快速开始
在终端中启动新的 Claude Code 会话并输入以下命令:
> /plugin marketplace add thedotmack/claude-mem
> /plugin install claude-mem
重启 Claude Code。来自先前会话的上下文将自动出现在新会话中。
核心特性:
- 🧠 持久化内存 - 上下文跨会话保留
- 📊 渐进式披露 - 分层内存检索,具有令牌成本可见性
- 🔍 基于技能的搜索 - 使用 mem-search 技能查询项目历史
- 🖥️ Web 查看器界面 - 在 http://localhost:37777 实时查看内存流
- 💻 Claude Desktop 技能 - 从 Claude Desktop 对话中搜索内存
- 🔒 隐私控制 - 使用
<private>标签排除敏感内容的存储 - ⚙️ 上下文配置 - 精细控制注入的上下文内容
- 🤖 自动操作 - 无需手动干预
- 🔗 引用 - 使用 ID 引用过去的观察(通过 http://localhost:37777/api/observation/{id} 访问,或在 http://localhost:37777 的 Web 查看器中查看全部)
- 🧪 测试版渠道 - 通过版本切换尝试实验性功能,如无尽模式
文档
📚 查看完整文档 - 在官方网站浏览
入门指南
最佳实践
架构
- 概述 - 系统组件与数据流
- 架构演进 - 从 v3 到 v5 的旅程
- 钩子架构 - Claude-Mem 如何使用生命周期钩子
- 钩子参考 - 7 个钩子脚本详解
- Worker 服务 - HTTP API 与 Bun 管理
- 数据库 - SQLite 模式与 FTS5 搜索
- 搜索架构 - 使用 Chroma 向量数据库的混合搜索
配置与开发
工作原理
核心组件:
- 5 个生命周期钩子 - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd(6 个钩子脚本)
- 智能安装 - 缓存依赖检查器(预钩子脚本,不是生命周期钩子)
- Worker 服务 - 在端口 37777 上的 HTTP API,带有 Web 查看器界面和 10 个搜索端点,由 Bun 管理
- SQLite 数据库 - 存储会话、观察、摘要
- mem-search 技能 - 具有渐进式披露的自然语言查询
- Chroma 向量数据库 - 混合语义 + 关键词搜索,实现智能上下文检索
详见架构概述。
mem-search 技能
Claude-Mem 通过 mem-search 技能提供智能搜索,当您询问过去的工作时会自动调用:
工作方式:
- 只需自然提问:“上次会话我们做了什么?” 或 “我们之前修复过这个 bug 吗?”
- Claude 自动调用 mem-search 技能查找相关上下文
可用搜索操作:
- 搜索观察 - 跨观察的全文搜索
- 搜索会话 - 跨会话摘要的全文搜索
- 搜索提示 - 搜索原始用户请求
- 按概念搜索 - 按概念标签查找(发现、问题-解决方案、模式等)
- 按文件搜索 - 查找引用特定文件的观察
- 按类型搜索 - 按类型查找(决策、bug修复、功能、重构、发现、更改)
- 最近上下文 - 获取项目的最近会话上下文
- 时间线 - 获取特定时间点周围的统一上下文时间线
- 按查询的时间线 - 搜索观察并获取最佳匹配周围的时间线上下文
- API 帮助 - 获取搜索 API 文档
自然语言查询示例:
"What bugs did we fix last session?"
"How did we implement authentication?"
"What changes were made to worker-service.ts?"
"Show me recent work on this project"
"What was happening when we added the viewer UI?"
详见搜索工具指南的详细示例。
测试版功能
Claude-Mem 提供测试版渠道,包含实验性功能,如无尽模式(用于扩展会话的仿生记忆架构)。从 Web 查看器界面 http://localhost:37777 → 设置 切换稳定版和测试版。
详见 测试版功能文档 了解无尽模式的详细信息和试用方法。
系统要求
- Node.js: 18.0.0 或更高版本
- Claude Code: 支持插件的最新版本
- Bun: JavaScript 运行时和进程管理器(如缺失会自动安装)
- uv: 用于向量搜索的 Python 包管理器(如缺失会自动安装)
- SQLite 3: 用于持久化存储(已内置)
配置
设置在 ~/.claude-mem/settings.json 中管理(首次运行时自动创建默认设置)。可配置 AI 模型、worker 端口、数据目录、日志级别和上下文注入设置。
详见 配置指南 了解所有可用设置和示例。
开发
详见 开发指南 了解构建说明、测试和贡献工作流程。
故障排除
如果遇到问题,向 Claude 描述问题,troubleshoot 技能将自动诊断并提供修复方案。
详见 故障排除指南 了解常见问题和解决方案。
Bug 报告
使用自动生成器创建全面的 bug 报告:
cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
贡献
欢迎贡献!请:
- Fork 仓库
- 创建功能分支
- 进行更改并添加测试
- 更新文档
- 提交 Pull Request
详见开发指南了解贡献工作流程。
许可证
本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可。
Copyright (C) 2025 Alex Newman (@thedotmack)。保留所有权利。
详见 LICENSE 文件了解完整详情。
这意味着什么:
- 您可以自由使用、修改和分发本软件
- 如果您修改并部署到网络服务器上,必须公开您的源代码
- 衍生作品也必须采用 AGPL-3.0 许可
- 本软件不提供任何保证
关于 Ragtime 的说明: ragtime/ 目录单独采用 PolyForm Noncommercial License 1.0.0 许可。详见 ragtime/LICENSE。
支持
- 文档: docs/
- 问题反馈: GitHub Issues
- 仓库: github.com/thedotmack/claude-mem
- 作者: Alex Newman (@thedotmack)
| 使用 Claude Agent SDK 构建 | 由 Claude Code 驱动 | 使用 TypeScript 制作 |
