Claude-Mem 持久记忆系统详解:从一键安装、Lifecycle Hooks 到 MCP 三层搜索工具与模式配置 Claude-Mem 持久记忆系统详解从一键安装、Lifecycle Hooks 到 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本文基于仓库中的荷兰语版说明文档 docs/i18n/README.nl.md 编写完整覆盖 Claude-Mem 的安装方式、核心架构Hooks Worker SQLite Chroma、MCP 搜索工具的三层工作流、CLAUDE_MEM_MODE模式配置与故障排查入口并结合 plugin/hooks/hooks.json、src/servers/mcp-server.ts 与 src/shared/SettingsDefaultsManager.ts 等源码逐条印证。读完后你将能够独立安装并理解 Claude-Mem 如何自动捕获会话、压缩记忆并在后续会话中注入上下文以及如何用 MCP 工具以最低 token 成本检索项目历史。一、项目定位跨会话的持久记忆压缩Claude-Mem仓库包名仍为claude-mem当前版本 13.24.0见 package.json是一个为 Claude Code 等 AI 编码代理构建的持久记忆压缩系统。它在会话运行期间自动记录工具使用观察observations、生成语义化摘要并把这些记忆提供给未来的会话——即使会话结束或断开重连项目知识的连续性依然保留。核心能力一览继承自原文档持久记忆上下文在会话之间保持渐进式披露Progressive Disclosure分层记忆检索并展示 token 成本技能化搜索通过mem-search技能plugin/skills/mem-search/SKILL.md用自然语言询问项目历史Web Viewer UI在 Worker 启动时打印的 URL 上查看实时记忆流隐私控制使用private标签可将敏感内容排除出存储引用Citations通过 Worker API 用 ID 指回更早的观察或在 Web Viewer 中浏览全自动运行无需人工干预。二、快速开始四种安装方式与一个常见陷阱2.1 标准安装Claude Codenpx claude-mem install2.2 安装到 OpenCode / Antigravity CLInpx claude-mem install --ide opencode npx claude-mem install --ide antigravity2.3 通过 Claude Code 插件市场安装/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem安装完成后重启 Claude Code之前会话的上下文会自动出现在新会话中。原文档强调的陷阱Claude-Mem 虽也发布在 npm 上但npm install -g claude-mem只安装SDK/库——它不会注册插件 Hooks也不会启动 Worker 服务。必须使用npx claude-mem install或上面的/plugin命令完成完整安装。这一区分在源码层面得到印证install/public/installer.js 是安装器入口而 src/npx-cli/index.ts 中封装了安装子命令--ide参数即由该 CLI 解析。2.4 OpenClaw 网关安装在 OpenClaw 网关上以单命令安装持久记忆插件curl -fsSL https://install.cmem.ai/openclaw.sh | bash安装器会处理依赖、插件配置、AI 提供方配置、Worker 启动以及可选的实时观察推送Telegram / Discord / Slack 等。仓库中 openclaw/ 目录包含对应插件openclaw/install.sh、openclaw/SKILL.md。三、工作原理六大核心组件与 Hooks 真实现原文档列出六大核心组件下面逐条给出仓库中的对应实现5 个 Lifecycle HooksSessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd共 6 个 Hook 脚本智能安装检查——带缓存的依赖校验pre-hook 脚本不是 lifecycle hookWorker 服务——由 Bun 管理的本地 HTTP API提供 Web Viewer UI 与搜索端点SQLite 数据库——存储会话、观察、摘要mem-search 技能——自然语言查询 渐进式披露Chroma 向量数据库——混合语义 关键词检索。3.1 Hook 注册表plugin/hooks/hooks.json 说了什么plugin/hooks/hooks.json 是全部 Hook 的注册中心可以看到每条 Hook 都以 bash 脚本定位插件根目录后调用node scripts/bun-runner.js scripts/worker-service.cjs hook claude-code action这一统一入口且普遍做了 nvm PATH 修复、孤儿缓存目录跳过.orphaned_at标记与 Windowscygpath路径转换等健壮性处理Hook 事件匹配器执行的 action超时/特性Setup*运行scripts/version-check.js即“智能安装”的依赖预检300sSessionStartstartup\|clear\|compact①worker-service.cjs start启动 Worker②hook claude-code context注入上下文各 60sUserPromptSubmit—hook claude-code session-init初始化会话60sPostToolUse*hook claude-code observation捕获工具观察120s异步PreToolUseReadhook claude-code file-context文件读取门控60s异步Stop—hook claude-code summarize会话结束生成摘要120s异步这解释了原文档的两个细节其一“6 个 Hook 脚本”指的是 5 个生命周期事件 1 个安装预检Setup 阶段的 version-check其二PostToolUse / PreToolUse / Stop 都标记为async: true即观察捕获与摘要生成不阻塞主对话这是“自动运行、零感知”体验的关键。3.2 各组件在仓库中的落点Worker 服务src/services/worker-service.ts、plugin/scripts/worker-service.cjsSQLite 存储src/services/sqlite/、src/storage/sqlite/schema 说明见 docs/public/architecture/database.mdxChroma 混合检索docs/public/architecture/search-architecture.mdx 与 src/services/worker/ 中的搜索编排上下文注入逻辑src/utils/context-injection.ts。架构数据流的完整描述可继续参考 docs/public/architecture/overview.mdx 与 docs/public/hooks-architecture.mdx。四、MCP 搜索工具三层工作流与真实参数签名Claude-Mem 通过4 个 MCP 工具提供智能记忆检索遵循 token 高效的三层工作流search——获得带 ID 的紧凑索引约 50–100 tokens/条结果timeline——获得感兴趣结果前后的时间线上下文get_observations——仅为筛选后的 ID 拉取完整细节约 500–1000 tokens/条。先过滤、后取详情可带来约 10 倍的 token 节省。src/servers/mcp-server.ts 中这三个工具的注册顺序与描述和文档完全一致描述里甚至直接标注了 Step 1 / Step 2 / Step 3源码给出的完整参数比文档更细searchmcp-server.ts 第 474 行起参数类型说明querystring搜索查询limitnumber最大结果数默认 20projectstring按项目名过滤platformSourcestring按平台源过滤如 claude、codex、cursor限定只看该代理自己的记忆typestring文档类别observations/sessions/prompts默认全部其他值视为观察类型过滤obs_type的别名obs_typestring按观察类型过滤如 bugfix、feature逗号分隔多个dateStart/dateEndstringISO 日期区间offsetnumber分页偏移orderBystringdate_desc或date_asctimelinemcp-server.ts 第 525 行起anchornumber时间线中心观察 ID与query二选一querystring自动查找锚点depth_before/depth_after锚点前后各取几条默认各 3 条project项目过滤。get_observationsmcp-server.ts 第 543 行起idsnumber 数组必填要拉取的观察 ID 列表文档强调务必批量传多个 ID 以减少往返另支持orderBy、limit、project。标准用法示例继承原文档// 第 1 步搜索索引 search(queryauthentication bug, typebugfix, limit10) // 第 2 步查看索引识别相关 ID例如 #123、#456 // 第 3 步拉取完整细节 get_observations(ids[123, 456])从源码结构看这些工具底层通过callWorker调用本地 Worker 的/api/search、/api/timeline、/api/observations/batch端点在 server 运行时下search还会按条件智能路由到远端/v1/search。完整的工具演示可参考 docs/public/usage/search-tools.mdx。五、Release Branches三条分支的发布模型main稳定发布分支唯一发布到 npm 的分支core-dev面向早期可靠性修复的源码运行分支community-edge面向社区集成的源码运行分支。分支流转策略与本地运行非稳定版本的步骤见 docs/public/branches.mdx。六、系统要求与 Windows 安装注意系统要求原文档Node.js20.0.0 或更高package.json的 engines 要求一致Claude Code支持插件机制的最新版本BunJavaScript 运行时与进程管理缺失时自动安装见 plugin/scripts/bun-runner.js 的运行时引导uv向量检索所需的 Python 包管理器缺失时自动安装SQLite 3持久化存储随环境自带。Windows 注意如果看到类似报错npm : The term npm is not recognized as the name of a cmdlet说明 Node.js/npm 未安装或未加入 PATH。请从 Node.js 官方渠道下载最新安装包安装后重启终端再试。相关回归问题在 tests/infrastructure/windows-hide-regressions.test.ts 等测试中有覆盖。七、配置settings.json 与 CLAUDE_MEM_MODE7.1 设置文件与内置变量清单所有设置保存在~/.claude-mem/settings.json首次运行时自动创建默认值。src/shared/SettingsDefaultsManager.ts 定义了全部受支持键及默认值是这份清单的权威来源常用的包括设置项默认值用途CLAUDE_MEM_MODELclaude-haiku-4-5-20251001摘要/观察生成所用 AI 模型CLAUDE_MEM_WORKER_PORT37700 (uid % 100)Worker 本地 HTTP 端口按用户错开避免多用户冲突CLAUDE_MEM_WORKER_HOST127.0.0.1Worker 监听地址CLAUDE_MEM_CONTEXT_OBSERVATIONS50会话启动时注入的观察条数CLAUDE_MEM_SKIP_TOOLS若干工具名记录观察时跳过的工具CLAUDE_MEM_DATA_DIR用户目录数据目录SQLite、日志CLAUDE_MEM_LOG_LEVEL—日志级别CLAUDE_MEM_PROVIDERclaudeAI 提供方另有 gemini、openrouter 等CLAUDE_MEM_SEMANTIC_INJECT/_LIMIT—会话启动时的语义检索注入开关与条数CLAUDE_MEM_CHROMA_ENABLED/_MODE/_HOST/_PORT—Chroma 向量库连接混合检索CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS等展示类开关—控制上下文头部的 token 成本显示完整键表与示例见 docs/public/configuration.mdx。7.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日语在仓库中得到完整印证plugin/modes/ 目录下共约 33 个模式文件遵循code--[lang]命名[lang]为 ISO 639-1 语言码除语言系列外还有chill、email-investigation、law-study、meme-tokens等专用工作流。例如 plugin/modes/code.json 声明了该模式的观察类型分类bugfix、feature、refactor、change、discovery、decision、security_alert、security_note等——这些类型正是 MCPsearch工具中obs_type过滤参数的取值来源形成了“模式定义 → 观察打标 → 按类型检索”的闭环。注意code--zh已内置无需额外安装或更新插件。修改模式后需重启 Claude Code 生效。八、故障排查、Bug 报告与开发自助诊断遇到问题时直接把问题描述给 Claudetroubleshoot 技能会自动诊断并给出解决方案常见问题的清单见 docs/public/troubleshooting.mdx。自动化 Bug 报告使用报告生成器scripts/bug-report/ 提供采集器与 CLIcd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report开发构建、测试与贡献流程见 docs/public/development.mdx贡献步骤为 fork → 建 feature 分支 → 带测试修改 → 更新文档 → 提 PR。九、许可与边界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/public/installation.mdx系统架构总览docs/public/architecture/overview.mdxHooks 参考docs/public/hooks-architecture.mdxWorker 服务docs/public/architecture/worker-service.mdx数据库与 FTS5docs/public/architecture/database.mdx混合检索架构docs/public/architecture/search-architecture.mdx搜索工具用法docs/public/usage/search-tools.mdx配置全表docs/public/configuration.mdx故障排查docs/public/troubleshooting.mdx分支策略docs/public/branches.mdx适用前提本文所有命令、参数与默认值均以当前仓库实际内容为准package 版本 13.24.0、Node ≥ 20不同发行分支main/core-dev/community-edge行为可能存在差异请以对应分支的文档为准。【免费下载链接】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),仅供参考