derekcedarbaum2/learnings-resurface

# 知识复现 **一项每周任务，重新阅读您的 AI agent 捕获的所有内容，并提取单个文件无法展示的模式。** ## 问题 大多数 AI agent 设置会捕获大量内容。会话记录会被自动保存。您会在会议后写下笔记。您录制语音备忘录。AI 会尽职地将它们放入正确的文件夹中。 **然后没有人——包括 AI——会再读它们一遍。** 因此，在两个项目中重复出现三次的模式仍然不可见。您在四次语音备忘录中陈述过的一项原则从未被提升为持久记忆。您在三周前的一次会话中做出的承诺被遗忘了，直到截止日期来临。系统拥有这些信息；只是没有*关联*起来。 解决办法是一项每周任务，*重新阅读* agent 捕获的所有内容——会话记录、按项目分类的持续笔记、语音备忘录——并寻找其中的模式。当相同的想法从多个来源的多个地方出现时，它就会被提升为持久的内容。当出现一次性的观察时，它会留在原处。当两个想法相互矛盾时，您会发现。 ## 它如何与相关 repos 配合使用 此技能是 [`ai-knowledge-system`](https://github.com/derekcedarbaum2/ai-knowledge-system) 记忆模式中的**第三个 3 级维护操作**，与两个手动操作并存： | 何时 | 操作 | 触发条件 | |---|---|---| | 每次有意义的聊天结束时 | `/archive-session`（在 `ai-knowledge-system` 中）— 每次会话的捕获 | 手动 | | 每 2–4 周 | `/distill`（在 `ai-knowledge-system` 中）— 在最近时间窗口上的定期跨会话整合 | 手动 | | **每周（周日晚上 10 点）** | **`learnings-resurface`（本 repo）** — 跨*整个累积语料库*进行聚类 + 分类，按类型路由 | **自动化 cron** | 前两个在单独的会话/最近的时间窗口上运行。这个运行在前两个建立起来的**完整语料库**上——因此只有当您运行它们几周后，它才会增加价值。如果没有积极的 `/archive-session` 习惯，这个技能就没有可以处理的内容。 它也是更广泛生态系统中三个“蒸馏”循环中的第三个。每个都重新阅读不同类型的输入： | 技能 / Repo | 重新阅读 | 来源 | |---|---|---| | [`note-highlight-indexer`](https://github.com/derekcedarbaum2/note-highlight-indexer) | *外部*内容 | 您阅读过的文章、书籍、推文（通过 Readwise） | | `voice-memo-process`（在 `claude-code-setup` 中） | *单个*语音备忘录 | 每日移动端捕获 | | **`learnings-resurface`（本 repo）** | *积累的内部*交互记忆 | 整个知识库中的会话存档 + `_learnings.md` + 语音备忘录 | ## 它的作用（技术细节） 每周一次（太平洋时间周日晚上 10 点），launchd cron 会触发 `learnings-resurface.sh`。运行器是一个**五步编排器**，将工作分解为有界限的阶段——大多数步骤是确定性的 bash；只有两个是 LLM 调用。每个 LLM 调用都在 `timeout 1800`（30 分钟挂钟时间）和 `--max-turns 80` 下运行，因此两者都不会拖过 API 流的空闲容忍度： ``` [bash] enumerate corpus → state/runs//enumerate.json [claude -p, ~10–15 min] Phase A: cluster + classify → state/runs//clusters.json [bash] pre-route guard (idempotency) → state/runs//clusters_filtered.json [claude -p, ~10–15 min] Phase B: route + log → state/runs//routed.json + actual writes [bash] finalize: merge run record + fingerprints → state/index.json + Vault/log.md ``` 如果阶段 A 或阶段 B 失败，中间状态会保留在磁盘上，运行可以恢复：`learnings-resurface.sh --resume --from-phase `。已完成的阶段将通过文件存在性检查跳过重新运行。 ### 每个步骤的作用 1. **枚举** *(bash, 无 LLM)* — 查找过去 N 天（默认为 90 天）的交互记忆： - 会话存档 (`Vault/AI Toolkit/CC Chat History/`) - 所有 `_learnings.md` 文件（不包括 `Personal/` 和雇主范围） - 语音备忘录 (`Vault/Voice Memos/`) - 跳过小于 500 B 的文件（空白脚手架）。 2. **阶段 A — 聚类 + 分类** *(claude -p)* — 提取原子（简短的属性信号单元；每个包含源文件、日期、项目背景、说话者/来源、类型猜测），按语义相似度进行聚类，应用阈值保护： - 丢弃少于 3 次提及的聚类。 - 丢弃少于 2 个不同人类来源的聚类（**来源多样性规则** — 您自己的三个语音备忘录说同一件事算作一个来源，而不是三个）。 - 丢弃所有来源都在同一周内的聚类（是回声，而非模式）。 - 按**时间衰减加权最近度**评分：每个原子贡献 `1 / (1 + days_old / 30)`。 - **产物类型 / 优化目标检查：** 只有当原子在*相同的产物类型*和*相同的优化目标*上操作时，它们才能聚类在一起。两个关于“多遍 QA 循环”的原子，如果一个针对营销文案（优化语调/真实性），另一个针对技能逻辑（优化健全性/缺口检测），则不属于同一个聚类。表面相似性不是标准。如有疑问，请分开。 阶段 A 还会检测原则/反模式聚类的矛盾——在现有记忆 + 语料库中搜索对立的陈述。浮现有争议的聚类供审查；**绝不自动使其失效**。输出为 `clusters.json`，包含每个聚类的 `fingerprint`（规范化标题 + 排序的源路径的 sha256）和预先解析的 `proposed_destinations`。 3. **预路由保护** *(bash, 无 LLM)* — Python 检查，丢弃提议的记忆文件已存在的聚类，或者其 fingerprint 已在先前运行的 `index.json` 的 `cluster_fingerprints` 中的聚类（除非提及次数超过了阈值）。这就是**以目标作为 fingerprint 的幂等性**，能在试运行和正式运行之间经受住 Opus 的不确定性。输出为 `clusters_filtered.json`。 4. **阶段 B — 路由 + 日志** *(claude -p)* — 应用 5 个上限，将多余的排队到 `Vault/raw-sources/_resurface-queue.md`，然后按类型路由每个聚类： | 类型 | 目标位置 | |---|---| | 原则 / 反模式 | 蒸馏到匹配的 playbook 中（通过 `auto-playbook-distill` 领域逻辑）。如果 `mentions ≥3` 且跨 `≥2 ventures` 浮现，则提升到 auto-memory Knowledge Router。 | | 状态 | 附加到相关 venture 的 `_learnings.md` Learnings 部分。不提升。 | | 承诺 | 如果操作员配置了任务管理器 MCP（Todoist / Linear / Things 等）并且定义了 venture → 目标位置的映射，则会在那里创建一个任务。否则（且总是），会在 venture 的 `_learnings.md` Key Decisions 表中追加一行。该技能在没有任何任务管理器集成的情况下也能完全工作。 | | 未决问题 | 附加到 venture 的 `_learnings.md` Open Threads 部分。 | 每个聚类及汇总行将写入 `Vault/log.md`。输出为 `routed.json`。 5. **最终确定** *(bash, 无 LLM)* — Python 将运行记录和新的聚类 fingerprint 合并到 `index.json` 中，将运行器级别的标记行写入 `Vault/log.md`。关闭运行。 ### 状态目录布局 ``` ~/.claude/state/learnings-resurface/ ├── index.json ← global state: last_run, runs, cluster_fingerprints └── runs/ └── / ├── enumerate.json ← bash output ├── clusters.json ← Phase A output ├── clusters_filtered.json ← bash guard output └── routed.json ← Phase B output ``` 这就是 *manifest + 幂等获取器* 模式——该运行器是此技能本身所提炼的确定性 vs 判断架构规则的工作示例（请参阅运行此技能的任何保管库中 `working-with-coding-agents.md` 的*架构*部分）。 ## 为什么大多数“记忆”系统会忽略这一点 捕获是容易的一半。大多数设置都有一个钩子，将会话记录写入磁盘并认为这就结束了。那只能给你一个语料库，而不是记忆。 困难的一半是**跨语料库的整合**。有三个属性很重要： 1. **跨来源聚合** — 一个在两个项目的三个不同会话中各出现过一次的原则，比在一个单独的语音备忘录中坚定陈述的原则更持久。如果不重新阅读所有内容，您是看不到这一点的。 2. **来源多样性** — 您自己的想法重述四次算作一个信号。一个 LLM 在监听单个人类的语音备忘录时，会对那个人类重复说的任何内容产生过高的置信度。多样性规则就是纠正措施。 3. **特定类型路由** — 原则、状态观察、承诺和未决问题都需要不同的归宿。将它们混淆是大多数“第二大脑”系统崩溃为单一无差别存储桶的原因。 此技能编码了这三个属性，外加尊重类别边界的矛盾检测。 ## 硬性规则（由技能强制执行） 1. **绝不重写或删除** `_learnings.md` 文件中的内容。仅限追加是保管库的不变量。 2. **绝不编辑** `Vault/Reading/`（Readwise 会覆盖它）。 3. **绝不编辑** `Vault/Personal/`。个人范围被排除。 4. **绝不包含雇主原始材料** 在跨项目聚类中。 5. **绝不自动使原则失效。** 矛盾仅供浮现审查。 6. **绝不捏造聚类。** 适用来源多样性规则（≥2 个不同人类来源）。 7. **绝不捏造引语。** 引用时必须逐字复述。 8. **绝不静默提升。** 路由器提升要求 `mentions ≥3` 且 `cross_venture: true`。 9. **上限：每次运行新增 5 个模式。** 超出部分排队等待。 10. **所有写入操作使用绝对路径**。 ## 本 repo 中包含什么 ``` learnings-resurface/ ├── README.md ├── LICENSE ├── skill/ │ └── SKILL.md ← The agent skill (Claude Code format) ├── runner/ │ └── learnings-resurface.sh ← Bash runner with concurrency lockdir ├── launchd/ │ └── com.user.learnings-resurface.plist ← macOS weekly cron config └── docs/ ├── classification-taxonomy.md ← Atom types + routing rules in detail └── adapting-to-other-vaults.md ← Notes for other knowledge-base layouts ``` ## 前提条件 运行器的预检会在执行任何工作之前验证以下所有内容，并在缺少某些内容时打印可操作的错误。如果您了解自己的设置，可以使用 `--skip-preflight` 跳过检查。 ### 必需（缺少这些会硬性失败） - **Claude Code** 已安装并在 `$PATH` 上（或设置 `CLAUDE_BIN_OVERRIDE` 环境变量）。 - **一个 Markdown 保管库**（Obsidian 或类似的）。运行器会自动发现 `$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/Vault/`（macOS 上的 Obsidian 默认路径），但任何路径都有效 — 设置 `VAULT_PATH` 环境变量以覆盖。 - **`python3`** 在 `$PATH` 上。运行器使用 Python 3 进行确定性的枚举 / 预路由保护 / 最终确定阶段（无 LLM 调用 — 只是快速的文件操作 + JSON 操作）。已在每台现代 macOS 和 Linux 发行版上安装。 - **[`ai-knowledge-system`](https://github.com/derekcedarbaum2/ai-knowledge-system) 已安装** — 提供 auto-memory + Knowledge Router 模式。该技能将路由器提升写入 `~/.claude/projects//memory/MEMORY.md`；如果该文件在任何地方都不存在，原则提升会静默失败。 - **[`vault-conventions`](https://github.com/derekcedarbaum2/vault-conventions) 已安装** — 提供此技能读取的 `_learnings.md` 模式（`## Learnings / ## Key Decisions / ## Open Threads`）和 `Vault/CLAUDE.md` 文件夹映射。没有它，追加内容会落在意想不到的地方或失败。 - **积累的内容。** 此技能跨 `_learnings.md` + 会话存档 + 语音备忘录进行聚类。如果您没有这些（例如，全新的 Obsidian 保管库），语料库将为空，该技能无事可做。**计划先进行大约 6 周以上的积极 Claude Code 使用。** 如果保管库中不存在任何 `_learnings.md` 文件，预检将会硬性失败。 ### 推荐（缺少这些会有软警告 — 可运行但功能减少） - **[`note-highlight-indexer`](https://github.com/derekcedarbaum2/note-highlight-indexer) 已安装** — 提供此技能调用的 `auto-playbook-distill` 技能，用于将原则/反模式路由到 playbook 中。还提供 `Vault/Playbooks-Index.md`（路由表）。没有它，原则聚类会路由到 `_resurface-queue.md`，而不是蒸馏到 playbook 主题文件中。 - **`archive-session.sh` SessionEnd hook**（来自 `vault-conventions`）— 填充位于 `Vault/AI Toolkit/CC Chat History/` 的会话存档。没有它，主要的语料库层（会话存档）将为空；该技能仅处理 `_learnings.md` 内容，这会稀疏得多。 ### 可选 - **任何任务管理器 MCP**（Todoist、Linear、Things、OmniFocus 等）— 用于承诺类型的聚类。如果您配置了一个，并且定义了 venture → 目标位置的映射（参见 SKILL.md "Reference: venture → task-destination mapping"），承诺将在那里创建任务。如果您没有，承诺只会退回写入 `_learnings.md` 的 Key Decisions。**该技能在没有任何任务管理器 MCP 的情况下也能完全工作。** - **`Vault/Voice Memos/` 目录** — 仅在您有语音备忘录捕获管道（例如，`claude-code-setup 中的 Monologue cron）时才相关。文件夹为空/缺失也没关系。 ### 配置覆盖 无需编辑脚本： ``` export VAULT_PATH="/path/to/your/vault" # if your vault isn't at the iCloud-Obsidian default export CLAUDE_BIN_OVERRIDE="/usr/local/bin/claude" # if claude isn't at $HOME/.local/bin/claude ``` ## 安装 (macOS) ``` # 1. 安装 skill cp -r skill ~/.claude/skills/learnings-resurface # 2. 安装 runner cp runner/learnings-resurface.sh ~/.claude/hooks/ chmod +x ~/.claude/hooks/learnings-resurface.sh # 3. 编辑 plist 的路径为你的用户名，然后安装 cp launchd/com.user.learnings-resurface.plist ~/Library/LaunchAgents/ launchctl load ~/Library/LaunchAgents/com.user.learnings-resurface.plist ``` 通过试运行验证： ``` ~/.claude/hooks/learnings-resurface.sh --dry-run --window 30 ``` 这会打印将要路由的内容而不写入任何内容。 ## 调优 | 旋钮 | 位置 | 默认值 | 何时更改 | |---|---|---|---| | 窗口（回顾天数） | `--window N` | 90 | 活跃期较短（30）；稀疏保管库较长（180） | | 每次运行的模式上限 | `SKILL.md` 硬性规则 9 | 5 | 如果您的保管库流量很大则提高；上限的存在是为了防止噪音洪流 | | 提及阈值 | `SKILL.md` 阶段 A.4 | 3 | 想要更多召回率时降低（2）；想要更多精确度时提高（5） | | 来源多样性阈值 | `SKILL.md` 阶段 A.4 | 2 个不同的人类来源 | 几乎从不更改 — 这是防回声保护 | | 提升阈值 | `SKILL.md` 阶段 B.3 | `mentions ≥3` 且 `cross_venture: true` | 如果您的路由器变得嘈杂，则收紧 | | 每阶段挂钟时间 | `runner/learnings-resurface.sh` `PHASE_TIMEOUT` | 1800 秒（30 分钟） | 仅在您的语料库非常大时提高；低于 900 秒会开始截断阶段 B | | 每阶段最大轮次 | `runner/learnings-resurface.sh` `MAX_TURNS` | 80 | 如果阶段 B 在有剩余待处理时截断，则提高 | ## 恢复失败的运行 如果某个阶段失败（网络波动、超时、瞬时错误），不会丢失任何内容 — 阶段 A 的聚类和阶段 B 的路由决定会在下一个阶段开始之前持久化到磁盘。从最后未完成的阶段恢复： ``` # 列出最近的运行 ls -lt ~/.claude/state/learnings-resurface/runs/ | head # 从 Phase B 恢复特定的运行（Phase A 的 clusters.json 已保留） ~/.claude/hooks/learnings-resurface.sh --resume 20260512-220015-12345 --from-phase B ``` 文件存在性检查确保已完成的步骤不会被重新运行。如果某次运行已成功完成，使用相同的 run-id 再次调用运行器将是一个空操作。 ## 这不是什么 - **不是基于聊天的“询问我的笔记”工具。** 它是一个写回的整合过程。输出会发送到 playbook、memory、`_learnings.md` 以及（可选）您的任务管理器 — 而不是一个对话式的答案。 - **不是实时的。** 每周 cron 是它所捕获模式的正确节奏。更快的运行会遗漏重复出现并过度路由噪音。 - **不是通用的。** 它假定一个带有按文件夹划分的 `_learnings.md` 的 venture-folder 保管库、一个 auto-memory Knowledge Router 以及一个用于 playbook 端的 `auto-playbook-distill` 技能。如果您的技术栈不同，请调整路由层。 ## 许可证 MIT.

标签：AI助手, AI智能体, Cron作业, Markdown, NLP, 个人知识库, 人工智能, 会话记录, 信息提取, 定期任务, 工作流自动化, 应用安全, 数据清洗, 数据聚类, 文本分析, 文本分类, 无数据库, 模式识别, 生产率工具, 用户模式Hook绕过, 矛盾检测, 知识沉淀, 知识管理系统, 自动化运维, 记忆检索, 语音备忘录整合, 跨文档分析, 防御加固