Claude-Mem 速览
- 它是记忆层，不是规则文件：hooks 把每次工具调用交给本地 worker，第二个 agent 把这些活动转成简短的观察记录，下一次会话则以一份紧凑索引开场。
- 两种受支持的安装方式：npx claude-mem install（准备好运行时并打开浏览器配置页），或者依次执行 /plugin marketplace add thedotmack/claude-mem 与 /plugin install claude-mem。
- Apache-2.0 许可，TypeScript 编写，由 Alex Newman（thedotmack）维护。记忆以 SQLite 形式保存在本地 ~/.claude-mem/claude-mem.db；云同步需自行开启。
- 它并不取代 CLAUDE.md，也不取代 Claude Code 的自动记忆——三者都在会话开始时加载，回答的却是不同的问题。下面的对比表是精简版。
thedotmack/claude-mem — README
来源github.comchecked 2026-11-13
.claude-plugin/marketplace.json — claude-mem 15.18.3
来源raw.githubusercontent.comchecked 2026-11-13
Installation Guide
来源docs.claude-mem.aichecked 2026-11-13
Configuration
来源docs.claude-mem.aichecked 2026-11-13
Telemetry — what is collected and how to opt out
来源docs.claude-mem.aichecked 2026-11-13
How Claude remembers your project — CLAUDE.md vs auto memory
来源code.claude.comchecked 2026-11-13
dsh-claude-mem — DeepSeek Harness port (unofficial)
来源deepseekharnessplugins.comchecked 2026-11-13
本页的命令、设置、默认值和路径均取自上游仓库与官方文档，核查时间为 2026-11-13。命令和设置名刻意保留原文，因为被翻译过的命令就是跑不通的命令。
仓库数据来自 2026-11-13 的 GitHub API：116,640 stars、10,120 forks、创建于 2025-08-31、最新版本 v15.18.3 发布于 2026-11-12。star 数每天都在变——请把它当作快照，而不是评分。
Claude-Mem 到底是什么
Claude-Mem 是一款开源插件，为 Claude Code（以及另外十几种编程 agent）赋予关于自身工作的记忆。项目对问题的描述很直白：每个新会话都从零开始，重复读同样的文件、重复问同样的问题，又踩回你们之前已经一起修掉的坑。
它的解法是在你身边再跑一个 agent。装进宿主 agent 的 hooks 会把每次工具调用——读了什么、改了什么、跑了什么——交给一个本地的小 worker。这个 worker 用观察模型处理这些活动，写出简短的结构化观察记录和一份会话结束总结，存入本地 SQLite 数据库。新会话启动时，宿主 agent 会收到一份只包含本项目相关观察记录的紧凑索引，需要细节时才去拉取完整内容。
所以这里的记忆单元是“对已发生工作的观察”，而不是你写下的指令。这正是它与 CLAUDE.md 的全部差别，也是两者并存而非相互竞争的原因。
- 许可证
- Apache-2.0
- 最新版本
- v15.18.3 · 2026-11-12
- 记忆存放位置
~/.claude-mem/claude-mem.db- 星标（2026-11-13）
- 116,640
三步看懂它的工作机制
README 用三句话讲清了这个循环，其余所有功能都挂在这条链上：
- 1
你的 agent 正常工作
宿主 agent 中的生命周期 hooks 会把每次工具调用交给本地的小 worker。对 Claude Code 来说，这些 hooks 覆盖 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、Stop、SubagentStop 和 SessionEnd，另有一个 Setup 入口用于 claude --init 和 --maintenance。每个 hook 都是一条不经过 shell 的命令：claude-mem hook claude-code <event>。
- 2
观察者负责做笔记
第二个 agent 把这些活动转成简短的观察记录，并在会话结束时写一份总结。默认的压缩模型是 Haiku（CLAUDE_MEM_MODEL=haiku），运行在你的 Anthropic 套餐上；也可以改用 OpenRouter 或 Gemini 的密钥，或使用厂商托管的观察服务。
- 3
下一次会话从这些记录开始
在 SessionStart 时，agent 会收到本项目的观察记录紧凑索引——默认 50 条，用 CLAUDE_MEM_CONTEXT_OBSERVATIONS 设置——只有需要时才取完整细节。注入从你在某个项目里的第二次会话才开始，因为第一次会话还没有东西可注入。
搜索用的是同一套分层思路。三个 MCP 工具——search、timeline、get_observations——先返回索引，再返回按时间排列的上下文，最后才给完整记录，这样 agent 只为它选中的那几行付出细节成本。mem-search 技能会替你调用这些工具，README 自己给出的数字是：索引一行约 50–100 tokens，完整记录为 500–1,000 tokens——README 明确说明这是单行比值，并不是实测的端到端节省。
worker 还给你什么
本地 worker 会在启动时打印的 URL 上提供查看器——/viewer 下有记忆、会话和设置，根路径则是 My Work——并暴露搜索之外的工具：用于代码导航的 smart_search、smart_outline 和 smart_unfold，用来主动写笔记的 save_memory，以及工作状态跟踪。每条观察记录都有 ID，可以通过 worker API 引用。
安装与验证
下面两种方式都摘自上游文档。项目推荐的是安装器方式，因为它会准备好运行时并编译 hook 启动器；插件方式则只是 Claude Code 里的两条提示。
方式一 —— 安装器
在终端里运行这条命令。安装器会检查 Bun 和 uv、复制插件文件、安装依赖、把 claude-mem 启动器放进 PATH，并打开浏览器配置页，让你挑选 agent、集成、技能和记忆提供方。使用那个页面时请让终端保持运行。
npx claude-mem install不要用 npm install -g claude-mem 安装。README 说得很明确：全局 npm 安装只会把 SDK/库放到你的机器上——它不注册任何插件 hook，不启动 worker，还可能遮蔽 PATH 上真正的启动器。
方式二 —— 插件市场
在 Claude Code 里把这两条作为两条独立的提示发送，然后重启。两种方式都会配置 hooks 并启动 worker；此后新会话会自动带上以往会话的上下文。
/plugin marketplace add thedotmack/claude-mem/plugin install claude-mem仅从插件市场安装没有安装器这一步，所以插件会在第一次会话启动、编译启动器的同时把它放好——那次会话可能没有记忆上下文，下一次就有了。跑一次 npx claude-mem install 就能补上这个缺口。
确认它确实在运行
运行 npx claude-mem doctor：它会检查 Bun、uv、hook 启动器和 worker，并告诉你该修什么。claude-mem --version 会打印启动器协议编号，启动时打印的 worker URL 则提供查看器。如果 hook 报出 “Executable not found in $PATH”，doctor 会显示 PATH 上解析到的是哪个 claude-mem、以及它是不是启动器。
npx claude-mem doctorclaude-mem --version开始前的环境要求
- 1Node.js 20.19 或更新（20.x 系列），或者 22.12 或更新。
- 2Bun 1.2.16 或更新——hook 启动器用它编译；如果缺失，安装器会装上 Bun。
- 3uv，缺失时自动安装：它为 Chroma 的语义搜索嵌入服务提供 Python 一侧的支持。
- 4Claude Code 2.1.139 或更新——这是第一个会执行 exec 形式 hook 参数的版本。更早的版本会忽略参数、直接运行裸的 claude-mem，结果什么都抓不到。SQLite 通过 bun:sqlite 内置提供。
真正会改变行为的设置
所有配置都在 ~/.claude-mem/settings.json 里，首次运行时按默认值自动创建，同名的环境变量会覆盖文件中的值。下面这些是值得了解的项，其余项见配置文档。
| 设置项 | 默认值 | 作用 |
|---|---|---|
CLAUDE_MEM_MODEL | haiku | provider 为 Claude 时用来压缩观察记录的模型。haiku 跟随最新的 Haiku；写完整 ID 则锁定某个版本。 |
CLAUDE_MEM_PROVIDER | claude | 由哪个提供方运行观察者：claude、codex、gemini、openrouter 或 openai-compatible。 |
CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | 会话开始时注入多少条观察记录。如果启动块显得太重，就把它调低。 |
CLAUDE_MEM_MODE | code | 工作流配置档以及生成观察记录所用的语言，例如 code、减少观察记录的 code--chill，或中文的 code--zh。 |
CLAUDE_MEM_DATA_DIR | ~/.claude-mem | 数据根目录。数据库、Chroma 索引、日志、设置、worker 的 pid 与端口文件等其余所有路径都由它派生。 |
CLAUDE_MEM_WORKER_PORT | 37700 + (uid % 100) | worker 端口。默认按用户区分，所以同一台机器上的两个用户不会冲突；如果你要针对 HTTP API 写脚本，就固定一个端口。 |
CLAUDE_MEM_CONTEXT_PROJECTS | current | SessionStart 读取哪些项目的记忆：current 表示当前这个检出目录，all 表示除你用 glob 排除掉的项目之外的所有项目。 |
CLAUDE_MEM_SKIP_TOOLS | ListMcpResourcesTool, SlashCommand, Skill, TodoWrite, AskUserQuestion | 不参与观察记录的工具。适合那些输出属于噪音而非知识的工具。 |
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES | false | SessionStart 上下文是否包含所有 harness 的观察记录，而不只是你当前所在的这一个。默认 false。 |
CLAUDE_MEM_SKILLS_DISABLED | (none) | 按裸文件夹名把内置技能从 Claude Code 的技能列表和斜杠命令中隐藏起来。 |
还有两个值得知道：CLAUDE_MEM_SKIP_BASH_PATTERNS 接收一个正则，对每条 shell 命令进行匹配，让噪音命令永远不会变成观察记录；CLAUDE_MEM_REDACT_ENABLED（默认关闭）会在存储前对已识别的密钥模式做自动脱敏。
Claude-Mem 与 Claude Code 内置记忆的对比
Claude Code 已经用两种方式跨会话携带知识，Anthropic 的文档把它们视为互补关系：你写的 CLAUDE.md，以及 Claude 自己写的自动记忆。Claude-Mem 是叠加其上的第三个独立层。
| 维度 | Claude Code 内置 | Claude-Mem 插件 |
|---|---|---|
| 谁来写 | CLAUDE.md 由你写；自动记忆由 Claude 根据你的纠正写入。 | 由第二个观察者 agent 写入，素材来自本次会话产生的工具活动。 |
| 存放在哪 | CLAUDE.md 位于项目根目录或 ~/.claude/CLAUDE.md；自动记忆位于 ~/.claude/projects/<project>/memory/，带一个 MEMORY.md 索引。 | SQLite 位于 ~/.claude-mem/claude-mem.db，设置和日志也在同一个文件夹。语义搜索可选配 Chroma 索引。 |
| 记录什么 | 指令和规则；自动记忆保存经验与模式，而且只加载前 200 行或 25KB。 | 对已发生工作的观察记录——决策、bug 修复、读了什么改了什么——由模型压缩而成。 |
| 何时加载 | 每次会话都自动加载，作为系统提示之后的上下文。 | 在 SessionStart 时通过 hook 加载，从你在某个项目里的第二次会话起生效。 |
| 如何读取 | 整个文件或自动记忆索引就直接存在于上下文中；/memory 可以列出并打开这些文件。 | 注入的是紧凑索引；细节通过三个 MCP 工具取回——search、timeline、get_observations。 |
| 依赖与成本 | 不需要任何额外东西——它随 Claude Code 一起提供。 | 需要 Node、Bun 和 uv，一个本地 worker 进程，以及一个负责压缩的模型：默认走你的 Anthropic 套餐，也可以用自己的密钥，或付费的托管观察服务。 |
实际分工是这样的：把规则和约定写进 CLAUDE.md，让自动记忆收集偏好，让 Claude-Mem 承载你实际做过什么的来龙去脉。如果某次会话的细节只重要一次，三者都不需要它；如果某条规则每次都必须遵守，那它唯一该待的地方就是 CLAUDE.md。两者在存储上甚至并不互斥——claude-mem 的 memory ingest 会把 Claude Code 自动记忆的 topic 文件直接导入自己的数据库作为观察记录，不消耗模型 token。
Claude Code 记忆攻略隐私、限制与坦率的提醒
这款插件会记录你的工作会话，所以在把它带进工作仓库之前，值得先读一遍默认值。
- 1默认本地。会话、观察记录和总结都写入 ~/.claude-mem/claude-mem.db 这个 SQLite 库；设置和日志放在同一个文件夹。云同步需自行开启，不会自动进行。
- 2把内容用 <private> 标签包起来，它就永远不会被存储——这是 README 的原话。对已识别密钥模式的自动脱敏是另一个开关 CLAUDE_MEM_REDACT_ENABLED，默认关闭。
- 3匿名遥测默认开启（PostHog，只关联一个随机安装 UUID）。用 npx claude-mem telemetry disable 关闭；DO_NOT_TRACK 会被尊重，并覆盖一切设置。
- 4压缩是一次模型调用，所以工具活动会离开本机，发往你选择的提供方——你的 Anthropic 套餐、你的 OpenRouter 或 Gemini 密钥，或者厂商托管的观察服务。请慎重选择。
- 5它是第三方软件，不是 Anthropic 的产品，而且会安装可执行的 hooks。在全团队推广之前，先读一读 plugin/hooks/hooks.json 和设置；把插件当成你正在运行的代码来对待，因为它本来就是。
- 6它消耗的不只是 token，还有上下文：一份注入的索引、一个 worker 进程，以及机器上的 Bun 和 uv。如果你的会话本来就短且自洽，收益很小——请在自己的仓库上实测，别信一个标题数字。
这些都不代表它不值得装。它只说明：先在一个真实项目上试用——把你绝不想被记录的仓库按 glob 排除掉，愿意的话再关掉遥测——然后再决定是否把它设为你打开的每个仓库的默认配置。
关掉遥测只要一条命令：
npx claude-mem telemetry disable