企业官网建设流程全解析

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-mem

claude-mem 是面向 Claude Code 等 AI 编码 Agent 的持久化记忆压缩系统：它在会话中自动捕获工具调用产生的“观察（Observation）”，用 AI 压缩成可检索的知识，并在未来会话启动时把相关上下文注入回去，从而让 Agent 跨会话保持项目认知。本文以仓库中的德语版 README（docs/i18n/README.de.md）为主体，完整覆盖其安装方式、核心组件、MCP 搜索工具、~/.claude-mem/settings.json配置项、模式与语言配置、系统要求与故障排查等全部实战内容，并结合仓库源码（Hook 定义、MCP 工具实现、默认值管理器、模式文件）逐项验证与扩充。读完本文，你可以独立安装并配置 claude-mem、用 MCP 三层工作流检索历史记忆，并能从源码层面理解每个配置项的实际默认值与作用。

安装与快速上手

README 提供四种安装入口，全部继承自原文档：

1. npx 一键安装（默认，针对 Claude Code）：

npx claude-mem install

2. 为 OpenCode 安装：

npx claude-mem install --ide opencode

3. 为 Antigravity CLI 安装（对应官方文档站antigravity-cli/setup指南，仓库内对应说明见 docs/public/antigravity-cli/setup.mdx）：

npx claude-mem install

npx claude-mem install --ide antigravity

4. 通过 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/Antigravity，claude-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.html）；
• Claude Desktop Skill——从 Claude Desktop 会话中检索记忆；
• 隐私控制——用<private>标签把敏感内容排除在存储之外（实现见 src/utils/tag-stripping.ts）；
• 上下文配置——细粒度控制注入哪类上下文（对应CLAUDE_MEM_CONTEXT_*系列设置，见下文配置节）；
• 自动运行——无需人工干预；
• 引用（Citations）——通过 Worker API 用 ID 引用历史观察，或在 Web 查看器中浏览全部记忆。

工作原理：六大核心组件与 Hook 架构

原文档“Wie es funktioniert”一节列出 6 个核心组件。下面按仓库实际代码逐一展开，特别是 Hook 部分——这是整套记忆管道的骨架。

原文档列出的核心组件：

1. 生命周期 Hook——SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd（共 6 个 Hook 脚本）；
2. Smart Install——带缓存的依赖检查器（Pre-Hook 脚本，非生命周期 Hook）；
3. Worker Service——本地 HTTP API，带 Web 查看器 UI 与搜索端点，由 Bun 管理；
4. SQLite 数据库——存储会话（sessions）、观察（observations）、摘要（summaries）；
5. mem-search Skill——自然语言查询，配合渐进式披露；
6. Chroma 向量数据库——混合的语义 + 关键词搜索，用于智能上下文召回。

Hook 定义源码解析

仓库 plugin/hooks/hooks.json 是 Hook 的权威定义。从源码结构看，当前版本实际注册了6 个 Hook 事件：Setup、SessionStart、UserPromptSubmit、PostToolUse、PreToolUse（matcher 为Read）、Stop。每个事件都通过node <插件目录>/scripts/bun-runner.js <插件目录>/scripts/worker-service.cjs hook claude-code <子命令>的形式，把控制权交给 Worker 服务的不同子命令。各事件与职责对应关系如下：

几点源码细节值得注意：

• 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 Runner（plugin/scripts/bun-runner.js）拉起。从 src/shared/SettingsDefaultsManager.ts 可确认其关键默认值：

• 监听127.0.0.1，端口默认为37700 + (uid % 100)——按用户 UID 派生端口，用于多账户隔离；
• 数据目录默认~/.claude-mem（CLAUDE_MEM_DATA_DIR）；
• 观察生成默认模型为claude-haiku-4-5-20251001（CLAUDE_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 层工作流：

1. search——取回紧凑索引（含 ID），约 50–100 Token/条；
2. timeline——取回有趣结果前后的时间线上下文；
3. get_observations——仅对筛选后的 ID 取完整详情，约 500–1000 Token/条。

工作方式：Claude 用 MCP 工具检索记忆；先用search拿索引，再用timeline看某条观察前后发生了什么，最后用get_observations批量取详情——先过滤后取详情，带来约 10 倍 Token 节省。

原文档示例用法（原样保留，注意批量取详情）：

// 步骤 1: 搜索索引 search(query="authentication bug", type="bugfix", limit=10) // 步骤 2: 检查索引，识别相关 ID（例如 #123、#456） // 步骤 3: 获取完整详情 get_observations(ids=[123, 456])

源码验证：工具如何落到 Worker API

MCP 服务器的完整实现在 src/servers/mcp-server.ts。三个核心工具的 schema 与路由均能从源码确认：

• search（src/servers/mcp-server.ts#L474-L523）：参数query, limit, project, platformSource, type, obs_type, dateStart, dateEnd, offset, orderBy。默认 Worker 模式下转发到本地/api/search；当运行时切换为 server 模式（CLAUDE_MEM_RUNTIME=server）且请求可被/v1/search忠实服务（纯观察文本查询、无额外过滤）时，改走服务端 GIN tsvector 全文索引——这段路由逻辑（resolveServerToolContext()）在每次调用时重新解析，因此切换运行时无需重启 MCP 服务器。
• timeline（src/servers/mcp-server.ts#L525-L541）：参数anchor（观察 ID）或query（自动定位锚点）、depth_before/depth_after（默认各 3）、project，转发到/api/timeline。
• get_observations（src/servers/mcp-server.ts#L543-L560）：ids为必填数组，转发到/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.log（src/servers/mcp-server.ts#L7-L9），防止任何杂散输出污染 stdio MCP 协议。

配置：settings.json 与源码级默认值

原文档指出：配置位于~/.claude-mem/settings.json（首次启动时自动用默认值创建），可配置 AI 模型、Worker 端口、数据目录、日志级别和上下文注入行为。

仓库中默认值与加载逻辑集中在 src/shared/SettingsDefaultsManager.ts。从源码看有三条重要的加载规则：

1. 缺省即落盘：若settings.json不存在，loadFromFile()会把全部默认值原子写入该文件（src/shared/SettingsDefaultsManager.ts#L264-L278）；
2. 持久值优先于内置默认：磁盘值覆盖DEFAULTS，再叠加环境变量覆盖（applyEnvOverrides），即优先级为环境变量 > settings.json > 内置默认；
3. 自动迁移：旧版{ env: {...} }嵌套结构会被自动展平为扁平 schema；某个遗留 Telegram 触发器默认值也会被一次性重写为当前默认。

关键配置项（节选自源码默认值表，可完整继承原文档“模型 / 端口 / 数据目录 / 日志 / 上下文注入”的配置面并进一步展开）：

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--[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.0）：

• Node.js：≥ 20.0.0；
• Claude Code：支持插件的最新版本；
• Bun：JS 运行时与进程管理器，缺失时自动安装；
• 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分支构建并发布到 npm；core-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.0（LICENSE）。原文档解释了选型理由：持久化 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 Worker（HTTP API + Web 查看器）→ PostToolUse/Stop Hook 异步触发观察生成（模式文件决定类型体系与语言）→ 观察写入 SQLite（FTS5）并同步 Chroma 向量库 → SessionStart 注入分层上下文（CLAUDE_MEM_CONTEXT_控制成本与内容）→ mem-search Skill 与 search/timeline/get_observations 三个 MCP 工具按 3 层工作流回查记忆*。每个环节都能在仓库中找到对应实现：Hook 契约在 plugin/hooks/hooks.json，默认值与配置加载在 src/shared/SettingsDefaultsManager.ts，MCP 工具在 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