# Agent Home *A directory per role, with history. Plain files you can take with you.* > **An Agent Home** is a directory per role, with history: instructions, skills, memory, journal and workspace, all as plain files. Any runtime can enter it, and you can take all of it with you when you leave. **AN-01** · Conformance level: L0 Files · Cluster: Work ## The problem An agent’s state is scattered across framework databases, vendor-hosted memory APIs and sandbox disks that can vanish at any time. Change framework or vendor and the state is lost; when something goes wrong, there is no single place to look at what the agent actually knows. At the same time, mainstream agents are converging on files: `AGENTS.md`, Agent Skills, Git-backed memory repositories. What is missing is not a new format but a place for them with **an owner, history, quotas and a guaranteed export**. ## How it works - **The layout follows open conventions.** `AGENTS.md`, Agent Skills’ `SKILL.md` and Markdown with YAML frontmatter, as in the sketch below. We do not invent a format. - **A Home belongs to a role, not to one run.** Runs use it through [branches](https://agentnas.com/concepts/agent-branch/): changes land on a branch first and are merged back into the Home after review. - **It has history.** Every change is a commit. `nas export` or `git clone` takes the whole Home with you, including the plain-text metadata in `.nas/`. - **Boot context is just reading a few files:** `AGENTS.md`, `memory/MEMORY.md` and an inbox summary. There is no special wake-up protocol; a NAS may offer a token-capped `briefing` view as a convenience, but it is not required. - **Only reviewed notes autoload.** Only notes marked `reviewed` enter `MEMORY.md` and the autoloaded context; see [Trust Labels](https://agentnas.com/concepts/trust-labels/) and [Agent Memory](https://agentnas.com/concepts/agent-memory/). - **Lifecycle.** Creation from a template, quotas, archival and retirement, with an heir that can be named at retirement. ## Start small - Make a directory with `AGENTS.md`, `skills/` and `memory/`, and run `git init`. Symlink `CLAUDE.md` and similar files to `AGENTS.md`. - Run `git worktree add` before each run so that the run works in its own working tree. - That is L0: without any Agent NAS software you already have a Home with history that you can take away. ## Interface sketch Illustrative only. Field names may change before specification 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 ``` ## What the specification asks for - A Home MUST be rebuildable from the Store alone; reading it MUST NOT depend on any derived data. - The `.nas/` metadata MUST be plain text and MUST be exported with the Home. - Autoloaded context MUST be token-capped and MUST come only from reviewed notes. - The layout SHOULD follow open conventions: `AGENTS.md`, `SKILL.md`, Markdown with YAML frontmatter. - Runs MUST use a Home through branches. ## Borrowed, and what is new What follows is all borrowed, and **very little is new**: the layout and Git already exist. The only new part is treating the Home as a first-class object with quotas, an heir and an export guarantee, and setting the trust boundary that only reviewed notes autoload. - [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/) ## Honest limits - Native memory formats differ between frameworks, so mapping them onto the Home conventions is lossy. - It only helps if runtimes are willing to read and write these files. - Hidden vendor-side state, such as memory hosted in a vendor’s cloud, cannot be brought in. ## Open questions - How should the formats of different frameworks map onto the Home in both directions? - How is the load and latency at start-up kept under control for a very large Home? ## Questions ### Is an Agent Home just a Git repository? Mostly, and deliberately: you can simply `git clone` it. The difference is that it also has an owner (a role), quotas, an heir, an export guarantee and the rule that only reviewed notes autoload, and the NAS enforces these rather than leaving them as convention. ### Will I lose memory if I change agent framework? No, as long as the new runtime is willing to read the files. A Home uses open conventions: `AGENTS.md`, `SKILL.md` and Markdown notes do not depend on any one framework. Parts whose mapping is lossy should be marked as unreviewed on import. ### Do I need to install Agent NAS to use a Home? No. A Git directory with an `AGENTS.md` is an L0 Home. What a NAS adds is quotas, protected merges, leases and an audit trail, not a file format. ## Related concepts - [Agent Branch](https://agentnas.com/concepts/agent-branch/): Each run works on a copy-on-write branch. Only a reviewed merge reaches the main line. - [Agent Memory](https://agentnas.com/concepts/agent-memory/): Notes you can read and edit are the truth. Indexes are a cache you can throw away. - [Capability Lease](https://agentnas.com/concepts/capability-lease/): A narrow authorization for one run, with an expiry and budgets. Child leases can only be narrower. --- Canonical URL: https://agentnas.com/concepts/agent-home/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0