claude-mem 持久记忆系统完整指南：跨会话上下文压缩、MCP 三层检索与多语言模式配置

claude-mem 持久记忆系统完整指南跨会话上下文压缩、MCP 三层检索与多语言模式配置【免费下载链接】claude-memPersistent 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项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem导读本文以 claude-mem 项目当前仓库根目录 README.md 及其西班牙语译本 docs/i18n/README.es.md为蓝本系统讲解这款为 Claude Code 等 Agent 打造的持久记忆压缩系统它如何通过生命周期 hooks 自动捕获会话中的工具使用观察压缩为语义化记忆并在新会话中回注上下文。读完本文你将掌握 claude-mem 的完整安装路径Claude Code / OpenCode / Antigravity / OpenClaw / 插件市场、六大核心组件的工作原理、MCP 搜索工具的三层 token 高效检索工作流以及CLAUDE_MEM_MODE多模式多语言配置的底层实现机制。一、项目定位与核心价值claude-mem 是一个为 Agent 构建的持久记忆压缩系统它自动捕获 Agent 在会话中使用工具的观察observations、生成语义化摘要并将相关上下文注入未来的会话让 Claude 在会话结束或重连后仍能保持对项目的知识连续性。从当前仓库的 docs/i18n/README.es.md 可以看到项目定位为 Sistema de compresión de memoria persistente construido para Claude Code即为 Claude Code 构建的持久记忆压缩系统并支持 Claude Code、OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode 等多种 Agent 环境。核心特性包括持久记忆Persistent Memory上下文跨会话存活渐进式披露Progressive Disclosure分层记忆检索且 token 成本可见基于技能的搜索Skill-Based Search通过 mem-search 技能查询项目历史️Web 查看器Web Viewer UI启动时打印的 worker URL 提供实时记忆流Claude Desktop 技能可在 Claude Desktop 对话中搜索记忆隐私控制Privacy Control使用private标签从存储中排除敏感内容⚙️上下文配置Context Configuration精细控制注入哪些上下文全自动运行无需手动干预引用Citations通过 worker API 用 ID 引用历史观察或在 Web 查看器中查看全部注意来自文档claude-mem 也发布在 npm 上但npm install -g claude-mem只安装SDK/库——不会注册插件 hooks也不会配置 worker 服务。始终通过npx claude-mem install或/plugin命令安装。二、快速安装五种官方安装路径2.1 Claude Code 一键安装默认npx claude-mem install安装器会先完成全部设置然后引导你在浏览器中登录 claude-mem邮件 magic link无需信用卡。登录会为你的账户签发 memory key 并解锁 claude-mem observer。如果希望跳过登录可显式传入--provider标志、设置CLAUDE_MEM_ONLINE_OPTINfalse或在 CI/非交互式 shell 中运行安装器会在无账户交互的情况下完成。2.2 为 OpenCode 安装npx claude-mem install --ide opencode仓库 cowork 与 src/integrations/opencode-plugin 目录印证了 OpenCode 是项目的一等公民集成目标。2.3 为 Antigravity CLI 安装npx claude-mem install --ide antigravity2.4 Claude Code 插件市场安装在 Claude Code 内执行/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem安装完成后重启 Claude Code历史会话的上下文会自动出现在新会话中。2.5 OpenClaw 网关单命令安装curl -fsSL https://install.cmem.ai/openclaw.sh | bash安装器负责依赖处理、插件配置、AI 供应商配置、worker 启动以及可选的到 Telegram、Discord、Slack 等的实时观察推送。仓库 openclaw 目录及 openclaw/SKILL.md 展示了完整的 OpenClaw 集成实现。2.6 系统要求来自文档依赖版本/说明Node.js20.0.0 或更高Claude Code支持插件的最新版本BunJavaScript 运行时与进程管理器缺失时自动安装uvPython 包管理器用于向量搜索缺失时自动安装SQLite 3持久化存储已内置2.7 Windows 环境注意事项如果在 PowerShell 中遇到如下错误npm : The term npm is not recognized as the name of a cmdlet请确认 Node.js 和 npm 已安装并加入 PATH从 https://nodejs.org 下载最新安装器安装后重启终端。仓库 docs/bug-fixes/windows-spaces-issue.md 还记录了 Windows 路径空格问题的修复经验。三、工作原理六大核心组件根据 docs/i18n/README.es.md 的 Cómo Funciona 章节系统由以下组件构成5 个生命周期 HooksSessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd共 6 个 hook 脚本智能安装器Smart Install带缓存的依赖检查器pre-hook 脚本不属于生命周期 hookWorker 服务本地 HTTP API带 Web 查看器 UI 与搜索端点由 Bun 管理SQLite 数据库存储会话sessions、观察observations、摘要summariesmem-search 技能渐进式披露的自然语言查询Chroma 向量数据库语义 关键词混合搜索实现智能上下文检索3.1 从 hooks 清单看真实调用链仓库 plugin/hooks/hooks.json 是上述架构的落地证据。除文档提到的 5 个生命周期 hook 外还包含Setup版本检查与PreToolUseRead 匹配器的 file-context 注入。每个 hook 通过node plugin/scripts/bun-runner.js plugin/scripts/worker-service.cjs hook claude-code subcommand调用 workerHookmatcher子命令职责Setup*version-check.js缓存依赖/版本检查pre-hookSessionStartstartup\|clear\|compactstart / context启动 worker 并注入上下文UserPromptSubmit全部session-init会话初始化PostToolUse*asyncobservation捕获工具使用观察PreToolUseReadasyncfile-context读取文件时注入相关记忆Stop全部asyncsummarize生成进度摘要对应的脚本实现位于 plugin/scripts/worker-service.cjs 与 plugin/scripts/bun-runner.js。3.2 数据层SQLite FTS5数据库位于~/.claude-mem/claude-mem.db使用 SQLite WALWrite-Ahead Logging模式支持并发读写。核心表包括sdk_sessions、observations、session_summaries、user_prompts并通过 FTS5 虚拟表observations_fts、session_summaries_fts、user_prompts_fts配合触发器实现全文本搜索自动同步。详细 Schema 见 docs/public/architecture/database.mdx类实现位于 src/services/sqlite/SessionStore.ts 与 src/services/sqlite/SessionSearch.ts。四、MCP 搜索工具三层 token 高效工作流claude-mem 通过4 个 MCP 工具提供智能记忆搜索遵循3 层工作流模式目标是先过滤再取详情实现约10 倍 token 节省。4.1 三层工作流search获取紧凑索引含 ID约50–100 tokens/结果timeline获取有趣结果周围的时间线上下文get_observations仅对被过滤出的 ID 获取完整详情约500–1,000 tokens/结果工作方式Claude 先用search拿到结果索引 → 用timeline观察特定观察点周边发生了什么 → 用get_observations拉取相关 ID 的完整详情。4.2 示例调用// 步骤 1搜索索引 search(queryauthentication bug, typebugfix, limit10) // 步骤 2审阅索引确定相关 ID如 #123, #456 // 步骤 3获取完整详情 get_observations(ids[123, 456])4.3 各工具参数详解来自 plugin/skills/mem-search/SKILL.mdsearch返回含 ID、时间戳、类型、标题的表格参数类型说明querystring搜索词limitnumber最大结果数默认 20上限 100projectstring项目名过滤typestring可选observations、sessions或promptsobs_typestring可选逗号分隔bugfix、feature、decision、discovery、changedateStart/dateEndstring可选YYYY-MM-DD 或 epoch 毫秒offsetnumber可选跳过 N 条结果orderBystring可选date_desc默认、date_asc、relevancetimeline返回depth_before 1 depth_after条按时间排序的混合条目observations、sessions、prompts 交错参数类型说明anchornumber可选围绕的观察 IDquerystring可选未提供 anchor 时自动定位depth_before/depth_afternumber可选默认 5上限 20projectstring项目名过滤get_observations返回完整的观察对象title、subtitle、narrative、facts、concepts、files约 500–1000 tokens/条参数类型说明idsnumber[]必填要获取的观察 IDorderBystring可选date_desc默认、date_asclimitnumber可选最大返回条数projectstring可选项目名过滤最佳实践2 条及以上观察始终使用get_observations批量获取——1 次 HTTP 请求替代 N 次独立请求。检索语义化总结而非原始记录时可结合/knowledge-agent技能构建可查询语料库。五、配置settings.json 与 CLAUDE_MEM_MODE 多语言模式5.1 全局设置文件所有设置统一管理在~/.claude-mem/settings.json首次运行自动创建默认值可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入设置。5.2 模式与语言配置CLAUDE_MEM_MODEclaude-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默认英文模式code--zh简体中文模式code--ja日语模式语言专属模式遵循code--[lang]模式其中[lang]为 ISO 639-1 语言代码如zh中文、ja日语、es西班牙语。code--zh简体中文已内置无需额外安装或更新插件。修改模式后需重启 Claude Code 生效。从源码看模式机制的实现细节当前仓库 plugin/modes/ 实际包含远超文档示例的模式文件——如 code--es.json西班牙语、code--de.json、code--fr.json 等 20 余个语言变体以及 code--chill、email-investigation、law-study 等工作流模式。src/services/domain/ModeManager.ts 中的parseInheritance实现了parent--override单层继承解析code--es会先加载父模式code再深度合并覆盖文件语言变体主要覆盖prompts.footer等提示词字段例如 code--es.json 的 LANGUAGE REQUIREMENTS: Please write the observation data in español。若模式文件缺失loadMode会记录警告并回退到code模式模式目录支持通过CLAUDE_MEM_MODES_DIR环境变量扩展且用户自定义模式存放于数据目录modes/可在插件升级后保留。六、发布分支、开发、故障排查与 Bug 报告6.1 发布分支Release Branches稳定版从main分支发布并推送 npmcore-dev和community-edge是从源码运行的分支用于早期可靠性修复与社区集成。只有main会发布到 npm其余分支从源码运行。6.2 开发与贡献构建、测试与贡献流程参见开发指南。贡献流程fork 仓库 → 创建功能分支 → 带测试地修改 → 更新文档 → 提交 Pull Request。仓库测试覆盖广泛见 tests/ 目录含 MCP 工具 schema、worker 服务、SQLite 存储等 200 测试文件。6.3 故障排查遇到问题时直接把问题描述给 Claudetroubleshoot 技能会自动诊断并提供修复方案。仓库 docs/public/troubleshooting.mdx 记录了常见问题与解法。6.4 一键 Bug 报告使用自动化生成器创建完整 bug 报告cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report对应实现见 scripts/bug-report/。七、许可证与生态说明claude-mem 采用Apache License 2.0详见 LICENSE。选择该许可证的考量是持久的智能体记忆应易于嵌入开发者工具、本地 Agent、MCP 服务器、企业系统、机器人技术栈以及生产环境 Agent harness。许可证范围与开源/商业边界详见 docs/license.md 与 docs/ip-boundary.md。特别说明ragtime/目录同样基于Apache License 2.0见 ragtime/LICENSE。八、总结从安装到深度使用的完整路径安装Claude Code 默认npx claude-mem installOpenCode 用--ide opencodeAntigravity 用--ide antigravity插件市场用/plugin命令OpenClaw 用官方脚本一行安装。运行机制5 个生命周期 hooks加 Setup、PreToolUse 共 7 个钩子点 Bun 管理的 worker 服务 SQLite/FTS5 存储 Chroma 向量混合检索。检索记住search → timeline → get_observations三层工作流先过滤索引再批量取详情可节省约 10 倍 token。定制通过~/.claude-mem/settings.json的CLAUDE_MEM_MODE切换工作流模式与观察语言code--[lang]继承机制让多语言支持开箱即用。如需继续深入建议阅读仓库内 docs/architecture-overview.md、docs/public/architecture/hooks.mdx、docs/public/architecture/worker-service.mdx 与 docs/public/progressive-disclosure.mdx或直接参考 plugin/skills/mem-search/SKILL.md 的完整检索参数表。【免费下载链接】claude-memPersistent 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项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考