Claude-Mem Hackathon Kit 深度解析：用一套幻灯片与六步教程讲清 Agent 记忆系统，冲刺 $1000 Memory Prize

本篇技术指南以本仓库中的黑客松工具包（hackathon kit）为核心，系统拆解其组织方式、全部演示资产、底层技术叙事与参赛框架。你将掌握：Claude-Mem"双 Agent 记忆层"的完整工作机制（observer 观察、结构化笔记、三层召回、可换 Mode）、一套可复现的演讲素材组装方案、已知的渲染缺陷清单，以及围绕"构建真正会记忆的 Agent 工具"设计的 $1,000 Memory Prize 七大赛道与评分逻辑，并能在仓库中找到每一份对应源码与配置文件作为证据。

一、工具包是什么：一份"黑客松参赛资产"的总纲

仓库 plans/hackathon/ 目录下的 README.md 本身是一份活动组织总纲，面向 2026-08-23 周日的一场黑客松，其中存在一条独立于总排名 1–3 名、单独评审、奖金 $1,000 的 Memory Prize（记忆奖赛道）。这份 README 的价值在于：它不是一篇普通项目文档，而是一套把 Claude-Mem 的记忆系统从"技术"转化为"可以演讲、可以教、可以参赛"的完整内容管线的索引。

它把全部资产划分为五类，且每类都落盘在本仓库中，可反复取用、修改与再生成：

资产类别	用途	仓库内文件
主叙事（Field Guide）	最全的单份讲解，覆盖一切	01-what-is-claude-mem-field-guide.md（约 3.2k 词）+ Story 版幻灯片 PDF（15 页）
图文册（Picture Book）	现场演讲，每页一个观点、极简文字	幻灯片 PDF（12 页）
速查表（Cheat Sheet）	发放给观众、可平铺扫读的参考	02-claude-mem-cheatsheet.md + 幻灯片 PDF（14 页）+ 可打印一页纸 claude-mem-cheatsheet.html
教程（Tutorial）	"照做→会看到→意味着什么"的分步走查	03-claude-mem-tutorial.md + 幻灯片 PDF（9 页）
奖品文案（Memory Prize）	每个赛道一页的参赛提案	04-the-memory-prize.md + 幻灯片 PDF（13 页）

二、为什么要为"讲清记忆"做五套不同素材

Claude-Mem 是一个开源记忆层：为 AI 编码 Agent 提供跨会话的持久上下文——捕获 Agent 在会话中的全部行为、用 AI 压缩为观察记录、并在未来会话中把相关上下文重新注入。据该项目宣讲材料称其已被 10 万+ 开发者使用。

要在一场黑客松里向素未谋面的评委快速讲清这样一套系统，单份 PPT 是不够的，因为听众的注意时长和目的各不相同。README 的素材分工恰恰解决了这个问题：Story 版（15 页）信息密度最高，适合"完整讲一遍"；Picture Book 版（12 页）每页只讲一个观点，适合现场演讲；Cheat Sheet 版（14 页）做成可平铺的 handout；Tutorial 版（9 页）按"操作→现象→含义"驱动走查；Memory Prize 版（13 页）则围绕七个赛道逐页 pitch。

而真正支撑这五套演示的，是"源文档"里那套深入浅出的技术叙事。下面按叙事顺序还原这套核心内容，这也是你要写进任何一页幻灯片的骨架。

三、叙事起点：Agent 失忆的三笔真实代价

工具包把问题定义为"失忆工程师"：一个异常聪明、但每天早晨都彻底失忆的工程师。每次开工都要重读文件、重新发现结构、重复问你已回答过的问题，甚至重试你已证明行不通的方案。今天的 AI 编码 Agent 正是如此——会话内聪明绝顶，会话一结束就回到空白状态。它带来三笔代价：

1. 时间：每次会话冷启动，Agent 前几轮都花在"重新发现自己昨天已知的东西"上；
2. 金钱：重新发现 = 重读文件 = token 消耗 = 真金白银，Agent 大量花销其实是在"重学已学过的东西"；
3. 决策丢失：最痛的并非慢启动，而是被遗忘的推理过程——"我们当时为什么这么做？"答案曾存在，却没人写下来，于是永远消失。

Memory Prize 赛道与整套演示的立意都在于此：解决方案不是把上下文窗口无限做大，也不是把所有内容塞进 prompt，而是"make memory matter"——让记忆真正发挥作用。

四、核心机制：一个建房者加一个旁观的书记官

工具包用一张极其朴素的图解释核心洞察（源自 Field Guide 第三部分）：主 Agent（builder）负责读文件、改代码、跑命令、做决策；而 Claude-Mem 在旁边放了第二个 Agent——observer（观察者）。它不写代码、不和你说话、不打断主 Agent，唯一的工作是对每一次动作提出同一个问题：

"这件事值得记下来吗？"

大多数时候答案是不：随手查一个文件、跑一条无果的命令，都不记。但当答案是"是"——修好一个 bug、做出一个决策、发现意外、上线一个功能——observer 就写一条结构化笔记。若 observer 崩溃，主 Agent 会照常工作，只是事后不再有任何记忆。

五、生命周期接入点与本地存储：Claude-Mem 如何"旁观"

observer 靠的是 Agent 环境暴露的"生命周期时刻"（见 Cheat Sheet 第 4 节）：

时刻	Claude-Mem 做什么
会话开始	注入时间线：最近观察的标题、ID、时间、类别图标，即"温启动（warm boot）"
每一次工具调用后	把"动作 + 结果"交给 observer，由其判定记 / 不记
一轮结束 / 会话结束	observer 写一段简短进度总结：进展到哪、下一步是什么

仓库中确实存在这套钩子的落地实现：plugin/ 下是构建产物，安装后进入 ~/.claude/plugins/marketplaces/thedotmack/，其 hooks.json 负责注册监听；数据全部落在本机 ~/.claude-mem/（主库 claude-mem.db 与语义检索索引 chroma/），这一存储布局在仓库根目录 CLAUDE.md 中有明确记载。除调用做观察的 AI 模型外，数据不出本机；README/宣讲稿中提及可选的 CMEM Pro 云端同步（黑客松参与者可按宣讲稿中的试用码换取 30 天试用，详见 Tutorial 结尾）。此外还有一个本地 viewer 网页，可实时看到笔记落地、按项目浏览与搜索。

六、一条笔记的解剖：8 个字段与源码中的真实定义

工具包把笔记称为 observation，强调其固定结构——"结构就是用途"，因为统一结构才让笔记可检索、可速读、可廉价回传。每条观察固定包含：

字段	内容	经验法则
Title（标题）	一行，讲清发生了什么	未来 Agent 通常只读这一行，必须让标题自带全部意义
Subtitle（副标题）	再一行上下文	属于系统的哪一部分、当时情境
Facts（事实）	约 3 条单句要点（语义块）	每句脱离上下文单独成立
Narrative（叙事）	一小段：经过、尝试、学到、为何重要	需要全貌时再读
Category（类别）	取自 Mode 固定列表的单一标签	bugfix / feature / decision 等
Tags / Concepts（标签）	可复用的知识类型	how-it-works / gotcha / problem-solution 等
Files（涉及文件）	读了哪些、改了哪些	下次直接跳转到正确位置
Timestamp（时间戳）	自动记录	使时间线成为可能

这条"笔记解剖"不是纸上谈兵，plugin/modes/code.json 就是它的落地定义：默认代码模式的 observation_types 共 9 种——bugfix（坏了又修好）、feature（新增能力）、refactor（重构不改行为）、change（文档/配置等一般改动）、discovery（对既有系统的认知）、decision（带理由的架构决策），另加 security_alert、security_note、sensitive 三类安全相关观察；observation_concepts 定义 7 个知识型标签：how-it-works、why-it-exists、what-changed、problem-solution、gotcha、pattern、trade-off。文件内同时写死了给 observer 的提示词纪律：观察必须"记录学到/建成/修好的东西"，而非"记录观察过程本身"；type 与 concepts 是两套正交维度，concepts 只允许 2–5 个裸关键词。

工具包给出的"一看就懂"示例（登录重定向死循环）长这样：

bugfix · 3:48 PM —— Fixed login redirect loop caused by stale session cookie • 只有会话 cookie 超过 24 小时才会死循环。 • 修复方式：重发登录重定向前先清掉 cookie。 • 逻辑在 auth 中间件里，不在登录页。 叙事：症状看着像前端路由 bug，根因在服务端。tags: problem-solution, gotcha · files: middleware/auth.ts

七、记忆如何廉价回流：先标题、再详情、按需取

如果每次会话开头都把所有笔记全文塞进上下文，预算瞬间爆掉。所以 Claude-Mem 采用先便宜后昂贵的分层回流（Tutorial Stage 3–4 中的核心图景）：

1. 第 1 层 · 时间线（每会话自动）：只注入 ID + 时间 + 类别图标 + 标题，约 50 条近期笔记只花几百 token，Agent 扫一眼标题通常就够了；
2. 第 2 层 · 按 ID 取详情（按需）：标题看起来相关，Agent 用 ID 单独拉取该条笔记的事实、叙事与文件，只为真正需要的内容付费；
3. 第 3 层 · 搜索（时间线覆盖不到的旧内容）：按语义、关键词、类别、日期、项目全局搜索，先返回标题，再筛选、再拉详情。

仓库的 mem-search skill 把这条纪律固化为"三步工作流"：search（返回带 ID 的标题表，每条约 50–100 token）→ timeline（锚定某条结果，读取其前后发生的 3–5 条内容）→ get_observations（只对筛出的 ID 批量取全文，每条约 500–1000 token）。其 frontmatter 描述就写着：当用户问"我们修过这个问题吗""上次 X 是怎么做的"时启用，并强调"先筛选再取详情，可省 10 倍 token"。

Tutorial 中给出一条极具说服力的启动上下文示例，统计行把整个价值主张压缩成一行：

# [claude-mem] recent context
Mode: Code Development (code)
Stats: 50 obs (17,530t read) | 1,324,849t work | 99% savings

50 条观察、约 1.75 万 token 即可读，背后却对应约 132 万 token 的真实工作量——笔记是巨量工作的压缩索引，Agent 只解压需要的部分，即"标题先行、按需详情"，这是记忆始终廉价的原因。README 中的多次论述（Cheat Sheet 第 7 节、Prize 方向 7）都在强调约 99% 的启动上下文节省。

八、Mode：observer 的"岗位说明书"是可换的

工具包最富创作空间的概念是 mode（模式）：一份纯配置 JSON 文件，只需定义四件事：

1. observer 是谁（软件工程师的书记官？取证分析师？法学生的学伴？）；
2. 笔记类别是什么（代码模式是 bugfix/feature/decision；邮件取证是 entity/relationship/timeline-event/evidence/anomaly/conclusion；机器人监控是 action-goal/state-change/error）；
3. 标签（概念）有哪些；
4. 用什么语言写（开箱即用 30+ 语言变体）。

"换掉 mode = 同一套机制观察完全不同的东西"，这是"任何数据进、任何模式出"的根基。仓库 plugin/modes/ 目录印证了这份多样性：

• code.json——默认代码模式；
• code--chill.json——更克制的代码变体，只记录"难以重新发现的痛苦之事"；
• 30+ 语言变体（code--ja、code--es、code--ar、code--zh、code--de 等一应俱全，文件名即 code--<locale>）；
• email-investigation.json——RAGTIME 式邮件欺诈调查：类别是 entity/relationship/timeline-event/evidence/anomaly/conclusion，标签则换成 who/when/what-happened/motive/red-flag/corroboration，提示词要求"每条观察原子化、一封邮件可拆出 3–5 条观察、人名一律用 'Full Name [e-mail]' 格式"；
• law-study.json 与 law-study--chill.json（法学生学伴，记录判例/规则/考试要点）、meme-tokens.json（代币交易信号）。

不用手写？/mode-creator 技能会以访谈形式向你提问（你在观察什么、什么值得记、类别该怎么定），然后写好、安装并激活 mode。仓库里的 mode-creator/SKILL.md 展示了完整流程：先问"你在做什么工作"而不是直接索要 JSON 字段 → 让用户给出 3 个下周还想找到的时刻与应跳过的日常 → 用交互工具确认 4–8 个互斥观察类型与 4–8 个标签 → 通过 install-mode.mjs（带 --dry-run 校验）写入 <data-dir>/modes/ 并设置 CLAUDE_MEM_MODE → 重启 worker → 用 session_start_context 验证启动上下文出现 Mode: <name> (<id>) 行。其内部还支持按类型/标签触发 Telegram 告警，安装时一律先备份、可回滚。

这套"可换岗位"也意味着观察对象不必是代码：白板照片、会议转录、Slack 导出、邮件堆、日志、issue、提交历史、客服工单都可以——只要 Agent 能读，observer 就能记，mode 决定"什么值得记"。

九、可被二次开发的积木：在记忆层之上造东西

工具包刻意强调"所有零件都小而暴露、可组合"：

• Timeline：带 ID 的有序笔记流，可锚定任意一条、读取其前后语境，适合当检索层；
• Search：跨全部历史的语义 + 关键词检索，可按项目 / 类别 / 日期过滤；
• Skills：仓库里一批 CLI 形态的助手（文本进、文本出），包括 mem-search、timeline-report（生成"项目旅程"报告）、knowledge-agent（基于观察历史构建可问答的知识库）、mode-creator、how-it-works、learn-codebase、make-plan / do 等——CLI 形态意味着易被包进 UI、编辑器、聊天机器人或 CI 任务；这些技能在仓库中均有落地目录（plugin/skills/）与 plugin/skills/*/SKILL.md；
• 实时观察：笔记在 Agent 工作过程中即时落地，因此"某个模式出现 → 某个动作被触发"成为可能；
• 会话摘要：每次会话结束，observer 写下"进展到哪、接下来做什么"的交接笔记，供下个会话续接。

十、六阶段上手教程：从安装到"它记得了"

Tutorial 把上述机制编排为可在一次坐下来完成的 6 个阶段，每步都遵循"做什么 → 会看到什么 → 意味着什么"：

1. 安装（2 分钟）：执行 npx claude-mem install。安装器会配好插件与一个小型后台服务，并检查它所依赖的两个助手（一个快速的 JS 运行时和一个提供 Python 的包管理工具，用于支撑语义检索索引），缺失时自动安装；
2. 第一次被观察的会话（5 分钟）：正常干活即可——主 Agent 行为毫无变化，这正是设计意图；所有读取/编辑/命令都被交给 observer，有趣的才落笔记。可选：打开本地 viewer，放在第二屏实时看笔记出现，这是"秒懂"的最佳方式；
3. 温启动（2 分钟）：结束会话，在同一项目开新会话，顶部会出现一段"recent context"时间线块——第一个会话"播种"记忆，第二个会话你才"感觉到"它；试着用大白话问"我们上次在 auth 流程改了啥"，Agent 会从时间线或按 ID 拉详情作答；
4. 搜索过去（3 分钟）：问"我们修过重定向死循环吗""上周测试库怎么搭的"，Agent 走 search → timeline → fetch-by-ID 三步；
5. 换观察目标（5 分钟）：/mode-creator，把 observer 指向白板照片、会议转录或聊天导出等非代码对象；
6. 该造什么（阅读，不动手）：理解 timeline / search / skills / 实时观察 / 会话摘要 / modes 这些抓手。

工具包还附了一段"一口气排障"：看不到时间线？它从项目第二个会话才开始（或先用 /learn-codebase 一次预载整个仓库）；想确认当前 mode？看启动上下文顶部的 Mode: 行；数据在哪？~/.claude-mem，卸载可干净移除。

十一、$1,000 Memory Prize：赛题与七个赛道

README 交代了赛制要点：由 Claude-Mem 赞助，与总排名 1–3 名分开评审（可同时获奖），奖金 $1,000。赛题一句话：

构建一个真正会记忆的 agentic 工具。 不是"窗口更大的 Agent"，不是"把所有东西塞进 prompt 的 Agent"——而是保留重要的、在相关时能找到的、并据此比上一次更快更聪明的 Agent。

七个方向可任选其一、组合几条或自带新方向：

#	方向	要点
1	Warm boot 温启动	开局即带即时上下文，而不是烧掉前十轮去重新发现代码库；量化对比冷启动与你的方案所需的回合数
2	Build on the timeline 基于时间线	把时间线 + 记忆搜索技能当作检索层，"如果你有了这个数据库，你会造什么？"
3	Give the skills a face 给技能一张脸	技能是 CLI 形态（文本进文本出），包上 UI/UX 让记忆可看、可操控、可分享：仪表盘、浏览器扩展、移动视图、编辑/审批笔记、把记忆交接给队友
4	Build an integration 构建集成	把 Claude-Mem 接到它尚未存在的地方：你的编辑器、CI、聊天应用、另一个 Agent 框架或 harness——记忆在"工作发生的地方"价值最高
5	Ingest anything, look for anything 摄入一切、寻找一切	观察不止文本：截图、UI 采集、设计文件、白板照片、转录、日志、issue、提交历史、工单都算；自定义 mode 告诉 observer 看什么
6	Fire on what it sees 见机行事	观察实时落地，据此挂接动作：安全笔记出现 → 通知频道；"决策"类观察出现 → 开 ticket；同一错误被观察三次 → 升级处理
7	Memory as a speed play 记忆即提速	用回忆削减 token、回合数或墙钟时间；"先标题后详情"已报告约 99% 启动上下文节省，可继续推进并量化展示

评分上加分铁律（README 与 Prize 文案一致强调）："一切按'是否真的会有人用它'额外加分"——一个真实需求的精致 demo，胜过想象需求的花哨 demo；"如果你周一早上还会用它，就走在正确的路上"。

十二、把工具包变成 15–17 页演讲：精选组装清单

README 直接给出了一条推荐的"精华版组装路线"（约 15 张幻灯片），把 Story / Picture Book / Cheat Sheet / Prize 四套素材按叙事动线穿插，覆盖"问题→机制→笔记→召回→Mode→可造积木→赛道→冷启动开场白"的完整弧线：

#	素材（套件 + 页码）	看点
1	Picture Book p1–p2	健忘的工程师：每个早晨都是"第一天"
2	Story p3	三笔代价：时间 / 金钱 / 丢失的决策
3	Story p2	builder vs observer 分工展开图
4	Story p5	每个动作 → "这值得记吗？"
5	Picture Book p6	漏斗：只有"aha 时刻"被留下
6	Story p6	笔记解剖（发光笔记本意象）
7	Cheat Sheet p6	笔记解剖（干净、准确的实例）
8	Story p8	标题先行、详情按需
9	Cheat Sheet p8	三层召回
10	Story p9	observer 的岗位说明是可换的
11	Story p10	照片 / 转录 / Slack 导出 → 结构化笔记
12	Cheat Sheet p10	现有 mode + /mode-creator
13	Cheat Sheet p11	可构建的积木
14	Prize p3	"让记忆发挥作用"（不是更大的上下文，不是塞满）
15	Cheat Sheet p13 或 Prize p4–p10	七个赛道
16	Prize p11	"周一早晨测试"
17	Story p14	五分钟上手 + 试用码

这 17 页涵盖了从"为什么要做"到"你来做什么"的完整说服链，是快速开讲时的首选装配。若只做一个手边速查，则可打印的 claude-mem-cheatsheet.html（单页）与 Cheat Sheet 的"词汇表"即可满足——observer、observation、tool use、timeline、mode、skill、session summary、warm boot 八个词各一句话。

十三、已知渲染缺陷与低成本再生成机制

README 诚实记录了一份使用 NotebookLM 生成幻灯片时的渲染缺陷清单，属于演示物料维护的一手经验，制作衍生 deck 时应直接避雷：

• Story p7："context. context." 出现重复；p13："Claude-Mem rrropers"（应为 "developers"）；
• Picture Book p2："the the same files"；p12："100,000 100,000 developers"（数字与单词重复）；
• Cheat Sheet p3：builder 卡片布局略有错乱；
• Tutorial / Prize：干净无缺陷。

由于每套 deck 的源文档与 NotebookLM notebook 均已保留（README 中登记了 Story、Picture Book、Cheat Sheet、Tutorial、Prize 五份 notebook 的 UUID），再生成任何一套 deck 的成本都很低：把 notebook 与源文档喂回去、微调 prompt 重新跑一遍即可。

十四、在本仓库中如何使用这套工具包

这套材料全部落在 plans/hackathon/ 下，任何想要自办"记忆主题"黑客松、做技术分享或参赛的人都可以直接复用：

1. 讲清原理：先读 01-what-is-claude-mem-field-guide.md（最全叙事），配合仓库中的两个 JSON mode 定义（code.json、email-investigation.json）对照讲解字段与提示词纪律；
2. 动手体验：执行 npx claude-mem install，按 03-claude-mem-tutorial.md 走完六阶段；数据落在本机 ~/.claude-mem/，通过 viewer 观察实时笔记；
3. 现场演示：取第 12 节的 17 页组装清单，从五套幻灯片 PDF 中挑页组合；
4. 进阶定制：研究 mem-search/SKILL.md 的三层召回参数与 mode-creator/SKILL.md 的安装/激活/验证全流程，即可朝七个赛道中的任何一个动手。

---

一句话回顾整条内容管线：问题（失忆的三笔代价）→ 方案（builder + observer 双 Agent）→ 数据（八字段结构化 observation）→ 回流（时间线 → 按 ID → 搜索的廉价分层）→ 泛化（可换的 mode）→ 扩展（timeline / search / skills / 实时观察 / 会话摘要）→ 参赛（七个方向的 $1,000 Memory Prize）。这套黑客松工具包的可贵之处在于：同一套技术事实被编排成五种深度与节奏各异的演示，还附带了可直接执行的演讲稿、已发现的渲染坑、可再生成的 notebook 源——它就是"把记忆系统讲明白"这份工作的可复现模板。