claude-mem 跨会话持久记忆系统安装、Hook 架构、MCP 三层搜索与配置全解基于德语官方 README【免费下载链接】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 编码 Agent 的持久化记忆压缩系统它在会话中自动捕获工具调用产生的“观察Observation”用 AI 压缩成可检索的知识并在未来会话启动时把相关上下文注入回去从而让 Agent 跨会话保持项目认知。本文以仓库中的德语版 READMEdocs/i18n/README.de.md为主体完整覆盖其安装方式、核心组件、MCP 搜索工具、~/.claude-mem/settings.json配置项、模式与语言配置、系统要求与故障排查等全部实战内容并结合仓库源码Hook 定义、MCP 工具实现、默认值管理器、模式文件逐项验证与扩充。读完本文你可以独立安装并配置 claude-mem、用 MCP 三层工作流检索历史记忆并能从源码层面理解每个配置项的实际默认值与作用。安装与快速上手README 提供四种安装入口全部继承自原文档npx 一键安装默认针对 Claude Codenpx claude-mem install为 OpenCode 安装npx claude-mem install --ide opencode为 Antigravity CLI 安装对应官方文档站antigravity-cli/setup指南仓库内对应说明见 docs/public/antigravity-cli/setup.mdxnpx claude-mem installnpx claude-mem install --ide antigravity通过 Claude Code 插件 Marketplace 安装/plugin marketplace add thedotmack/claude-mem /plugin install claude-mem安装后重启 Claude Code之前会话的上下文会自动出现在新会话中。重要提示原文档强调虽然 claude-mem 也发布在 npm 上但npm install -g claude-mem只安装 SDK/库——它既不注册插件 Hook也不配置 Worker 服务。完整安装必须走npx claude-mem install或上述/plugin命令。仓库内 src/npx-cli/index.ts 是 npx 安装入口的实现src/npx-cli/install/ 下是各 IDE 安装流程的具体代码可作为安装行为的源码佐证。OpenClaw Gateway 安装除了 Claude Code/OpenCode/Antigravityclaude-mem 还支持作为持久存储插件装到 OpenClaw 网关上原文档中的单行安装命令指向外部安装脚本此处说明方式与仓库 openclaw/install.sh、openclaw/README.md 对应# 仓库内 OpenClaw 安装脚本本地查看 bash openclaw/install.sh安装器负责依赖安装、插件配置、AI 提供商配置、Worker 启动以及可选的实时观察推送Telegram、Discord、Slack 等。仓库内 openclaw/ 目录包含 OpenClaw 插件的源码openclaw/src/index.ts、插件清单openclaw/openclaw.plugin.json与端到端验证脚本openclaw/e2e-verify.sh是理解该集成最直接的入口。核心特性原文档列出九项主要特性逐条对应仓库实现持久记忆——上下文跨会话保留SQLite 存储见 src/storage/sqlite/渐进式披露Progressive Disclosure——分层记忆读取并显示 Token 成本基于 Skill 的搜索——mem-searchSkill 检索项目历史plugin/skills/mem-search/SKILL.md;Web 查看器 UI——启动时输出的 Worker URL 上提供实时记忆流plugin/ui/viewer.htmlClaude Desktop Skill——从 Claude Desktop 会话中检索记忆隐私控制——用private标签把敏感内容排除在存储之外实现见 src/utils/tag-stripping.ts上下文配置——细粒度控制注入哪类上下文对应CLAUDE_MEM_CONTEXT_*系列设置见下文配置节自动运行——无需人工干预引用Citations——通过 Worker API 用 ID 引用历史观察或在 Web 查看器中浏览全部记忆。工作原理六大核心组件与 Hook 架构原文档“Wie es funktioniert”一节列出 6 个核心组件。下面按仓库实际代码逐一展开特别是 Hook 部分——这是整套记忆管道的骨架。原文档列出的核心组件生命周期 Hook——SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd共 6 个 Hook 脚本Smart Install——带缓存的依赖检查器Pre-Hook 脚本非生命周期 HookWorker Service——本地 HTTP API带 Web 查看器 UI 与搜索端点由 Bun 管理SQLite 数据库——存储会话sessions、观察observations、摘要summariesmem-search Skill——自然语言查询配合渐进式披露Chroma 向量数据库——混合的语义 关键词搜索用于智能上下文召回。Hook 定义源码解析仓库 plugin/hooks/hooks.json 是 Hook 的权威定义。从源码结构看当前版本实际注册了6 个 Hook 事件Setup、SessionStart、UserPromptSubmit、PostToolUse、PreToolUsematcher 为Read、Stop。每个事件都通过node 插件目录/scripts/bun-runner.js 插件目录/scripts/worker-service.cjs hook claude-code 子命令的形式把控制权交给 Worker 服务的不同子命令。各事件与职责对应关系如下Hook 事件触发时机matcherWorker 子命令超时作用Setup*version-check.js独立脚本300s安装前置检查依赖就绪、版本缓存SessionStartstartup\|clear\|compactstart拉起 Workercontext60s ×2启动 Worker 服务并注入历史上下文UserPromptSubmit每次提交session-init60s会话初始化/标记PostToolUse*observationasync120s异步捕获工具调用生成观察PreToolUseReadfile-contextasync60s读取文件前注入该文件相关历史StopAgent 停止时summarizeasync120s生成进度摘要/检查点几点源码细节值得注意hooks.json中的启动命令包含一段较长的 shell 前导逻辑优先取CLAUDE_PLUGIN_ROOT否则在~/.claude/plugins/cache/thedotmack/claude-mem/下按版本号降序挑选**最新且未标记孤儿.orphaned_at**的插件缓存副本最后兜底到~/.claude/plugins/marketplaces/thedotmack/plugin。这保证了多版本共存时 Hook 总是调用最新插件副本且 Windows 下会通过cygpath转换路径。PostToolUse、PreToolUse、Stop三个捕获类 Hook 都标记了async: true说明观察生成、文件上下文与摘要生成不阻塞主会话与“静默运行”的设计目标一致。各子命令的实现位于 src/cli/hook-command.ts它按hook claude-code 子命令分发到 src/cli/handlers/ 下各处理器超时上限常量集中在 src/shared/hook-constants.ts例如CLAUDE_MEM_API_TIMEOUT_MS默认值即取自其中的HOOK_TIMEOUTS.API_REQUEST。Worker 服务与数据存储组件 3 的 Worker 是本地 HTTP 服务入口脚本为 plugin/scripts/worker-service.cjs由 Bun Runnerplugin/scripts/bun-runner.js拉起。从 src/shared/SettingsDefaultsManager.ts 可确认其关键默认值监听127.0.0.1端口默认为37700 (uid % 100)——按用户 UID 派生端口用于多账户隔离数据目录默认~/.claude-memCLAUDE_MEM_DATA_DIR观察生成默认模型为claude-haiku-4-5-20251001CLAUDE_MEM_MODEL默认 Provider 为claude认证方式默认走已登录的 Claude SDK 订阅而非 API Key。组件 4 的 SQLite 层会话与观察的持久化实现在 plugin/sqlite/SessionStore.js 与 src/storage/sqlite/并带 FTS5 全文索引对应原文档 Architecture 文档中提到的 “SQLite-Schema FTS5-Suche”。组件 6 的 Chroma 混合搜索默认开启CLAUDE_MEM_CHROMA_ENABLED: true模式local通过 uvx 运行持久化 chroma-mcp主机127.0.0.1:8000设为false时退化为纯 SQLite 搜索。mem-search Skill 的三层工作流组件 5 的 Skill 定义在 plugin/skills/mem-search/SKILL.md其核心纪律是“search → filter → fetch永远不要先取详情再过滤可节省约 10 倍 Token”。该 Skill 与下文 MCP 工具一一对应并在 docs/public/usage/search-tools.mdx 中有完整使用示例。MCP 搜索工具token 高效的 3 层工作流原文档“MCP-Suchwerkzeuge”一节是全文技术密度最高的部分claude-mem 通过MCP 工具对外暴露记忆检索核心是 3 层工作流模式。3 层工作流search——取回紧凑索引含 ID约 50–100 Token/条timeline——取回有趣结果前后的时间线上下文get_observations——仅对筛选后的 ID 取完整详情约 500–1000 Token/条。工作方式Claude 用 MCP 工具检索记忆先用search拿索引再用timeline看某条观察前后发生了什么最后用get_observations批量取详情——先过滤后取详情带来约 10 倍 Token 节省。原文档示例用法原样保留注意批量取详情// 步骤 1: 搜索索引 search(queryauthentication bug, typebugfix, limit10) // 步骤 2: 检查索引识别相关 ID例如 #123、#456 // 步骤 3: 获取完整详情 get_observations(ids[123, 456])源码验证工具如何落到 Worker APIMCP 服务器的完整实现在 src/servers/mcp-server.ts。三个核心工具的 schema 与路由均能从源码确认searchsrc/servers/mcp-server.ts#L474-L523参数query, limit, project, platformSource, type, obs_type, dateStart, dateEnd, offset, orderBy。默认 Worker 模式下转发到本地/api/search当运行时切换为 server 模式CLAUDE_MEM_RUNTIMEserver且请求可被/v1/search忠实服务纯观察文本查询、无额外过滤时改走服务端 GIN tsvector 全文索引——这段路由逻辑resolveServerToolContext()在每次调用时重新解析因此切换运行时无需重启 MCP 服务器。timelinesrc/servers/mcp-server.ts#L525-L541参数anchor观察 ID或query自动定位锚点、depth_before/depth_after默认各 3、project转发到/api/timeline。get_observationssrc/servers/mcp-server.ts#L543-L560ids为必填数组转发到/api/observations/batch源码注释明确要求“2 个以上 ID 必须批量”。从源码结构看该 MCP 服务器实际注册的工具远不止这 3 个还包括session_start_context渲染与 SessionStart Hook 完全一致的注入文本便于调试注入内容、server 运行时专用的observation_add/observation_record_event/observation_search/observation_context/observation_generation_status走服务端/v1REST 核心与 Hook 共享同一套事件写入 outbox 入队逻辑以及基于 tree-sitter AST 的代码结构工具smart_search/smart_unfold/smart_outline和语料库工具build_corpus等见 src/servers/mcp-server.ts#L669-L888。此外 src/servers/mcp-tool-visibility.ts 按运行时决定对外暴露哪些工具——这就是 README 说“4 MCP-Tools”与源码中工具数量不完全一致的原因可见工具集合是随运行时动态裁剪的。该服务器还刻意拦截了console.logsrc/servers/mcp-server.ts#L7-L9防止任何杂散输出污染 stdio MCP 协议。配置settings.json 与源码级默认值原文档指出配置位于~/.claude-mem/settings.json首次启动时自动用默认值创建可配置 AI 模型、Worker 端口、数据目录、日志级别和上下文注入行为。仓库中默认值与加载逻辑集中在 src/shared/SettingsDefaultsManager.ts。从源码看有三条重要的加载规则缺省即落盘若settings.json不存在loadFromFile()会把全部默认值原子写入该文件src/shared/SettingsDefaultsManager.ts#L264-L278持久值优先于内置默认磁盘值覆盖DEFAULTS再叠加环境变量覆盖applyEnvOverrides即优先级为环境变量 settings.json 内置默认自动迁移旧版{ env: {...} }嵌套结构会被自动展平为扁平 schema某个遗留 Telegram 触发器默认值也会被一次性重写为当前默认。关键配置项节选自源码默认值表可完整继承原文档“模型 / 端口 / 数据目录 / 日志 / 上下文注入”的配置面并进一步展开配置项默认值说明CLAUDE_MEM_MODELclaude-haiku-4-5-20251001观察生成使用的 AI 模型CLAUDE_MEM_PROVIDERclaude观察生成 Provider交互安装器另可选 cmem/gemini/openrouter 等CLAUDE_MEM_CLAUDE_AUTH_METHODsubscription默认使用已登录 Claude SDK 订阅认证CLAUDE_MEM_WORKER_PORT37700 (uid % 100)Worker HTTP 端口按 UID 派生实现多账户隔离CLAUDE_MEM_WORKER_HOST127.0.0.1Worker 绑定地址CLAUDE_MEM_DATA_DIR~/.claude-memSQLite 数据目录CLAUDE_MEM_LOG_LEVELINFO日志级别CLAUDE_MEM_MODEcode工作流模式/语言见下一节CLAUDE_MEM_CONTEXT_OBSERVATIONS50上下文注入的观察条数上限CLAUDE_MEM_CONTEXT_SESSION_COUNT10注入的最近会话数CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARYtrue是否展示最近一次摘要CLAUDE_MEM_CONTEXT_FULL_FIELDnarrative完整模式下展开的字段CLAUDE_MEM_CONTEXT_SHOW_TERMINAL_OUTPUTtrue是否展示终端输出CLAUDE_MEM_SKIP_TOOLSListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion捕获时跳过的工具CLAUDE_MEM_MAX_CONCURRENT_AGENTS2并发 SDK 观察子进程上限CLAUDE_MEM_SEMANTIC_INJECTfalse每次提交时语义注入历史观察实验特性默认关CLAUDE_MEM_SEMANTIC_INJECT_LIMIT5语义注入的 Top-N 条数CLAUDE_MEM_TIER_ROUTING_ENABLEDtrue按复杂度把任务路由到不同档位模型$TIER:fast/$TIER:smart解析到CLAUDE_MEM_TIER_FAST_MODELhaiku /CLAUDE_MEM_TIER_SMART_MODELsonnetCLAUDE_MEM_CHROMA_ENABLEDtrue关闭后仅用 SQLite 搜索CLAUDE_MEM_CHROMA_MODE/HOST/PORTlocal/127.0.0.1/8000Chroma 本地 uvx 模式或远程服务器CLAUDE_MEM_QUEUE_ENGINEsqlite队列引擎可切 RedisCLAUDE_MEM_RUNTIMEworker本地 Worker 运行时或server运行时CLAUDE_MEM_CONTEXT_*一组开关正是原文档“上下文配置——细粒度控制注入哪类上下文”特性的落地Token 成本显示SHOW_READ_TOKENS/SHOW_WORK_TOKENS/SHOW_SAVINGS_*、最近消息展示SHOW_LAST_MESSAGE、文件夹 CLAUDE.md 生成FOLDER_CLAUDEMD_ENABLED默认关开启后FOLDER_USE_LOCAL_MD可改为写CLAUDE.local.md等都可以在同一文件中逐项开关。完整配置说明另见 docs/public/configuration.mdx 与 docs/public/hooks-architecture.mdx。模式与语言配置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/原文档列出的可用模式表模式描述code默认模式英语code--zh简体中文模式code--ja日语模式语言模式遵循code--[lang]命名规则[lang]为 ISO-639-1 语言码如zh、ja、es。原文档特别注明code--zh已内置无需额外安装或更新插件。从仓库源码看plugin/modes/ 实际包含 20 种语言变体code--ar.json、code--de.json、code--fr.json直至code--no.json以及chill、investigation等行为变体plugin/modes/code--chill.json、law-study、meme-tokens等扩展模式——原文档只列了最常用的三种本地目录才是完整清单。模式文件的结构以 plugin/modes/code.json 为例定义了观察类型bugfix/feature/refactor/change/discovery/decision/security_alert/security_note/sensitive共 9 种各带 emoji 与说明、观察概念how-it-works/why-it-exists/what-changed/problem-solution/gotcha/pattern/trade-off共 7 种以及观察者提示词系统身份、静默原则、记录重点、输出 XML 格式等。也就是说CLAUDE_MEM_MODE实际决定了观察生成器的分类体系与提示词模板这解释了为什么改模式后观察内容的类型和语言会同时变化。修改模式后需重启 Claude Code 生效。系统要求与 Windows 注意事项原文档“Systemanforderungen”一节对应徽章声明的版本事实License Apache-2.0、version 13.4.0、Node ≥ 20.0.0Node.js≥ 20.0.0Claude Code支持插件的最新版本BunJS 运行时与进程管理器缺失时自动安装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 下进程隐藏、wmic 解析的回归测试tests/infrastructure/windows-hide-regressions.test.ts、tests/infrastructure/wmic-parsing.test.ts说明 Windows 路径与进程管理是项目重点维护的边界。开发、发布分支与故障排查发布分支原文档“Release-Branches”节稳定版从main分支构建并发布到 npmcore-dev与community-edge是从源码直接运行的分支分别用于早期可靠性修复与社区集成。三个分支的流转与本地运行非稳定版的方法见 docs/public/branches.mdx。开发构建、测试与贡献流程见 docs/public/development.mdx。仓库测试规模可观例如 Hook 生命周期测试tests/hook-lifecycle.test.ts、MCP 工具可见性测试tests/servers/mcp-runtime-tool-visibility.test.ts、MCP 工具 schema 测试tests/servers/mcp-tool-schemas.test.ts、Session 存储迁移测试tests/sqlite/session-store-migrations.test.ts可作为验证各组件行为的参照。故障排查原文档方案遇到问题时直接向 Claude 描述troubleshoot Skill 会自动诊断并给出解决方案常见问题的完整清单见 docs/public/troubleshooting.mdx。自动化 Bug 报告原文档命令cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report该命令对应仓库 scripts/bug-report/ 下的采集器实现scripts/bug-report/collector.ts。贡献流程Fork 仓库 → 建功能分支 → 带测试提交改动 → 更新文档 → 提 PR。注意仅main发布到 npm其余两个分支以源码方式运行。许可证与边界claude-mem 采用Apache License 2.0LICENSE。原文档解释了选型理由持久化 Agent 存储应能被轻松嵌入开发者工具、本地 Agent、MCP 服务器、企业系统、机器人栈与生产级 Agent Harness。许可证范围与“开源/商业”边界的说明见 docs/license.md 和 docs/ip-boundary.md。另外ragtime/目录ragtime/ragtime.ts同样在 Apache License 2.0 下ragtime/LICENSE。小结从文档到源码的完整闭环这篇德语 README 的技术骨架可以浓缩为一条可验证的闭环Setup/SessionStart Hook 拉起 Bun WorkerHTTP API Web 查看器→ PostToolUse/Stop Hook 异步触发观察生成模式文件决定类型体系与语言→ 观察写入 SQLiteFTS5并同步 Chroma 向量库 → SessionStart 注入分层上下文CLAUDE_MEM_CONTEXT_控制成本与内容→ mem-search Skill 与 search/timeline/get_observations 三个 MCP 工具按 3 层工作流回查记忆*。每个环节都能在仓库中找到对应实现Hook 契约在 plugin/hooks/hooks.json默认值与配置加载在 src/shared/SettingsDefaultsManager.tsMCP 工具在 src/servers/mcp-server.ts模式定义在 plugin/modes/Skill 契约在 plugin/skills/mem-search/SKILL.md。配置与运行时行为均以当前仓库内容为准若切换 server 运行时或关闭 Chroma部分工具与搜索路径会按本文标注的源码逻辑自动降级或改道。【免费下载链接】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），仅供参考