Claude-Mem 实战指南：用“观察者代理 + 渐进式披露“为 AI 编码代理打造跨会话记忆

Claude-Mem 实战指南用观察者代理 渐进式披露为 AI 编码代理打造跨会话记忆【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文以仓库中的黑客松指南 01-what-is-claude-mem-field-guide.md 为主体逐层拆解 Claude-Mem 的完整机制第二个观察者代理如何通过 Hook 生命周期旁观主代理的每次工具调用、如何把值得记住的事写成结构化观察记录observation、如何以标题先行、按需取详情的低成本方式把记忆注回新会话以及如何通过可替换的 Mode 把同一套机制指向代码之外的任何数据源。读完本文你既能理解这套记忆层的底层实现证据也能直接上手完成安装与二次构建。一、一句话版本Claude-Mem 给你的 AI 编码代理装上记忆。它在主代理旁边坐着一个观察者代理observer旁观主代理做的所有事把值得记住的部分写下来并在你下次开始工作时把这些笔记交还回去——于是你的代理醒来时就已经知道昨天发生了什么。指南原文的表述是Thats it. Everything else in this guide is detail.其余一切皆为细节。二、问题AI 代理会忘记一切指南用了一个贴切的类比你雇了一位天才工程师——极快、精通所有语言、不知疲倦——但他每天早上都带着完全失忆的状态上班。他不记得代码库、不记得昨天一起修的 bug、不记得上周关于数据库的决定也不记得那三种已经被证明走不通的方案。因此每天早上都一样重新读文件、重新发现结构、重新问你早已回答过的问题甚至重新尝试你已证明行不通的方法。每个会话的前十到二十分钟都只花在回到上次进度上。这正是今天使用 AI 编码代理的真实感受代理在会话内很聪明会话一结束就是一片空白。它带来三类真实成本时间每个会话都从冷启动开始代理把开头若干轮次烧在重新发现昨天就知道的东西上。金钱重新发现意味着重读文件意味着 token意味着真金白银。AI 代理的大量开销其实是它在重新学习已经学过的东西。丢失的决策最糟的不是慢启动而是被遗忘的推理过程。我们当时为什么这么做这个答案曾经存在过但没人写下来现在它没了。Claude-Mem 的目标就是同时修复这三点。三、核心思路给主代理配一个书记员核心洞察很简单你不需要让主代理自己去记住你只需要有个人在它工作时做笔记并在恰当的时机把笔记交还回去。于是 Claude-Mem 加入第二个代理叫它observer观察者。它不写代码、不与你对话只有一个职责看着主代理干活维护一本值得记住的事的笔记本。可以把它想象成房间里的书记员主代理是工匠——读文件、改代码、跑命令、做决策观察者坐在角落拿着笔记本工匠每做一件事它就瞟一眼并问同一个问题这值得记一笔吗大多数时候答案是否定的为查个小事读文件不记。跑了一条没什么发现的小命令不记。观察者是刻意做筛选的——一本装满琐事的笔记本和没有笔记本一样没用。这一点在源码中有直接证据默认 code 模式的提示词里专门有一段WHEN TO SKIP何时跳过指令明确要求跳过例行操作空状态检查、无报错的依赖安装、没有后续发现的简单目录列表、已记录过的重复操作等并要求跳过时只返回空响应不要用散文解释。见 code 模式配置 中prompts.skip_guidance字段。而当答案是肯定的时候——bug 修好了、做出了一个决定、发现了意外的东西、某个功能上线了——观察者就写一条结构化的笔记而不是倾倒原始文本。下次你坐下干活时观察者翻开笔记本说这是最近发生的事这是你做到一半的事这是你做过什么决定、以及为什么。工匠读完笔记热启动开工。这就是 Claude-Mem 的全部两个代理一个干活一个负责记住。四、观察者如何看见正在发生的事这是它到底怎么插进来的的问题答案比想象的更简单。AI 编码代理工作时不做魔法——它执行的是动作actions读一个文件、改一个文件、跑一条命令、搜索某样东西。每一个动作都叫一次tool use工具调用。一个会话其实就是一长串 tool use 序列。Claude-Mem 挂钩在这批动作前后的时机上。代理的运行环境Claude Code 等允许外部程序监听少数几个生命周期时刻会话开始时Claude-Mem 利用这个时机把笔记交还——向代理上下文注入一份最近观察记录的紧凑时间线让它热启动。每次工具调用之后每一次读取、每一次编辑、每一条命令。Claude-Mem 抓住该动作及其结果交给观察者。代理完成一轮 / 会话结束时Claude-Mem 让观察者写一段简短的进度总结——当前进展到哪、下一步是什么。关键性质Claude-Mem 从不打断或改变主代理的行为。它从外部旁观。即使 Claude-Mem 整体崩溃主代理也会像以前一样继续干活——只是之后不会记得任何东西。主代理永远不会被等观察者记笔记拖慢记笔记发生在后台。这一点在 Hook 配置文件 中可以得到精确印证。该文件定义了六个 Hook 事件全部通过node plugin/scripts/bun-runner.js plugin/scripts/worker-service.cjs调用 worker 服务Hook 事件matcher子命令超时异步Setup*version-check.js安装期版本检查300s否SessionStartstartup\|clear\|compactworker-service.cjs start拉起 workerhook claude-code context注入上下文60s否UserPromptSubmit—hook claude-code session-init60s否PostToolUse*所有工具hook claude-code observation120s是PreToolUseRead仅读文件hook claude-code file-context60s是Stop—hook claude-code summarize120s是可以看到捕获每次工具调用的是PostToolUse事件matcher 为*即全部工具且标记为async: true——与记笔记在后台发生、不阻塞主代理的叙述完全吻合注入记忆的是SessionStart覆盖startup、clear、compact三种会话起点Stop事件负责生成会话总结。整幅图景看起来是这样的Your main agent The observer agent (does the work) (takes the notes) ───────────────── ─────────────────── reads a file ──► handed over ──► worth a note? ...no. edits a file ──► handed over ──► worth a note? ...no. runs the tests ──► handed over ──► worth a note? YES — tests went green after the config fix. ✎ writes note fixes a bug ──► handed over ──► worth a note? YES. ✎ writes note ... session ends ──► handed over ──► writes a short summary of the session每一次 tool use 都会送达到观察者手中由观察者的模式见第六节与提示词决定哪些会变成笔记。此外code.json的提示词还规定观察者是SILENT BY DESIGN设计上保持静默的单向记录器它不能接触、联系或影响被观察的会话——一个知道自己正在被观察的代理会以不可预测的方式改变行为从而破坏你要创建的记录。这从实现层面保证了观察者真正只是看着。五、一条笔记长什么样结构化的观察记录观察者不写日记它写结构化的笔记——而正是结构让它们日后有用因为结构让笔记可搜索、可快速浏览、交还成本低。每条笔记Claude-Mem 称之为observation都有相同的形状共八个部分1. 标题title一行。发生了什么写成只看标题就能判断你关不关心的程度。例如Fixed login redirect loop caused by stale session cookie修复了由过期会话 cookie 引起的登录重定向循环。标题是最重要的字段因为多数时候标题是未来代理唯一会读到的部分。2. 副标题subtitle再多一行上下文系统的哪个部分、当时的情境。code 模式的提示词里给出了硬性约束——One sentence explanation (max 24 words)一句话最多 24 个词见 code.json 中xml_subtitle_placeholder。3. Facts——语义块semantic chunks大约三条单句要点。每一条都是一个独立、真实、脱离任何上下文也能成立的陈述。这些就是语义块——小的、自包含的意义单元可以被搜索找到也能被孤立理解。例子The redirect loop only happened when the session cookie was older than 24 hours.The fix was to clear the cookie before re-issuing the login redirect.The relevant logic lives in the auth middleware, not the login page.每条 fact 是一句话可以被抽出来丢进另一个完全不同的对话里仍然有用——这是检验标准。源码侧同样如此约束prompts.field_guidance要求每条 fact 是一条信息不用代词每条必须独立成立包含具体细节文件名、函数名、值。4. 叙事narrative一段短文讲故事当时在做什么、尝试了什么、学到了什么、为什么重要。这是需要完整图景时用的字段。facts 供快速扫读narrative 供深入理解。5. 类别category固定列表中的一个标签让笔记本可以按类过滤和配色。默认 code 模式的类别与 code.json 中observation_types完全对应实际共 9 种bugfix— 有东西坏了现在修好了feature— 新增了能力refactor— 重构了结构行为不变change— 一般性修改文档、配置、杂项discovery— 对现有系统的认识decision— 架构或设计选择附理由另外还有安全相关类型security_alert需要立即处理的安全问题、security_note值得记录但不紧急的安全观察、sensitive不宜泄入后续内容开发的敏感信息提示词还硬性规定类型MUST be EXACTLY one of these 9 options保证类别是封闭集合、可过滤。6. 标签tags / concepts一组可复用的标签描述笔记里是哪种知识独立于具体主题。code 模式固定为 7 个对应observation_conceptshow-it-works、why-it-exists、what-changed、problem-solution、gotcha、pattern、trade-off。提示词要求每条笔记取 2–5 个且不得把类型type当概念用——types 和 concepts 是两个不同维度。标签让你以后可以问给我看这个项目里踩过的所有 gotcha。7. 涉及的文件files touched读了哪些文件、改了哪些文件让未来的代理直接跳到位点。8. 时间戳自动每条笔记精确知道发生时刻这正是**时间线timeline**存在的基础——你可以对任何一条笔记问它前后各发生了什么合在一起一条笔记大致长这样指南用自然语言示意不是真实存储格式bugfix· 15:48Fixed login redirect loop caused by stale session cookieWeb app 的 auth 中间件重定向循环只在会话 cookie 超过 24 小时时发生。修复方式是在重新发起登录重定向前先清掉 cookie。逻辑位于 auth 中间件不在登录页。用户报告被 /login 与 /dashboard 之间无限弹跳。排查发现中间件信任了一个服务端已判定过期的 cookie。在重定向前清掉它循环即断。值得记住因为表象像前端路由 bug根因却在服务端。tags: problem-solution, gotcha · files: middleware/auth.ts标题、facts、narrative、类别、标签、文件、时间——每条笔记同样的形状。这种一致性本身就是全部技巧所在。六、笔记存在哪里又怎么回来存储位置在你的机器上。Claude-Mem 把每条观察存进主目录下的本地数据库~/.claude-mem旁边还有一个按语义而非仅精确词理解的搜索索引所以你搜那个 cookie 的事也能找到重定向循环那条笔记。除了调用执行观察的 AI 模型之外没有任何东西离开你的机器另有一个可选的 Pro 层提供云同步可在多台机器间共享同一份记忆——纯可选项。数据目录的解析逻辑见 src/shared/paths.tsjoin(homedir(), .claude-mem)。取回方式——先走最便宜的路这是让 Claude-Mem实用而非仅仅好看的部分。如果它在每个会话开始时把全部笔记全文塞给代理预算会立刻爆掉。于是它分层取回最便宜的先官方称之为 progressive disclosure即渐进式披露有专门文档 progressive-disclosure.mdx第 1 层——时间线索引自动每个会话都注入。会话开始时Claude-Mem 注入一张紧凑清单ID、时间、类别图标、标题。只有标题。50 条最近笔记可能只花几百个 token。代理扫一遍标题通常就够了——哦对我们昨天修过 cookie 那件事。索引按日期和文件路径分组每行还标注了取回成本token 数让代理自行做性价比决策。第 2 层——按 ID 取详情按需。如果某条标题看起来相关代理用get_observations按 ID 取回那条笔记的 facts、narrative 和 files。只为真正需要的部分付费。第 3 层——搜索时间线里没有的东西。对更旧的记录或不同主题代理可以检索全部历史——按语义、关键词、类别、日期、项目。搜索先返回标题代理过滤后再对感兴趣的批量取详情。同样是便宜优先的纪律。这三个工具在仓库中是真实存在的 MCP 工具mem-search 技能 完整记录了它们的参数与成本模型search(query, limit, project, type, obs_type, dateStart, dateEnd, offset, orderBy)—— 返回 ID/时间/类型/标题的索引表每条约 50–100 tokentimeline(anchor, depth_before, depth_after, project)—— 以某条观察为锚点返回前后各 N 条默认 5最大 20的交错时间线理解叙事弧线get_observations(ids, orderBy, limit, project)—— 批量取完整对象标题、副标题、narrative、facts、concepts、files每条约 500–1000 token。技能明确要求2 条以上一律批量取并强调10 倍 token 节省来自先过滤、后取详情。这正是你在新会话开头看到的注入文本会写着类似50 observations, 17,530 tokens to read, 1.3 million tokens of work behind them, 99% savings的原因。这些数字不是口号而是从数据库里算出来的TokenCalculator 用savings 实际完成的工作所需 token 总量 − 笔记本身 token 总量计算节省量与百分比再由 AgentFormatter 格式化成注入文本里的99% savings一行。笔记是大量工作的一份压缩索引代理只解包它需要的部分。查看器viewer另有一个本地网页让你人类能实时看着笔记在代理工作时落地、按项目浏览、并搜索。这是看见记忆发生的最直接方式对应仓库中的 viewer 前端。七、Modes告诉观察者该盯什么到这里以上内容都默认观察者在盯一个编码会话。那是默认值。但下面这部分是创意空间最大的地方观察者的工作描述是可替换的。Claude-Mem 把一份工作描述称为一个mode模式。一个 mode 就是一个普通的配置文件定义四件事观察者是谁你是软件工程师的书记员还是你是审查邮件的法医分析师还是你是法学专业的学习伙伴。笔记类别是什么code 模式有 bugfix / feature / decision一个 email 调查模式有 entity / relationship / timeline-event / evidence / anomaly / conclusion一个机器人监控模式有 action-goal / state-change / error。什么合理就配什么。标签是什么按领域定制的可复用概念标签。用什么语言书写仓库内置 30 多种语言版本——同一个 code 模式可以用日文、西文或阿拉伯文写笔记对应 plugin/modes 目录下成组的code--*.json文件。一个 mode 就是这些而已。换个 mode同一套机器——同一个第二代理、同一个看每一个动作的循环、同样的 标题/facts/narrative/类别/标签 笔记形状——就开始观察完全不同的东西。以 code.json 为例其结构就是observation_types9 种类别各带 label、描述、图标observation_concepts7 个概念标签prompts观察者身份、静默纪律、记录/跳过策略、类型约束、XML 输出格式模板——与上面第六节讲的笔记形状一一咬合。这解锁了什么因为观察者只是盯着动作及其结果而动作可以是代理做的任何事被观察的对象不必是代码一张照片代理打开一张白板照片或截图观察者能看到它。用一个写着记录你在白板上看到的设计决定和未决问题的 mode你就能从一张图里得到结构化笔记。一份会议记录喂入逐字稿一个记录决定、负责人和截止日期的 mode能把一小时谈话变成几条可搜索的笔记。一段对话或聊天记录客服工单、Slack 导出、邮件倒仓——一个为实体、关系、时间线事件调校的 mode把它变成一条可调查的时间线。日志、issue、提交历史、客服工单代理能读到的任何东西观察者的 mode 决定值得记的含义。仓库中已存在的 mode 包括code默认、一个更安静的 code 变体只记录重新发现起来很痛的东西、email 调查、法律学习、meme-token 交易信号、机器人监控——足以感受这个范围。而且你不必手写一个仓库提供 /mode-creator 技能它会访谈你——你在观察什么、哪类东西重要、类别应该是什么——然后替你写好、安装并激活这个 mode。其流程是先了解你的工作而不是上来就问 JSON 字段再提议一套 4–8 种类别 4–8 个标签的小分类学经你批准后安装到数据目录的modes/下并重启 worker还建议用继承式 ID如code--xxx复用稳定的输出协议、只替换领域分类学。任何数据进任何模式出。挑你要盯的东西告诉观察者什么重要得到带时间戳、可搜索的结构化笔记。八、可以在上面搭建的东西因为所有部件都简单且对外暴露它们是好的积木时间线timeline——按时间排序的结构化笔记流带 ID。锚定任何一条笔记读取它前后发生的事。搜索search——跨全部历史笔记的语义 关键词搜索可按项目、类别、日期过滤。技能skills——仓库里一批命令行形态的小助手搜索记忆mem-search、生成时间线报告timeline-report这个项目的旅程、从观察记录构建聚焦知识库knowledge-agent、创建 modemode-creator、解释自身原理how-it-works。它们都是文本进、文本出意味着很容易被包进 UI、编辑器、聊天机器人或 CI 任务。实时观察——笔记在代理干活时就落地而不是事后可用。意味着可以有东西对它们做出反应某种模式一出现 → 某件事就运行。会话总结——每个会话结束时观察者写一段我们到了哪、下一步是什么这就是交给下一个会话的接力棒由前述StopHook 触发。九、为什么这件事重要诚实版AI 代理将承担世界上大量的工作。眼下每一个都带着失忆醒来。任何修复这一点的东西都会很重要。Claude-Mem 的押注是解法不是一个不知为何记得一切的巨型模型而是无聊且稳健的东西第二个代理、一本笔记本、一种一致的笔记形状、以及一种便宜优先的笔记交还方式。这是今天就能工作、成本极低、并能与一切其他东西组合的东西。该指南声明它已被超过 10 万名开发者使用并且开源部件小到一个人、一个周末就能在上面构建出真正新东西。十、五分钟上手安装npx claude-mem install开一个编码会话干点活。观察者会立即开始记笔记。在同一项目里开第二个会话。看顶部——你会看到时间线上次发生过的标题列表。这就是记忆注入。第一个会话负责播种记忆第二个会话你才感觉到它。问你的代理我们是不是已经修过 X——它会用搜索技能。打开本地查看器边干活边看笔记落地。跑/mode-creator把观察者指向一件不是代码的东西。指南还提到每位黑客松参与者可获 30 天 CMEM Pro 免费试用安装后使用兑换码 FASTHACK30。十一、1000 美元记忆大奖黑客松赛道由 Claude-Mem 赞助与总评一、二、三名分开评所以你可以两个都拿。挑战构建一个真的会记得的 agentic 工具。七个方向——任选其一、组合几个、或自带题目热启动Warm boot一个开场即拥有即时上下文、而不必烧掉前十轮去重新发现代码库的代理。在时间线上构建把时间线 搜索技能当检索层搭点新的东西。给技能一张脸技能是 CLI 形态的。用 UI/UX 包住它们让记忆变成你能看见、能操纵、能分享的东西。构建一个集成把 Claude-Mem 接进它还没待过的地方——你的编辑器、CI、聊天应用、另一个代理框架或 harness。任何数据进任何模式出观察记录不只有文本——截图、UI 捕获、设计文件、白板照片、逐字稿、日志、issue、提交历史、客服工单。一个自定义 mode 告诉观察者该盯什么。对它看见的东西开火观察实时落地。把它们挂上动作一种模式一出现某件事就运行。构建对刚发生的事做出反应、而不是等被问的代理。记忆作为提速手段用回忆砍掉 token、轮次或墙钟时间。最后任何有人真的会去用的东西都额外加分。十二、整件事的一页纸总结是什么AI 代理的记忆层。怎么做第二个观察者代理接收每一次 tool use决定是否记一笔。一条笔记是标题 副标题 单句 facts narrative 类别 标签 文件 时间。笔记怎么回来标题先行便宜、按 ID 取详情、其余靠搜索。Modes换掉观察者的工作描述——观察代码、邮件、照片、逐字稿、机器人任何东西。可构建的积木时间线、搜索、技能、实时观察、会话总结。大奖$1,000奖励一个真的会记得的 agentic 工具。七个方向。有人真的会去用额外加分。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考