记忆与技能

内置 agent 每个会话都从头开始，所以它的连续性来自醒来时读的两份文件 —— 一份记录持久事实的记忆，和一份教它怎么驱动某个具体 app 的技能。记忆是它知道的；技能是它能做的。两者都以纯 Markdown 存在磁盘上，所以你可以手动读、改，或者预先给它喂料。

记忆：什么会跨会话带走

一个会话就是一次醒来 —— agent 因一个 trigger 而活过来、做完任务、退出。它脑子里的东西没有一样能活到下一次醒来。能活下来的，是 ~/.physiclaw/memory/ 下的三个文件：

• 文件夹~/.physiclaw/memory/

  • USER.md your profile — curated by you, read-only to the agent
  • memory.md durable facts, one per line
  • 2026-06-22.md that day’s activity log, [HH:MM] … per line
  • 2026-06-21.md
  • …

每个文件各司其职：

文件	装的是	谁来写
USER.md	你是谁、你的偏好、你的默认设定	你
memory.md	agent 学到的、该留着的事实	agent（追加 / 编辑）
YYYY-MM-DD.md	它当天所做之事的带时间戳日志	agent（追加）

每次醒来，agent 的系统提示里都已经含着 memory.md 和你的 USER.md —— 它们小而扎实，所以自动加载。每日日志更大，所以默认只带上最近约 10 条；当某个任务需要更早的历史时，agent 再用 read_logs 按需拉取更深的窗口。

为什么把”事实”和”日志”分开？

memory.md 回答*“什么是真的？”* —— 你的地址、你偏好燕麦奶、你买的尺码。每日日志回答*“发生了什么？”* —— [14:02] jd: cart → checkout — added 2× oat milk ¥39。事实是无关时间且寥寥几条的；日志是一卷滚动的磁带且数量众多。把它们分开，意味着总被加载的那部分（事实）保持极小，而按需召回的那部分（日志）可以增长而不撑大每一次提示。

agent 怎么写记忆

这些你都不用操心 —— agent 一边干活一边自己维护记忆：

• 你说”记住 X” → 它往 memory.md 追加一行。
• 你改了一个偏好 → 它就地编辑对应的那一行。
• 它完成了一个有意义的步骤 → 它往今天的日志追加一行，形如 [HH:MM] app: page → page — what it did。正是这些逐步日志，让未来的一次醒来能从一个半完成的任务里恢复：它能读日志、看见购物车里已经有两件商品，从那儿接着干。

USER.md 是例外 —— agent 只会读它。那个文件归你打理，正是放置那些你想从第一个会话起就被尊重的长期偏好的好地方。

在你的第一个真任务之前先喂料

把你的要紧事项一上来就写进 USER.md —— 姓名、地址、你用哪些 app、硬性规矩（“绝不从 X 下单”）。agent 每次醒来都读它，所以一份好的档案能省得它反复追问、也省得它猜错。

技能：教 agent 新本领

记忆是 agent 知道的。一个技能是它能做的 —— 一个自成一体的文件夹，教它某个 app 或某类任务的确切工作流。开箱即用时它能点屏幕；一个技能把”点屏幕”变成”在这个特定 app 上、用对的方式下一单生鲜”。

一个技能就是一个根目录下有 SKILL.md 的目录：

• 文件夹~/.physiclaw/skills/

  • 文件夹jobs/

    • SKILL.md frontmatter (name + description) + the workflow
  • 文件夹jd/

    • SKILL.md
    • 文件夹references/ deep detail, loaded only when needed

      • …
    • 文件夹assets/ freeform files a reference can point at

      • …

会扫描两个位置：~/.physiclaw/skills/（主目录，这样装好的 agent 不用 checkout 仓库就能找到它的技能）和相对于运行位置的 ./skills/（你迭代时很方便）。要是两处都定义了同名技能，主目录那份胜出。

一个技能怎么被发现、被加载 —— 三个层级

技能是渐进式加载的，这样一台装满技能的手机不会淹没提示。agent 只为它真正打开的细节买单：

1. 元数据 —— 醒来时，每个技能的 name 和一行 description 被注入系统提示。那行描述是 agent 唯一能用来判断一个技能是否相关的信号，正因如此，描述要写成具体的触发条件 —— “何时用…；不要用于…” —— 而不是含糊的简介。

2. 工作流 —— 当一个任务匹配上，agent 调用 Skill(name="jd")， 拿回完整的 SKILL.md 正文：要遵循的逐步流程。这是那个 app 的章法 —— 它的搜索框、它的结账流程、它的坑。

3. 参考资料 —— 对于罕见的细节，正文会指向一个参考文件，agent 调用 Skill(name="jd", reference="checkout.md") 按需把它拉进来。大多数任务永远到不了第 3 层。

这套分层，正是为什么一个搭建者能不停加技能而不拖慢 agent。装十个技能，在提示里只花十行单行描述 —— 而不是十套完整工作流。

描述是承重的

描述写得弱的技能，哪怕它正是对的工具也会闲置着，因为 agent 永远看不到打开它的理由。当你写或装一个技能时，把功夫花在描述上：点名那些该触发它的 app、动词、说法 —— 以及那些不该触发它的情形。

例子：jobs 技能

内置的 jobs 技能很好地示范了一个技能长什么样。它的活儿是排定未来的工作，它的描述精确地点名了何时该用它：

Use when the task involves scheduling future work — any "remind me at …",
"every weekday …", "check again in 30 min", or closing a fired cron job.
… NOT for one-off in-session waits. NEVER edit jobs.md by hand.

正文接着教那套工作流：排定的工作住在一个严格、机器解析的 jobs.md 里，所以这个技能禁止直接编辑那个文件，把每一处改动都引到一个带四个子命令的 CLI 上 —— create、list、get、finish。agent 读到这些，学会安全地排一个提醒，从此再不必去逆向那个文件格式。这就是每个技能的套路：把一件事的正确做法编码一次，往后每个会话都继承它。

agent 自主那一面也是靠技能运转的 —— 正是 jobs 技能让它能设置 自主任务 里讲的那些 cron 和 poll trigger。

技能在醒来时被快照

agent 在会话开始时捕获每份 SKILL.md 正文；会话中途改一个技能，要到下次醒来才会改变行为。这是有意为之的 —— 它让提示里被缓存的那部分逐字节稳定，于是模型不会在每个回合为一段没变的前缀被重复计费。