# Agent Home (智能体之家)

*按角色划分、带历史的目录，全是普通文件，可以带走。*

> **Agent Home（智能体之家）** 是按角色划分、带历史的目录：指令、技能、记忆、日志和工作区，全是普通文件。任何运行时都能进入，离开时可以整个带走。

**AN-01** · 符合性等级: L0 Files · 概念簇: 工作

## 要解决的问题

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

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

## 工作方式

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

## 从小处开始

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

## 接口草图

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

*layout*

```text
/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](https://agents.md)
- [Agent Skills](https://agentskills.io/specification)
- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [Turso AgentFS](https://github.com/tursodatabase/agentfs)
- [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/)

## 坦诚的局限

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

## 开放问题

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

## 常见问题

### Agent Home 只是一个 Git 仓库吗？

大体上是，而且这是有意的：你可以直接 `git clone` 它。区别在于它还有归属（属于一个角色）、配额、继承者、导出保证，以及“已审阅才自动加载”的规则；这些由 NAS 保证，而不只是约定。

### 换一个智能体框架，记忆会丢吗？

不会，只要新的运行时愿意读这些文件。Home 用的是开放约定，`AGENTS.md`、`SKILL.md` 与 Markdown 笔记不依赖任何一个框架。映射有损的部分，应当在导入时标记为未审阅。

### 我需要先装 Agent NAS 才能用 Home 吗？

不需要。一个带 `AGENTS.md` 的 Git 目录就是 L0 的 Home。NAS 提供的是配额、受保护的合并、租约与审计，而不是文件格式。

## 相关概念

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

---

规范网址: https://agentnas.com/zh-cn/concepts/agent-home/
更新于: 2026-11-11 · 规范草案 v0.2 · CC BY 4.0