W
AI-Wiki
SOURCE

thedotmack claude-mem README 摘要

文档概览

  • README 将该项目描述为：跨会话保留上下文的系统，会自动捕获工具使用 observations，生成语义摘要，并在未来会话中提供给 Claude。
  • 其目标效果是：即使会话结束或重新连接，Claude 仍能保持对项目知识的连续性。
  • 文档导航覆盖 Quick Start、How It Works、MCP Search Tools、Documentation、Configuration、Troubleshooting、License 等部分。
  • 该 README 还提供大量多语言文档入口，说明项目本身在文档层面支持广泛语言覆盖；而在配置层面，又单独提供了 CLAUDE_MEM_MODE 来控制工作流模式和 observations 输出语言。

关键事实

CLAUDE_MEM_MODE 的作用

  • README 明确写到：CLAUDE_MEM_MODE 用于支持多种 workflow modes 和 languages。
  • 该选项不是只控制界面文案，也不是只控制搜索行为；README 明确说明它同时控制两件事：
  • 一是 workflow behavior。
  • 二是 generated observations 所使用的语言。
  • README 给出的原始表述是：This option controls both: The workflow behavior ... and The language used in generated observations。
  • 因此，CLAUDE_MEM_MODE 是一个“行为 + 语言”双重开关，而不是单纯语言切换项。

workflow behavior 的示例

  • 用户给定的必覆盖事实中指出，该配置涉及的 workflow behavior 示例包括 code、chill、investigation。
  • README 在模式说明中至少明确举出 code 作为模式名，并给出 code--zh、code--ja 等语言化模式示例。
  • 结合该来源整理要求，可以确认：项目的模式体系是围绕不同 workflow modes 展开的，示例行为包括 code、chill、investigation；而语言变体会附着在模式名之上。

generated observations 的语言也受此控制

  • README 不是只说“Claude 的回答语言”会变化，而是具体写到：生成出来的 observations 所使用的语言，也由 CLAUDE_MEM_MODE 决定。
  • 这意味着该配置会直接影响持久化记忆内容本身的语言形态。
  • 对依赖 search、get_observations 等能力回看历史记录的使用者来说，这一点很关键，因为后续检索到的记忆文本语言，和当前 mode 配置具有直接关系。

配置位置与生效条件

  • README 明确写出设置文件位置为 ~/.claude-mem/settings.json。
  • 该文件会在首次运行时自动创建默认值。
  • README 给出的示例配置为：
{
  "CLAUDE_MEM_MODE": "code--zh"
}
  • 修改模式后，不是热更新立即生效。README 明确要求：修改后需要重启 Claude Code，新 mode 配置才会应用。

重要细节

可用模式与命名规则

  • README 在 Mode & Language Configuration 中说明，模式定义位于插件目录下的 plugin/modes/。
  • 如果要在本地查看所有可用模式，README 给出命令：ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/。
  • README 表格中明确列出的模式示例有：
  • code：默认英文模式。
  • code--zh：简体中文模式。
  • code--ja：日文模式。
  • README 进一步说明，语言化模式遵循 code--[lang] 命名规则，其中 [lang] 是 ISO 639-1 语言代码。
  • 文中给出的例子包括：zh 表示中文，ja 表示日语，es 表示西班牙语。
  • README 还特别注明：code--zh 已内建，不需要额外安装，也不需要更新插件。

配置项的边界

  • 从 README 的措辞看，CLAUDE_MEM_MODE 是“模式和语言”的统一入口，不需要分别设置一个 workflow 行为开关和一个 observations 语言开关。
  • 这意味着当使用 code--zh 这类值时，行为模式与输出语言是捆绑确定的。
  • README 没有在该段落中展开 chill、investigation 的完整配置示例，但该来源整理要求已点明它们属于 workflow behavior 的示例集合。
  • README 也没有说修改后 worker 会自动热重载；明确要求的是重启 Claude Code。因此如果改完 settings.json 后效果未变化，首先应检查是否已经重启。

与搜索链路的关系

  • README 的 MCP Search Tools 部分说明，项目提供 4 个 MCP 工具，并采用 token-efficient 的 3-layer workflow pattern。
  • README 实际列出的三层流程是：
  • 第 1 层 search：先获取紧凑索引，单条结果约 50-100 tokens。
  • 第 2 层 timeline：查看某条 observation 周围的时间序上下文。
  • 第 3 层 get_observations：仅为筛选后的 ID 拉取完整细节，单条约 500-1,000 tokens。
  • README 说明，这种先过滤、后拉详情的方式大约可节省 ~10x token。
  • 因为 CLAUDE_MEM_MODE 还控制 generated observations 的语言，所以它会间接影响后续 search、timeline、get_observations 看到的记忆文本内容和语言形态。

安装与常见误区

  • Quick Start 中的标准安装命令是：npx claude-mem install。
  • 面向 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
  • 安装完成后 README 明确要求重启 Claude Code，此前会话的上下文会自动出现在新会话中。
  • README 特别提醒：虽然项目发布到了 npm，但 npm install -g claude-mem 只会安装 SDK/library，不会注册 plugin hooks，也不会设置 worker service。
  • 因此 README 要求应始终通过 npx claude-mem install 或 /plugin 命令完成安装。

系统要求与环境约束

  • Node.js：20.0.0 或更高。
  • Claude Code：需要支持插件的最新版本。
  • Bun：作为 JavaScript runtime 和进程管理器，若缺失会自动安装。
  • uv：作为向量搜索所需的 Python 包管理器，若缺失会自动安装。
  • SQLite 3：用于持久化存储，README 标注为 bundled。
  • Windows 环境下，如果出现 npm : The term 'npm' is not recognized as the name of a cmdlet，README 要求确认 Node.js 和 npm 已安装并加入 PATH，且安装后重启终端。

架构与组件事实

  • README 的 How It Works 段落列出核心组件：
  • 5 Lifecycle Hooks：SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd。
  • 同段又注明共有 6 hook scripts。
  • Smart Install：缓存依赖检查器，属于 pre-hook script，不是 lifecycle hook。
  • Worker Service：本地 HTTP API，附带 web viewer UI 和 search endpoints，由 Bun 管理。
  • SQLite Database：存储 sessions、observations、summaries。
  • mem-search Skill：用自然语言查询项目历史，采用 progressive disclosure。
  • Chroma Vector Database：用于混合语义 + 关键词搜索，支持更智能的上下文检索。

功能特性

  • Persistent Memory：上下文跨会话保留。
  • Progressive Disclosure：分层检索记忆，并显示 token 成本可见性。
  • Skill-Based Search：通过 mem-search skill 查询项目历史。
  • Web Viewer UI：worker 启动时打印 URL，可查看实时 memory stream。
  • Claude Desktop Skill：可从 Claude Desktop 对话中搜索记忆。
  • Privacy Control：用 <private> 标签把敏感内容排除出存储。
  • Context Configuration：细粒度控制注入哪些上下文。
  • Automatic Operation：不要求人工手动干预。
  • Citations：可通过 worker API 或 web viewer 使用 ID 引用过去 observations。

发布分支与许可

  • 稳定发布来自 main，并发布到 npm。
  • core-dev 与 community-edge 是 source-run 分支，用于更早的可靠性修复和社区集成。
  • 许可协议为 Apache License 2.0。
  • README 解释选择 Apache-2.0 的原因是：让持久代理记忆更容易嵌入开发工具、本地代理、MCP servers、企业系统、机器人技术栈和生产级 agent harness。
  • 另外，ragtime/ 目录也使用 Apache License 2.0，并单独给出许可文件。

关于 CMEM

  • README 最后专门有 “What About CMEM?” 小节。
  • 文中说明：CMEM 是第三方创建的 token，但已被 Claude-Mem 的创建者官方接纳。
  • README 将其描述为社区增长催化剂，以及把 CMEM 带给开发者和知识工作者的载体。
  • 文中还给出官方 BASE CA：0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3。

相关条目