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-memclaude-mem 是一个面向 Claude Code 等编码 Agent 的记忆压缩系统它在会话期间自动记录工具调用的观察Observation用 AI 压缩成语义摘要再在未来会话中把相关上下文注入回来。本文基于官方文档乌尔都语版 README与主 README 内容对应并结合仓库源码展开带你掌握三种安装方式、生命周期钩子的底层机制、Token 高效的三层 MCP 搜索工作流以及CLAUDE_MEM_MODE模式与语言配置的完整细节。一、快速上手三种官方安装方式1. 一行命令安装最标准的安装方式是 npx 命令npx claude-mem install针对不同 IDE/Agent 有不同的变体# OpenCode 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之前会话的上下文就会自动出现在新会话中。重要注意npm install -g claude-mem只会安装SDK/库——它既不会注册插件钩子也不会启动 worker 服务。请始终使用npx claude-mem install或上面的/plugin命令安装。这一点可以从 package.json 中得到印证包入口bin指向./dist/npx-cli/index.js而真正的钩子与 worker 脚本位于plugin/hooks/与plugin/scripts/目录下只有走完整安装流程才会被部署到位。2. OpenClaw 网关安装对于运行 OpenClaw 网关的场景可以用一条 curl 命令把 claude-mem 作为持久记忆插件接入curl -fsSL https://install.cmem.ai/openclaw.sh | bash该安装器会处理依赖、插件配置、AI 供应商配置、worker 启动以及 Telegram、Discord、Slack 等可选的实时观察推送。仓库内openclaw/目录即对应该平台的插件源码含 openclaw 插件清单 与安装脚本 install.sh。3. 核心特性一览官方文档列出的关键能力持久记忆——上下文在多个会话之间延续渐进式披露——分层恢复记忆并附带 Token 开销的量化说明基于技能的搜索——通过mem-search技能用自然语言向项目历史提问Web 查看器——启动时打印的 worker URL 上可看实时记忆流Claude Desktop 技能——在 Claude Desktop 对话中检索记忆隐私控制——用private标签将敏感内容排除在存储之外上下文注入配置——精细控制哪些上下文会被注入自动运行——无需人工干预引用能力——通过 worker API 以 ID 形式引用过去的观察二、工作原理生命周期钩子 worker 服务官方文档给出的六个核心组件是5 个生命周期钩子——SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd共 6 个钩子脚本智能安装——带缓存的依赖检查器pre-hook 脚本不属于生命周期钩子worker 服务——提供 Web 查看器 UI 与搜索 API 端点的本地 HTTP 服务由 Bun 管理SQLite 数据库——存储会话、观察与摘要mem-search 技能——带渐进式披露的自然语言问答Chroma 向量数据库——为混合语义 关键词搜索提供智能上下文恢复结合仓库源码 plugin/hooks/hooks.json可以看到这些钩子的真实注册方式与执行参数钩子事件执行动作超时备注Setup运行 version-check.js300s智能安装检查/更新依赖属于前置脚本SessionStartworker-service.cjs start60smatcher 为startup\|clear\|compact确保 worker 已启动SessionStartworker-service.cjs hook claude-code context60s将历史上下文注入新会话UserPromptSubmitworker-service.cjs hook claude-code session-init60s每次用户提交提示时初始化会话记录PostToolUseworker-service.cjs hook claude-code observation120sasync: true异步记录工具调用观察PreToolUseworker-service.cjs hook claude-code file-context60smatcher 为Read读取文件前补充文件上下文Stopworker-service.cjs hook claude-code summarize120sasync: true会话停止时生成进度摘要每条钩子命令都通过bun-runner.js定位最新版插件目录优先CLAUDE_PLUGIN_ROOT其次是版本排序后的插件缓存最后是 marketplace 副本并在 Windows 上通过cygpath转换路径——这就是文档中智能安装在源码层面的实现形态。每个钩子脚本最终都调用 plugin/scripts/worker-service.cjs 的不同子命令。模式即提示词模板plugin/modes/观察生成的模式mode以 JSON 文件形式定义在plugin/modes/下。以默认的 plugin/modes/code.json 为例它规定了9 种观察类型bugfix、feature、refactor、change、discovery、decision、security_alert、security_note、sensitive——观察必须且只能是这 9 个值之一7 种概念分类how-it-works、why-it-exists、what-changed、problem-solution、gotcha、pattern、trade-off观察者提示词明确观察者记录的是主会话做了什么实现/修复/部署/配置了什么而不是观察过程本身并且设计上保持静默——被观察的主会话不能感知到自己正在被记录code.json之外plugin/modes/目录下还有code--zh.json、code--ja.json等数十个语言变体以及email-investigation.json、law-study.json等专用工作流模式。三、MCP 搜索工具Token 高效的三层工作流claude-mem 通过 MCP 提供智能记忆搜索。官方文档强调其遵循Token 高效的三层工作流模式文档称提供 4 个 MCP 工具核心为以下 3 个三层工作流search——获取带 ID 的紧凑索引约 50–100 Token/条timeline——获取感兴趣结果前后的时间线上下文get_observations——只为筛选后的 ID 获取完整详情约 500–1,000 Token/条工作原理先用search拿到索引再用timeline看某个观察前后发生了什么最后用get_observations批量拉取完整内容——通过先过滤再取详情实现约10 倍的 Token 节省。// 第 1 步搜索索引 search(queryauthentication bug, typebugfix, limit10) // 第 2 步审查索引识别相关 ID例如 #123、#456 // 第 3 步获取完整详情 get_observations(ids[123, 456])仓库内的 plugin/skills/mem-search/SKILL.md 给出了每个工具的完整参数表可直接用于实战search参数参数类型说明querystring搜索词limitnumber最大结果数默认 20上限 100projectstring按项目名过滤typestringobservations、sessions或promptsobs_typestring逗号分隔bugfix、feature、decision、discovery、changedateStart/dateEndstringYYYY-MM-DD 或 epoch 毫秒offsetnumber跳过 N 条结果orderBystringdate_desc默认、date_asc、relevancetimeline参数参数类型说明anchornumber时间线居中的观察 IDquerystring未提供 anchor 时自动定位锚点depth_beforenumber锚点之前取几条默认 5上限 20depth_afternumber锚点之后取几条默认 5上限 20projectstring项目名过滤get_observations参数参数类型说明idsnumber[]必填要获取的观察 ID 列表2 条以上务必批量orderBystringdate_desc默认或date_asclimitnumber最大返回观察数projectstring项目名过滤从源码看src/servers/mcp-server.ts 中的search、timeline、get_observations工具并不直接访问数据库而是通过callWorker()转发到 worker 的 HTTP API如/api/timeline当运行时切换为CLAUDE_MEM_RUNTIMEserver时MCP 侧改用observation_*系列工具与 server 的/v1端点通信从而与钩子共享同一套 REST 写入/搜索核心——工具集按运行时动态可见见 mcp-tool-visibility.ts。MCP 服务器在启动时若 worker 不可用还会尝试自动拉起 worker见 worker-spawner。四、系统要求与 Windows 注意事项Node.js20.0.0 及以上当前 package.json 中engines声明为node 20.12.0、bun 1.0.0Claude Code支持插件的最新版本BunJavaScript 运行时与进程管理器缺失时自动安装uv向量搜索用的 Python 包管理器缺失时自动安装SQLite 3持久化存储随包捆绑Windows 注意事项如果遇到以下报错npm : The term npm is not recognized as the name of a cmdlet请确认 Node.js 与 npm 已安装并加入了PATH从 nodejs.org 下载最新安装器安装后重启终端。仓库中亦有专门的 Windows 回归测试如tests/infrastructure/windows-hide-regressions.test.ts守护跨平台启动行为。五、配置settings.json 与 CLAUDE_MEM_MODE配置统一存放在~/.claude-mem/settings.json首次运行时以默认值自动创建。这一点可从 src/shared/paths.ts 确认USER_SETTINGS_PATH join(DATA_DIR, settings.json)DATA_DIR默认为~/.claude-mem。SettingsDefaultsManager.ts 定义了完整默认值集合可配置的键包括但不限于AI 模型CLAUDE_MEM_MODEL、CLAUDE_MEM_PROVIDER、worker 端口与主机CLAUDE_MEM_WORKER_PORT、CLAUDE_MEM_WORKER_HOST、日志级别CLAUDE_MEM_LOG_LEVEL、数据目录CLAUDE_MEM_DATA_DIR、上下文注入粒度CLAUDE_MEM_CONTEXT_OBSERVATIONS、CLAUDE_MEM_CONTEXT_SESSION_COUNT、CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY等、跳过哪些工具CLAUDE_MEM_SKIP_TOOLS、排除项目CLAUDE_MEM_EXCLUDED_PROJECTS、Chroma 向量库连接CLAUDE_MEM_CHROMA_HOST等、模式CLAUDE_MEM_MODE。模式与语言配置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才能生效。从源码结构看模式目录的解析还支持CLAUDE_MEM_MODES_DIR环境变量注入自定义模式目录见 ModeManager.ts即高级用户可以挂载自己的模式集。六、故障排除与 Bug 报告遇到问题时直接在 Claude 中描述问题即可——内置的 troubleshooting 技能会自动诊断并给出修复建议。也可以运行带自动信息收集的 bug-report 生成器生成包含详细环境信息的报告cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report对应仓库中的 scripts/bug-report/cli.ts 及其信息收集器 collector.ts。仓库内另有多个守护脚本可辅助定位钩子与进程问题例如scripts/check-hook-io-discipline.cjs检查钩子 IO 纪律与scripts/check-spawn-env-discipline.cjs检查 spawn 环境变量纪律。七、发布分支与开发流程稳定版从main分支发布并推送到 npmcore-dev与community-edge是用于早期采用者修复验证与社区集成的源码运行分支source-run branches。只有main会发布到 npm其余分支从源码直接运行。参与贡献的流程fork 仓库 → 建特性分支 → 带测试提交变更 → 更新文档 → 发起 Pull Request。构建与测试流程npm run build、bun test tests、市场同步sync-marketplace等见 package.json 的scripts段文档站源码位于docs/public/下如installation.mdx、configuration.mdx、troubleshooting.mdx等页面。八、许可证与支持claude-mem 采用Apache License 2.0见 LICENSE。选择 Apache-2.0 的考量是持久化 Agent 记忆应能被方便地嵌入开发者工具、本地 Agent、MCP 服务器、企业系统、机器人技术栈与生产级 Agent 框架中。许可范围与开源/商业边界的完整说明见 docs/license.md 与 docs/ip-boundary.md。另外注意ragtime/目录同样以 Apache License 2.0 单独许可详见 ragtime/LICENSE。支持渠道文档位于仓库docs/目录官方文档站为 docs.claude-mem.ai问题反馈走官方 GitHub Issues作者为 Alex Newmanthedotmack。小结claude-mem 的价值链路是钩子采集 → AI 压缩观察 → SQLite/Chroma 双存储 → 会话启动注入 MCP 三层搜索。安装只需npx claude-mem install日常使用中最常用的是search → timeline → get_observations的 10 倍 Token 节省工作流多语言用户只需在~/.claude-mem/settings.json中设置CLAUDE_MEM_MODE如code--zh并重启 Claude Code。建议进一步阅读 hooks 架构文档、worker 服务文档 与 搜索架构文档 深入理解各组件。【免费下载链接】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），仅供参考