Claude-Mem 深度指南跨会话持久上下文、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-memClaude-Mem 是一个为 Claude Code 构建的持久化记忆压缩系统它在每次会话中自动捕获工具使用观察observations用 AI 压缩成语义化摘要并在未来会话启动时把相关上下文重新注入给 Agent。本文基于仓库中的丹麦语版 READMEdocs/i18n/README.da.md及其对应的源码实现完整讲解安装方式、六条 Hooks 生命周期数据流、SQLite/Chroma 存储架构、MCP 三层搜索工作流以及CLAUDE_MEM_MODE多语言模式配置帮助你在自己的项目中落地跨会话不失忆的 Agent 工作流。一、Claude-Mem 是什么用仓库原文的话说Claude-Mem 通过在会话结束时自动捕获工具使用观察、生成语义化摘要semantic summaries并使其在未来会话中可检索从而在会话之间无缝保留上下文。这让 Claude 在会话结束或断开重连后依然能维持对项目知识的连续性。官方文档丹麦语版 README列出的核心能力包括持久化记忆Persistent Memory上下文跨会话存活渐进式披露Progressive Disclosure分层获取记忆并让 token 开销可见技能化搜索Skill-based Search通过mem-search技能用自然语言查询项目历史Web Viewer UI在 Worker 启动时打印的 URL 上实时查看记忆流Claude Desktop 技能在 Claude Desktop 对话中检索记忆隐私控制用private标签将敏感内容排除在存储之外上下文配置精细控制哪些上下文会被注入全自动运行无需人工干预引用Citations通过 Worker API 用 ID 引用历史观察或在 Web Viewer 中浏览全部记录。二、快速开始2.1 安装最简安装只需一条命令npx claude-mem install按目标环境安装# 安装到 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此前会话的上下文会自动出现在新会话中。注意Claude-Mem 虽然发布在 npm 上但npm install -g claude-mem只会安装SDK/库——它不会注册插件 Hooks也不会启动 worker 服务。完整安装必须走npx claude-mem install或上面的/plugin命令。2.2 OpenClaw Gateway 安装如果要把 claude-mem 作为持久记忆插件安装到 OpenClaw 网关上可用一条 curl 命令完成curl -fsSL https://install.cmem.ai/openclaw.sh | bash安装器会自动处理依赖、插件配置、AI 供应商配置、worker 启动以及可选的 Telegram / Discord / Slack 实时观察流。仓库中 openclaw/ 目录包含该插件的完整实现与测试脚本如 openclaw/install.sh、openclaw/e2e-verify.sh。2.3 系统要求Node.js20.0.0 或更高对应 package.json 中的node 20.0.0约束Claude Code支持插件plugin机制的版本BunJavaScript 运行时兼进程管理器缺失时自动安装uvPython 包管理器用于向量搜索缺失时自动安装SQLite 3用于持久化存储随包附带。2.4 Windows 注意事项在 PowerShell 中若看到类似错误npm : The term npm is not recognized as the name of a cmdlet说明 Node.js 与 npm 未安装或未加入 PATH。从 nodejs.org 下载最新的 Node.js 安装包安装后重启终端即可。三、架构五条生命周期 Hooks 如何驱动记忆数据流README 给出的核心组件清单是5 条生命周期 Hooks—— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd共 6 个 hook 脚本Smart Installation智能安装—— 带缓存的依赖检查器属于 pre-hook 脚本不是生命周期 HookWorker Service—— 本地 HTTP API带 Web Viewer UI 与搜索端点由 Bun 托管SQLite 数据库—— 存储会话、观察与摘要mem-search 技能—— 自然语言查询 渐进式披露Chroma 向量数据库—— 混合语义 关键词检索实现智能上下文召回。更完整的组件与数据流说明见 docs/public/architecture/overview.mdxHooks 机制详解见 docs/public/architecture/hooks.mdx。3.1 从源码看真实的 Hook 注册表仓库中的 plugin/hooks/hooks.json 是这份数据流地图的权威来源。当前版本实际注册了 6 个 Hook 事件每一个都通过bun-runner.js调用 worker-service.cjs 的对应子命令Hook 事件Matcherworker 子命令超时/模式职责Setup*version-check.js300s缓存式依赖检查即Smart Installation而非生命周期 HookSessionStartstartup\|clear\|compactworker-service.cjs starthook claude-code context60s拉起 worker 服务然后把历史记忆上下文注入新会话UserPromptSubmit—hook claude-code session-init60s用户提交 prompt 时初始化会话记录PostToolUse*hook claude-code observation120sasync: true每次工具调用后异步生成/追加观察PreToolUseReadhook claude-code file-context60sasync: true读取文件前注入该文件相关的历史上下文Stop—hook claude-code summarize120sasync: true会话停止时生成进度摘要summary几个值得注意的实现细节异步化观察PostToolUse与Stop都标记为async: true观察与摘要生成不阻塞主会话这与 README自动运行、零人工干预的承诺一致插件版本自解析每条 Hook 命令的 shell 脚本都会先扫描~/.claude/plugins/cache/thedotmack/claude-mem/下的版本目录、按语义化版本排序选择最新非孤儿无.orphaned_at标记的缓存再回落到marketplaces/thedotmack/plugin保证多版本共存时总是命中正确的脚本上下文注入入口SessionStart的第二条命令hook claude-code context正是历史记忆回到新会话的关键路径MCP 侧对应的session_start_context工具会调用 worker 的/api/context/inject渲染完全相同的注入文本见 src/servers/mcp-server.ts。3.2 Worker Service 与存储层Worker Service 是本地 HTTP 服务由 Bun 作为运行时与进程管理器托管同时提供 Web Viewer UI实时记忆流和搜索端点。其架构文档见 docs/public/architecture/worker-service.mdx。存储分两层SQLite主存储保存会话sessions、观察observations、摘要summaries内置 FTS5 全文索引。Schema 与检索细节见 docs/public/architecture/database.mdxChroma 向量数据库叠加语义向量检索与全文检索组成混合搜索hybrid search为上下文召回排序。见 docs/public/architecture/search-architecture.mdx。四、MCP 搜索工具token 高效的三层工作流Claude-Mem 通过 MCP 工具暴露记忆检索遵循一个 token 高效的3 层工作流模式3-Layer Workflowsearch—— 拿到带 ID 的紧凑索引约 50–100 tokens/条结果timeline—— 查看某个结果前后的时间线上下文get_observations—— 只对筛选后的 ID 拉取完整详情约 500–1000 tokens/条。使用方式Claude 用search获得结果索引 → 用timeline观察特定观察前后发生了什么 → 用get_observations批量取详情。先过滤再取详情可节省约 10 倍 token。官方示例// 第 1 步搜索索引 search(queryauthentication bug, typebugfix, limit10) // 第 2 步浏览索引识别相关 ID例如 #123、#456 // 第 3 步批量拉取完整详情 get_observations(ids[123, 456])更详细的示例见 docs/public/usage/search-tools.mdx。4.1 源码中的工具定义与参数全集MCP 工具集中在 src/servers/mcp-server.ts 的tools数组中定义。值得注意的第一个工具是important_workflowL438-L471——它没有实际查询逻辑只是一个自我说明书工具把三层工作流原样喂给调用方 Agent强制其遵守绝不未过滤就取详情的约束这就是渐进式披露哲学在协议层的落地。search工具的完整入参L474-L523参数说明query搜索文本limit最大结果数默认 20project按项目名过滤platformSource按来源平台过滤如claude、codex、cursor只看该 Agent 自己的记忆type文档类别observations/sessions/prompts默认全部其他取值会当作obs_type处理obs_type按观察类型过滤如bugfix、feature可逗号分隔多个dateStart/dateEndISO 日期区间过滤offset分页偏移orderBydate_desc或date_asctimelineL524-L541支持anchor观察 ID或直接给query自动定位锚点depth_before/depth_after默认各取 3 条get_observationsL542-L560要求ids数组参数底层转发到 worker 的/api/observations/batch所以批量 ID 是一次 HTTP 调用。此外服务端运行时server-beta还额外暴露了observation_add、observation_record_event、observation_search、observation_context等observation_*工具走 Postgres GIN tsvector 索引的/v1/*REST 路径L583-L659search工具内部也会在服务端可用且查询不含本地 Worker 才支持的过滤器时自动路由到 PG 后端的/v1/search——从这段分支逻辑可以推断检索链路对本地 SQLite Chroma与服务端 Postgres两种部署形态做了透明的双轨适配。4.2 观察类型从哪里来search(typebugfix)这类过滤值的定义不在 MCP 层而在模式文件里。默认的 plugin/modes/code.json 精确约束了 9 种观察类型observation_typesbugfix、feature、refactor、change、discovery、decision、security_alert、security_note、sensitive以及 7 种知识维度conceptshow-it-works、why-it-exists、what-changed、problem-solution、gotcha、pattern、trade-off。观察生成的提示词observer 系统提示、跳过规则、XML 输出格式也全部定义在该模式的prompts区块中——模式文件是观察长什么样的单一事实来源。五、配置settings.json 与 CLAUDE_MEM_MODE5.1 配置文件设置集中在~/.claude-mem/settings.json首次运行自动以默认值创建可配置项包括AI 模型、worker 端口、数据目录、日志级别、上下文注入选项。完整参数清单与示例见 docs/public/configuration.mdx。5.2 用 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/README 给出的基础模式表模式说明code默认英语模式code--zh简体中文模式code--ja日语模式语言模式的命名约定是code--[lang][lang]为 ISO 639-1 语言代码zh中文、ja日语、es西班牙语……。code--zh已内置无需额外安装或升级插件。模式体系详解见 docs/public/modes.mdx。5.3 从源码看模式加载与继承机制模式加载由 src/services/domain/ModeManager.ts 实现几个关键机制模式搜索路径L16-L27依次查找环境变量CLAUDE_MEM_MODES_DIR→ 用户数据目录modes/跨插件升级持久化的用户自建模式→ 包内modes/→ 开发布局plugin/modes取第一个存在的${modeId}.json一级继承parseInheritanceparent--override形式的模式 ID 会被拆成父模式 覆盖模式做深度合并deepMerge且只支持一层继承a--b--c会直接抛错安全回退找不到指定模式文件时回落到code模式而不是让 worker 崩溃ID 合法性模式 ID 必须匹配^[a-z0-9](?:-[a-z0-9])*(?:--[a-z0-9](?:-[a-z0-9])*)?$这也是code--zh这类命名的来源约束。当前仓库plugin/modes/目录实际内置的模式比 README 示例表丰富得多除code外还有29 个语言变体code--ar、code--bn、code--da、code--de、code--es、code--fr、code--ru、code--sv、code--zh等覆盖阿拉伯语到越南语以及非代码场景模式code--chill、email-investigation、law-study、law-study--chill继承示例和meme-tokens。重要修改CLAUDE_MEM_MODE之后必须重启 Claude Code 才能生效。六、Release 分支、开发、排障与 Bug 报告6.1 三条 Release 分支main稳定版发布分支发布到 npmcore-dev源码运行的早期可靠性修复分支community-edge社区集成分支。只有main会发布到 npm其余两条需要从源码运行。分支流程与本地运行方式见 docs/public/branches.mdx。6.2 开发与贡献构建、测试与贡献工作流见 docs/public/development.mdx。贡献流程Fork 仓库 → 建特性分支 → 带测试地修改 → 更新文档 → 提交 Pull Request。6.3 故障排除遇到问题时直接把问题描述给 Claudetroubleshoot 技能会自动诊断并给出修复。常见问题清单见 docs/public/troubleshooting.mdx。6.4 自动化 Bug 报告在插件目录中运行生成器自动收集环境信息生成结构化缺陷报告cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report对应源码为 scripts/bug-report/cli.ts入口 collector.ts信息收集器。七、许可与边界Claude-Mem 采用Apache License 2.0许可见 LICENSE。官方选择 Apache-2.0 的理由是持久的 Agent 记忆应当容易嵌入开发者工具、本地 Agent、MCP 服务器、企业系统与生产级 Agent 框架。许可范围与开源 vs 商业的边界说明docs/license.md、docs/ip-boundary.mdRagtime 特别说明ragtime/ 目录同样在 Apache 2.0 下许可详见 ragtime/LICENSE其向量时间序列检索实现见 ragtime/ragtime.ts。八、延伸阅读仓库内文档索引主题文档安装快速 进阶docs/public/installation.mdx使用入门docs/public/usage/getting-started.mdx搜索工具详解docs/public/usage/search-tools.mdx上下文工程原则docs/public/context-engineering.mdx渐进式披露哲学docs/public/progressive-disclosure.mdx架构总览与数据流docs/public/architecture/overview.mdx从 v3 到 v5 的架构演进docs/public/architecture-evolution.mdxHooks 参考7 个 hook 脚本docs/public/architecture/hooks.mdxWorker ServiceHTTP API 与 Bun 管理docs/public/architecture/worker-service.mdxSQLite Schema 与 FTS5docs/public/architecture/database.mdxChroma 混合搜索架构docs/public/architecture/search-architecture.mdx全部配置项docs/public/configuration.mdx一句话总结Claude-Mem 的工程骨架是Hooks 捕获 → Observer 压缩 → SQLite/Chroma 双存储 → 三层 MCP 检索 → SessionStart 回注的闭环理解 plugin/hooks/hooks.json 的六条 Hook 与 src/servers/mcp-server.ts 的工具定义基本就掌握了它的全部行为面。【免费下载链接】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），仅供参考