claude-mem：把 Claude Code 会话记忆持久化并自动注入
给 Claude Code 用户保存会话经验的记忆插件，靠 SQLite、Chroma 和生命周期钩子在新会话自动召回。
GitHub thedotmack/claude-mem 更新 2026-09-04 分支 main 星标 92.9K 分叉 8.2K
TypeScript AI Agent 记忆 SQLite Chroma Claude Code Bun

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你在 Claude Code 中频繁开启新会话，需要自动带回旧会话上下文
    README 的 Quick Start：重启 Claude Code 后，previous sessions 的 context 会自动出现在 new sessions
  • 你的 Agent 环境是 OpenCode、Grok Bot 或 Antigravity CLI
    README 的 Quick Start 提供 npx claude-mem install --ide opencode、--ide grok-bot 和 --ide antigravity
  • 你需要对项目历史做自然语言检索，而不是只保存原始日志
    README 的 Search Tools 与 How It Works：mem-search Skill 支持 natural language queries，Chroma 提供 hybrid semantic + keyword search
  • 你接受 CMEM Pro 托管记忆，或愿意使用 OpenRouter、Gemini 或 Anthropic plan
    README 的 Quick Start：登录后可选择 claude-mem observer、自己的 OpenRouter 或 Gemini key，或 Anthropic plan

不适合，如果你

  • 你只能接受完全不登录的默认安装流程
    README 的 Quick Start：默认安装会要求浏览器登录；虽然可用 --provider 或 CLAUDE_MEM_ONLINE_OPTIN=false 跳过
  • 你准备通过 npm install -g claude-mem 来完成 Claude Code 插件安装
    README 的 Note：全局 npm 安装只提供 SDK/library，不注册 plugin hooks，也不设置 worker service
  • 你的环境无法提供 Node.js 20.0.0、Bun 或 uv
    README 的 System Requirements 明确要求 Node.js 20.0.0+，并要求 Bun 与 uv；缺失时会自动安装
  • 你的 Grok Bot 聊天记录不适合被插件监视
    README 的 Quick Start：Grok Bot 没有 host hooks，因此插件会 watch chat log files

前置条件

  • Node.js 20.0.0 or higher
  • Claude Code: Latest version with plugin support
  • Bun: JavaScript runtime and process manager
  • uv: Python package manager for vector search
  • SQLite 3: For persistent storage (bundled)

第一步命令（README 原文）

npx claude-mem install

要注意

  • 不要用 npm install -g claude-mem 代替安装器，否则不会注册 plugin hooks 或 worker service
    README 的 Quick Start Note
  • Grok Mem 的包名仍是 claude-mem，产品名称与 npm 包名称不一致
    README 开头：Claude-Mem is now Grok Mem. The package is still claude-mem
  • 安装后默认是 CMEM Pro hosted memory；本地 observer 需要显式使用 --provider host
    README 的 Quick Start：Default is CMEM Pro，Local observer is opt-in: --provider host
  • 设置保存在 ~/.claude-mem/settings.json，可配置 AI model、worker port 和 data directory
    README 的 Configuration 章节
  • Windows 出现 npm not recognized 时，需要把 Node.js 和 npm 加入 PATH
    README 的 Windows Setup Notes

材料未说明

  • README 未提供 CMEM Pro 试用结束后的具体订阅价格或配额细节。
  • README 未说明 SQLite、Chroma 和聊天日志中的数据如何加密或隔离。
  • README 未提供不同 AI model、worker port 或项目规模下的性能数字。
  • README 的项目元数据显示贡献者 0 人、版本 0 个、最近提交 0 个，无法据此确认实际维护活跃度。
  • README 未给出 Claude Code、OpenCode、Grok Bot 与 Antigravity CLI 的完整版本兼容矩阵。
  • README 未提供从 claude-mem v3 到 v5 的具体迁移步骤，只有 Architecture Evolution 章节链接。

💡 深度解析

6
不适合 我想让多人围绕同一代码库共享 claude-mem 的项目记忆，同时要求权限隔离、并发写入和团队级治理；这个项目是否适合直接作为共享知识库？
适合读者： 两名以上成员需要共享同一项目记忆、同时关心权限隔离和并发写入的技术负责人

不适合直接作为团队共享知识库：README 展示的是本地 Worker、SQLite 和个人 Agent 插件工作流，并未提供团队权限与并发治理能力。

  • Worker 是本地 HTTP API，并由 Bun 管理；SQLite 负责保存 sessions、observations 和 summaries，整体形态更接近单机工作区。
  • 配置文件位于 ~/.claude-mem/settings.json，数据目录和 Worker 端口可配置，但这不等于提供用户、项目或角色级访问控制。
  • README 提供 Cloud Sync，可把 memories 备份到 cmem.ai；但备份机制并不自动解决多人实时协作、权限隔离、冲突处理或审计要求。
  • 项目洞察明确指出 SQLite 和本地 Worker 更适合个人或单机工作流，不天然解决多人并发写入、权限隔离、组织级知识治理和高可用部署。

因此可把它作为每位成员的工作记忆，或另行验证托管服务；不应仅凭 README 把本地存储当成团队知识库后端。

  • How It Works: “Worker Service - Local HTTP API with web viewer UI and search endpoints, managed by Bun”
  • How It Works: “SQLite Database - Stores sessions, observations, summaries”
  • Configuration: “Settings are managed in `~/.claude-mem/settings.json`”
  • 项目洞察 solution_analysis.usage_limitations：SQLite 和本地 Worker 更适合个人或单机工作流
材料未说明：README 未说明 CMEM hosted memory 是否提供组织、项目、角色权限、并发控制和审计日志。；README 未说明 Cloud Sync 的冲突解决、删除传播、数据驻留和恢复机制。
适合 我同时使用 Claude Code、OpenCode 和 Codex，项目历史已经无法完整塞进一次会话；claude-mem 能否让我按需找回旧决策，而不是每次复制整段记录？
适合读者： 在长期项目中使用 Claude Code、OpenCode 和 Codex，历史信息已超出单次上下文窗口的高级 Agent 用户

适合：它的存储、压缩、混合检索和渐进式披露正好针对跨会话历史过长的问题。

  • Worker 会把工作过程转为 observations、summaries、decisions 和后续任务，而不是只保存原始聊天文本。
  • SQLite FTS5 支持关键词检索，Chroma Vector Database 提供语义搜索；文件名、错误信息等精确内容和相似历史决策可以走不同检索路径。
  • mem-search Skill 通过自然语言查询并采用 progressive disclosure，先取相关摘要或观察，再按需展开，避免一次性注入全部历史。
  • README 明确列出 Claude Code、OpenCode 等接入，并在项目描述中列出 Codex；但不同宿主的接入深度并不保证一致。

它适合作为项目工作记忆层，但不应替代代码仓库、测试或正式设计文档，因为 AI 压缩可能遗漏细节。

  • How It Works: “mem-search Skill - Natural language queries with progressive disclosure”
  • How It Works: “Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval”
  • How It Works: “SQLite Database - Stores sessions, observations, summaries”
  • 项目描述： “Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More”
npx claude-mem install
材料未说明：README 未提供 Claude Code、OpenCode 和 Codex 三者在事件采集、MCP/Skill 和自动注入方面的逐项能力矩阵。；README 未量化压缩后的令牌节省、检索延迟或大规模历史下的数据库容量上限。
视情况 我把 Grok Bot 用于连续调试，但 Grok Bot 没有 host hooks；我能否依靠 claude-mem 完整记录工具操作和后续决策？
适合读者： 每天使用 Grok Bot 进行代码调试、但宿主不提供插件级 hooks 的个人开发者

视情况：Grok Bot 有专用安装路径，但采集依赖聊天日志文件监视，完整性不等同于原生生命周期钩子。

  • README 明确写着“Grok Bot has no host hooks, so we watch the chat log files”，因此它不是通过 SessionStart 或 PostToolUse 等宿主事件直接采集。
  • 安装命令会针对 grok-bot 配置插件，默认 provider 是 CMEM Pro hosted memory；本地 observer 需要显式使用 --provider host。
  • 日志格式、文件权限、日志路径变化或 Grok 平台更新，都可能让采集缺失；项目洞察也指出这类替代方案的及时性和覆盖范围较弱。
  • README 没有承诺日志监视能够捕获每一次工具调用，也没有给出丢失事件的恢复机制。

所以它适合把 Grok Bot 的工作沉淀为辅助记忆，不适合把结果当成完整审计记录或唯一事实来源。

  • Quick Start: “Grok Bot has no host hooks, so we watch the chat log files.”
  • Quick Start: “Default is CMEM Pro, the hosted memory. Local observer is opt-in: `--provider host`.”
  • 项目洞察 user_experience.common_pitfalls：Grok Bot 依赖聊天日志文件，日志格式、权限、路径变化可能导致采集不完整
npx claude-mem install --ide grok-bot
材料未说明：README 未说明 Grok Bot 聊天日志的具体路径、格式、轮询延迟和日志轮转处理方式。；README 未说明工具调用是否都会出现在可监视的聊天日志中。
视情况 我使用 Claude Code，已经有自己的 OpenRouter 和 Gemini key，不想默认订阅托管服务；我能否在 claude-mem 中切换 provider，并明确知道费用边界？
适合读者： 希望使用自己的 OpenRouter 或 Gemini key、同时比较 Anthropic plan 与托管 observer 成本的 Claude Code 用户

视情况：provider 选择是可配置的，但 README 只说明了入口和试用逻辑，没有给出各路径的完整计费、模型调用量或性能差异。

  • 安装登录后可选择 claude-mem observer、自己的 OpenRouter 或 Gemini key，或 Anthropic plan，说明不必锁定单一供应商。
  • claude-mem observer off-plan 运行，前 30 天免费；试用结束后会自动回退到 Anthropic plan，除非订阅，这会影响费用归属判断。
  • 也可以传入显式 --provider、设置 CLAUDE_MEM_ONLINE_OPTIN=false 或在 CI 中跳过账户交互，适合不想登录托管服务的安装流程。
  • README 没有列出支持的具体模型、每次观察/摘要/向量检索的调用次数，也没有说明 OpenRouter 与 Gemini key 的费用如何分别计算。

因此可以切换 provider，但不能仅凭 README 完成预算核算；需要再查配置和服务商计费文档。

  • Quick Start: “you pick your memory provider — the claude-mem observer, your own OpenRouter or Gemini key, or your Anthropic plan”
  • Quick Start: “memory that runs off-plan, free for your first 30 days”
  • Quick Start: “After the free trial ends, memory automatically falls back to your Anthropic plan unless you subscribe.”
  • Quick Start: “Pass an explicit `--provider` flag, set `CLAUDE_MEM_ONLINE_OPTIN=false`”
npx claude-mem install
材料未说明：README 未说明 provider 切换是否会影响已有 SQLite/Chroma 记忆，或是否需要重新索引。；README 未说明各 provider 支持的具体模型、调用频率、价格和失败回退规则。
视情况 我使用支持插件的最新 Claude Code，代码包含商业机密，而且希望跨会话恢复上下文但不把会话内容发送到外部服务；claude-mem 是否适合？
适合读者： 使用 Claude Code 最新插件版、处理商业代码并要求记忆留在本机的个人开发者

视情况：它适合本地持久化和跨会话恢复，但前提是你明确选择本地 provider 并接受本地运行时依赖。

  • README 说明系统通过 SQLite 保存 sessions、observations 和 summaries，并可用配置文件设置 data directory。
  • 生命周期钩子包含 SessionStart、UserPromptSubmit、PostToolUse、Stop、SessionEnd，Claude Code 重启后会自动显示之前会话的上下文。
  • 默认安装流程会引导登录并选择 claude-mem observer、OpenRouter、Gemini 或 Anthropic plan；在线 provider 可能处理会话内容，因此不能默认视为离线。
  • 本地路径仍需要 Node.js 20+、Bun、uv 和 SQLite；AI 观察与摘要是否完全由本地模型完成，README 摘要没有明确说明。

因此，隐私边界可控时可以采用；若组织要求绝不发送任何代码片段，应先确认 provider 的实际网络行为。

  • How It Works: “SQLite Database - Stores sessions, observations, summaries”
  • How It Works: “5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd”
  • Quick Start: “After sign-in you pick your memory provider”
  • System Requirements: “Node.js: 20.0.0 or higher”, “Bun”, “uv”, “SQLite 3”
npx claude-mem install
材料未说明：README 未明确说明本地 provider 使用的具体 AI 模型及其是否完全离线。；README 未给出在线 provider 会发送哪些字段、保留多久以及是否支持企业级数据隔离。
视情况 我需要给 OpenCode 和 Antigravity CLI 配置 claude-mem，并且安装过程会运行在 CI/non-interactive shell；README 提供的路径是否足够？
适合读者： 需要同时维护 OpenCode 和 Antigravity CLI 接入、并在无交互 CI shell 中安装的自动化开发者

视情况：README 提供了两个宿主的安装命令，也明确支持非交互安装，但 CI 是否能稳定运行还取决于运行时和认证策略。

  • OpenCode 与 Antigravity CLI 都有独立的 npx claude-mem install --ide ... 命令，说明项目提供了明确接入入口。
  • README 写明在 CI/non-interactive shells 中安装器无需账户交互即可完成，也可通过 --provider 或 CLAUDE_MEM_ONLINE_OPTIN=false 跳过登录。
  • 系统仍要求 Node.js 20+；Bun 和 uv 缺失时会自动安装，但 CI 的 PATH、网络权限和写入权限可能影响这一过程。
  • 安装器配置的是插件与 Worker；README 没有说明 CI 中是否需要持续运行后台 Worker，也没有描述 OpenCode 与 Antigravity CLI 的 hooks 覆盖差异。

因此，非交互安装路径是可行的；若 CI 只执行安装后立即退出，记忆采集和检索是否可用仍需确认。

  • Quick Start: `npx claude-mem install --ide opencode`
  • Quick Start: `npx claude-mem install --ide antigravity`
  • Quick Start: “run in CI/non-interactive shells — the installer completes without any account interaction”
  • System Requirements: “Node.js: 20.0.0 or higher”; “Bun” and “uv”
npx claude-mem install --ide opencode
材料未说明：README 未说明 CI 中 Worker 的生命周期、持久化目录挂载和跨 job 数据保留方式。；README 未说明 OpenCode 与 Antigravity CLI 的具体 hook 覆盖范围。

✨ 核心亮点

  • SQLite 保存会话，Chroma 提供混合语义搜索
  • 5 个生命周期钩子自动捕获并注入上下文
  • 支持 Claude Code、OpenCode 与 Grok Bot
  • 93,134 颗星，提供自然语言历史查询

🔧 工程化

  • 用 SQLite 保存 sessions、observations 和 summaries
  • 通过 mem-search Skill 用自然语言查询项目历史
  • Worker Service 提供 HTTP API、Web 查看器和搜索端点
  • 5 个生命周期钩子在新会话自动恢复历史上下文

⚠️ 风险

  • 默认使用 CMEM Pro 托管记忆，安装会引导浏览器登录
  • Grok Bot 没有 host hooks，改为监视聊天日志文件
  • npm install -g claude-mem 只安装 SDK，不注册插件钩子
  • 依赖 Node.js 20、Bun、uv、SQLite 3 四项运行环境
  • README 已改称 Grok Mem，但 npm 包仍名为 claude-mem

👥 适合谁？

  • 使用 Claude Code plugin 的开发者，需要跨会话保留工作上下文
  • 使用 OpenCode、Grok Bot 或 Antigravity CLI 的 Agent 团队
  • 已有 Node.js 20、Bun 和 uv 环境的 TypeScript 项目