Claude-Mem：AI 编程助手的跨会话持久记忆 —— 安装、Hook 工作原理与三层 MCP 检索深度解析
Claude-MemAI 编程助手的跨会话持久记忆 —— 安装、Hook 工作原理与三层 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 等 AI 编程环境的“记忆压缩系统”它在会话中自动记录工具调用产生的观察observations用 AI 生成语义摘要并在未来会话开始时把相关上下文注入回去让 Agent 在多次会话之间保持对项目的连续认知。本文基于仓库根 README 的匈牙利语翻译版 docs/i18n/README.hu.md内容与 README.md 同源展开并结合 plugin/hooks/hooks.json、src/shared/SettingsDefaultsManager.ts、plugin/skills/mem-search/SKILL.md 等源码文件完整覆盖安装方式、生命周期 Hook 机制、MCP 检索工具的参数细节、settings.json配置项与默认值、发布分支策略和故障排查入口读完你可以独立完成安装、配置模式/语言并理解每次 Hook 背后实际执行的命令链。快速开始与安装方式仓库文档给出的标准安装命令是一条npxnpx claude-mem install针对不同宿主环境README 提供了三个变体# 为 OpenCode 安装 npx claude-mem install --ide opencode # 为 Antigravity CLI 安装对应 docs/public/antigravity-cli/setup.mdx 中的设置指引 npx claude-mem install --ide antigravity如果宿主是 Claude Code 的插件市场也可以走/plugin命令安装/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem安装完成后重启 Claude Code历史会话的上下文会自动出现在新会话中。重要提示原文档明确强调npm install -g claude-mem只会安装SDK/库部分不会注册插件 Hook也不会配置 worker 服务日常使用必须走npx claude-mem install或上面的/plugin命令。从 package.json 可以看到该包的bin入口指向./dist/npx-cli/index.js即npx claude-mem实际执行的 CLI而插件本体由plugin/目录下的hooks/、modes/、skills/、scripts/、sqlite/、ui/等目录构成并随 npm 包的files字段一起发布。OpenClaw Gateway 一键安装OpenClaw 是另一类 Agent 宿主Claude-Mem 为其提供了持久记忆插件的独立安装脚本curl -fsSL https://install.cmem.ai/openclaw.sh | bash该安装器会处理依赖安装、插件注册、AI 供应商配置、worker 启动以及可选的 Telegram/Discord/Slack 实时观察流。仓库中 openclaw/ 目录含openclaw.plugin.json、install.sh、e2e-verify.sh即对应这条集成链路的实现与测试。核心能力一览README 列出的主要特性如下后文逐一给出源码级对应特性说明仓库中对应位置持久记忆上下文跨会话存活SQLite 存储层plugin/sqlite/、src/storage/渐进式披露多层记忆检索token 成本可见docs/public/progressive-disclosure.mdxSkill 检索用 mem-search 技能自然语言查询历史plugin/skills/mem-search/SKILL.mdWeb 视图worker 启动时打印 URL 的实时记忆流plugin/ui/viewer.html数据隐私用private标签排除敏感内容见“配置”小节自动运行无需手动干预全靠生命周期 Hookplugin/hooks/hooks.json引用回跳按 ID 引用历史观察经 worker API 或 Web 界面查看worker HTTP API下文说明工作原理Hook、Worker 与存储三件套README 的 “Hogyan működik”工作原理一节将系统归纳为 6 个主组件5 个生命周期 Hook对应 6 个 Hook 脚本SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd智能安装带缓存的依赖检查器属于 pre-hook 脚本不是生命周期 HookWorker 服务本地 HTTP API带 Web 视图和检索端点由 Bun 进程管理SQLite 数据库存储会话、观察、摘要mem-search 技能带渐进式披露的自然语言查询Chroma 向量库混合语义 关键词检索的智能上下文召回。从 hooks.json 看每条 Hook 实际做什么plugin/hooks/hooks.json 是插件向宿主注册的 Hook 清单每个条目都是node 插件目录/scripts/bun-runner.js 插件目录/scripts/worker-service.cjs hook claude-code 子命令形式的 bash 命令。当前仓库注册的实际条目为Hook 事件matcherworker 子命令超时备注Setup*scripts/version-check.js300sREADME 所称“智能安装”的依赖检查器缓存命中时快速跳过SessionStartstartup\|clear\|compactworker-service.cjs starthook claude-code context60s ×2先确保 worker 运行再注入历史上下文UserPromptSubmit无hook claude-code session-init60s用户提交提示时初始化会话PostToolUse*hook claude-code observation120sasync: true工具调用后异步记录观察PreToolUseReadhook claude-code file-context60sasync: true读文件前注入文件相关记忆Stop无hook claude-code summarize120sasync: true会话停止时异步生成摘要两个值得注意的工程细节插件目录解析逻辑内联在命令里每段 bash 都会先在CLAUDE_PLUGIN_ROOT、~/.claude/plugins/cache/thedotmack/claude-mem/版本/目录按版本号降序、跳过带.orphaned_at标记的孤儿目录以及~/.claude/plugins/marketplaces/thedotmack/plugin中挑选第一个“存在目标脚本”的目录Windows 下还会尝试cygpath -w转成 Windows 路径。这与 tests/infrastructure/ 中的插件分发/禁用检查测试相呼应。Hook 失败不阻塞主流程观察与摘要类 Hook 都是异步执行worker 不可达时 Hook 返回放行continue只有连续失败达到阈值默认 3 次见CLAUDE_MEM_HOOK_FAIL_LOUD_THRESHOLD才会以退出码 2 大声报错——这套 fail-loud 策略的常量定义在 src/shared/hook-constants.ts。Worker 服务懒启动、版本回收与进程监督worker 的实际入口是 plugin/scripts/worker-service.cjs由 TypeScript 构建产物打包的 Bun 单文件 bundlebun plugin/scripts/worker-service.cjs start可手动启动。从源码结构看围绕它的进程管理集中在 src/services/worker-service.ts、src/services/worker-spawner.ts 与 src/supervisor/ 目录懒启动Hook 调用前先探测 worker 健康端点/api/health、/api/readiness不健康则用spawn.lock防止并发重复拉起再后台--daemon方式启动并带指数退避等待端口就绪版本一致性若运行中 worker 版本与插件版本不一致会先杀掉旧进程再冷启动避免“新旧脚本混合”状态进程注册表src/supervisor/process-registry.ts 把 SDK 子进程、worker 等记入~/.claude-mem/supervisor.json配合 src/supervisor/shutdown.ts 做 SIGTERM→宽限期→SIGKILL 的级联清理并带“PID 复用”防护用进程启动时间戳作为身份令牌。数据目录统一收敛在~/.claude-mem/下settings.json、claude-mem.dbSQLite 主库、chroma/向量数据、logs/按日期的claude-mem-YYYY-MM-DD.log、worker.pid、supervisor.json等路径常量都定义在 src/shared/paths.ts 中CLAUDE_MEM_DATA_DIR可整体迁移。MCP 检索工具三层工作流与 token 经济学README 指出 Claude-Mem 通过4 个 MCP 工具提供记忆检索核心的 3 个如下采用 token 高效的三层工作流模式search— 取回带 ID 的紧凑索引约 50–100 token/条timeline— 围绕感兴趣的观察取回时间序上下文get_observations— 只对被筛选出的 ID 取回完整细节约 500–1000 token/条。典型用法来自 README 的示例// 第 1 步索引检索 search(queryauthentication bug, typebugfix, limit10) // 第 2 步浏览索引识别相关 ID如 #123、#456 // 第 3 步批量取回完整细节 get_observations(ids[123, 456])“先筛选、再取细节”带来约10 倍 token 节省——因为批量取回是 1 次 HTTP 请求而完整观察远比索引条目贵。plugin/skills/mem-search/SKILL.md 给出了比 README 更细的参数表安装后 Claude 会直接按它执行值得开发者了解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参数anchor观察 ID可省略或query自动定位锚点、depth_before/depth_after默认各 5上限 20、project。返回锚点前后共depth_before 1 depth_after条观察、会话、提示按时间交错排列。get_observations参数ids必填数组、orderBy、limit、project。SKILL 特别强调取 2 条以上观察时永远用一次get_observations(ids[...])批量请求而不是逐条请求。示例查询search(querybug, typeobservations, obs_typebugfix, limit20, projectmy-project) search(typeobservations, dateStart2025-11-11, limit20, projectmy-project) timeline(anchor11131, depth_before5, depth_after5, projectmy-project) get_observations(ids[11131, 10942, 10855], orderBydate_desc)从源码结构看MCP 服务端在 src/servers/mcp-server.ts而 src/servers/mcp-tool-visibility.ts 显示工具集会按运行时裁剪——observation_add、memory_search等仅 server 运行时可见的工具在 worker 运行时会被从广告列表中过滤掉因此不同部署形态下你能看到的 MCP 工具名略有差异这是设计行为而非缺陷。检索引擎本身由 SQLite FTS5 与可选的 Chroma 向量库混合驱动对应文档 docs/public/architecture/search-architecture.mdx 与 docs/public/architecture/database.mdx。配置settings.json、默认值与模式/语言README 说明配置集中在~/.claude-mem/settings.json首次运行自动创建。这一点在源码中有更精确的对应src/shared/SettingsDefaultsManager.ts 的loadFromFile在文件不存在时用全部默认值写入一份完整的 settings.json之后“已持久化的值优先于默认值”且环境变量可再覆盖applyEnvOverrides。也就是说新装用户拿到的配置里包含几十项键而不是空文件。常用默认值摘录来自同一文件的DEFAULTSpackage.json当前版本为 13.24.0配置键默认值说明CLAUDE_MEM_MODEcode工作流模式同时决定生成语言CLAUDE_MEM_MODELclaude-haiku-4-5-20251001观察生成使用的模型CLAUDE_MEM_PROVIDERclaude无头安装默认的 AI 提供方CLAUDE_MEM_WORKER_PORT37700 (uid % 100)worker HTTP 端口按 UID 派生避免多账号冲突CLAUDE_MEM_WORKER_HOST127.0.0.1仅本机监听CLAUDE_MEM_DATA_DIR~/.claude-mem数据根目录CLAUDE_MEM_LOG_LEVELINFO日志级别DEBUG/INFO/WARN/ERROR/SILENTCLAUDE_MEM_CONTEXT_OBSERVATIONS50上下文注入的观察条数CLAUDE_MEM_CHROMA_ENABLEDtrue设为false可退回纯 SQLite 检索CLAUDE_MEM_CHROMA_MODE/HOST/PORTlocal/127.0.0.1/8000本地经 uvx 拉起持久化 chroma-mcpCLAUDE_MEM_SKIP_TOOLSListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion不记录观察的工具名CLAUDE_MEM_SEMANTIC_INJECTfalse实验性每次提交提示时语义注入历史观察CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLEDfalse是否按文件夹生成 CLAUDE.mdCLAUDE_MEM_TELEGRAM_*见源码安全告警/敏感事件的 Telegram 通知完整键表可直接阅读 src/shared/SettingsDefaultsManager.ts官方配置文档为 docs/public/configuration.mdx。模式与语言配置CLAUDE_MEM_MODE同时控制两件事工作流行为如 code、chill、investigation和生成观察所用语言。修改方式{ 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 语言码。对照仓库 plugin/modes/ 目录当前随包发布约 30 个code--xx语言模式ar、bn、cs、de、es、fr、hi、hu、it、ko、nl、pl、pt-br、ru、th、uk、vi……另有code--chill.json、email-investigation.json、law-study.json、meme-tokens.json等主题模式。改完模式后必须重启 Claude Code 才能生效。系统要求与 Windows 注意事项README 列出的运行环境Node.js20.0.0 及以上package.json 的engines更精确地要求20.12.0另需bun 1.0.0Claude Code支持插件的最新版本Bunworker 的运行时兼进程管理器依赖bun:sqlite缺失时安装流程会尝试自动安装uvPython 包管理器用于 Chroma 向量检索链路缺失时同样会自动安装SQLite 3持久存储随 Bun 内建。Windows 上若出现npm : The term npm is not recognized as the name of a cmdlet说明 Node.js/npm 未安装或不在 PATH 中——安装最新版 Node.js 后需重启终端再执行安装命令。发布分支、故障排查与许可证发布分支稳定版从main分支发布并推送到 npmcore-dev与community-edge是供“早期可靠性修复”和“社区集成”使用的源码运行分支。只有main会发布到 npm其余分支从源码运行具体流程见 docs/public/branches.mdx。故障排查与 Bug 报告遇到问题可直接把现象描述给 Claude其内置的 troubleshoot 流程会自动诊断并给出修复建议常见问题清单见 docs/public/troubleshooting.mdx结构化日志位于~/.claude-mem/logs/claude-mem-日期.logCLAUDE_MEM_LOG_LEVELDEBUG时更详细worker 生命周期日志可经npm run worker:logs对应 scripts/worker-logs.cjs查看自动生成包含环境、版本、DB 规模等信息的完整 bug 报告cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report报告收集器实现在 scripts/bug-report/collector.tscli.ts由 package.json 的bug-report脚本暴露。许可证Claude-Mem 采用Apache License 2.0选择理由是持久 Agent 记忆需要能被方便地嵌入开发工具、本地 Agent、MCP 服务器、企业系统乃至机器人技术栈。全文见 LICENSE授权范围与开源/商业边界见 docs/license.md 与 docs/ip-boundary.md。子目录ragtime/单独以 Apache 2.0 授权见 ragtime/LICENSE。此外 README 说明了 CMEM 代币由第三方发行、作者官方认可用作社区增长催化剂官方 BASE CA 见原文档末尾。延伸阅读仓库内路径安装docs/public/installation.mdx使用入门docs/public/usage/getting-started.mdx检索工具docs/public/usage/search-tools.mdx架构总览 / Hook 架构 / Worker 服务 / 数据库 / 检索架构docs/public/architecture/overview.mdx、docs/public/hooks-architecture.mdx、docs/public/architecture/worker-service.mdx、docs/public/architecture/database.mdx、docs/public/architecture/search-architecture.mdx上下文工程与渐进式披露docs/public/context-engineering.mdx、docs/public/progressive-disclosure.mdx开发指南docs/public/development.mdx核心源码plugin/hooks/hooks.json、plugin/scripts/worker-service.cjs、src/services/worker-service.ts、src/servers/mcp-server.ts、src/shared/SettingsDefaultsManager.ts、src/supervisor/测试tests/infrastructure/插件分发、优雅停机、版本一致性、tests/hooks/、tests/worker/search/【免费下载链接】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），仅供参考