claude-mem 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

claude-mem 是一个用 JavaScript 发布的持久化上下文与记忆压缩系统，目标是把智能代理在会话中的工具使用记录保存下来，经人工智能压缩后，在后续会话中检索并注入相关上下文。仓库 README 将其描述为面向 Claude Code 的“Persistent memory compression system”，项目说明同时列出 Claude Code、OpenClaw、Codex、Gemini、Hermes、Copilot、OpenCode 等使用场景。

仓库默认分支为 main，许可证为 Apache-2.0。GitHub 元信息显示 Star 数为 90888、Fork 数为 7938，仓库主语言标注为 JavaScript；这些数据属于所给仓库资料中的快照，不代表实时统计。

“Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions.”
来源：README

定位与目标用户

本项目解决的是代理会话之间的上下文断裂问题。它不是单纯的聊天记录查看器，而是通过观察记录、语义摘要、持久化存储和后续检索，将过去会话中的项目知识重新提供给代理。

根据仓库描述，目标使用者包括使用 Claude Code 的个人开发者、需要让代理跨会话保持项目状态的工程团队，以及部署 OpenClaw Gateway 并需要持久记忆插件的使用者。对于采用其他代理客户端的用户，是否能够完整使用某一集成方式，应以对应官方文档为准；资料没有给出各客户端的功能差异矩阵。

它处理的上下文问题

单次会话结束后，代理通常无法直接访问前一会话中的全部决策、命令输出和工具调用过程。claude-mem 的工作重点是把这些过程转化为可保存、可查询、可引用的记忆对象，并在新会话建立时提供相关内容。

这个设计适合具有连续任务特征的项目，例如多次修改同一个代码库、持续追踪某项排障工作，或者需要让不同会话共享已经确认的项目事实。它不会自动替代代码仓库、工单系统或正式文档，关键结论仍应写入可审查的项目资料。

核心功能

核心能力可以归纳为“捕获、压缩、检索、注入”四个环节。每个环节都有明确的输入和输出，且完整运行依赖代理插件、工作进程、持久化存储以及配置的人工智能提供方。

会话观察捕获

项目通过插件钩子捕获代理会话中的工具使用观察结果。输入是代理执行过程中产生的工具调用及相关观察内容，输出是交给后续处理流程的观察记录；README 将这一过程概括为“automatically capturing tool usage observations”。

触发条件由插件与钩子机制决定，而不是由用户手动复制聊天记录。资料明确说明，直接执行 npm install -g claude-mem 只会安装 SDK 或库，不会注册插件钩子，也不会设置工作进程，因此完整功能必须通过 npx claude-mem install 或 Claude Code 插件市场命令完成安装。

人工智能压缩与语义摘要

捕获的观察结果会进入压缩流程，由人工智能生成语义摘要。输入是原始观察记录，输出是便于后续检索的压缩内容；README 使用“generating semantic summaries”描述该阶段。

Docker 部署资料表明，生成工作由独立的 claude-mem-worker 服务承担，服务端通过 BullMQ 队列与 Valkey 连接。工作进程需要配置人工智能提供方凭据；Docker Compose 注释明确指出，没有相应提供方密钥时，worker 会保持运行，但不会生成观察结果。

渐进式披露与记忆检索

README 将“Progressive Disclosure”列为关键功能，并说明它提供分层记忆检索和令牌成本可见性。实际使用时，检索不要求把全部历史内容一次性放入新会话，而是按查询结果逐层获取相关信息。

仓库同时列出基于技能的搜索方式，使用 mem-search skill 查询项目历史。该机制的输入是搜索请求或当前任务上下文，输出是相关历史观察与摘要；具体搜索参数、返回字段和排序规则没有在所给资料中完整提供，使用时应以官方文档为准。

跨会话上下文注入

当新会话启动或需要历史信息时，系统会把检索到的相关记忆提供给代理，使其能够延续项目背景。README 表述为“making them available to future sessions”，并说明重启 Claude Code 后，前一会话的上下文会自动出现在新会话中。

注入内容受上下文配置控制。README 将“Context Configuration”列为能力之一，表示使用者可以对注入内容进行细粒度控制；但所给摘录没有列出全部配置键及其取值，不能据此推导具体配置文件格式。

隐私标记与引用

项目支持使用 <private> 标签排除敏感内容，使这些内容不被保存。该能力只描述了存储排除边界，不能被理解为对已经发送给人工智能提供方、终端日志或操作系统缓存的全面清除保证。

README 还列出 Citations 能力，允许通过工作进程 API 使用观察记录 ID 进行引用，并在 Web Viewer 中查看全部内容。资料没有提供该 API 的完整接口签名，因此文章不构造未经资料支持的请求示例。

系统架构与关键模块

从仓库 README、package.json 和 Docker Compose 可以确认，项目同时包含本地插件运行形态和服务端部署形态。两者都围绕观察记录与记忆检索展开，但服务拆分、队列和数据库要求不同。

本地插件与工作进程

本地安装通过命令行工具注册插件相关文件和钩子。package.json 将命令行入口声明为 ./dist/npx-cli/index.js，并导出 claude-mem 命令；仓库发布文件包括 plugin/hooks、plugin/skills、plugin/ui 和若干插件清单。

工作进程负责处理观察与生成任务。仓库脚本包含 worker:start、worker:stop、worker:restart、worker:status、worker:logs 和 worker:tail，这些脚本使用 Bun 调用 plugin/scripts/worker-service.cjs。

服务端部署形态

Docker Compose 定义了四类服务：Postgres 17、Valkey 8、claude-mem-server 和 claude-mem-worker。其中 server 提供 HTTP 服务，worker 消费 BullMQ 队列并执行生成任务，Postgres 保存规范数据，Valkey 承担队列运行所需的服务。

Compose 注释明确规定，服务端模式不会启动旧的 worker-service.cjs 运行时；server 使用 server-beta-service.cjs --daemon，worker 使用同一服务的 worker start 子命令。HTTP 服务和生成工作分离后，提供 HTTP 响应的服务不会直接执行提供方调用。

构建与依赖组织

package.json 的依赖说明指出，发布产物中保留的运行时依赖包括 better-auth 与 @better-auth/api-key；Express、BullMQ、Ioredis、React、React DOM、Postgres 客户端、模型上下文协议（Model Context Protocol，MCP）SDK 等依赖会被构建工具内联到 worker、server 或 npx bundle，或者由插件自身的依赖清单提供。

这意味着源码开发环境的依赖集合与消费者安装包实际下载的依赖集合并不完全相同。构建流程包含同步插件清单、构建钩子和生成插件锁文件等步骤，源码贡献者应以仓库脚本为准，不应仅凭最终运行时依赖判断完整开发环境。

依赖与运行环境

运行环境的最低版本信息以两个文件为准，且存在版本表述差异：README 徽章写作 Node.js 20.0.0 及以上，package.json 的 engines 字段写作 Node.js 20.12.0 及以上，并声明 Bun 1.0.0 及以上。部署或开发时，建议按更严格的 package.json 约束准备 Node.js。

• 主要语言：GitHub 元信息标注为 JavaScript；项目包关键词和源码脚本同时出现 TypeScript。
• 模块类型：package.json 设置 "type": "module"。
• Node.js：package.json 声明 >=20.12.0。
• Bun：package.json 声明 >=1.0.0。
• 容器数据库：Compose 使用 postgres:17-alpine。
• 容器队列：Compose 使用 valkey/valkey:8-alpine。
• 人工智能提供方：Compose 注释和环境变量列出 Claude、Gemini、OpenRouter 配置路径。

README 的版本徽章为 13.4.0，而 package.json 当前资料中的版本字段为 13.15.2。两者来源不同，本文不将其合并为单一版本结论；安装前应以实际发布包和最新仓库内容为准。

快速开始

本地使用的最小闭环是安装插件、重启代理客户端、确认新会话能够看到历史上下文。README 明确推荐使用 npx 安装器，而不是把全局 npm 安装命令当作完整插件安装方式。

安装 Claude Code 集成

npx claude-mem install

该命令来自 README。安装完成后，按 README 要求重启 Claude Code，使插件钩子和工作进程配置生效；仓库资料没有提供一个可在所有本地环境通用的固定工作进程端口。

通过插件市场安装

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

这两行命令应在 Claude Code 的插件命令环境中执行，而不是在普通 shell 中执行。重启 Claude Code 后，新会话会自动获得过去会话的上下文，具体展示位置以客户端和当前插件版本为准。

OpenCode 安装方式

npx claude-mem install --ide opencode

该用法是 README 明确列出的安装路径。它只说明 OpenCode 的安装入口，资料没有提供 OpenCode 端的完整验证步骤。

本地容器验证示例

若需要验证服务端 Compose 形态，必须先准备本地测试用的数据库凭据，并提供生成所需的人工智能提供方密钥。下面的命令只针对本机部署，不能把默认配置直接暴露到公网。

export POSTGRES_USER=claude_mem_local
export POSTGRES_PASSWORD=<本地测试数据库密码>
export POSTGRES_DB=claude_mem
export ANTHROPIC_API_KEY=<你的-API-KEY>
export CLAUDE_MEM_RUNTIME=server-beta
export CLAUDE_MEM_QUEUE_ENGINE=bullmq
export CLAUDE_MEM_AUTH_MODE=api-key

docker compose up -d
curl -fsS http://127.0.0.1:37877/healthz

端口 37877、健康检查路径 /healthz、数据库和队列服务均来自 docker-compose.yml。占位符只表示本地环境中的实际凭据，不应提交到版本库；若不配置提供方密钥，Compose 注释说明 worker 不会产生观察结果。

配置说明

配置应区分本地插件模式和 Docker 服务端模式。下表只列出资料中真实出现的字段；“默认值”严格按 Compose 或 package.json 可确认的内容填写，未在资料中给出的值不作推断。

认证与提供方凭据

Compose 使用 api-key 认证模式，并要求请求携带由 server api-key create 创建的 bearer key。生成阶段则需要配置提供方凭据，Compose 列出 ANTHROPIC_API_KEY、CLAUDE_MEM_ANTHROPIC_API_KEY、GEMINI_API_KEY 和 OPENROUTER_API_KEY。

这些密钥属于敏感参数，本文示例中的 <你的-API-KEY> 需要由使用者在本地安全注入。资料还提到 subscription 认证路径，但没有给出完整配置样例；实际使用应以服务端文档为准。

进阶用法

进阶使用的重点是把记忆检索嵌入已有工作流，而不是手工维护一份不断增长的提示词。README 已提供技能搜索、桌面客户端技能、Web Viewer、上下文配置和引用能力的方向。

OpenClaw Gateway 集成

README 提供了 OpenClaw Gateway 的安装脚本，并说明安装器会处理依赖、插件设置、人工智能提供方配置和工作进程启动。该集成还可以选择把实时观察流发送到 Telegram、Discord、Slack 等目标，具体目标和设置步骤应阅读官方集成指南。

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

上述命令来自 README，适合在已获得目标 Gateway 管理权限的环境中执行。安装前应审查脚本内容、网络出口、凭据注入方式和数据保存位置；本文不建议在生产网关上未经审查地执行远程脚本。

Antigravity CLI 安装

npx claude-mem install --ide antigravity

README 将此命令与 Antigravity CLI 配置指南关联。资料没有提供其他 IDE 参数的完整清单，不能将仓库描述中的客户端名称直接当作所有客户端都支持同一种安装参数。

记忆搜索与逐层读取

对于需要追踪历史决策的任务，可以使用 mem-search skill 查询项目历史，再根据结果决定是否读取更细的观察内容。这样做的价值在于把检索范围限制在任务相关部分，同时保留 README 所说的令牌成本可见性。

在团队流程中，建议把重要的历史观察 ID 与提交、问题单或变更记录关联。项目支持通过工作进程 API 或 Web Viewer 引用观察记录，但完整 API 路径和鉴权请求格式在资料中缺失，不能在此虚构。

可观测性与运维

本项目提供了进程状态、日志、健康检查和 Web Viewer 等运维入口。运维重点是确认观察是否进入队列、worker 是否拥有提供方凭据、数据库和 Valkey 是否健康，以及 HTTP server 是否仍能响应。

本地 worker 管理

npm run worker:status
npm run worker:logs
npm run worker:tail
npm run worker:restart

这些脚本均在 package.json 中声明。日志路径模板为 ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log，其中 worker:logs 查看当天日志末尾内容，worker:tail 用于持续跟踪日志。

Docker 服务健康检查

Compose 为 Postgres、Valkey 和 server 声明了健康检查。server 的检查地址是 http://127.0.0.1:37877/healthz；worker 依赖数据库、Valkey 以及健康的 server 容器。

部署规模方面，Compose 注释明确给出可以使用 docker compose up -d --scale claude-mem-worker=N 扩展生成消费者。资料没有提供吞吐量、延迟、资源消耗或并发上限，因此不能据此制定容量承诺。

数据持久化

Compose 定义了 claude-mem-data、postgres-data 和 valkey-data 三个卷。Postgres 卷保存数据库数据，Valkey 开启 AOF 并设置 noeviction，应用数据卷用于保存 claude-mem 数据。

卷并不等同于备份。资料没有给出备份脚本、恢复演练流程、数据保留期限或跨地域复制方案，生产环境应由运维人员补充并验证这些制度。

安全与合规边界

claude-mem 会保存代理观察内容，并在生成阶段把数据交给配置的人工智能提供方处理，因此隐私、访问控制和数据驻留是部署前必须确认的边界。该项目不是安全测试或攻击工具，本文只讨论授权环境中的本地开发和受控部署。

• 使用 <private> 标签排除不应存储的敏感内容，但必须在数据进入观察流程前设计标记策略。
• 不要把 API 密钥、个人身份信息、生产凭据或未获授权的第三方数据写入可持久化观察。
• Docker Compose 明确拒绝在容器环境使用 local-dev 认证模式，示例使用 api-key。
• Compose 文件不能未经修改部署到公网可达环境；文件注释明确要求先配置数据库凭据和认证模式。
• server 与 worker 使用分离架构时，应分别限制网络暴露面，HTTP 端口不应直接暴露给不受信任网络。

安全边界还包括人工智能提供方的服务条款、数据处理协议、日志留存和跨境传输要求。仓库资料没有给出特定地区的合规认证、数据驻留承诺或审计报告，相关结论必须由部署组织自行核验。

许可证与商用条款

仓库许可证为 Apache License 2.0。该许可证授予使用、复制、准备衍生作品、公开展示、公开执行、再许可和分发等权利，具体条件和例外以仓库中的 LICENSE 文件为准。

Apache-2.0 允许在满足许可证条件的前提下用于商业场景。分发原始作品或衍生作品时，需要向接收者提供许可证、保留相应版权、专利、商标和归属声明；如果修改文件，还需要保留显著的修改说明。许可证不授予使用许可方商号、商标、服务标记或产品名称的权利。

仓库资料没有提供独立的商业支持协议、服务等级协议、托管服务条款或商标政策。涉及再分发、专利、商标和企业合规时，应以仓库 LICENSE 及相关正式文件为准。

局限性与已知限制

项目资料能够确认功能方向，但没有给出完整的性能基线、容量模型和 API 参考。使用者应把它视为需要验证的工程组件，而不是具备预设服务等级的托管产品。

• 摘要由人工智能生成，资料没有提供准确率、召回率或错误修正机制，因此关键事实需要人工复核。
• 持久化内容可能包含代理观察中的项目细节；使用隐私标签仍需要配合访问控制、日志策略和数据审查。
• 没有人工智能提供方密钥时，Docker worker 不会生成观察结果，进程存活不代表记忆处理链路正常。
• 本地插件安装与 Docker server-beta 部署是不同运行形态，不能把本地工作进程脚本直接视为容器部署入口。
• 资料没有说明各个兼容客户端的版本要求、能力差异和兼容性测试范围。
• 资料没有提供固定 API 接口签名、备份恢复方案、数据保留策略、SLA 或基准测试。
• README 与 package.json 的版本和 Node.js 下限标注存在差异，安装时应以实际包元数据和最新 README 为准。

适合谁与不适合谁

是否采用该项目，应根据会话连续性、数据敏感程度和现有部署能力判断。下面的信号用于做技术选型初筛，不构成对未提供指标的性能推断。

适合使用的信号

• 团队持续在同一代码库中使用 Claude Code，并且任务跨越多个会话，需要保留历史决策和工具观察。
• 已有 Node.js 20.12.0 及以上和 Bun 1.0.0 及以上运行环境，能够接受插件钩子与独立 worker 的运行方式。
• 能够配置人工智能提供方凭据，并已完成对应数据处理、密钥管理和访问授权评估。
• 需要通过 mem-search skill、Web Viewer 或观察 ID 引用历史内容，而不是依赖手工复制完整会话。
• 具备本地容器、Postgres、Valkey、日志和卷管理能力，需要把 HTTP 服务与生成消费者分离。

不适合使用的信号

• 组织要求所有代理观察都不得持久化，且无法实施 <private> 标记、数据隔离和删除流程。
• 运行环境无法安装 Node.js 20.12.0 及以上或 Bun 1.0.0 及以上，也不能采用仓库要求的插件安装机制。
• 团队只需要一次性会话，不需要跨会话上下文，也不愿维护 worker、数据库或队列。
• 部署要求已有明确的 SLA、性能上限、灾备和合规认证，但项目资料没有提供这些承诺或证明材料。
• 需要一个完全离线、无需人工智能提供方凭据的摘要系统；Docker 资料明确说明无提供方密钥时不会生成观察结果。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分“插件未安装”“worker 未处理”“提供方未配置”和“服务端未健康”四类问题。每一类问题的检查入口都能在仓库资料中找到对应依据。

为什么全局安装后没有插件功能

README 明确说明，npm install -g claude-mem 安装的是 SDK 或库，不会注册插件钩子，也不会设置 worker。应改用 npx claude-mem install，或在 Claude Code 中执行插件市场命令。

安装后为什么新会话没有历史上下文

先确认是否按 README 要求重启了 Claude Code。然后检查 worker 状态和日志；可执行 npm run worker:status 与 npm run worker:logs，再确认会话中确实产生了可捕获的工具使用观察。

Docker worker 在运行但没有新观察

检查 ANTHROPIC_API_KEY、CLAUDE_MEM_ANTHROPIC_API_KEY、GEMINI_API_KEY 或 OPENROUTER_API_KEY 是否按选择的提供方配置。Compose 注释明确指出，worker 没有生成凭据时会保持运行但不产生观察结果。

容器启动失败如何定位

Compose 要求 POSTGRES_USER、POSTGRES_PASSWORD 和 POSTGRES_DB，缺少任意必填数据库变量时，堆栈会拒绝启动。随后检查 Postgres 与 Valkey 健康状态，再检查 CLAUDE_MEM_SERVER_DATABASE_URL、CLAUDE_MEM_REDIS_URL 和认证模式是否符合 Compose 要求。

如何验证 HTTP server

在 Compose 部署中，可以访问 http://127.0.0.1:37877/healthz。该路径来自 server 的 healthcheck；它只能说明健康检查端点响应，不等同于已经验证人工智能生成、队列消费或历史检索全部成功。

版本应以哪份资料为准

README 徽章显示 13.4.0，package.json 显示 13.15.2；Node.js 下限也分别出现 20.0.0 和 20.12.0。遇到安装或兼容性问题时，应优先查看正在安装的包元数据和最新 README，官方仓库未提供该差异的解释，建议以最新 README 为准。

项目结构与开发入口

仓库的发布文件和脚本能够反映主要开发入口，但所给资料没有完整目录树。下面只列出在 package.json 的 files、scripts 或配置中明确出现的路径。

• dist/npx-cli/index.js：命令行入口。
• plugin/hooks：插件钩子发布目录。
• plugin/skills：技能发布目录，README 提到 mem-search skill。
• plugin/ui：插件 UI 发布目录。
• plugin/scripts/worker-service.cjs：worker 服务脚本。
• plugin/.claude-plugin、plugin/.codex-plugin：插件相关清单目录。
• src/ui/viewer/tsconfig.json：viewer TypeScript 检查配置路径。
• tests：测试目录，脚本进一步划分 sqlite、worker、search、context、infrastructure 和 server 测试入口。

源码贡献者可以使用 npm run typecheck 执行根项目和 viewer 的类型检查，使用 npm test 运行测试。构建入口是 npm run build，它会同步插件清单、构建钩子并生成插件锁文件。

部署决策与运维边界

本地插件模式适合直接服务于代理客户端的个人开发环境，Docker Compose 模式则提供了 server、worker、数据库和队列的拆分结构。选择前应先确认是否需要 HTTP 服务、队列扩展和多容器生命周期管理。

1. 仅需要 Claude Code 跨会话记忆时，优先依据 README 的插件安装路径验证本地流程。
2. 需要 OpenClaw Gateway 时，使用 README 指定的 OpenClaw 安装方式，并单独审查实时观察流的外发目标。
3. 需要服务端 HTTP 接入、Postgres 规范存储和 BullMQ 队列时，评估 Docker Compose 的 server-beta 形态。
4. 需要扩展生成消费者时，使用 Compose 注释给出的 worker scale 命令，并为数据库、Valkey 和提供方调用建立独立监控。

根据本文作者的经验判断，记忆系统的运营风险主要集中在数据边界和错误摘要，而不是安装命令本身。上线前应准备脱敏规则、访问密钥轮换、卷备份、队列积压告警和人工复核流程；这些流程不属于仓库资料已经提供的内置保证。

项目地址与资源

以下链接均来自项目仓库资料或 README 中出现的官方站点，适合用于安装、文档阅读和集成核验。

• claude-mem GitHub 仓库
• claude-mem 官网
• claude-mem 官方文档
• 安装指南
• OpenClaw 集成指南
• Antigravity CLI 配置指南
• OpenClaw 官方站点
• Claude Code 官方站点
• Vercel Open Source Program