feat(seed): plant SKILL.md as a skill-track memory at setup time

[Shawn-Dong]

What this is

The redundancy layer for the bare-"uninstall memU" problem, complementary to #583 — same problem, different delivery channel.

#583 puts the routing in the push channel: the managed instruction block, unconditionally in context on every turn of an integrated host. This PR puts the packaged guide in the pull channel: setup plants the root SKILL.md into the store as a skill-track recall file, so a bare "uninstall memU" can surface it through retrieval — including on hosts whose instruction file was never patched, was hand-edited since, or belongs to an existing install that hasn't re-run install-instruction yet (the staleness gap #583 has on skill hosts). The two layers' failure modes are disjoint by construction.

How it works

• New module memu/hosts/seed.py: reads the packaged SKILL.md verbatim and commits it via commit_results. No rewriting: the document's own frontmatter is already the recall-file convention, and its description — the embedded retrieval surface — already carries the trigger words ("install, set up, integrate, remove, or uninstall memU"). The skill's author owns the retrieval surface, not the seeder.
• Committing through commit_results makes reseeding an upsert by (track, name) — a second install (same host or another sharing the store) refreshes the stored copy instead of stacking a twin.
• The ~/.memu/skill/ mirror is written too: the self-evolve loop works against markdown on disk, and a seeded file it cannot see is a file it would recreate or contradict.
• New host command memu-<host> seed-skills (all seven hosts get it), invoked in the install flow right after the doctor gate — the closest thing local mode has to "registration complete". Wired into claude_code/INSTALL.md as the reference host; the other six guides follow once the direction is settled.
• The wheel force-includes the repo-root SKILL.md as memu/SKILL.md; dev checkouts fall back to the repo-root copy. One source document, never a second copy that can drift.
• Small refactor: read_recall_file splits out parse_recall_text, so the seed parses with the mirror's own convention instead of growing a second parser.

Open questions (deliberately not resolved here — this PR is write-side only)

This PR makes the seed exist in the store; whether it gets found reliably is a retrieval-side question with three open decisions. None of them block the write side, and this PR is compatible with every outcome:

1. Hard rule or not — should a query containing "memU" force-include this file in retrieval results? Deterministic for gates 2–3 (semantic match + top-k), and it ships with the package so upgrades activate it everywhere at once. But it special-cases vendor content inside a neutral engine, false-positives on every memU-development query, and still can't fix gate 1 (the agent must run retrieve at all — only the inject seam reaches that). Leaning no until the data says otherwise.
2. Track semantics vs. recall stability — skill track is semantically correct (this is a procedure), and that's where this PR puts it. But skill-track recall is currently less stable than memory-track. We deliberately did not mislabel it into memory to game the ranking — that fixes a ranking problem by corrupting data.
3. Per-track quota balancing — a guaranteed minimum of skill-track results in top-k. This is the general fix: it serves every self-evolved skill, not just this seeded one, and once it lands the hard rule is likely unnecessary. Tracked as its own work item.

Known limitation, inherent to the design and left visible on purpose: the seeded copy is frozen at install time (refreshed only on reseed), retrieval is probabilistic until (3) lands, and an uninstalled machine keeps the seed in its retained store. This layer is a net, not a guarantee — the guarantee is #583.

Tests

Four in test_host_seed.py: the seed is the packaged document with its own frontmatter (including the embedded trigger words); planting writes mirror and store with an exact round-trip; reseeding overwrites in place; the CLI registers the command. Full suite: 209 passed. Wheel build verified to contain memu/SKILL.md.

---

这是什么

裸说「卸载 memU」问题的冗余层,与 #583 互补——同一个问题,不同的投放通道。

#583 把路由放进推送通道:managed instruction block,在已集成 host 的每个 turn 无条件在上下文里。本 PR 把包内指南放进拉取通道:安装时把根目录 SKILL.md 作为 skill track 的 recall file 种进 store,这样裸说的「卸载 memU」可以通过检索召回它——包括指令文件从未打过补丁的 host、之后被手动编辑过的 host、以及还没 re-run install-instruction 的存量安装(#583 在 skill host 上的真空期)。两层的失效条件在构造上互斥。

工作方式

• 新模块 memu/hosts/seed.py:读包内 SKILL.md 原样,通过 commit_results 提交。不做任何改写:文档自己的 frontmatter 本来就是 recall file 的格式约定,它的 description——被 embed 的检索面——已自带触发词("install, set up, integrate, remove, or uninstall memU")。检索面归 skill 的作者所有,不归 seeder。
• 走 commit_results 提交,重复 seed 是按 (track, name) 的 upsert——第二次安装(同 host 或共享 store 的另一个 host)只会刷新存储副本,不会堆出第二份。
• 同时写 ~/.memu/skill/ 镜像:self-evolve 循环的工作介质是磁盘上的 markdown,一个它看不见的 seed 文件,是一个它会重造或与之矛盾的文件。
• 新 host 命令 memu-<host> seed-skills(七个 host 全部获得),挂在安装流程 doctor gate 通过之后——本地模式里最接近「注册完成」的时刻。以 claude_code/INSTALL.md 为参考实现接线;方向确定后再铺其余六个指南。
• wheel 通过 force-include 把仓库根目录的 SKILL.md 打包为 memu/SKILL.md;dev checkout 回退读仓库根副本。单一真相源,不存在会漂移的第二份。
• 小重构:read_recall_file 拆出 parse_recall_text,seed 复用镜像自己的解析约定,不长第二个 parser。

待决问题(本 PR 刻意不解决——这里只做写入侧)

本 PR 让 seed 在 store 里存在;它能否被稳定找到是检索侧的问题,有三个待决事项。它们都不阻塞写入侧,且本 PR 与任何结论兼容:

1. 硬规则上不上——query 含 "memU" 时是否强制把这个 file 加进检索结果?它对第二、三关(语义命中 + top-k 排序)是确定性的,且随包分发、升级即全面生效。但它在 neutral 引擎里为厂商内容开特例,对所有 memU 开发类查询误触发,而且修不了第一关(agent 得先跑 retrieve——那一关只有 inject seam 够得着)。倾向先不上,等数据说话。
2. track 语义 vs 召回稳定性——skill track 语义正确(这就是一个 procedure),本 PR 也放在那里。但 skill track 目前召回不如 memory track 稳。我们刻意没有为了博排序把它错标进 memory——那是用污染数据的方式修排序问题。
3. per-track 配平——top-k 里保证 skill track 的最小名额。这是通用修法:它服务所有 self-evolve 萃取出的 skill,不只这一个 seed;配平落地后,硬规则大概率不再需要。作为独立工作项跟踪。

设计固有、刻意保持可见的已知限制:seed 副本冻结在安装时刻(只在重新 seed 时刷新)、在 (3) 落地前检索是概率性的、卸载后保留的 store 里 seed 仍在。这一层是兜底网,不是保证——保证是 #583。

测试

test_host_seed.py 共 4 个:seed 是带自身 frontmatter 的包内文档原样(含被 embed 的触发词);种植同时写镜像和 store 且精确 round-trip;重复 seed 原地覆盖;CLI 已注册该命令。全量测试:209 通过。wheel 构建验证含 memu/SKILL.md。

🤖 Generated with Claude Code