构建真正"记得住"的 AI 代理记忆：Claude-Mem 千元 Memory Prize 挑战赛全解与七大构建方向

本文围绕 Claude-Mem 官方的《The $1,000 Memory Prize》挑战赛文档（04-the-memory-prize.md）展开，完整讲解这场"构建真正能记忆的 agentic 工具"挑战的定义、七个参赛方向与评分规则，并结合当前仓库的 observer 提示词、观察记录数据模型、hook 生命周期与三层检索工作流源码，说明每个方向背后可以直接"长"出来的技术底座。读完本文，你既能理解 Claude-Mem 双代理（builder + observer）记忆的完整机制，也能拿到可复制的安装、检索与自定义模式操作步骤，直接上手构建参赛作品。

一、Claude-Mem 是什么：一句话定义与挑战背景

原文档对 Claude-Mem 的定义只有一口气（one breath）的篇幅：它是 AI 编码代理的开源记忆层。一个"第二代理"（observer）在旁边看着主代理工作，把发生的事转成结构化、带时间戳的观察记录（observation），并使其可被检索——这样下一个会话从"温启动"（warm boot）开始，而不是"冷启动"。项目文档声称已有 100,000+ 开发者在使用。

用大白话讲这套机制（原文档原文）：

1. 你的主代理执行动作——读文件、改文件、跑命令；
2. 每一个动作都会交给第二个 "observer" 代理，observer 会问一句："这件事值得记一笔吗？"多数时候答案是"不"；
3. 当答案为"是"时，它写入一条结构化笔记：标题（title）、副标题（subtitle）、若干单句事实（facts，即可以独立成立的语义块）、一段简短叙述（narrative）、一个类别（category，如 bugfix/feature/decision/discovery…）、若干标签（tags）、涉及的文件（files）以及时间戳；
4. 笔记存放在本地的、理解语义的检索索引中；
5. 下个会话开始时，标题会以时间线（timeline）形式回到上下文；细节只在需要时按 ID 取回；
6. observer 的"工作说明书"——模式（mode）——是可替换的，同一套机器既能盯代码，也能盯邮件、照片、会议记录、机器人日志，任何数据流。

挑战本身的定义也非常明确：

构建一个真正"记得住"的 agentic 工具。 不是"上下文窗口更大的 agent"，不是"把一切塞进 prompt 的 agent"。而是一个能保留重要的东西、在相关时找到它、并利用它变得比上一次更快、更聪明或更有用的 agent——或者给 agent 用的工具。 Claude-Mem 提供记忆层；你负责构建让记忆"产生意义"的那个东西。

从源码结构看，"观察者从外部旁观、永不干预"这句话有直接实现证据。plugin/hooks/hooks.json 注册了完整生命周期 hook：SessionStart（matcher 为 startup|clear|compact）负责启动时注入上下文（worker-service.cjs hook claude-code context）、PostToolUse（matcher 为 *，异步执行、120 秒超时）负责把每次工具使用交给 observer（hook claude-code observation）、Stop 负责回合/会话结束时的进度摘要（hook claude-code summarize）。observer 自身的全部"人设"写在默认模式文件 plugin/modes/code.json 的提示词里，其中有两条关键约束：

• SILENT BY DESIGN（默认为设计）：observer 会话在后台不可见地运行，被观察的会话不知道自己在被观察——"知道被观察的代理会以不可预测的方式改变行为，从而腐蚀你存在的意义所在的那份记录"；
• NO CONTACT（零接触）：observer 不得联系、ping、通知任何其他代理或会话，不生成子代理、不请求输入、不影响正在进行的任何工作。它是单向记录器：观察进来，XML 出去。

这解释了为什么原挑战文档反复强调"主代理永不等待 observer"——观察链路是异步旁路，observer 消失时 builder 照常干活，只是事后没有记忆。

二、七大赛道方向：逐个拆解，以及仓库里现成的技术底座

原文档给出七个方向（pick one, combine a few, or bring your own），以下逐条继承原文并补充仓库内可落地的实现入口。

方向 1：Warm Boot（温启动）

原文要求：让 agent 开局即拥有上下文，而不是烧掉前十个回合去重新发现代码库。并且必须测量：冷启动版本在有用了之前花了几回合？你的版本花几回合？把差异展示出来。

仓库中的对应实现是 SessionStart hook：会话开始（含 /clear 与 compact 之后）时执行 hook claude-code context，把该项目的近期笔记标题、ID、时间注入上下文——这就是"warm boot"。想在这个方向上做出成绩，可对比"有/无注入时间线"两种会话在同一任务上的回合数与 token 消耗，测量口径原文档已经替你定好了。

方向 2：Build on the Timeline（以时间线为检索层）

原文要求：把时间线 + memory-search 技能当作新东西的检索层。时间线是带 ID 的时序结构化笔记流——锚定任意一条，就能读出它前后发生了什么；搜索支持语义和关键词，可按项目、类别、日期过滤。原文的启发式问题是："如果把它当数据库，你会构建什么？"

仓库里这条链路有完整的技能文档：plugin/skills/mem-search/SKILL.md 定义了三层工作流（search → timeline → fetch），底层是 search、timeline、get_observations 三个 MCP 工具。这意味着参赛者的"新东西"可以直接消费这三个工具，而不需要碰存储层。

方向 3：Give the Skills a Face（给技能一张脸）

原文指出：仓库里的技能都是 CLI 形态（text in, text out），方向是包一层 UI/UX，让记忆变成可以看到、可以操纵、可以分享的东西——仪表盘、浏览器扩展、移动端视图、编辑或审批笔记的方式、把记忆交给队友的方式。

从源码结构看，项目已经自带了一个"雏形脸"：本地 viewer（plugin/ui/viewer.html，前端组件在 src/ui/viewer/）可以实时看到笔记落库、浏览并搜索。参赛作品可以以此为基线，做审批流、协作分享或移动端视图等差异化能力。

方向 4：Build an Integration（构建集成）

原文要求：把 Claude-Mem 接进它还不存在的地方——你的编辑器、CI 流水线、聊天应用、另一个 agent 框架或 harness。核心论点是"记忆在工作已经发生的地方最有价值"。

当前仓库已经演示了集成的形态：除 Claude Code 插件（plugin/hooks/hooks.json）外，还有 Cursor 适配（cursor-hooks/hooks.json）、OpenClaw 插件（openclaw/openclaw.plugin.json）、Grok bot（claude-mem-grok-bot/mcp.json）、Cowork（cowork/hooks/hooks.json），以及 MCP 服务入口 src/servers/mcp-server.ts。参赛集成的标准动作就是复用"MCP 工具 + 生命周期 hook"这套组合拳，接到一个新的宿主上。

方向 5：Ingest Anything, Look for Anything（万物可入，万物可查）

原文强调：观察记录不是纯文本——Claude-Mem 可以接收图片，所以截图、UI 截图、设计稿、白板照片与转录、日志、issue、提交历史、工单一样都是合法输入。自定义模式告诉 observer 该盯什么，"/mode-creator 会采访你并替你写好模式"。口号是 "Any data in, any pattern out"。

对应实现是 mode 体系：plugin/modes/ 下已内置 30+ 语言/领域的模式文件（code--es.json、code--ja.json、code--ar.json 等语言变体，以及 email-investigation.json、law-study.json、meme-tokens.json 等领域模式），手写模式的参考在 plugin/skills/mode-creator/references/mode-authoring.md，交互式的 /mode-creator 技能位于 plugin/skills/mode-creator/SKILL.md。

方向 6：Fire on What It Sees（对所见实时开火）

原文的核心是：观察记录在你的 agent 工作时实时落库。据此挂动作：某个模式出现就跑某件事——安全类笔记落库 → ping 频道；出现"decision"观察 → 开 ticket；同一个错误被观察到第三次 → 升级处理。目标是"对刚刚发生的事做出反应的代理，而不是等着被问的代理"。

这个方向在仓库里有现成的"事件类型"支撑：默认模式的类别表（plugin/modes/code.json 的 observation_types）中明确存在 security_alert（需要立即处理的安全问题）与 security_note（值得记录但不紧急的安全观察）两个类别，正好对应原文"安全笔记落库 → 通知"的例子；仓库中也存在可参考的通道集成，例如 src/services/integrations/TelegramNotifier.ts。参赛者的工作就是在这两类事件（或任意自定义类别）上做反应式接线。

方向 7：Memory as a Speed Play（把记忆当速度玩）

原文要求：用回忆（recall）削减 token、回合数或墙钟时间。标题优先（titles-first）的回忆模式据项目文档报告在启动上下文上约有 ~99% 的节省——要求你在此基础上再推进一步，测量并展示数字。这个方向的关键是"必须测量"，而三层检索的 token 账本（见下文第四节）就是现成的测量基线。

三、一条笔记（Observation）的解剖：从文档定义到数据模型

原文档对笔记结构的定义与仓库代码完全一致。观察记录的数据模型定义在 src/core/schemas/memory-item.ts（Zod schema），字段一一对应：

字段	是什么	经验法则（来自原系列文档的速记表）
Title（title）	一行：发生了什么	未来的代理通常只读这一行，让它承载含义
Subtitle（subtitle）	再多一行上下文	系统的哪个部分、什么情境
Facts（facts）	约 3 条单句要点（"语义块"）	每句话必须脱离上下文也成立，不含代词
Narrative（narrative）	一段短故事：过程与原因	需要全貌时读它
Category / Type（type）	模式中类别列表里的一个标签	如 bugfix · feature · refactor · change · discovery · decision
Tags / Concepts（concepts）	可复用的知识类型标签	如 how-it-works · why-it-exists · what-changed · problem-solution · gotcha · pattern · trade-off
Files（filesRead / filesModified）	读过的 / 改过的文件	下次跳去哪
Timestamp（createdAtEpoch）	自动	时间线得以成立的基础

schema 中还有一个值得注意的设计：kind 取值为 observation | summary | prompt | manual（memory-item.ts）——也就是说"观察"只是记忆条目的一种，会话摘要、用户 prompt、手工条目与观察共用同一套存储与检索通道。这解释了原文档速记里"Build on: timeline · search · skills · real-time observations · session summaries · modes"中为何会话摘要也在一列。

observer 如何"生产"这样的笔记？plugin/modes/code.json 的提示词给出了完整答案：

• 该记什么（recording_focus）：聚焦持久的技术信号——系统现在有什么不同、什么交付给了用户/生产环境、技术领域（auth、数据、UI、基础设施…）的变化、来自日志/追踪/队列/数据库的具体调试发现。用 "implemented / fixed / deployed / configured / migrated / discovered / confirmed / traced" 这类动词。反例被明确禁止：不得记录"分析了认证实现并保存了发现"这类描述观察过程本身的句子。
• 该跳过什么（skip_guidance）：空状态检查、无报错的包安装、无后续发现的简单列目录、已记录过的重复操作——跳过时只返回空响应，不解释为什么跳过。
• 输出格式：固定的 XML 结构，标题/副标题（最多 24 词）/事实/叙述/concepts（2–5 个，只能从固定关键词集合中选）/文件路径；概念里不得混入类型（type 与 concept 是正交的两个维度）。

速记表里那个示例笔记，正是这套规则的产物：

🔴 bugfix · 3:48 PM — 修复了陈旧 session cookie 导致的登录重定向循环 • 循环只在 cookie 超过 24 小时时才出现。• 修复方式是在重定向前清掉 cookie。• 逻辑在 auth 中间件里，不在登录页。 叙述：看起来像前端路由 bug，根因在服务端。 tags: problem-solution, gotcha

四、记忆如何回来：三层回忆机制（cheapest first）

原文档速记的回忆口诀是：titles first（标题优先）→ details by ID（按 ID 取细节）→ search for the rest（其余靠搜索），"永不一次性倾倒一切"。

完整的三层工作流写在 plugin/skills/mem-search/SKILL.md（"ALWAYS Follow"），且给出了每一层的精确参数与 token 预算，参赛者做"speed play"可以直接引用这些数字：

第 1 层：Search——拿带 ID 的索引（约 50–100 token/条）

search(query="authentication", limit=20, project="my-project")

参数：query（检索词）、limit（默认 20，上限 100）、project（项目过滤）、type（"observations"/"sessions"/"prompts"）、obs_type（逗号分隔：bugfix, feature, decision, discovery, change）、dateStart/dateEnd（YYYY-MM-DD 或毫秒时间戳）、offset、orderBy（"date_desc" 默认 / "date_asc" / "relevance"）。返回 ID、时间、类型、标题的表格。

第 2 层：Timeline——在锚点周围取上下文

timeline(anchor=11131, depth_before=3, depth_after=3, project="my-project")

参数：anchor（观察 ID，可省略；省略时可用 query 自动找锚点）、depth_before/depth_after（默认各 5，上限各 20）、project。返回锚点前后 depth_before + 1 + depth_after 条按时间交错的观察、会话与 prompt。

第 3 层：Fetch——只为过滤后的 ID 取全量（约 500–1000 token/条）

get_observations(ids=[11131, 10942])

参数：ids（必填数组）、orderBy、limit、project。技能文档特别强调：取 2 条及以上观察时永远用 get_observations 批量取——1 次请求代替 N 次。

技能文档给出的算账结论：先过滤再取全量，可获得约 10 倍 token 节省；而会话启动时的时间线注入（只有标题 + ID）则是方向 7 所引用的"~99% 启动上下文节省"的来源。两层数据合起来，就是参赛者做测量对比时的"冷/热基线"。

五、Modes：可替换的 observer 工作说明书

原文档说得很直白：mode = observer 的工作说明书，可替换。"同一套机器，不同的工作说明书 → 可以观察任何东西"。

一个 mode 就是一个普通配置文件，设定四件事（以 plugin/modes/code.json 为范本）：

1. observer 是谁（软件工程师的速记员？取证分析师？学习伙伴？）——即 prompts.system_identity / observer_role / recording_focus / skip_guidance 等提示词段；
2. 笔记类别（observation_types，如 bugfix/feature/… 或 entity/relationship/timeline-event/evidence/anomaly/conclusion）——每个类别带 label、描述与图标；
3. 该领域的标签（observation_concepts，如 how-it-works、gotcha、pattern）；
4. 语言——仓库 plugin/modes/ 下已内置 30+ 语言变体（code--es.json、code--ja.json、code--ar.json…）。

内置领域模式的示例光谱（继承原系列文档的表格）：

模式	observer 盯什么
code（默认）	bugfix、feature、decision、discovery
code--chill	只有"重新发现会很痛"的东西
email-investigation	人、组织、关系、时间线事件、异常
law-study	判例、规则、考试要点
meme-tokens	pump 信号、交易模式
robot monitoring	目标、状态变化、错误
你的模式	白板照片 · 会议转录 · 聊天日志 · 工单 · 日志 · 截图

不想手写模式？运行 /mode-creator（plugin/skills/mode-creator/SKILL.md）：它会采访你，然后替你写好、安装并激活该模式。这是方向 5（万物可入）的最低门槛入口。

六、评分规则、奖励与上手步骤

评分附加项（tiebreaker）（原文原话）：

任何条目，只要"确实有人会用"，都额外加分。 真实需求的精致演示，胜过虚构需求的巧妙演示。如果你周一早上还会继续用它，你就在正确的方向上。

奖励：1,000 美元现金。与总成绩的 1–3 名分开评审——两奖可以同时赢。

参赛环境准备（原文"Get set up"章节完整继承）：

• 每位黑客可获得 30 天免费 CMEM Pro：运行 npx claude-mem install 安装，然后在 cmem.ai 使用优惠码 FASTHACK30；
• 最快"上头"路径：安装 → 在一个项目里认真干一个会话的活 → 开启第二个会话 → 看顶部的时间线。然后打开 viewer，实时看笔记落库。（第一个会话是播种，第二个会话才是你"感觉到"记忆的时刻。）

七、Cheat-sheet 速记（原文档收官六条）

原文档最后用六条 bullet 收束全场，这里原样继承并给出对应仓库落点：

速记	含义	仓库落点
两个代理	builder 干活；observer 记笔记	plugin/hooks/hooks.json（生命周期旁路）
每次工具使用都送进 observer；它决定记 / 不记	PostToolUse hook，matcher *，异步	同上 PostToolUse 段
一条笔记 = 标题 + 副标题 + 单句事实 + 叙述 + 类别 + 标签 + 文件 + 时间	Zod 数据模型	src/core/schemas/memory-item.ts
回忆 = 标题优先（timeline）→ 按 ID 取细节 → 其余靠搜索	三层工作流 + token 账本	plugin/skills/mem-search/SKILL.md
Modes = observer 可替换的工作说明书：代码、邮件、照片、转录、机器人、万物	30+ 内置模式 + /mode-creator	plugin/modes/
可构建于： timeline · search · skills · 实时观察 · 会话摘要 · modes	七大赛道的公共底座	见上文各方向小节

适用前提与边界说明：本文所有机制描述以当前仓库快照为准；"100,000+ 开发者"与"~99% 启动上下文节省"均出自项目自身文档（plans/hackathon/04-the-memory-prize.md 及其系列文档）的口径，属于项目方数据而非独立测量值，做"speed play"方向时建议按原文要求自行实测对比。CMEM Pro 云服务为可选组件，纯本地使用时笔记存于本机，只有执行观察所用的 AI 模型调用会离开本机。