作者前言如果你曾经在使用 Claude Code 时感到沮丧——每次新会话都要重新解释项目背景、重复之前的决策、忘记上周修复的 Bug 细节——那么 Claude-Mem 就是为你准备的。这个拥有 17k Star 的开源项目正在重新定义 AI 辅助编程的边界。目录一、为什么需要 Claude-Mem二、Claude-Mem 是什么三、核心功能特性详解四、技术架构深度解析五、安装与配置完全指南六、实战场景演示七、高级功能与最佳实践八、与原生 Claude Code 的对比九、总结与展望一、为什么需要 Claude-Mem1.1 AI 的失忆症痛点在使用 Claude Code 进行开发时你或许遇到过这些场景场景一周一你花了一小时向 Claude 解释项目架构、数据库表结构、 编码规范。周五再次打开项目Claude 完全不记得这些上下文。 场景二上周你和 Claude 一起修复了一个棘手的并发 Bug 今天类似问题再次出现Claude 却无法参考之前的解决方案。 场景三团队成员用 Claude 完成了一个复杂功能 其他成员无法从 Claude 中获得任何关于这个功能的背景知识。根本问题Claude Code 的上下文窗口在会话结束后完全清空无法跨会话保留记忆。1.2 现有解决方案的局限方案局限性手动维护 CLAUDE.md需要人工整理容易过时无法捕获细节复制粘贴历史记录繁琐、不可持续、信息丢失严重商业记忆服务价格昂贵、隐私风险、 vendor lock-inClaude-Mem 的出现正是为了解决这些痛点。二、Claude-Mem 是什么2.1 项目概览项目信息详情项目名称claude-mem开发者thedotmackGitHub 地址https://github.com/thedotmack/claude-mem官方网站https://claude-mem.ai开源协议AGPL-3.0Star 数量17k主要语言TypeScript/JavaScript最新版本v10.3.12026年2月系统支持Windows / macOS / Linux2.2 一句话定义Claude-Mem 是一个专为 Claude Code 设计的持久化记忆压缩系统通过自动捕获工具使用观察、生成语义摘要并将其注入未来会话实现真正的跨会话上下文连续性。2.3 核心价值主张传统 Claude Code: [会话1] *** 遗忘 *** [会话2] *** 遗忘 *** [会话3] 安装 Claude-Mem: [会话1] → [记忆存储] → [会话2] → [记忆存储] → [会话3] ↑____________自动注入____________↑三、核心功能特性详解3.1 持久化记忆Persistent Memory工作原理会话期间Claude-Mem 通过生命周期钩子自动捕获所有工具调用会话结束时AI 自动生成语义摘要新会话启动时相关记忆自动注入上下文效果新功能开发时间缩短40%新成员上手时间从3周→3天3.2 渐进式披露Progressive Disclosure这是 Claude-Mem 的核心设计哲学灵感来自人类记忆的工作方式。三层检索策略第一层索引层轻量级 ├── 观察记录标题 ├── 类型标签bugfix/feature/decision ├── 时间戳 └── Token 成本~50-100 tokens/结果 第二层上下文层按需加载 ├── 时间线上下文 ├── 相关代码片段 └── Token 成本~200-500 tokens/结果 第三层完整细节层精确回忆 ├── 完整的工具输出 ├── 原始代码片段 └── Token 成本~500-1000 tokens/结果优势相比传统一次性加载所有上下文节省约10倍 Token。3.3 智能语义搜索Claude-Mem 提供自然语言搜索能力无需记住精确的关键词。搜索示例// 方式一自然语言查询推荐上次我们如何修复了身份验证的 Bug我们之前关于数据库索引的决策是什么这个模块之前做过类似的重构吗// 方式二结构化搜索精确控制search(query:authentication bug,type:bugfix,limit:10)// 方式三时间线查询timeline(sessionId:abc-123)搜索类型支持搜索类型说明示例概念标签搜索按主题查找“关于 API 设计的讨论”文件引用搜索按文件查找“worker-service.ts 的修改记录”观察类型搜索按类型筛选“显示所有 bugfix 记录”时间线搜索按会话查看“上周一的会话内容”3.4 可视化 Web 管理界面安装后访问http://localhost:37777即可使用。界面功能┌─────────────────────────────────────────────────────┐ │ Claude-Mem Web Viewer │ ├─────────────────────────────────────────────────────┤ │ [仪表板] [搜索] [会话] [设置] │ │ │ │ 最近记忆: │ │ [Critical] 修复了支付接口并发问题 - 2小时前 │ │ [Decision] 选择 PostgreSQL 作为主数据库 - 昨天 │ │ [Info] 添加了用户注册 API - 3天前 │ │ │ │ 统计信息: │ │ 总观察记录: 1,247 │ │ 总会话数: 89 │ │ 数据库大小: 45.7 MB │ └─────────────────────────────────────────────────────┘3.5 隐私保护机制Claude-Mem 提供多层隐私保护隐私标签private数据库密码supersecret123 API 密钥sk_live_abc123 内部服务器地址192.168.1.100/private被private标签包裹的内容不会被记录。工具过滤配置// ~/.claude-mem/settings.json{skipTools:[ListMcpResourcesTool,SlashCommand,AskUserQuestion]}配置后这些工具的执行结果不会被记录。四、技术架构深度解析4.1 系统架构图┌─────────────────────────────────────────────────────────────┐ │ Claude Code 会话 │ │ (用户输入 → Claude 处理 → 工具调用 → 结果返回) │ └─────────────────────────────────────────────────────────────┘ ↓ 触发 ┌─────────────────────────────────────────────────────────────┐ │ 生命周期钩子 (Lifecycle Hooks) │ │ SessionStart │ UserPromptSubmit │ PostToolUse │ Stop │ └─────────────────────────────────────────────────────────────┘ ↓ 捕获 ┌─────────────────────────────────────────────────────────────┐ │ Worker 服务 (端口 37777) │ │ ├── HTTP API 服务器 │ │ ├── 观察记录处理器 │ │ ├── AI 摘要生成器 │ │ └── 搜索索引维护 │ └─────────────────────────────────────────────────────────────┘ ↓ 存储 ┌─────────────────────────────────────────────────────────────┐ │ 双数据库存储系统 │ │ ┌─────────────┐ ┌─────────────────────────────┐ │ │ │ SQLite DB │ │ Chroma 向量数据库 │ │ │ │ (结构化) │ │ (语义搜索) │ │ │ │ · 观察记录 │ │ · 向量嵌入 │ │ │ │ · 会话信息 │ │ · 语义索引 │ │ │ │ · 摘要 │ │ · 混合搜索 │ │ │ └─────────────┘ └─────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ↓ 注入 ┌─────────────────────────────────────────────────────────────┐ │ 下次会话启动时自动注入上下文 │ │ 根据您之前的工作我注意到您正在继续开发... │ └─────────────────────────────────────────────────────────────┘4.2 五大生命周期钩子详解钩子名称触发时机执行内容技术实现SessionStartClaude Code 启动启动 Worker 服务检索最近观察记录注入相关上下文调用/api/session/startUserPromptSubmit用户发送消息记录用户原始提示关联当前会话写入 SQLiteprompts表PostToolUse工具执行完成捕获工具名称、参数、输出、执行时间JSON 格式存储到observations表StopClaude 停止任务生成当前会话的 AI 驱动摘要调用 Claude API 生成摘要SessionEnd会话完全结束标记会话完成确保数据持久化更新会话状态为completed4.3 双数据库存储设计SQLite 数据库结构化存储位置~/.claude-mem/claude-mem.db核心表结构-- 会话表CREATETABLEsessions(idTEXTPRIMARYKEY,start_timeINTEGER,end_timeINTEGER,summaryTEXT,project_pathTEXT);-- 观察记录表支持全文搜索CREATEVIRTUALTABLEobservationsUSINGfts5(id,session_id,tool_name,input,output,timestamp,type,contentobservations_content);-- 摘要表CREATETABLEsummaries(idTEXTPRIMARYKEY,session_idTEXT,contentTEXT,model_usedTEXT,generated_atINTEGER);Chroma 向量数据库语义搜索位置~/.claude-mem/chroma/功能存储观察记录的向量嵌入embedding支持混合语义 关键词搜索根据含义而非仅关键词查找相关内容搜索流程用户查询 → 生成查询向量 → Chroma 相似度搜索 → 返回 Top-K 结果4.4 AI 压缩引擎Claude-Mem 使用 AI 模型对原始观察记录进行智能压缩。压缩策略原始观察记录 (可能 10,000 tokens) ↓ AI 压缩 语义摘要 (约 500-1000 tokens) ↓ 提取 关键学习点 (约 100-200 tokens)观察记录结构{id:obs_abc123,sessionId:sess_xyz789,toolName:Edit,input:{filePath:src/auth.ts,oldString:...,newString:...},output:File edited successfully.,timestamp:1709875200000,type:code_change,summary:修复了身份验证中间件的逻辑错误}五、安装与配置完全指南5.1 系统要求依赖项最低要求推荐配置Node.js18.0.022.x LTSClaude Code支持插件的最新版最新版Bun 运行时自动安装v1.0uv (Python)自动安装v0.1RAM4GB8GB磁盘空间100MB1GB5.2 安装方式一插件市场安装推荐# 步骤1启动 Claude Codeclaude# 步骤2添加插件市场/plugin marketplaceaddthedotmack/claude-mem# 步骤3安装插件/plugininstallclaude-mem# 步骤4重启 Claude Code# (将自动启动 Worker 服务)安装后验证# 检查 Worker 服务是否运行curlhttp://localhost:37777/api/health# 预期输出{status:ok,version:10.3.1,database:connected}5.3 安装方式二源码安装开发者选项# 克隆仓库gitclone https://github.com/thedotmack/claude-mem.gitcdclaude-mem# 安装依赖npminstall# 构建项目npmrun build# 启动 Worker 服务npmrun worker:start# 查看实时日志npmrun worker:logs5.4 配置详解配置文件位置~/.claude-mem/settings.json完整配置示例{provider:claude,model:claude-sonnet-4-5-20250929,workerPort:37777,dataDir:~/.claude-mem,logLevel:info,contextObservations:10,skipTools:[ListMcpResourcesTool,SlashCommand],privacyTags:[private,secret],compressionEnabled:true,semanticSearchEnabled:true,autoContextInjection:true}配置参数说明参数类型默认值说明providerstring“claude”AI 服务提供商modelstring“claude-sonnet-4-5”摘要生成使用的模型workerPortnumber37777Worker 服务端口dataDirstring“~/.claude-mem”数据目录logLevelstring“info”日志级别 (error/warn/info/debug)contextObservationsnumber10每次注入的观察记录数量compressionEnabledbooleantrue是否启用 AI 压缩semanticSearchEnabledbooleantrue是否启用语义搜索5.5 环境变量配置# 自定义数据目录exportCLAUDEMEM_DATA_DIR/path/to/custom/dir# 自定义 Worker 端口exportCLAUDEMEM_PORT37778# 自定义日志级别exportCLAUDEMEM_LOG_LEVELdebug# 指定 AI 提供商exportCLAUDEMEM_AI_PROVIDERclaude六、实战场景演示6.1 场景一长期项目的上下文连续性第一次会话项目初始化$ claude帮我创建一个美发预约系统需要1. 用户注册登录JWT 认证2. 服务项目管理3. 在线预约功能4. 管理员仪表板Claude 完成开发后Claude-Mem 自动记录项目架构决策数据库表结构设计API 端点定义关键代码实现第二次会话功能扩展一周后$ claude早上好我们之前做了什么项目Claude 的回答由 Claude-Mem 注入的上下文支持根据之前的会话记录我们创建了一个美发预约系统包括以下模块 1. 认证模块 (src/auth/) - 使用 JWT 认证 2. 服务管理模块 (src/services/) - 支持 CRUD 操作 3. 预约模块 (src/bookings/) - 支持时间冲突检测 4. 管理员模块 (src/admin/) - 提供仪表板 API 现在您可以继续开发我会参考之前的架构决策...6.2 场景二Bug 修复的历史参考问题场景你这个并发问题之前好像遇到过当时是怎么解决的 Claude(通过 claude-mem 搜索) 根据 2026-02-15 的记录您之前遇到过类似的并发问题 问题支付接口的并发重复扣款 解决方案 1. 添加数据库行级锁 (SELECT ... FOR UPDATE) 2. 实现幂等性令牌机制 3. 添加 Redis 分布式锁作为二级保护 相关文件src/payments/processor.ts 提交的修复commit a1b2c3d6.3 场景三团队协作知识共享Claude-Mem 支持项目级记忆共享。配置项目级记忆# 在项目根目录创建配置echo{ claudeMem: { scope: project, shareWith: [team-member1, team-member2] } }.claude-mem.json效果开发者A: 完成了用户认证模块的重构 ↓ Claude-Mem 记录重构决策、新架构、迁移步骤 ↓ 开发者B: (一周后) 需要理解新的认证流程 ↓ Claude: (通过项目级记忆) 自动提供完整背景七、高级功能与最佳实践7.1 无尽模式Endless Mode问题背景标准 Claude Code 会话的限制约 50 次工具调用后达到上下文限制每个工具输出可能包含 1,000-10,000 tokens复杂度O(N²)每次响应需重新合成所有历史无尽模式的解决方案传统模式: [工具1输出] → [工具2输出] → [工具3输出] → ... → 上下文溢出 无尽模式: [工作记忆] ← 压缩 → [存档记忆(磁盘)] ↓ ↓ 当前上下文 按需召回性能对比指标标准模式无尽模式上下文窗口使用~100% (50工具后)~5%支持的工具体数~50~1000复杂度O(N²)O(N)观察记录大小10,000 tokens~500 tokens (压缩后)启用无尽模式1. 访问 http://localhost:37777 2. 点击 Settings 3. 找到 Endless Mode (Beta) 4. 切换开关启用注意无尽模式目前处于 Beta 阶段每个工具观察生成可能有 60-90 秒延迟。7.2 分布式上下文生成Claude-Mem 集成了Live Context 系统支持自动生成和维护CLAUDE.md。自动生成示例# 在项目根目录运行请帮我生成项目的 CLAUDE.md 文档Claude-Mem 自动分析项目结构核心依赖编码规范构建命令测试命令生成标准化的CLAUDE.md供所有团队成员使用。7.3 MCP 工具集成Claude-Mem 提供5 个 MCP 工具遵循三层工作流模式。工具列表工具名称功能使用场景search获取紧凑索引第一步快速筛选相关记忆timeline获取时间线上下文第二步理解记忆的演变get_observations获取完整详情第三步深入特定记忆save_memory手动保存重要信息随时保存关键决策workflow查看工作流文档参考了解最佳实践完整使用流程// 第1步搜索相关记忆获取索引search(query:身份验证实现,limit:10)// 返回[{id: 123, title: JWT 认证实现, type: feature, time: 2天前}, ...]// 第2步查看时间线理解上下文timeline(sessionId:sess_xyz)// 返回按时间排序的相关观察记录// 第3步获取完整详情深入研究get_observations(ids:[123,456])// 返回完整的工具输出、代码片段、决策理由7.4 实时观察馈送Live FeedClaude-Mem 支持将实时观察记录馈送到团队协作平台。支持的集成// Telegram 集成curl-XPOSThttps://api.telegram.org/botTOKEN/sendMessage \-d chat_idCHAT_ID\-d text [Claude-Mem] 修复了支付并发问题// Discord 集成curl-XPOSThttps://discord.com/api/webhooks/ID/TOKEN\-d content [Decision] 选择 PostgreSQL 作为主数据库配置实时馈送// ~/.claude-mem/settings.json{liveFeed:{enabled:true,platform:telegram,webhookUrl:https://api.telegram.org/bot...,filters:{types:[bugfix,decision],minPriority:medium}}}八、与原生 Claude Code 的对比8.1 功能对比表功能维度原生 Claude CodeClaude-Mem跨会话记忆❌ 不支持✅ 自动持久化语义搜索❌ 不支持✅ 混合语义关键词上下文注入⚠️ 仅当前会话✅ 自动跨会话注入记忆可视化❌ 无✅ Web 查看器隐私控制⚠️ 基础✅ 多层隐私保护团队协作❌ 不支持✅ 项目级记忆共享Token 优化⚠️ 手动管理✅ 渐进式披露长期项目管理❌ 困难✅ 专为长期设计8.2 性能对比场景两周后继续之前的项目原生 Claude Code时间成本 - 重新解释项目背景15-30分钟 - 回忆之前的决策10-20分钟 - 查找之前的代码5-15分钟 总计30-65分钟 Token 成本 - 项目背景文档~2000 tokens - 代码解释~3000 tokens - 问答交互~1000 tokens 总计~6000 tokens使用 Claude-Mem时间成本 - Claude 自动注入上下文0分钟后台完成 - 确认理解1-2分钟 总计1-2分钟 Token 成本 - 压缩后的观察记录~500 tokens - 精确召回详情~1000 tokens (按需) 总计~500-1500 tokens效率提升时间节省95%Token 节省75%。九、总结与展望9.1 Claude-Mem 的核心价值┌─────────────────────────────────────────────────┐ │ Claude-Mem 价值三角 │ ├─────────────────────────────────────────────────┤ │ │ │ 持久化记忆 │ │ ↓ │ │ 智能语义搜索 ← → 可视化管理的项目背景 │ │ ↓ │ │ 开发效率提升 │ │ │ └─────────────────────────────────────────────────┘9.2 适用场景推荐用户类型推荐指数主要收益长期项目开发者⭐⭐⭐⭐⭐上下文连续性无需重复解释开源项目维护者⭐⭐⭐⭐⭐历史决策可追溯Issue 处理更高效团队协作开发⭐⭐⭐⭐知识共享新成员快速上手学习新技术的开发者⭐⭐⭐⭐学习过程可回溯知识点关联短期项目开发者⭐⭐收益有限但未来回顾有帮助9.3 未来展望根据项目 RoadmapClaude-Mem 正在开发以下功能多 AI 提供商支持- 除了 Claude还将支持 GPT、Gemini 等更强大的无尽模式- 降低延迟支持更复杂的项目团队协作增强- 实时协作编辑、冲突解决AI 驱动的洞察- 自动识别代码模式、潜在问题企业级功能- 权限管理、审计日志、合规工具9.4 快速上手检查清单✅ 安装 Claude Code 最新版 ✅ 运行安装命令/plugin marketplace add thedotmack/claude-mem ✅ 安装插件/plugin install claude-mem ✅ 重启 Claude Code ✅ 访问 http://localhost:37777 验证安装 ✅ 开始第一个会话让 Claude-Mem 自动记录 ✅ 开启新会话体验上下文自动注入参考资料GitHub 仓库https://github.com/thedotmack/claude-mem官方网站https://claude-mem.ai文档中心https://docs.claude-mem.aiDiscord 社区https://discord.gg/claude-mem相关文章开源 Claude Code 自动记忆管理插件 Claude-MemClaude-MemClaude Code的持久内存…给Claude Code装上长期记忆写在最后Claude-Mem 正在改变我们与 AI 协作的方式。它不再是一个健忘的助手而是一个能够真正理解你项目历史、延续你思考过程的智能伙伴。如果你每天都在使用 Claude Code 进行开发Claude-Mem 绝对值得一试。作者注本文基于 Claude-Mem v10.3.1 版本撰写后续版本可能有所变化请以官方文档为准。如果本文对你有帮助欢迎点赞、收藏、关注三连如有任何问题欢迎在评论区留言讨论。