跳到主要内容
claude-mem · prolist
查看仓库原始简介 Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
来自项目 README 项目解读 README
项目解读由 AI 根据历史资料整理，尚未经人工复核。仓库资料更新于 2026-09-08，与历史解读分开保留。
项目概览 Claude-Mem 是一个为 Claude Code 设计的持久化记忆压缩系统，以插件形式运行。它通过生命周期钩子自动捕获 Claude Code 在编码会话中的所有工具使用行为，利用 Claude Agent SDK 对这些观察数据进行 AI 压缩提炼，生成语义摘要，并在未来的会话中自动注入相关上下文。其核心管线为“观察-压缩-注入”，由 6 个 Hook 覆盖会话生命周期，Worker 服务负责异步处理和 AI 压缩，数据存储采用 SQLite、FTS5 和可选的 ChromaDB 三层架构。系统支持渐进式披露检索，通过 mem-search Skill 或 MCP 工具实现约 10 倍的 token 节省。安装后全自动运行，无需手动操作，并支持通过标签排除敏感内容。
解决什么问题 Claude Code 天然是无状态的，每次启动新会话，它对项目的理解全部从零开始。这导致完全失忆、重复探索、上下文断裂、决策丢失和协作空白等问题。传统替代方案如手动维护 CLAUDE.md、复制粘贴、使用 MCP Memory Server 或项目文档，本质上都在优化“静态知识存储”，无法解决“动态观察记忆”的问题。Claude-Mem 解决的核心问题是：如何在跨会话场景下，让 AI 编程助手保持对项目的持续认知。
工作方式 Claude-Mem 的核心是一个“观察-压缩-注入”管线。它通过 6 个 Hook 脚本对应 Claude Code 的 5 个生命周期事件和 1 个预检查，自动捕获工具调用数据。原始数据存入 SQLite，异步发送到 Worker 服务（Express.js HTTP 服务器，端口 37777），由 Worker 调用 Claude Agent SDK 进行 AI 压缩，提取结构化知识点并写回数据库。下次会话启动时，Context Hook 查询历史记忆并注入上下文。数据存储采用三层架构：SQLite 用于关系存储，FTS5 用于全文搜索，ChromaDB（可选）用于向量语义搜索。
核心能力
零干预：安装后全自动运行，无需手动操作
非侵入：通过 Hook 外部观察，不影响 Claude Code 性能
AI 驱动压缩：用 Claude Agent SDK 对原始数据进行语义提炼
渐进式披露：3 层检索大幅节约 token（约 10 倍节省）
丰富的可视化：Web Viewer UI 实时查看记忆流
多 IDE 支持：Claude Code、Gemini CLI、OpenCode
隐私可控：支持用标签排除敏感内容
混合搜索：FTS5 关键词 + ChromaDB 语义搜索
多 AI 提供商支持：可配置 OpenRouter 或 Gemini
记忆导出与导入：方便备份或迁移
使用前需要了解
AI 整理 · 本地测试，未经人工复核；依据历史报告节选，不代表当前产品状态。
Claude-Mem 核心功能绑定 Claude Code 的 Hook 系统，不能用于其他 AI 工具。AI 压缩依赖 Claude API，离线环境无法使用压缩功能。注入的观察数量有上限（默认 50 条），特别长的项目历史需要搜索而非自动注入。AI 压缩是有损的，可能丢失细节。Worker 服务常驻后台并调用 Claude API，会产生资源消耗和费用。依赖较多，需要 Bun、uv、ChromaDB 等。Windows 兼容性体验不如 macOS/Linux。不建议用于短期一次性脚本编写、对 API 费用极度敏感的场景、需要完全离线运行的环境，以及不使用 Claude Code 的团队。
Claude-Mem 通过自动捕获工具使用观察、生成语义摘要并使其可用于未来会话,无缝保留跨会话的上下文。这使 Claude 能够在会话结束或重新连接后,依然保持对项目知识的连续性。
快速开始 npx claude-mem install --ide opencode
或为 Antigravity CLI 安装(设置指南 ):
npx claude-mem install --ide antigravity
或在 Claude Code 内部从插件市场安装:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
重启 Claude Code。来自先前会话的上下文将自动出现在新会话中。
注意: Claude-Mem 也已发布到 npm,但 npm install -g claude-mem 仅安装 SDK/库本身 —— 它不会注册插件钩子,也不会设置 worker 服务。请始终通过 npx claude-mem install 或上述 /plugin 命令进行安装。
🦞 OpenClaw Gateway 只需一条命令,即可在 OpenClaw 网关上将 claude-mem 安装为持久化内存插件:
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
该安装程序会处理依赖项、插件设置、AI 提供商配置、worker 启动,以及可选的向 Telegram、Discord、Slack 等平台的实时观察推送。详情请参阅 OpenClaw 集成指南 。
🧠 持久化内存 - 上下文跨会话保留
📊 渐进式披露 - 分层内存检索,具有令牌成本可见性
🔍 基于技能的搜索 - 使用 mem-search 技能查询项目历史
🖥️ Web 查看器界面 - 在启动时打印的 worker URL 上实时查看内存流
💻 Claude Desktop 技能 - 从 Claude Desktop 对话中搜索内存
🔒 隐私控制 - 使用 <private> 标签排除敏感内容的存储
⚙️ 上下文配置 - 精细控制注入的上下文内容
🤖 自动操作 - 无需手动干预
🔗 引用 - 通过 worker API 使用 ID 引用过去的观察,或在 Web 查看器中查看全部
文档
入门指南
安装指南 使用指南 搜索工具
最佳实践
上下文工程 渐进式披露
架构
概述 架构演进 钩子架构 钩子参考 Worker 服务 数据库 搜索架构
配置与开发
配置 开发 发布分支 故障排除
工作原理
5 个生命周期钩子 - SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd(6 个钩子脚本)智能安装 - 缓存依赖检查器(预钩子脚本,不是生命周期钩子)Worker 服务 - 本地 HTTP API,带有 Web 查看器界面和搜索端点,由 Bun 管理SQLite 数据库 - 存储会话、观察、摘要mem-search 技能 - 具有渐进式披露的自然语言查询Chroma 向量数据库 - 混合语义 + 关键词搜索,实现智能上下文检索
MCP 搜索工具 Claude-Mem 通过 4 个 MCP 工具 提供智能内存搜索,遵循一种省令牌的三层工作流模式 :
searchtimelineget_observations
Claude 使用 MCP 工具搜索您的内存
首先使用 search 获取结果索引
使用 timeline 查看特定观察周围发生的情况
使用 get_observations 为相关 ID 获取完整详情
通过在获取详情前进行筛选,节省约 10 倍的令牌
searchtimelineget_observations // 步骤 1:搜索索引
search(query="authentication bug", type="bugfix", limit=10)
// 步骤 2:查看索引,识别相关 ID(例如 #123、#456)
// 步骤 3:获取完整详情
get_observations(ids=[123, 456])
发布分支 稳定版发布自 main 分支,并发布到 npm。core-dev 和
community-edge 是用于早期可靠性修复和社区集成的源码运行分支。请参阅
发布分支
系统要求
Node.js : 20.0.0 或更高版本Claude Code : 支持插件的最新版本Bun : JavaScript 运行时和进程管理器(如缺失会自动安装)uv : 用于向量搜索的 Python 包管理器(如缺失会自动安装)SQLite 3 : 用于持久化存储(已内置)
Windows 设置说明 npm : The term 'npm' is not recognized as the name of a cmdlet
配置 设置在 ~/.claude-mem/settings.json 中管理(首次运行时自动创建默认设置)。可配置 AI 模型、worker 端口、数据目录、日志级别和上下文注入设置。
模式与语言配置 Claude-Mem 通过 CLAUDE_MEM_MODE 设置支持多种工作流模式和语言。
工作流行为(例如 code、chill、investigation)
生成观察时所使用的语言
配置方法 编辑位于 ~/.claude-mem/settings.json 的设置文件:
{
"CLAUDE_MEM_MODE": "code--zh"
}
模式定义在 plugin/modes/ 中。要在本地查看所有可用模式:
ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/
可用模式 特定语言模式遵循 code--[lang] 的模式,其中 [lang] 是 ISO 639-1 语言代码(例如中文为 zh,日语为 ja,西班牙语为 es)。
注意:code--zh(简体中文)已内置 —— 无需额外安装或更新插件。
更改模式后
重启 Claude Code 以应用新的模式配置。
开发 详见 开发指南
故障排除 如果遇到问题,向 Claude 描述问题,troubleshoot 技能将自动诊断并提供修复方案。
Bug 报告 cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report
贡献
Fork 仓库
创建功能分支
进行更改并添加测试
更新文档
提交 Pull Request
Claude-Mem 从三个分支发布:main(稳定版)、core-dev 和
community-edge。只有 main 会发布到 npm;其他分支从源码运行。请参阅
发布分支 了解相关策略和本地运行说明。
许可证 Claude-Mem 根据 Apache License 2.0 授权。
我们选择 Apache-2.0 是因为持久化的代理内存应该易于嵌入到
开发者工具、本地代理、MCP 服务器、企业系统、机器人技术栈,
以及生产环境的代理运行框架中。
支持
使用 Claude Agent SDK 构建 | 兼容 Claude Code | 使用 TypeScript 制作
CMEM 是什么? CMEM 是由第三方创建、但获得 Claude-Mem 创建者(Alex Newman,@thedotmack)正式认可的代币。该代币作为社区增长的催化剂,以及将 CMEM 带给最需要它的开发者和知识工作者的载体。
官方 BASE 合约地址:0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3
09.08
