Agent Home 智能体之家

要解决的问题 #

智能体的状态散落在框架的数据库、厂商托管的记忆接口和随时会消失的沙箱磁盘里。换一个框架或厂商，状态就丢；出了问题，也没有一个地方可以“看一眼它到底知道什么”。

与此同时，主流智能体已经在向文件收敛：AGENTS.md、Agent Skills、以 Git 为后端的记忆仓库。缺的不是新格式，而是一个有归属、有历史、有配额、可导出的地方来放它们。

工作方式 #

• 布局遵循开放约定。 AGENTS.md、Agent Skills 的 SKILL.md、带 YAML frontmatter 的 Markdown，如下面的草图所示。我们不发明新格式。
• Home 属于角色，不属于某一次运行。 运行通过分支使用它：改动先落在分支上，再经审阅合并回 Home。
• 带历史。 每次改动都是一次提交。nas export 或 git clone 就能带走整个 Home，包括 .nas/ 里的纯文本元数据。
• 启动上下文就是读几个文件： AGENTS.md、memory/MEMORY.md、收件箱摘要。没有专门的“醒来协议”；NAS 可以提供一个有 token 上限的 briefing 视图作为便利，但不是必需。
• 已审阅才自动加载。 只有被标记为 reviewed 的笔记才会进入 MEMORY.md 和自动加载的上下文，见 Trust Labels 与 Agent Memory。
• 生命周期。 从模板创建、配额、归档、退役，退役时可以指定继承者。

从小处开始 #

• 建一个目录，放 AGENTS.md、skills/ 和 memory/，git init。用符号链接让 CLAUDE.md 等文件指向 AGENTS.md。
• 每次运行前执行 git worktree add，让运行在自己的工作树里干活。
• 这就是 L0：不需要任何 Agent NAS 软件，你已经拥有一个带历史、可带走的 Home。

接口草图 #

仅作示意。字段名在规范 v0.3 之前可能调整。

/agents/cleo/                    # a role's Home: it belongs to the role, not to one run
├── AGENTS.md                    # instructions (open convention)
├── skills/                      # Agent Skills: one directory per skill
│   └── release-notes/SKILL.md
├── memory/
│   ├── MEMORY.md                # reviewed core memory: auto-loaded, token-capped
│   ├── notes/                   # notes: Markdown + YAML frontmatter
│   ├── journal/                 # raw log: append-only
│   └── quarantine/              # unreviewed notes: recallable, never auto-loaded
├── inbox/                       # tasks and messages received
├── outbox/                      # deliverables and replies
├── workspace/                   # scratch space (retention class: scratch)
└── .nas/                        # plain-text metadata: role.yaml, limits.yaml, maintenance.yaml

规范的要求 #

• Home 必须仅凭 Store 就能重建；读取它不得依赖任何派生数据。
• .nas/ 元数据必须是纯文本，并随 Home 一起导出。
• 自动加载的上下文必须有 token 上限，并且只能来自已审阅的笔记。
• 布局应当遵循开放约定：AGENTS.md、SKILL.md、带 YAML frontmatter 的 Markdown。
• 运行必须通过分支使用 Home。

借鉴与区别 #

下面这些都是现成的做法，真正新的部分很少：布局和 Git 都已经存在。新的只是把 Home 当作带配额、继承者和导出保证的一等对象，并规定“已审阅才自动加载”这条信任边界。

• AGENTS.md
• Agent Skills
• Letta Context Repositories
• Turso AgentFS
• Cloudflare Artifacts

坦诚的局限 #

• 各框架的原生记忆格式并不一致，映射到 Home 的约定是有损的。
• 只有运行时愿意读写这些文件才有用。
• 厂商侧的隐藏状态（例如云端托管的记忆）无法纳入。

开放问题 #

• 各框架的格式如何双向映射？
• 一个很大的 Home 怎样控制启动时的加载量与延迟？

常见问题 #

相关概念 #

• Agent Branch (智能体分支) 每次运行在写时复制的分支里工作，经审阅的合并才进入主线。
• Agent Memory (智能体记忆) 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
• Capability Lease (能力租约) 发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。