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-mem本文基于 claude-mem 仓库的越南语官方 READMEdocs/i18n/README.vi.md整理成文系统讲解这套为 Claude Code 构建的持续记忆压缩系统的核心能力一条命令完成安装、5 个生命周期 Hook 如何驱动观察捕获与语义摘要、4 个 MCP 工具构成的三层 token 高效检索模型以及CLAUDE_MEM_MODE模式与语言配置。读完后你将掌握从安装配置到源码级原理的完整知识链路并能直接在实际项目中落地跨会话记忆能力。项目定位跨会话的持久上下文Claude-Mem 通过自动记录工具使用观察observations、生成语义摘要并将这些上下文回注到未来的会话中实现工作会话之间的连贯记忆。正如 README 所述Claude-Mem 通过自动记录工具使用观察、创建语义摘要并将其提供给未来会话来维护连贯的上下文——这使 AI 代理在项目会话结束或重连后仍能保持对项目知识的连续性。当前 package.json 显示项目版本为13.24.0engines字段要求node 20.12.0与bun 1.0.0README 徽章标注 Node 20实际约束以 package.json 为准。项目采用 TypeScript 编写基于 Claude Agent SDK 构建使用 Apache-2.0 许可证。快速开始一条命令安装npx claude-mem install针对其他 IDE / 运行时的安装变体# 为 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命令安装。这一点可以从 package.json 的bin字段得到印证可执行入口是./dist/npx-cli/index.js即 npx CLI而不是一个全局 SDK。OpenClaw Gateway 安装curl -fsSL https://install.cmem.ai/openclaw.sh | bash安装器负责处理依赖、配置插件、设置 AI 提供商、启动 worker并可选择将实时观察流推送到 Telegram、Discord、Slack 等。仓库内 openclaw/ 目录包含该集成的插件定义与脚本docs/public/openclaw-integration.mdx 提供完整集成说明。核心特性一览持续记忆上下文跨会话保留渐进式披露分层记忆检索附带 token 成本可视化技能化搜索通过 mem-search 技能以自然语言查询项目历史Web Viewerworker 启动时打印的 URL 处提供实时记忆流界面Claude Desktop 技能从 Claude Desktop 对话中搜索记忆隐私控制使用private标签将敏感内容排除在存储之外上下文配置精细控制被注入的上下文自动运行无需人工干预引用机制通过 worker API 按 ID 引用过往观察或在 web viewer 中浏览工作原理六大核心组件README 列出了系统骨架我们逐一对照源码验证5 个生命周期 Hooks— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd6 个 hook 脚本Smart Install— 依赖检查工具pre-hook script不是 lifecycle hookWorker Service— 由 Bun 管理的本地 HTTP API提供 web viewer 与搜索端点SQLite 数据库— 存储会话、观察与摘要mem-search 技能— 带渐进披露的自然语言查询Chroma 向量数据库— 语义 关键词混合检索从 plugin/hooks/hooks.json 的源码结构看实际注册的 Hook 事件比 README 的概括更细致Hook 事件Matcher执行的 worker 子命令说明Setup*version-check.js预检查版本与插件路径即Smart Install式的前置脚本SessionStartstartup\|clear\|compactworker-service.cjs starthook claude-code context启动 worker 并注入历史上下文UserPromptSubmit—hook claude-code session-init用户提交提示词时初始化会话记录PostToolUse*asynchook claude-code observation每次工具调用后异步捕获观察PreToolUseReadasynchook claude-code file-context读文件前注入文件相关历史上下文Stop—asynchook claude-code summarize会话停止时异步生成语义摘要每个 hook 命令都会先在CLAUDE_PLUGIN_ROOT或~/.claude/plugins/cache/thedotmack/claude-mem/*/中按版本号排序定位插件脚本目录再通过bun-runner.js执行worker-service.cjs见 plugin/scripts/worker-service.cjs 与 plugin/scripts/bun-runner.js。PostToolUse、PreToolUse、Stop 三个 hook 均设置async: true并配置了 60–120 秒超时说明观察捕获与摘要生成不阻塞用户交互——这与自动运行、无感的产品定位一致。更完整的 hooks 生命周期说明见 docs/public/hooks-architecture.mdx 与 docs/public/architecture/hooks.mdxworker 服务架构见 docs/public/architecture/worker-service.mdxSQLite 与 FTS5 全文检索的数据库设计见 docs/public/architecture/database.mdxChroma 向量混合检索见 docs/public/architecture/search-architecture.mdx。MCP 搜索工具三层 token 高效检索模型Claude-Mem 通过4 个 MCP 工具提供智能记忆搜索遵循一套按 token 优化的三层流程three-layer workflow三层流程search— 获取带 ID 的轻量索引约 50–100 token/条结果timeline— 获取有趣结果周围的时间线上下文get_observations— 仅对筛选后的 ID 获取完整详情约 500–1000 token/条工作方式先用search拿到结果索引再用timeline查看特定观察前后发生了什么最后用get_observations只取相关 ID 的完整细节——先筛选再取详情带来约10 倍 token 节省。这一工作流在 MCP server 源码中得到直接印证src/servers/mcp-server.ts 中的工具描述明确写着三步search(query) → Get index with IDs (~50-100 tokens/result)、timeline(anchorID) → Get context around interesting results、get_observations([IDs]) → Fetch full details ONLY for filtered IDs。该文件同时表明当CLAUDE_MEM_RUNTIMEserver时另有observation_search等服务端观察工具worker 模式下则使用现有的 search/timeline/get_observations 工具。各工具参数详解结合 plugin/skills/mem-search/SKILL.md 的完整参数定义search工具参数参数说明query(string)搜索词limit(number)最大结果数默认 20上限 100project(string)项目名过滤type(string, 可选)observations、sessions或promptsobs_type(string, 可选)逗号分隔bugfix, feature, decision, discovery, changedateStart/dateEnd(string, 可选)YYYY-MM-DD或 epoch 毫秒offset(number, 可选)跳过 N 条结果分页orderBy(string, 可选)date_desc默认、date_asc、relevancetimeline工具参数参数说明anchor(number, 可选)以其为中心的观察 IDquery(string, 可选)未提供 anchor 时自动定位锚点depth_before(number, 可选)锚点前取 N 条默认 5上限 20depth_after(number, 可选)锚点后取 N 条默认 5上限 20project(string)项目名过滤get_observations工具参数参数说明ids(array of numbers, 必填)要获取的观察 ID 列表orderBy(string, 可选)date_desc默认或date_asclimit(number, 可选)最大返回条数project(string, 可选)项目名过滤使用示例// 步骤 1搜索获取索引 search(queryauthentication bug, typebugfix, limit10) // 步骤 2审视索引确定相关 ID例如 #123、#456 // 步骤 3获取完整详情 get_observations(ids[123, 456])更多实战示例查找上周发生的事、围绕某条 discovery 建立时间线、批量获取详情等见 plugin/skills/mem-search/SKILL.md 与 docs/public/usage/search-tools.mdx。发行分支策略稳定版从main分支构建并发布到 npmcore-dev与community-edge是供可靠性修复提前体验与社区集成直接运行源码的分支。分支策略与运行不稳定版本的指南见 docs/public/branches.mdx。系统要求Node.js20.0.0 或更高package.json 的engines字段实际要求20.12.0Claude Code支持插件的最新版本BunJavaScript 运行时与进程管理器缺失时自动安装uvPython 包管理器用于向量检索缺失时自动安装SQLite 3用于持久存储内置Windows 安装注意事项若遇到如下错误npm : The term npm is not recognized as the name of a cmdlet请确保已安装 Node.js 与 npm 并加入 PATH从 nodejs.org 下载最新安装器安装后重启终端。配置配置文件位于~/.claude-mem/settings.json首次运行自动以默认值创建可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入设置。完整的配置项清单与示例见 docs/public/configuration.mdx。模式与语言配置CLAUDE_MEM_MODEClaude-Mem 通过CLAUDE_MEM_MODE设置支持多种工作模式与语言它同时控制工作流行为如 code、chill、investigation生成的观察所使用的语言配置方法编辑~/.claude-mem/settings.json{ CLAUDE_MEM_MODE: code--zh }各模式定义在plugin/modes/目录下本仓库 plugin/modes/ 中包含code.json、code--zh.json、code--ja.json、code--chill.json、law-study.json、meme-tokens.json等 30 余个模式文件。查看本机已安装的全部模式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 使新配置生效。开发、排错与错误报告开发指南构建、测试与贡献流程见 docs/public/development.mdx自动排错遇到问题时可直接向 Claude 描述troubleshoot 技能会自动诊断并给出修复方案常见故障与解法见 docs/public/troubleshooting.mdx自动错误报告cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report该命令对应仓库中的 scripts/bug-report/ 目录含cli.ts与collector.ts用于采集环境信息并生成全面的错误报告。许可证Claude-Mem 采用Apache License 2.0授权。选择 Apache-2.0 的考量是代理式持久记忆应能轻松集成进开发者工具、本地 agent、MCP 服务器、企业系统、机器人平台与生产级 agent 框架。完整条款见 LICENSE授权范围与开源/商业边界见 docs/license.md 与 docs/ip-boundary.md。关于 Ragtimeragtime/目录同样采用 Apache License 2.0详见 ragtime/LICENSE。贡献流程Fork 仓库创建功能分支提交变更并附带测试更新文档提交 Pull RequestClaude-Mem 从三个分支发布main稳定版唯一发布到 npm 的分支、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），仅供参考 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-mem本文基于 claude-mem 仓库的越南语官方 READMEdocs/i18n/README.vi.md整理成文系统讲解这套为 Claude Code 构建的持续记忆压缩系统的核心能力一条命令完成安装、5 个生命周期 Hook 如何驱动观察捕获与语义摘要、4 个 MCP 工具构成的三层 token 高效检索模型以及CLAUDE_MEM_MODE模式与语言配置。读完后你将掌握从安装配置到源码级原理的完整知识链路并能直接在实际项目中落地跨会话记忆能力。项目定位跨会话的持久上下文Claude-Mem 通过自动记录工具使用观察observations、生成语义摘要并将这些上下文回注到未来的会话中实现工作会话之间的连贯记忆。正如 README 所述Claude-Mem 通过自动记录工具使用观察、创建语义摘要并将其提供给未来会话来维护连贯的上下文——这使 AI 代理在项目会话结束或重连后仍能保持对项目知识的连续性。当前 package.json 显示项目版本为13.24.0engines字段要求node 20.12.0与bun 1.0.0README 徽章标注 Node 20实际约束以 package.json 为准。项目采用 TypeScript 编写基于 Claude Agent SDK 构建使用 Apache-2.0 许可证。快速开始一条命令安装npx claude-mem install针对其他 IDE / 运行时的安装变体# 为 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命令安装。这一点可以从 package.json 的bin字段得到印证可执行入口是./dist/npx-cli/index.js即 npx CLI而不是一个全局 SDK。OpenClaw Gateway 安装curl -fsSL https://install.cmem.ai/openclaw.sh | bash安装器负责处理依赖、配置插件、设置 AI 提供商、启动 worker并可选择将实时观察流推送到 Telegram、Discord、Slack 等。仓库内 openclaw/ 目录包含该集成的插件定义与脚本docs/public/openclaw-integration.mdx 提供完整集成说明。核心特性一览持续记忆上下文跨会话保留渐进式披露分层记忆检索附带 token 成本可视化技能化搜索通过 mem-search 技能以自然语言查询项目历史Web Viewerworker 启动时打印的 URL 处提供实时记忆流界面Claude Desktop 技能从 Claude Desktop 对话中搜索记忆隐私控制使用private标签将敏感内容排除在存储之外上下文配置精细控制被注入的上下文自动运行无需人工干预引用机制通过 worker API 按 ID 引用过往观察或在 web viewer 中浏览工作原理六大核心组件README 列出了系统骨架我们逐一对照源码验证5 个生命周期 Hooks— SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd6 个 hook 脚本Smart Install— 依赖检查工具pre-hook script不是 lifecycle hookWorker Service— 由 Bun 管理的本地 HTTP API提供 web viewer 与搜索端点SQLite 数据库— 存储会话、观察与摘要mem-search 技能— 带渐进披露的自然语言查询Chroma 向量数据库— 语义 关键词混合检索从 plugin/hooks/hooks.json 的源码结构看实际注册的 Hook 事件比 README 的概括更细致Hook 事件Matcher执行的 worker 子命令说明Setup*version-check.js预检查版本与插件路径即Smart Install式的前置脚本SessionStartstartup\|clear\|compactworker-service.cjs starthook claude-code context启动 worker 并注入历史上下文UserPromptSubmit—hook claude-code session-init用户提交提示词时初始化会话记录PostToolUse*asynchook claude-code observation每次工具调用后异步捕获观察PreToolUseReadasynchook claude-code file-context读文件前注入文件相关历史上下文Stop—asynchook claude-code summarize会话停止时异步生成语义摘要每个 hook 命令都会先在CLAUDE_PLUGIN_ROOT或~/.claude/plugins/cache/thedotmack/claude-mem/*/中按版本号排序定位插件脚本目录再通过bun-runner.js执行worker-service.cjs见 plugin/scripts/worker-service.cjs 与 plugin/scripts/bun-runner.js。PostToolUse、PreToolUse、Stop 三个 hook 均设置async: true并配置了 60–120 秒超时说明观察捕获与摘要生成不阻塞用户交互——这与自动运行、无感的产品定位一致。更完整的 hooks 生命周期说明见 docs/public/hooks-architecture.mdx 与 docs/public/architecture/hooks.mdxworker 服务架构见 docs/public/architecture/worker-service.mdxSQLite 与 FTS5 全文检索的数据库设计见 docs/public/architecture/database.mdxChroma 向量混合检索见 docs/public/architecture/search-architecture.mdx。MCP 搜索工具三层 token 高效检索模型Claude-Mem 通过4 个 MCP 工具提供智能记忆搜索遵循一套按 token 优化的三层流程three-layer workflow三层流程search— 获取带 ID 的轻量索引约 50–100 token/条结果timeline— 获取有趣结果周围的时间线上下文get_observations— 仅对筛选后的 ID 获取完整详情约 500–1000 token/条工作方式先用search拿到结果索引再用timeline查看特定观察前后发生了什么最后用get_observations只取相关 ID 的完整细节——先筛选再取详情带来约10 倍 token 节省。这一工作流在 MCP server 源码中得到直接印证src/servers/mcp-server.ts 中的工具描述明确写着三步search(query) → Get index with IDs (~50-100 tokens/result)、timeline(anchorID) → Get context around interesting results、get_observations([IDs]) → Fetch full details ONLY for filtered IDs。该文件同时表明当CLAUDE_MEM_RUNTIMEserver时另有observation_search等服务端观察工具worker 模式下则使用现有的 search/timeline/get_observations 工具。各工具参数详解结合 plugin/skills/mem-search/SKILL.md 的完整参数定义search工具参数参数说明query(string)搜索词limit(number)最大结果数默认 20上限 100project(string)项目名过滤type(string, 可选)observations、sessions或promptsobs_type(string, 可选)逗号分隔bugfix, feature, decision, discovery, changedateStart/dateEnd(string, 可选)YYYY-MM-DD或 epoch 毫秒offset(number, 可选)跳过 N 条结果分页orderBy(string, 可选)date_desc默认、date_asc、relevancetimeline工具参数参数说明anchor(number, 可选)以其为中心的观察 IDquery(string, 可选)未提供 anchor 时自动定位锚点depth_before(number, 可选)锚点前取 N 条默认 5上限 20depth_after(number, 可选)锚点后取 N 条默认 5上限 20project(string)项目名过滤get_observations工具参数参数说明ids(array of numbers, 必填)要获取的观察 ID 列表orderBy(string, 可选)date_desc默认或date_asclimit(number, 可选)最大返回条数project(string, 可选)项目名过滤使用示例// 步骤 1搜索获取索引 search(queryauthentication bug, typebugfix, limit10) // 步骤 2审视索引确定相关 ID例如 #123、#456 // 步骤 3获取完整详情 get_observations(ids[123, 456])更多实战示例查找上周发生的事、围绕某条 discovery 建立时间线、批量获取详情等见 plugin/skills/mem-search/SKILL.md 与 docs/public/usage/search-tools.mdx。发行分支策略稳定版从main分支构建并发布到 npmcore-dev与community-edge是供可靠性修复提前体验与社区集成直接运行源码的分支。分支策略与运行不稳定版本的指南见 docs/public/branches.mdx。系统要求Node.js20.0.0 或更高package.json 的engines字段实际要求20.12.0Claude Code支持插件的最新版本BunJavaScript 运行时与进程管理器缺失时自动安装uvPython 包管理器用于向量检索缺失时自动安装SQLite 3用于持久存储内置Windows 安装注意事项若遇到如下错误npm : The term npm is not recognized as the name of a cmdlet请确保已安装 Node.js 与 npm 并加入 PATH从 nodejs.org 下载最新安装器安装后重启终端。配置配置文件位于~/.claude-mem/settings.json首次运行自动以默认值创建可配置 AI 模型、worker 端口、数据目录、日志级别与上下文注入设置。完整的配置项清单与示例见 docs/public/configuration.mdx。模式与语言配置CLAUDE_MEM_MODEClaude-Mem 通过CLAUDE_MEM_MODE设置支持多种工作模式与语言它同时控制工作流行为如 code、chill、investigation生成的观察所使用的语言配置方法编辑~/.claude-mem/settings.json{ CLAUDE_MEM_MODE: code--zh }各模式定义在plugin/modes/目录下本仓库 plugin/modes/ 中包含code.json、code--zh.json、code--ja.json、code--chill.json、law-study.json、meme-tokens.json等 30 余个模式文件。查看本机已安装的全部模式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 使新配置生效。开发、排错与错误报告开发指南构建、测试与贡献流程见 docs/public/development.mdx自动排错遇到问题时可直接向 Claude 描述troubleshoot 技能会自动诊断并给出修复方案常见故障与解法见 docs/public/troubleshooting.mdx自动错误报告cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report该命令对应仓库中的 scripts/bug-report/ 目录含cli.ts与collector.ts用于采集环境信息并生成全面的错误报告。许可证Claude-Mem 采用Apache License 2.0授权。选择 Apache-2.0 的考量是代理式持久记忆应能轻松集成进开发者工具、本地 agent、MCP 服务器、企业系统、机器人平台与生产级 agent 框架。完整条款见 LICENSE授权范围与开源/商业边界见 docs/license.md 与 docs/ip-boundary.md。关于 Ragtimeragtime/目录同样采用 Apache License 2.0详见 ragtime/LICENSE。贡献流程Fork 仓库创建功能分支提交变更并附带测试更新文档提交 Pull RequestClaude-Mem 从三个分支发布main稳定版唯一发布到 npm 的分支、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），仅供参考