92K 星的 claude-mem 让 AI 编程智能体跨会话保留记忆与决策上下文

GitHub 标星达到 92,288 的开源持久记忆系统 thedotmack/claude-mem 在 2026 年 8 月 26 日发布了 v13.16.1 正式版本。表面看它是给 Claude Code、OpenClaw 以及 Codex 等 AI 编码工具挂载的一个外部记忆插件，本质是将智能体每次工具调用的生命周期事件转化为结构化观察图谱的分层状态召回引擎。

在日常使用 AI 编码工具（即智能体 Agent，一种能够自主感知环境、调用工具并执行复杂任务的程序）时，最常见的痛点莫过于新会话启动后的“上下文遗忘症”。开发者不得不反复粘贴架构说明与历史修复记录。claude-mem 改变了传统 RAG（检索增强生成）简单匹配向量切片的粗暴方式，通过多生命周期钩子实时捕获操作，将代码修改、调试推演与架构决策自动提炼为长期记忆。

捕获与三层渐进式披露的工作原理

claude-mem 建立在 Node 运行环境之上，核心由一个由 Bun 管理的后台 Worker 服务、SQLite 本地数据库以及 Chroma 向量数据库共同驱动。系统在智能体运行期间挂载了 5 个关键生命周期钩子（SessionStart、UserPromptSubmit、PostToolUse、Stop 与 SessionEnd），全面监控 Read、Write、Edit、Bash、Glob 和 Grep 等工具调用。

每次智能体完成工具操作，Worker 会调度轻量级语言模型将原始输入输出提炼为结构化观察数据，包含标题、副标题、叙事描述、确立事实、核心概念、类型标记（如 decision、bugfix、feature）以及涉及的文件路径。在会话结束时，Stop 钩子会自动整合并产出包含请求目标、调查路径、所获认知、完成事项和后续规划的完整会话摘要。

为解决海量历史信息瞬间挤爆上下文窗口的问题，claude-mem 采用了三层渐进式披露架构：

• 第一层（索引概要）：新会话启动时，系统仅在初始上下文注入最近 50 条观察的紧凑标题与 Token 成本估算，消耗控制在 50 到 200 个 Token 之间。
• 第二层（按需搜索）：当用户询问特定历史（如“上次我们是如何重构认证模块的？”）时，Claude 会通过 MCP（模型上下文协议，一种标准化的智能体工具交互协议）调用 mem-search 检索紧凑索引与时间线上下文，每条结果消耗约 100 到 500 个 Token。
• 第三层（代码级还原）：如果过滤后的观察 ID 仍不足以支撑决策，智能体才会提取完整详情并直接读取底层源码。

这种设计相比全量上下文拼接，实现了约 10 倍的 Token 消耗削减，使智能体能够在超大工程中维持极低成本的高效回忆。

极简安装与多环境快速配置

部署 claude-mem 时无需复杂的编译流程，官方提供了面向多种 IDE 与网关的一键安装脚本。安装过程中需区分 SDK 与插件的差异，单纯执行全局安装命令只会下载底层库文件，必须通过专用安装器注册钩子脚本。

针对主流智能体环境的安装命令如下：

# Claude Code 官方环境一键安装
npx claude-mem install

# OpenCode 环境安装
npx claude-mem install --ide opencode

# Antigravity CLI 环境安装
npx claude-mem install --ide antigravity

# OpenClaw 专用全自动网关安装脚本（自动处理依赖、插件与 Worker 启动）
curl -fsSL https://install.cmem.ai/openclaw.sh | bash

若在 Claude Code 内部使用插件市场安装，可直接输入：

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

安装完成后，系统会在用户目录自动生成配置文件 ~/.claude-mem/settings.json。用户可以通过修改参数调整抽取模型、后端服务提供商以及语言显示模式：

{
"CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001",
"CLAUDE_MEM_PROVIDER": "claude",
"CLAUDE_MEM_MODE": "code--zh",
"CLAUDE_MEM_CONTEXT_OBSERVATIONS": 50,
"CLAUDE_MEM_WORKER_PORT": 37785,
"CLAUDE_MEM_DATA_DIR": "~/.claude-mem"
}

如果希望降低观察提炼的 API 支出，可以直接配置免费额度的 Gemini 服务商，支持即时生效：

{
"CLAUDE_MEM_PROVIDER": "gemini",
"CLAUDE_MEM_GEMINI_API_KEY": "AIzaSyYourKeyHere",
"CLAUDE_MEM_GEMINI_MODEL": "gemini-flash-latest"
}

若使用 OpenRouter，可将 CLAUDE_MEM_PROVIDER 设为 openrouter，默认模型会自动匹配免费的 xiaomi/mimo-v2-flash:free。每次手动修改配置后，需要在终端执行 npm run worker:restart 重启后台服务。

OpenClaw 深度集成与多端实时推送

作为当前热门的自主智能体框架，OpenClaw 与 claude-mem 的集成展现了深度解耦的系统设计。该插件完全依托 OpenClaw 内部事件流工作，在 before_agent_start 初始化追踪，在 before_prompt_build 将提炼的上下文无感拼接入系统提示词，在 tool_result_persist 记录观察，并在 agent_end 触发摘要归档。

该集成绝不直接污染工作区文件，它通过内存级系统上下文追加配合 60 秒本地缓存策略，完整保留项目自带的 MEMORY.md 供智能体自主管理。

OpenClaw 用户可以在配置文件中开启实时观察推送（Observation Feed）。Worker 借助 SSE（服务端发送事件）流式传输技术，将新生成的观察结构体即时分发至即时通讯平台：

{
"plugins": {
"claude-mem": {
"enabled": true,
"config": {
"project": "core-backend",
"observationFeed": {
"enabled": true,
"channel": "telegram",
"to": "887654321"
}
}
}
}
}

开启后，系统在捕获到代码重构或 Bug 修复决策时，会自动向 Telegram、Discord 或 Slack 频道投送格式为 🧠 Claude-Mem Observation 的通知卡片。开发者在日常对话中也可以随时调用 /claude_mem_status 检查健康指标，或使用 /claude_mem_feed 快速开关推送流。

记忆系统演进阶段与避坑实战指南

AI 智能体记忆管理经过数次架构迭代，各阶段的取舍直接影响了开发效率与系统稳定性：

在实际配置与高频编码过程中，开发者需要规避以下实测踩坑点：

• Windows 僵尸进程与端口占用：在 v13.16.1 之前，Windows 平台下 Chroma 向量库关联的 Python 子进程容易在会话强制中断后滞留。新版本加入了跨进程树清理（严格按 uvx -> uv -> python -> chroma-mcp 链路终止，并校验 PID 身份防止误杀），若遇到老版本端口占用，可手动指定端口 export CLAUDE_MEM_WORKER_PORT=38000 后重启。
• Gemini 限速与无自动降级：未绑定账单的 Gemini 免费 Key 存在 5 到 10 RPM 的频次限制，密集工具调用可能触发限流。部分早期第三方文档称其支持失败自动回退到 Claude SDK，但源码层面并未实现自动重试切换，生产环境建议绑定 Google Cloud 账单解锁 1000 RPM 并持续使用免费额度。
• 多用户与多 Profile 端口冲突：系统默认 Worker 端口计算规则为 37700 + uid % 100。在同一台开发机上运行多个隔离环境时，需在 settings.json 中为不同项目分配互不重叠的独立端口。
• 敏感信息隐私保护：对于包含密码、Token 或商业机密的临时测试输入，可以在 Prompt 中包裹 与 标签，底层钩子捕获时会自动剔除被标记字段，避免敏感数据写入 SQLite 数据库。

综合判断与未来演进

从工程架构视角审视，claude-mem 并非传统意义上的外挂知识库检索工具，而是面向智能体操作行为的状态快照器。一些开发者误以为安装此类插件会篡改本地 Git 提交或强行改写智能体的自主行为，事实上它仅充当只读的结构化认知层，把跨会话的记忆索引交由大模型按需唤醒。

对于在生产环境中重度依赖 Claude Code 进行持续重构的团队，这套方案显著降低了长周期项目的上下文交互损耗。伴随近期更新的 claude-mem-cowork 插件开始支持临时容器与云端协同，智能体记忆正从单一终端走向分布式网络。

当前系统尚未彻底解决的难题在于跨分支代码演进时的过时认知冲突。当项目经历激进的大版本架构重写或并行分支合并时，数据库中存留的历史观察事实可能与当下最新代码产生语义矛盾。系统目前仍缺乏一套全自动的旧认知失效与修剪算法，在极端重构场景下，仍需开发者手动介入清理或重置数据库索引。

引用来源

1. thedotmack/claude-mem 官方代码仓库与发行说明，更新于 2026 年 8 月 26 日。https://github.com/thedotmack/claude-mem
2. GitHub Releases: claude-mem v13.16.1 Windows Megafix 更新日志，发布于 2026 年 8 月 26 日。https://github.com/thedotmack/claude-mem/releases/tag/v13.16.1
3. claude-mem 官方架构与 OpenClaw 接入配置文档，更新于 2026 年 8 月 20 日。https://docs.claude-mem.ai/integrations/openclaw
4. claude-mem 官方服务商配置与模型定价指南，更新于 2026 年 8 月 15 日。https://docs.claude-mem.ai/configuration/providers
5. GitHub Trending 技术榜单智能体持久化项目收录档案，记录于 2026 年 8 月 28 日。https://github.com/trending/claude-mem