Agent Home

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: 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 and 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.

/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
• Agent Skills
• Letta Context Repositories
• Turso AgentFS
• Cloudflare Artifacts

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 #

Related concepts #

• Agent Branch Each run works on a copy-on-write branch. Only a reviewed merge reaches the main line.
• Agent Memory Notes you can read and edit are the truth. Indexes are a cache you can throw away.
• Capability Lease A narrow authorization for one run, with an expiry and budgets. Child leases can only be narrower.