Claude-Mem 跨会话持久记忆系统全解：安装方式、Hooks 架构、MCP 三层检索与配置实战

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 等 Agent 环境设计的持久记忆压缩系统它自动捕获会话中的工具使用观察observations、用 AI 生成语义摘要并在未来的会话中把相关上下文注入回来使 Agent 在会话结束或重启后仍保留项目知识。本文基于仓库中的 docs/i18n/README.el.md希腊语版项目 README 的自动化翻译展开结合 plugin/hooks/hooks.json、src/shared/SettingsDefaultsManager.ts、plugin/modes/ 等仓库内的源码与配置完整还原其安装流程、生命周期 Hook 架构、MCP 三层检索工作流、模式/语言配置与许可边界读完即可在本地完成安装、理解记忆数据流向并正确配置CLAUDE_MEM_MODE。项目定位与核心特性原文档将 Claude-Mem 定义为Σύστημα συμπίεσης μόνιμης μνήμης面向 Claude Code 的持久记忆压缩系统。其工作原理可以概括为一句话自动捕获 → AI 压缩 → 未来会话注入。围绕这一主线原文档列出了九项关键特性持久记忆上下文在会话之间存活渐进式披露Progressive Disclosure分层记忆检索每层都带 token 成本可见性基于技能的搜索通过mem-search技能用自然语言查询项目历史Web Viewerworker 启动时打印的 URL 上可看到实时记忆流Claude Desktop 技能在 Claude Desktop 对话中搜索记忆隐私控制使用private标签可将敏感内容排除在存储之外上下文配置细粒度控制注入哪些上下文自动运行无需人工干预引用Citations可通过 worker API 按 ID 引用过往观察或在 Web viewer 中查看全部。需要注意一点版本事实希腊语 README 顶部的徽章标注的是13.4.0而当前仓库 package.json 中实际版本为13.24.0——翻译版文档的徽章未随主 README 同步更新以当前仓库的 13.24.0 为准。快速上手四种安装路径原文档给出的安装方式共有四条全部继承如下。1. 单命令安装Claude Code 主线npx claude-mem install安装完成后重启 Claude Code之前会话的上下文会自动出现在新会话中。原文档的重要提醒Claude-Mem 虽然发布在 npm 上但npm install -g claude-mem只安装 SDK/库——不会注册 plugin hooks也不会配置 worker 服务。必须始终通过npx claude-mem install或下面的/plugin命令安装。2. 面向 OpenCode / Antigravity CLI 的安装# OpenCode npx claude-mem install --ide opencode # Antigravity CLI npx claude-mem install --ide antigravity3. 通过 Claude Code 内的 plugin marketplace/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem4. OpenClaw Gateway 插件curl -fsSL https://install.cmem.ai/openclaw.sh | bash原文档说明该安装器会处理依赖、plugin 配置、AI 提供方设置、worker 启动以及可选的实时观察流推送到 Telegram、Discord、Slack 等。仓库中openclaw/目录含 openclaw/SKILL.md、openclaw/install.sh即为该集成的来源实现。系统要求与 Windows 注意事项原文档列出的运行前提Node.js20.0.0 或更高package.json徽章同样标注node 20.0.0Claude Code支持 plugin 的最新版本BunJavaScript 运行时与进程管理器缺失时自动安装uv向量搜索所用的 Python 包管理器缺失时自动安装SQLite 3持久化存储内置。Windows 上若看到类似npm : The term npm is not recognized as the name of a cmdlet的错误说明 Node.js/npm 未安装或未加入 PATH——安装最新版 Node.js 后重启终端即可。仓库内docs/bug-fixes/windows-spaces-issue.md还记录了一类 Windows 特定问题可作为排障参考。工作原理五个生命周期 Hook 与六大核心组件原文档的Πώς ΛειτουργείHow It Works列出六个核心组件5 个生命周期 Hook——SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd共 6 个 hook 脚本智能安装Smart Install——带缓存的依赖检查器pre-hook 脚本不属于生命周期 hookWorker 服务——本地 HTTP API带 Web viewer 与搜索端点由 Bun 托管SQLite 数据库——存储会话、观察observations、摘要mem-search 技能——自然语言查询 渐进式披露Chroma 向量数据库——语义 关键词混合搜索支撑智能上下文检索。结合仓库源码可以印证这一架构plugin/hooks/hooks.json 中实际注册了Setup、SessionStart、UserPromptSubmit、PostToolUse、PreToolUse、Stop等事件每个事件都通过plugin/scripts/下的脚本转发到 workerSetup事件执行 plugin/scripts/version-check.js对应智能安装/依赖检查组件且带CLAUDE_PLUGIN_ROOT解析与版本缓存逻辑SessionStart事件执行 plugin/scripts/worker-service.cjs 的start子命令拉起 worker随后执行hook claude-code context注入上下文运行时统一经 plugin/scripts/bun-runner.js 用 Bun 拉起与Worker 由 Bun 管理的文档描述一致。也就是说从源码结构看Hook 脚本本身只是轻量转发器真正的记忆写入、压缩、检索逻辑都落在 worker 进程内SQLite 存储层见 src/storage/sqlite/MCP 工具见 src/servers/mcp-server.ts。MCP 检索工具三层工作流与约 10 倍 token 节省原文档指出 Claude-Mem 通过4 个 MCP 工具提供记忆搜索并遵循一个 token 高效的三层工作流search——获取带 ID 的紧凑索引每条约 50–100 tokenstimeline——获取感兴趣结果周围的时序上下文get_observations——仅为筛选后的 ID 拉取完整细节每条 500–1000 tokens。工作机制先用search拿到结果索引再用timeline查看特定观察前后的时间线最后用get_observations拉取相关 ID 的完整细节由于先过滤、后取详情原文档给出约 10 倍 token 节省的效果。原文档的调用示例完整保留// Step 1: Search for index search(queryauthentication bug, typebugfix, limit10) // Step 2: Review index, identify relevant IDs (e.g., #123, #456) // Step 3: Fetch full details get_observations(ids[123, 456])仓库中 src/servers/mcp-server.ts 定义了这些 MCP 工具并且对get_observations类工具带有运行时守卫当CLAUDE_MEM_RUNTIME为server之外的模式时会明确提示当前是 worker 运行时请使用 worker 模式下的 search/timeline/get_observations 工具可见 worker 与 server 两种运行时对同一组工具的可见性做了区分见 src/servers/mcp-tool-visibility.ts。配置settings.json 与 CLAUDE_MEM_MODE 模式/语言系统设置文件原文档说明配置集中在~/.claude-mem/settings.json首次运行时自动以默认值创建可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入行为。这与源码中的默认值管理器一致src/shared/SettingsDefaultsManager.ts 显示CLAUDE_MEM_DATA_DIR默认即~/.claude-memCLAUDE_MEM_MODE默认为codeCLAUDE_MEM_MODEL默认为claude-haiku-4-5-20251001且文件注释明确全新的 settings.json 会被播种seed全部默认项。模式与语言CLAUDE_MEM_MODECLAUDE_MEM_MODE同时控制两件事工作流行为如 code、chill、investigation与生成观察所用的语言。配置方式{ CLAUDE_MEM_MODE: code--zh }编辑~/.claude-mem/settings.json后重启 Claude Code 生效。模式定义在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已内置无需额外安装。从仓库实况看plugin/modes/ 目录下实际提供了远比表格更多的模式文件除code.json默认与code--zh.json、code--ja.json外还有code--el.json希腊语与本文翻译版 README 同源、code--fr.json、code--de.json、code--es.json、code--ru.json等约 28 个语言模式以及code--chill.json、email-investigation.json、law-study.json等非编码场景模式——正好对应原文档所说的工作流行为 语言双维度控制。发布分支、开发与排障三个发布分支原文档说明稳定版从main分支发布并推送到 npmcore-dev与community-edge是源码运行source-run分支用于早期可靠性修复与社区集成。仓库中 docs/public/branches.mdx 与 plans/2026-07-05-three-release-branches.md 进一步记录了这套三分支策略的背景。Bug 报告生成器cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report该命令对应仓库中 scripts/bug-report/ 目录下的收集器与 CLI 实现。排障方式原文档建议遇到问题时直接描述给 Claudetroubleshoot技能会自动诊断并给出解决方案同时仓库内 docs/public/troubleshooting.mdx 与 docs/bug-fixes/windows-spaces-issue.md 提供了常见问题的书面记录。开发流程构建、测试、贡献参见 docs/public/development.mdx贡献流程为 Fork → 特性分支 → 带测试的变更 → 更新文档 → 提交 PR。许可与知识产权边界原文档声明 Claude-Mem 采用Apache License 2.0许可并给出选型理由持久化 Agent 记忆应能轻松嵌入开发者工具、本地 Agent、MCP 服务器、企业系统、机器人技术栈与生产级 Agent harness。完整条款见 LICENSE许可范围与开源/商业边界见 docs/license.md 和 docs/ip-boundary.md。关于 ragtime 的单独说明ragtime/目录同样以 Apache License 2.0 分发详见 ragtime/LICENSE其实现为 ragtime/ragtime.ts。小结这篇希腊语 README 完整覆盖了 Claude-Mem 的使用者视角全貌四种安装入口npx、--ide变体、plugin marketplace、OpenClaw 网关、六组件架构5 个生命周期 Hook Smart Install Bun 托管 worker SQLite mem-search 技能 Chroma 向量库、token 高效的三层 MCP 检索工作流、~/.claude-mem/settings.json与CLAUDE_MEM_MODE模式/语言配置、三分支发布策略以及 Apache-2.0 许可边界。结合仓库源码plugin/hooks/hooks.json 的事件注册、src/shared/SettingsDefaultsManager.ts 的默认值播种、plugin/modes/ 的 30 余个模式文件可以确认原文档描述的自动捕获—AI 压缩—上下文注入闭环在代码层面有完整对应实现且当前仓库实际版本为 13.24.0安装与配置操作请以该版本的package.json与源码为准。【免费下载链接】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），仅供参考