# Agent NAS: complete documentation > Agent NAS is network-attached storage designed around the run: every agent run works in an isolated branch and reaches data through a short-lived, narrow lease; every change can be traced and undone; and memory is plain files with provenance. It speaks what agents already speak: files, Git, S3 and MCP. Status: concept and draft specification v0.2, November 2026. No reference implementation yet. Content licensed under CC BY 4.0. --- # Agent NAS: network-attached storage for AI agents > Agent NAS is network-attached storage designed around the run: every agent run works in an isolated branch and reaches data through a short-lived, narrow lease; every change can be traced and undone; and memory is plain files with provenance. It speaks what agents already speak: files, Git, S3 and MCP. **Where agents work, and you stay in control.** A NAS that takes the run as its basic unit: every run gets its own branch and lease, every change can be traced and undone, and memory is notes you can read, edit and take with you. ## At a glance - **Category**: Network-attached storage for AI agents, also called agent-native storage. - **Core idea**: The unit of access is the **run**, not the account: a run works on a branch, reaches data through a lease and leaves a record. - **Four promises**: Bounded, recoverable, accountable and inspectable. - **Core nouns**: Tree, Commit, Principal, Run, Lease and Record. - **Concepts**: Nine named concepts in three clusters: Work, Authority and Knowledge. - **Interfaces**: Data plane: mount, Git, S3, WebDAV. Control plane: MCP, HTTP, CLI. - **Specification**: Draft v0.2 with conformance levels from L0 Files to L4 Sync, each with executable acceptance tests. - **Status**: Concept and specification stage, no reference implementation yet. L0 and L1 can be built today from existing parts. - **License**: Content under CC BY 4.0. ## Why now Four things have already happened in the past year. - **Agents work in files.** [AGENTS.md](https://agents.md), [Agent Skills](https://agentskills.io/specification), Git-backed memory ([Letta Context Repositories](https://www.letta.com/blog/context-repositories/)) and [dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery), which writes long output to files, have made files the working medium of agents. - **Mistakes are fast and expensive.** In April 2026 a coding agent used an over-broad token it found in an unrelated file and [deleted a company’s production database and the backups on the same volume in 9 seconds](https://www.theregister.com/software/2026/04/27/cursor-opus-agent-snuffs-out-startups-production-database/5224442). - **People cannot review every step.** Anthropic reports that users approve [93% to 97% of permission prompts](https://claude.com/resources/articles/auto-mode-default-in-claude-code); in its controlled experiment, people caught only 13.6% of planted dangerous commands. - **Memory became an attack surface.** [Several 2026 studies](https://arxiv.org/abs/2606.04329) show that a malicious instruction written into persistent memory survives across sessions, and that defending only at input or retrieval helps little. Storage vendors have moved too: [QNAP QuAgent](https://www.qnap.com/en/software/quagent), [Synology DSM Agent](https://www.synology.com/en-us/beta/2026_DSM_Agent_1_0_Beta/release_note) and [TrueNAS MCP](https://truenas.github.io/truenas-research-labs/) all let an agent manage the box. But as far as we can see, there is still no self-hosted, open, verifiable contract for how other agents work safely on the data inside it. See [how Agent NAS compares with existing approaches](https://agentnas.com/compare/). ## Four promises | Promise | Meaning | Delivered by | | --- | --- | --- | | Bounded | A run can touch only what its lease names, and the lease stops working on time; a session that read untrusted content cannot also hold sensitive data and an outbound channel. | [Capability Lease](https://agentnas.com/concepts/capability-lease/), [Trust Labels](https://agentnas.com/concepts/trust-labels/) | | Recoverable | Writes land on a branch first; protected data changes only through reviewed merges; deletes are soft; snapshots are outside any lease. | [Agent Branch](https://agentnas.com/concepts/agent-branch/), [Human Gate](https://agentnas.com/concepts/human-gate/) | | Accountable | Every change can answer: who did it, on whose behalf, under which lease, and what was read. | [Flight Recorder](https://agentnas.com/concepts/flight-recorder/) | | Inspectable | Memory is plain notes with provenance, indexes can be thrown away and rebuilt, and all data can be exported. | [Agent Home](https://agentnas.com/concepts/agent-home/), [Agent Memory](https://agentnas.com/concepts/agent-memory/), [Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/), [Cascade Forget](https://agentnas.com/concepts/cascade-forget/) | ## Nine concepts, three questions Agent NAS proposes nine named concepts. Each has its own page: a definition you can quote, a mechanism, a way to start small, an interface sketch, what the specification asks of it, and its honest limits. ### Work Where does the work happen, and what happened? - AN-01 [Agent Home](https://agentnas.com/concepts/agent-home/): A directory per role, with history. Plain files you can take with you. - AN-02 [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. - AN-03 [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read. ### Authority Who may do what, and on whose say-so? - AN-04 [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. - AN-05 [Human Gate](https://agentnas.com/concepts/human-gate/): Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff. - AN-06 [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two. ### Knowledge What does the agent know, how does it read, and how does it forget? - AN-07 [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. - AN-08 [Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/): Read a file as an outline, a section, a line range or in full, degrading to fit the budget. - AN-09 [Cascade Forget](https://agentnas.com/concepts/cascade-forget/): Delete derivatives along lineage, handle history by retention class, and report what it could not do. ## Four layers, six nouns The Store layer uses mature storage as it is. Every layer above it can be rebuilt from it, and the core is just six nouns: Tree, Commit, Principal, Run, Lease and Record. We do not invent a storage engine; the innovation is in the contract. - **Interface**: Projects capabilities into interfaces that agents, people and tools already use. Gateways are stateless and never decide who may do what. (Mount (POSIX), Git, S3, WebDAV/SMB, MCP, HTTP, CLI, A2A (optional)) - **Trust**: The single point of authorization. Deterministic policy, with no model in the decision. (Principals and runs, Capability Lease, Policy engine, Human Gate, Trust Labels, Credential Broker, Flight Recorder) - **Memory**: Turns notes into searchable knowledge. All of it can be rebuilt from the layer below. (Agent Memory, Budgeted Reads, Cascade Forget, Indexes, Maintenance jobs, Lineage) - **Store**: A tree with history, on mature file-system snapshots, Git or versioned object storage. (Tree, Commit, Agent Branch, File-system snapshots, Git, Object storage) - **Sync (optional)**: Replication and sharing between nodes. Last on purpose: get a single node right first. (Git remotes, Snapshot transfer, Lease links, Handoff bundles) [Read the architecture](https://agentnas.com/architecture/). ## The journey of a run 1. **Request a lease.** The orchestrator of the research agent Cleo requests a [Capability Lease](https://agentnas.com/concepts/capability-lease/) for this run: read `/shared/launch`, propose changes, valid for four hours. The owner’s pre-set policy envelope approves it automatically. 2. **Start work.** The NAS creates the run and its branch `cleo/run_91ab`; the sandbox mounts the branch as an ordinary directory. Cleo reads `AGENTS.md` and its reviewed memory from its [Agent Home](https://agentnas.com/concepts/agent-home/). 3. **Read within a budget.** It reads a long report with [Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/): a 400-token outline first, then specific line ranges as needed. Every read is added to the run’s read manifest. 4. **Work on a branch.** Changes land on an [Agent Branch](https://agentnas.com/concepts/agent-branch/). The shared `main` does not change at all for now. 5. **Meet a gate.** Cleo has read a web page, so [Trust Labels](https://agentnas.com/concepts/trust-labels/) give its session `external` taint. When it proposes a merge into `main`, policy requires a [Human Gate](https://agentnas.com/concepts/human-gate/): the owner sees the real diff computed by the NAS and the untrusted source on a phone, and approves. 6. **Leave a record.** The merge creates a commit with provenance. What was read, what was written and who approved what all go into the [Flight Recorder](https://agentnas.com/concepts/flight-recorder/), hash-chained. 7. **Settle memory.** Cleo notes down a few new facts. Because this session read external content, these [Agent Memory](https://agentnas.com/concepts/agent-memory/) notes go into quarantine first: they can be recalled but will not autoload until a person reviews them. 8. **Forget.** Weeks later, a customer asks to be forgotten. [Cascade Forget](https://agentnas.com/concepts/cascade-forget/) deletes the related summaries and indexes along lineage and issues a report that states what it could not cover. ## It speaks what agents already speak No new SDK is needed to start. Any agent that can read and write files, use Git or S3, or call MCP tools can use Agent NAS. The session below only illustrates the planned command line. *Illustrative session* ```bash $ nas lease create --role cleo --paths "/shared/launch/**" --actions read,write,propose --ttl 4h lease lse_7Qk3 · run run_91ab · branch cleo/run_91ab · expires 16:00 $ nas mount --lease lse_7Qk3 ~/work # plain files, on a branch $ ./draft-release-notes.sh # the agent works with ordinary tools $ nas propose --into main gate gt_2Mx4 waiting for approval: merge cleo/run_91ab into main (4 files) $ nas gate approve gt_2Mx4 # the owner, from another terminal or a phone merged · commit 91ce3a7 · record 18211 ``` [See all interfaces](https://agentnas.com/interfaces/). ## What we are betting on A design that hopes to hold up for years should say what it bets on and what happens if it bets wrong. - **Agents will keep using file systems and Git as their main working medium.** If not, Agent Home degrades to an export format and the other concepts still stand. - **“A run” remains the natural unit of authorization and accountability.** If long-lived autonomous processes appear, leases become rolling renewals with budgets. - **Prompt injection will not be eradicated at the model layer in the foreseeable future.** If it is, Trust Labels become a cheap layer of defence in depth. - **Human attention stays scarce.** If full automation becomes reliable enough, a Human Gate gives way to pre-authorizing policy and the audit trail stays. All seven bets are in the [design principles](https://agentnas.com/principles/). ## This site is readable by agents too Every page has a Markdown twin, the site publishes `llms.txt` and it runs a small read-only MCP server. Try it in a terminal: *Terminal* ```bash curl -H "Accept: text/markdown" https://agentnas.com/what-is-agent-nas/ curl https://agentnas.com/llms.txt curl -X POST https://agentnas.com/api/search \ -H "content-type: application/json" \ -d '{"query": "capability lease", "limit": 5}' ``` Add the documentation server to an MCP client: *mcp.json* ```json { "mcpServers": { "agentnas-docs": { "url": "https://agentnas.com/mcp" } } } ``` ## The questions people ask first ### What is Agent NAS in one sentence? Network-attached storage designed around the run: every agent run works in an isolated branch and reaches data through a short-lived, narrow lease; every change can be traced and undone; and memory is plain files with provenance. ### Is there software to download? Not yet. Agent NAS is currently a concept and a draft specification (v0.2). L0 and L1 can be built today from Git, file-system snapshots and a small gateway; the target for reference implementation v0 is the first half of 2027. See the [roadmap](https://agentnas.com/roadmap/). ### How does it differ from the AI agents NAS vendors ship? Those agents manage the box. Agent NAS specifies how other agents work on the data inside the box: branches, leases, memory and forgetting. The two complement each other, and a vendor’s box can be the foundation of an Overlay deployment. ### Will it replace my existing storage? No. The Overlay deployment form sits in front of an existing NAS, object store or Git host and manages only one directory or bucket within it. ### Can it stop prompt injection? No. It limits what happens after an injection and makes the consequences visible and reversible. Its honest limits are on the [security](https://agentnas.com/security/) page. ### Can I leave at any time? Yes. Everything can be exported as plain files and Git history. This is a design guarantee, not an optional feature. [All questions](https://agentnas.com/faq/). ## Where things stand > **Status.** Agent NAS is at the concept and draft specification stage (v0.2, November 2026). v0.2 is a grounding revision: thirteen concepts were reduced to nine, and each states how to start small and what its honest limits are. There is no reference implementation yet. - [Draft specification](https://agentnas.com/spec/): Conformance levels and executable acceptance tests. - [Roadmap](https://agentnas.com/roadmap/): Now, next, later, and what we will not do. - [About this project](https://agentnas.com/about/): License, how to cite, and how to take part. --- Canonical URL: https://agentnas.com/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # What is Agent NAS? > Agent NAS is network-attached storage designed around the run: every agent run works in an isolated branch and reaches data through a short-lived, narrow lease; every change can be traced and undone; and memory is plain files with provenance. It speaks what agents already speak: files, Git, S3 and MCP. ## In a paragraph Agent NAS holds everything an agent needs to work over time: instructions, skills, memory, work in progress and history. It answers questions a traditional NAS does not care about: what can this run touch, can a mistake be undone, who approved what, and where did a memory come from. It is not a new storage engine. It is a **contract** on top of mature storage (file systems, Git, object stores) that specifies how authority, isolation, traceability and memory between agents and data should work, and how to verify that. ## Reading the name apart - **Agent**: An AI system that acts on someone’s behalf: it reads, decides and uses tools over many steps. In Agent NAS an agent belongs to a **role**, and each piece of work is a **run**. - **Network-attached**: Reached over a network by many clients at once, whether a home LAN, a team server or a cloud region. Not tied to one sandbox or one machine. - **Storage**: Durable, versioned and exportable. Storage is the source of truth; everything “intelligent” is derived from it and can be discarded and rebuilt. ## What makes something an Agent NAS 1. **The unit of access is the run.** Every run has its own [lease](https://agentnas.com/concepts/capability-lease/), not a shared key or a human account. 2. **Isolated and undoable by default.** Writes land on a [branch](https://agentnas.com/concepts/agent-branch/) first; protected data changes only through merges; deletes are soft. 3. **Every change is traceable.** Who did it, on whose behalf, under which lease, and what was read ([Flight Recorder](https://agentnas.com/concepts/flight-recorder/)). 4. **Memory is files with provenance, and indexes are disposable** ([Agent Memory](https://agentnas.com/concepts/agent-memory/)). 5. **It is served through existing interfaces:** mounts, Git, S3 and MCP, not a new protocol. 6. **Without the AI layer it is still a sound general-purpose NAS,** and all data can be exported in full. ## What it is not - **Not a new storage engine, file system or vector database.** They are all used as existing parts. - **Not a sandbox.** It does not isolate compute; it constrains the relationship between agents and data, and should be used together with a sandbox. - **Not a cure for prompt injection.** It limits consequences and does not stop injection from happening. See [security](https://agentnas.com/security/). - **Not an agent framework.** It does not say how agents reason, plan or call models. ## Who it is for, and who does not need it - **Developers who already use `AGENTS.md` and Git:** they want a protected main line, undoable runs and a traceable record. - **Teams running several agents:** they need a shared tree, review of agents’ changes and an answer to “what did it actually read?”. - **Individuals with a personal agent:** they want the memory to stay in their own hands, readable, editable and portable. - **Organizations handling customer data:** they need retention and forgetting as explicit choices at write time, and an honest forgetting report. > **Who does not need it.** If you have one agent and data you can happily redo, you do **not** need Agent NAS: a Git repository with an `AGENTS.md` is enough. It earns its place when data starts to matter, agents multiply and you want to know “what did it actually read and change?”. More cases are in [use cases](https://agentnas.com/use-cases/). ## Agent NAS and vendors’ management agents | Question | NAS vendors’ management agents | Agent NAS | | --- | --- | --- | | What does the agent do? | Manages this NAS in natural language, turning conversation into operations. | Works on the data inside the box: reading, writing, remembering, and leaving a record. | | How is access granted? | Reuses the user’s permissions, with a second confirmation for dangerous operations. | A short-lived lease bound to one run: paths, actions, expiry, budgets. | | What if something goes wrong? | Relies on confirmations and logs. | Writes land on a branch; deletes are soft; snapshots are outside every lease. | | Where does memory live? | On the assistant’s or the vendor’s servers. | As notes with provenance in the agent’s Home; indexes are disposable. | | Untrusted content? | Enters the model like any other text. | Carries an `external` label; after reading it, consequential actions go through a gate. | | How do I leave? | Depends on the vendor. | Everything exports as plain files and Git history. | ## What to read next - [The nine concepts](https://agentnas.com/concepts/): One page each, with how to start small. - [Architecture](https://agentnas.com/architecture/): Four layers, six nouns and the journey of a run. - [Security](https://agentnas.com/security/): Threat model, controls and honest limits. - [FAQ](https://agentnas.com/faq/): Short answers to common questions. --- Canonical URL: https://agentnas.com/what-is-agent-nas/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # The nine concepts > Agent NAS is built on nine named concepts. They answer three questions: where the work happens and what happened; who may do what and on whose say-so; and what the agent knows, how it reads and how it forgets. The concept names are coined terms and stay in English in every language, with a gloss in the local language. Each page opens with one quotable definition and then covers the problem, the mechanism, how to start small, an interface sketch, what the specification asks for, and what is borrowed along with honest limits. The conformance level says when an implementation should support the concept; see the [specification](https://agentnas.com/spec/). > **About “new”.** Most of the nine concepts combine mature parts. Each concept page says what it borrows and what is genuinely new. The summary list is on the [comparison](https://agentnas.com/compare/) page. ## Three clusters ### Work Where does the work happen, and what happened? - AN-01 [Agent Home](https://agentnas.com/concepts/agent-home/): A directory per role, with history. Plain files you can take with you. - AN-02 [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. - AN-03 [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read. ### Authority Who may do what, and on whose say-so? - AN-04 [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. - AN-05 [Human Gate](https://agentnas.com/concepts/human-gate/): Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff. - AN-06 [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two. ### Knowledge What does the agent know, how does it read, and how does it forget? - AN-07 [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. - AN-08 [Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/): Read a file as an outline, a section, a line range or in full, degrading to fit the budget. - AN-09 [Cascade Forget](https://agentnas.com/concepts/cascade-forget/): Delete derivatives along lineage, handle history by retention class, and report what it could not do. --- Canonical URL: https://agentnas.com/concepts/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Architecture > Agent NAS has four layers and an optional sync layer: Interface projects capabilities into existing interfaces, Trust is the single point of authorization, Memory turns notes into searchable knowledge, and Store keeps a tree with history. The Memory layer can be deleted and rebuilt as a whole, and Store simply uses mature storage. ## Four layers and optional sync - **Interface**: Projects capabilities into interfaces that agents, people and tools already use. Gateways are stateless and never decide who may do what. (Mount (FUSE, NFS, SMB), Git, S3-compatible, WebDAV, MCP, HTTP API, CLI, A2A (optional)) - **Trust**: The single point of authorization. A deterministic policy engine with no model in the decision; record first, then act. (Principals and runs, Capability Lease, Policy engine, Human Gate, Trust Labels, Credential Broker, Flight Recorder) - **Memory**: Turns notes into searchable, budget-readable knowledge. All of it can be rebuilt from the layer below. (Note conventions, Indexes (full-text, vector, graph), Budgeted Reads, Maintenance jobs, Lineage, Cascade Forget) - **Store**: A tree with history, on mature file-system snapshots, Git or versioned object storage. It does not understand memory or labels. (Tree, Commit, Agent Branch, File-system snapshots, Git, Object storage) - **Sync (optional)**: Replication and sharing between nodes. Last on purpose: get a single node right first. (Git remotes, Snapshot transfer, Lease links, Handoff bundles) - **The Memory layer is rebuildable.** Delete every index and rebuild, and the notes in Store remain fully readable. - **Gateways are stateless.** All persistent state is in Store and in Trust’s records; a gateway can restart freely and scale horizontally. - **Trust is the only point of authorization.** That includes the NAS’s own background jobs (indexing, maintenance): they too run as `svc:*` principals holding leases. - **Store does not understand memory or label semantics.** It only keeps a tree with metadata. - **Record first, then act.** A consequential operation must first write an intent record. ## The narrow waist: six nouns The whole design depends on six nouns; labels, gates, memory and read manifests are conventions built on top of them. | Noun | Meaning | Key invariant | | --- | --- | --- | | Tree | A directory tree with history. | Any commit can be reproduced; there is a content hash or equivalent change detection. | | Commit | One immutable change. | Carries provenance metadata: `principal`, `on_behalf_of`, `run`, `lease`. | | Principal | An entity that can be authenticated and held accountable. | Type is `human`, `agent`, `service` or `node`; an `agent` belongs to a role, not to one run. | | Run | One execution with a start, an end, a purpose and a responsible party. | Holds one root lease; owns one branch. | | Lease | The authorization of a run. | Has an expiry; can only be narrowed; revocable; carries budgets. | | Record | An append-only record. | Hash-linked; record first, then act. | ## The Store layer: contract and optional engines The Store contract is provided by an engine or emulated by the gateway. An implementation may combine engines, for example Git for text and snapshots for large files; the contract does not prescribe the engine, the hash function or the on-disk format. 1. Atomic commits. 2. Cheap forks: ideally close to O(1); at worst degrading to a copy, in which case quotas and a TTL are mandatory. 3. Immutable snapshots. 4. Change detection: a content hash or an equivalent. 5. The difference between two commits. 6. Complete export in a standard format: a directory, Git history and the plain-text `.nas/` metadata. | Engine | Suited to | Fork cost | Note | | --- | --- | --- | --- | | Git (with worktrees) | Text, memory, skills, small code bases | Low | Large files need LFS or external storage; binary merges are poor. | | File-system snapshots and clones (ZFS, btrfs, APFS) | Large directories, mixed files | About O(1) | Depends on the file system; copying across machines needs send/receive. | | Versioned object storage (Tigris forks, lakeFS, S3 plus a manifest) | Datasets, large files | About O(1) | Needs the gateway to provide a file view. | | Plain directory plus copy | Starting out with Lite | O(n) | Only for small data; quotas and a TTL are mandatory. | > **The recovery path is outside the blast radius.** Snapshots and backups are held by the owner principal, and no lease may include “delete a snapshot” or “delete a backup”. That is the most direct lesson of the April 2026 incident: the recovery path must lie outside the blast radius of what it protects. - Encryption at rest comes from the layer below; the `sensitive` retention class uses its own key domain, so it can be shredded by destroying the key. - Deduplication and shredding conflict: the `sensitive` class is not deduplicated across key domains. ## The journey of a run 1. **Request.** The orchestrator (or the owner) requests a lease for a run: paths, actions, expiry, purpose. Inside the **policy envelope** it is issued automatically; outside it goes to a Human Gate. 2. **Start.** The NAS creates the `run` and the branch `/` and hands the lease to the run; the sandbox mounts the branch (or does a `git clone`). 3. **Work.** The agent reads and writes with ordinary file tools. Reads accumulate into the **read manifest** and the session taint updates with them; out-of-bounds access is refused and recorded. 4. **Commit.** Changes are committed automatically (debounced) or explicitly, and every commit carries provenance metadata. 5. **Propose.** `propose` creates an **Agent PR**: the diff, intent, a read-manifest summary, check results and a label summary. 6. **Decide.** The policy engine decides: if checks pass and the risk is low, merge automatically; if protected data, an outward action or a Rule of Two violation is involved, go to a Human Gate; if clearly forbidden, refuse. 7. **Merge and record.** The merge creates a commit with provenance and writes a Record. 8. **Wrap up.** The lease expires; the branch is recycled after its TTL; read manifests and Records are kept according to retention policy. **The read path:** request, lease check, label check (does the current session taint allow this read?), budget counting, read from Store, record in the read manifest, return content and evidence pointers. > **Record first, then act.** A consequential operation (merge, delete, share, egress, lease change) must first write an intent record; if it cannot be written, the operation fails (fail closed). Reads go into the read manifest, which is flushed in batches and does not need to be synchronous per read. ## Deployment forms | Form | Description | Suited to | | --- | --- | --- | | Lite | Single machine, single user: one gateway process plus local storage (Git or file-system snapshots); L0 to L1. | Individuals and developers trying it out. | | Overlay | Leaves the existing NAS or object store alone: a gateway sits in front and manages only one directory or bucket; mounts and the S3 view pass through the gateway. | **The most realistic starting point:** people who already have a box. | | Team | Multiple users and agents, one server or a small cluster; L0 to L3; gate notifications and a control room. | Small teams. | | Cloud | A hosted multi-tenant service with strong isolation; L0 to L3. | People without their own hardware. | The principle: no special hardware is required, and any always-on machine will do; accelerators are optional, since small models are enough for embeddings and summaries, and external services can be called too. ## Building a v0 from existing parts | Capability | Parts you can use today | | --- | --- | | Store and branches | Git and worktrees; btrfs or ZFS snapshots; or Tigris and lakeFS (object storage). | | Protected main line | Branch protection in Forgejo, Gitea or GitHub; or lakeFS protected branches. | | Leases | An OAuth authorization server (for example Keycloak) with token exchange, and a resource server that checks path prefix and action; or a signing service of a few hundred lines. | | Records | An append-only SQLite table plus a daily hash; Git trailers in commits; OpenTelemetry export. | | Gates | PR review plus a push notification; the `nas gate approve` CLI. | | Memory | Markdown under `memory/` plus SQLite FTS5; add a vector store later. | | Labels | Mark the import directory `external`; keep run-level session taint in the gateway. | | Interfaces | NFS, SMB or a FUSE mount; Git over SSH or HTTPS; an S3 gateway; a small MCP server. | What this table says: **L0 and L1 need no new invention.** What is new is the contract that combines them and the tests that verify it; see the [specification](https://agentnas.com/spec/). ## Operations - **Backups:** 3-2-1; snapshots and backups belong to the owner principal and no lease may touch them; run a restore drill every quarter and keep a record of it. - **Upgrades:** gateways are stateless and can be upgraded in a rolling fashion; any Store format change must ship with a migration and rollback plan; the Memory layer can be rebuilt as a whole. - **Monitoring:** lease issuance and denial rates; gate queue length and approval rate (an approval rate that stays above 95% says gates are too frequent and should be merged or policy tightened); branch count and age; index freshness; record-chain verification; quotas. - **Capacity:** branches have a TTL and quotas; the recycle area has a retention period; derived data has a budget. ## The control room The interface for people can be a web page, a CLI or a chatbot. It is not essential: L0 to L1 can run entirely on a CLI and an existing Git platform. - **Activity timeline:** aggregated by run: who did what, and what they read. - **Gate inbox:** actions awaiting approval, shown as Gate Cards. - **Role directory:** each role’s Home, leases, budgets and recent runs. - **Memory browser:** notes and sources, the quarantine of unreviewed notes, maintenance proposals. - **Branches and PRs:** unmerged branches and the recycle area. - **Forgetting console:** requests, a lineage preview and reports. People can also look directly over SMB or WebDAV: `/humans//Agent Activity/` is a read-only activity view made of plain files. --- Canonical URL: https://agentnas.com/architecture/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Interfaces > Agent NAS uses files for the data plane and tools for the control plane: bytes travel over mounts, Git and S3; authorization, approval, memory, search and explanation go through MCP, HTTP and a CLI. Every interface is a projection of the same data, and differences in semantics are expressed as explicit errors instead of being pretended away. ## Principles 1. **Files for the data plane, tools for the control plane.** Bytes travel over mounts, Git and S3; authorization, approval, memory, search and explanation go through MCP, HTTP and a CLI. 2. **Gateways are stateless.** Authorization happens at exactly one point in the Trust layer. 3. **Every interface is a projection.** Differences in semantics are expressed through explicit error mappings (for example “gate pending” maps to an `EACCES` with an explanatory file), and S3 is not pretended to have branches. 4. **A narrow tool surface.** No more than 10 MCP tools face agents; actions for people and operators live in a separate operator interface. 5. **Adapters isolate protocol change.** Version changes in MCP and A2A only affect the adapters. ## Interface matrix | Interface | Plane | Aimed at | Mapping | Level | | --- | --- | --- | --- | --- | | Mount (FUSE, NFS, SMB) | Data | Agents, people, any program | A branch view; error mapping below | L0 | | Git (SSH, HTTPS) | Data | Agents, people, CI | A run branch is a Git branch; an Agent PR is a merge request | L0 | | S3-compatible | Data | Data pipelines, batch jobs | A bucket maps to a branch view of one tree; a version ID is a commit | L0 (optional) | | WebDAV | Data | People (Finder, Explorer) | A read-only activity view | L0 (optional) | | CLI `nas` | Control | People, scripts | One to one with the HTTP API | L0 | | HTTP API | Control | Orchestrators, the control room | All `POST` with JSON; fields in `snake_case` | L1 | | MCP | Control | Agents | Nine tools (below) | L1, L2 | | A2A | Control | Other agents | A task maps to `inbox/` and `outbox/` | L4 (optional) | ## The MCP tool surface Only nine tools face agents: | Tool | What it does | Lease action needed | Note | | --- | --- | --- | --- | | `nas_list` | List a directory, with labels and review state | `list` | Paths outside the lease are invisible. | | `nas_read` | Budgeted read: view, range, budget | `read` | [Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/) | | `nas_search` | Search (full-text, optionally vector), returning snippets and pointers | `read` | Quarantine is excluded by default. | | `nas_write` | Write a file inside the branch, with an optional `intent` | `write` | Most runtimes use the mount directly and do not need it. | | `nas_branch` | Create, checkpoint, restore and list branches | `write` | [Agent Branch](https://agentnas.com/concepts/agent-branch/) | | `nas_propose` | Create an Agent PR | `propose` | May trigger a gate. | | `nas_lease` | Request a narrower child lease; query the current lease and budgets; request wider authority (via a gate) | None | [Capability Lease](https://agentnas.com/concepts/capability-lease/) | | `nas_remember` | Write a note, with sources and kind | `write` | [Agent Memory](https://agentnas.com/concepts/agent-memory/) | | `nas_recall` | Recall notes: budgeted, with sources and review state | `read` | [Agent Memory](https://agentnas.com/concepts/agent-memory/) | > **Actions for people and operators only.** `explain`, `gate approve/deny`, `forget`, `trash restore`, `label admin`, `lease revoke` and `policy edit` are **not exposed** to agents. These actions change the guarantees themselves and should not be callable by the party being constrained. An agent may **request** some of them (wider authority, forgetting) but cannot execute them. ## Mount semantics - A mount binds **one branch and one lease**; when the lease expires the mount turns read-only and is then unmounted. - Automatic commits (debounced, for example after 5 quiet seconds); `fsync` triggers a commit. - Paths outside the lease **do not appear in directory listings:** this reduces information leakage and shrinks the attack surface for prompt injection. - Sandbox-friendly: no root needed; FUSE or NFS, one of the two, with no kernel module; read-only mounts are possible. | Situation | POSIX error | Note | | --- | --- | --- | | A path outside the lease | `ENOENT` (`EACCES` when visible but refused) | The refusal is recorded. | | Quota or budget exhausted | `EDQUOT` | Lets the run throttle itself. | | Gate pending | `EACCES`, with an explanation in `/.nas/pending` | Keeps the agent from retrying forever. | | Lease expired | `ESTALE`, then read-only | The branch is kept until its own TTL expires. | ## Git - Run branches are named `/`; `main` is protected, and a server-side `pre-receive` hook rejects direct pushes. - `nas propose` creates an Agent PR. - Commits automatically carry trailers such as `Run:`, `Lease:` and `Principal:`. ## S3 - A bucket corresponds to a branch view of one tree; an object version ID is a commit. - Semantics S3 lacks, such as branches, are expressed with a bucket prefix or a request header (`x-nas-branch`). This is a **degraded projection:** data pipelines can read and write, but do not get the full branch experience. - Leases are passed as STS-style temporary credentials. ## A2A (optional) - Incoming tasks land as task files in `inbox/`; deliverables go into `outbox/`. - The Agent Card declares the role’s skills and the leases it needs. - **The NAS is not an A2A participant;** the runtime acting for the role is. The NAS only stores tasks and deliverables, handoff bundles and leases. ## HTTP API conventions - **Every endpoint uses `POST`, with parameters in a JSON body;** response fields are always `snake_case`. - Paths are versioned: `/v1/...`. - Idempotency: write operations accept an `idempotency_key`. - Pagination: `cursor` plus `limit`. - Budgets and rate limits are fed back in response headers (bytes left, requests left) so runtimes can throttle themselves. A budgeted read request and response look roughly like this: *Budgeted read* ```http POST /v1/files/read { "path": "/agents/cleo/memory/notes/customer-acme.md", "view": "outline", "budget_tokens": 400 } 200 OK { "view": "outline", "tokens": 212, "generated": false, "truncated": false, "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)", "evidence": [ { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" } ] } ``` Errors use one uniform structure: *Error response* ```json { "error": { "code": "gate_required", "message": "This merge requires human approval.", "retryable": false, "request_id": "req_01JB7W2X4N", "details": { "gate_id": "gt_2Mx4" } } } ``` ## Discovery - The machine-readable entry points are the same as on this site: `/.well-known/ai-catalog.json`, the MCP Server Card and `llms.txt`. - An endpoint that resolves and verifies `nas://` evidence pointers. - MCP `server/discover`. --- Canonical URL: https://agentnas.com/interfaces/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Security > Agent NAS does not stop prompt injection; it limits what happens after one. A narrow lease bounds what a run can touch, branches make mistakes undoable, the Rule of Two stops a session that read untrusted content from also holding sensitive data and an outbound channel, and a traceable record is left behind. ## Scope and trust assumptions - **What we protect:** the data and history in the NAS; the boundary of authority; the integrity of the record; the traceability of memory. - **What we do not protect:** what an agent does outside the NAS; isolation of the compute itself (that is the sandbox’s job); anything that happens on the model provider’s side. - **Trust assumptions:** the trusted computing base (TCB) is the NAS gateway, the policy engine and the record service; the host is not compromised; the sandbox isolates compute. If the TCB is compromised, the guarantees on this page no longer hold. ## The Rule of Two: a session invariant Three properties: **[A]** the session has read untrusted content, **[B]** the lease allows reading sensitive data, **[C]** the lease allows changing protected state or communicating outward. When all three hold in one session, the call that triggers C is not let through automatically. | Scenario | A | B | C | Result | | --- | --- | --- | --- | --- | | Summarize a web page into a note on the branch | Yes | Yes | No (branch only) | Automatic: a write inside the branch does not count as C. | | After reading a web page, propose a merge into `main` | Yes | Yes | Yes | Human Gate. | | Read public data only, write to a scratch area | Yes | No | No | Automatic. | | After reading an external email, send an email (egress) | Yes | Yes | Yes | Gate; refused if `secret` is involved. | This is Meta’s [Agents Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/) implemented at the **storage boundary**. Meta itself stresses that it is a heuristic for reducing risk, not an end point, and no substitute for least privilege; we use it the same way. The mechanism is in [Trust Labels](https://agentnas.com/concepts/trust-labels/). ## Threat model | Threat | What the NAS can enforce | What the NAS cannot do | Residual risk | | --- | --- | --- | --- | | T1 Indirect prompt injection (via files, web pages, email) | The Rule of Two; lease scoping; branches; gates. | Stop an injection from happening, or stop malicious behaviour within the lease after one. | Misuse inside the lease. | | T2 Credential leakage (an agent reads a long-lived key) | Long-lived credentials are never in a run’s hands; a secret scanner marks `secret`; short TTLs. | Stop an agent sending data within its lease to an authorized egress. | Data leaving within the lease. | | T3 Over-broad permissions and mistakes | Narrow leases; branches; soft delete; snapshots outside every lease. | Undo side effects outside the NAS. | Consequences beyond the NAS. | | T4 Memory poisoning (including spread across roles) | Provenance and taint; quarantine; autoload only when reviewed; rollback. | Recognize facts that are wrong but look plausible. | Poison that a reviewer lets through. | | T5 Stolen or replayed leases | Short TTL; revocable; optional holder binding (DPoP, mTLS). | Stop abuse within the TTL. | The TTL window. | | T6 Approval fatigue and rubber-stamping | Rare gates; the NAS renders the diff; approvals bound to a digest; approval rate monitored. | Make people look carefully. | Human error. | | T7 Log tampering | Hash chain; optional external anchoring. | Without anchoring, stop root from destroying the log. | A malicious administrator. | | T8 Data exfiltration (egress, sharing, search results) | Egress needs a lease action and a gate; `secret` may not leave; derivatives inherit labels. | Prevent leaks after a person approves; covert channels. | Leaks after approval. | | T9 Supply chain (skills, MCP servers, plugins, models) | Content of skills and external MCP servers is treated as `external`; a skill directory can be pinned to a commit; the runtime manifest is written to the record. | Guarantee that third-party code is harmless. | A pinned malicious version. | | T10 Resource exhaustion (branch bombs, exhausted budgets, read loops) | Quotas; TTLs; budgets; circuit breakers. | Tell a legitimate large task from a runaway one. | Local denial of service. | ## Controls - **Policy engine:** deterministic (Cedar or Rego style), deny by default, and on denial it gives a readable reason and the rule that matched; it **does not call an LLM**. - **Credential broker:** long-lived keys stay with the broker; it mints short-lived downstream tokens for a run only inside an approved egress action. - **Isolation and keys:** one Home and path space per role; the `sensitive` retention class uses a separate key domain. - **Supply chain:** the content of skills, MCP servers and plugins is treated as `external`; at the start of a run, the skills and versions used are written to the record. ## Honest limits 1. This is **not** a defence against prompt injection. It limits the consequences and makes them visible. 2. Legitimate permissions inside a lease can still be misused. 3. It can do nothing about side effects outside the NAS: an email already sent, an API already called. 4. Covert channels and side channels are out of scope. 5. If the TCB is compromised, the guarantees fail. 6. People make mistakes: gates lower that risk but cannot remove it. 7. Taint is conservative and brings friction and false positives; it needs tuning and visible denial reasons. 8. Crypto-shredding only protects the copies we control. ## Incident response - **Circuit breaker:** `revoke_run` and `revoke_role` revoke leases at once and freeze the branch. - **Rollback:** restore the affected tree to an earlier commit. - **Trace:** use the read manifest and the record chain to find what a run read, what it wrote and which notes it touched. - **Clean-up:** use [Cascade Forget](https://agentnas.com/concepts/cascade-forget/) to delete the affected derivatives, and issue a report. ## Observability and audit - **Three kinds of data:** the record (events), the read manifest (the set of inputs), and metrics and traces. - **`explain(commit)`:** returns which run and lease produced a commit, which gates it passed, what was read, and the inputs it depends on. - **Integration with existing observability:** a run maps to one OpenTelemetry GenAI span, with leases and gates attached as events; records can be exported as JSON Lines or fed to a SIEM. - **Metrics:** lease issuance and denial rates; gate queue length, approval rate and approval latency; branch count and age; index freshness; budget consumption; record-chain verification results. - **Privacy and retention:** by default only metadata is recorded, never content; retention of records and deletion of content are independent; reading the record itself needs a lease. --- Canonical URL: https://agentnas.com/security/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Use cases > Each scenario starts from something people already do, and shows which step Agent NAS changes, which conformance level it needs, and what you can build with today. ## An agent that runs overnight Before bed you give an agent a task: tidy the release notes. It works on its own branch; in the morning you see a Gate Card on your phone: 4 files, the real diff, and the sources it read. Approve and it merges; reject and the branch is discarded, with the main line untouched. - **Concepts used:** [Agent Branch](https://agentnas.com/concepts/agent-branch/), [Capability Lease](https://agentnas.com/concepts/capability-lease/), [Human Gate](https://agentnas.com/concepts/human-gate/). - **Conformance:** L0 to L1. - **Buildable today:** a Git worktree, a protected `main` and a push notification. ## Change frameworks, keep your memory You move an agent from one runtime to another. Its Home is a directory following open conventions: `AGENTS.md`, `skills/`, `memory/notes/`. The new runtime reads the same directory; anything that maps lossily is marked unreviewed on import. - **Concepts used:** [Agent Home](https://agentnas.com/concepts/agent-home/), [Agent Memory](https://agentnas.com/concepts/agent-memory/). - **Conformance:** L0 to L2. - **Buildable today:** a Git directory with an `AGENTS.md`. ## A team, several agents, one shared body of knowledge Three agents write to the same knowledge base. Each works on its own branch and merges are reviewed; notes written by a run that read an external web page go into quarantine and are not autoloaded by other agents. What is shared is notes, not indexes. - **Concepts used:** [Trust Labels](https://agentnas.com/concepts/trust-labels/), [Agent Memory](https://agentnas.com/concepts/agent-memory/), [Agent Branch](https://agentnas.com/concepts/agent-branch/). - **Conformance:** L0 to L3. - **Buildable today:** a protected main line, an `external` mark on the import directory, and a rule that autoloads only reviewed notes. ## Incident review After a merge you find a page that looks wrong. `explain(commit)` tells you which run, which lease and which gate decided it; the read manifest shows that run read an external web page. You follow the provenance to the affected notes, roll back, and quarantine them. - **Concepts used:** [Flight Recorder](https://agentnas.com/concepts/flight-recorder/), [Agent Branch](https://agentnas.com/concepts/agent-branch/). - **Conformance:** L1. - **Buildable today:** Git trailers in commits plus an append-only SQLite table. ## A customer asks to be forgotten The customer’s data was marked with the `sensitive` retention class at write time. When the request arrives, Cascade Forget follows lineage to the summaries, embeddings and notes that cite it, destroys that key domain, and issues a report: what was done, and what could not be (copies outside the NAS, the model provider’s logs, model weights). - **Concepts used:** [Cascade Forget](https://agentnas.com/concepts/cascade-forget/), [Agent Memory](https://agentnas.com/concepts/agent-memory/). - **Conformance:** L3. - **Buildable today:** retention classes, soft delete, and recording the inputs of every derivative. ## Add a door to a box you already own You already have a NAS. The Overlay form puts a gateway in front of it and manages only one directory. Agents come and go through a mount or the S3 view; the owner’s backups and snapshots stay out of the agents’ reach. - **Concepts used:** [Capability Lease](https://agentnas.com/concepts/capability-lease/), [Agent Branch](https://agentnas.com/concepts/agent-branch/). - **Conformance:** L0 to L1. - **Buildable today:** NFS or SMB plus a small gateway that checks tokens against a path prefix and an action. ## When not to use Agent NAS | Your situation | A simpler approach | | --- | --- | | One agent, and data you can happily redo | A Git repository with an `AGENTS.md`. | | You only want an agent to help manage your NAS | The vendor’s own management agent. | | You only need forkable datasets | lakeFS or Tigris. | | You only need memory retrieval | Any memory library. | | You need isolated compute | A sandbox. | --- Canonical URL: https://agentnas.com/use-cases/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Comparison > Agent NAS is not meant to replace these approaches. Most neighbouring work is good at what it does and can become a part of it. We try to be honest about what is borrowed and what is genuinely new. ## The landscape | Category | Examples | What it already does | Where it stops | | --- | --- | --- | --- | | NAS vendors’ management agents | QNAP QuAgent, Synology DSM Agent, TrueNAS MCP | Manage the box in natural language; reuse user permissions; confirm dangerous operations twice; logs. | Aimed at “managing”, not at “working in the data”; no run-level leases, branches or memory contract. | | Agent file systems and Git | Turso AgentFS, Letta Context Repositories, Cloudflare Artifacts, Redis Agent Filesystem | Put files, state and tool-call audit into portable storage; Git-versioned memory; Git for agents. | Each is tied to one runtime or platform; authorization, approval, taint and forgetting mostly sit outside. | | Forkable object storage and data version control | Tigris Agent Kit, lakeFS | Copy-on-write forks, checkpoints, protected branches, scoped credentials, pre-merge hooks. | Aimed at data lakes and cloud object storage; no memory or lease semantics, and no human approval experience. | | Memory frameworks | Letta, Mem0, Zep/Graphiti, OpenClaw memory architecture | Retrieval, consolidation, temporal graphs; OpenClaw already has provenance labels and quarantine. | Mostly bound to one framework; the index and the truth are not separated; migration and deletion are hard. | | Sandboxes and runtimes | E2B, Daytona, Vercel Sandbox | Isolated compute and snapshots. | Storage is not the focus; state disappears with the sandbox. | | General-purpose storage | S3 and S3 Files, NFS, SMB, Git | Durable, mature, with a complete ecosystem. | Does not know “run”, “lease” or “taint”. | **The gap.** Every part has been built by someone. What we do not see is a **self-hosted, open, testable** contract that combines them, with the run as the unit, binding branches, leases, approval, records, memory and forgetting together, and with conformance tests attached. We do not claim that nobody has done any one of these things; that is exactly why we borrow so much. ## How it relates to neighbouring approaches | Approach | Good at | Relation to Agent NAS | | --- | --- | --- | | QNAP QuAgent, Synology DSM Agent, TrueNAS MCP | Managing a NAS in natural language | Complementary; their boxes can be the foundation of an Overlay. | | Turso AgentFS, Redis Agent Filesystem, LayerFS | Agent file systems | Can serve as Store engines; Agent NAS adds the contract on top. | | Letta Context Repositories | Git-backed memory | Agent Home borrows its layout ideas; Letta can be a runtime for Agent Memory. | | Cloudflare Artifacts, Tigris, lakeFS | Forkable, versioned storage | Can be used directly as Store engines. | | Mem0, Zep/Graphiti | Memory retrieval and consolidation | Can be indexers, that is, producers of derivatives. | | OpenClaw memory architecture | Provenance labels and quarantine | A forerunner; we put the same ideas in the shared storage layer. | | S3, S3 Files, NFS, SMB | General-purpose storage | Can serve as the Store; they do not know runs, leases or taint. | | E2B, Daytona, Vercel Sandbox | Isolated compute | Complementary; they should be used together. | ## What we borrowed - From **Git and lakeFS:** branches, protected branches, pre-merge hooks. - From **Letta and Cursor:** files are the interface agents know best, and context should be disclosed progressively. - From **OpenClaw and memory-security research:** provenance cannot be forged, and untrusted memory is quarantined. - From **Meta’s Rule of Two, CaMeL and Fides:** limit consequences outside the model. - From **OAuth (RFC 8693, RFC 9396), Biscuit and UCAN:** token exchange and attenuating authorization. - From **OpenTelemetry and Certificate Transparency:** exportable traces and discoverable tampering. - From **Anthropic’s auto-mode research:** keep approvals few, and put them on plans and merges. ## What is genuinely new We try to be honest about it. The list is short: 1. Using the **run** as the unit, binding branch, lease, budget and record together. 2. The **read manifest** and session taint: enforcing the Rule of Two at the storage boundary. 3. Memory writes that carry **provenance and taint**, and the trust boundary of “autoload only when reviewed”. 4. **Retention classes:** making “recoverable” versus “forgettable” an explicit choice. 5. **A conformance ladder with executable acceptance tests.** > **A judgement that still has to be proven.** Everything else, including branches, tokens, logs and retrieval, is a combination of existing techniques. We believe that combining them into an open, testable contract has value of its own, but that is a **judgement that still has to be proven**, not an established fact. --- Canonical URL: https://agentnas.com/compare/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Specification > Specification draft v0.2 defines five cumulative conformance levels, from L0 Files to L4 Sync. Each level corresponds to a set of concepts and a set of executable acceptance tests; a claim of “compatible” without a `conformance.json` is not accepted. > **Draft.** There is no reference implementation and no runnable conformance suite yet. The acceptance tests below are part of the specification: their job is to make the word “compatible” checkable. ## Components of the specification | Component | Contents | Target version | | --- | --- | --- | | Core | The six nouns, the Store contract, branches and protected trees, merges, soft delete. | v0.3 draft | | Lease & Record | The lease format (an `authorization_details` profile), the format of records and read manifests, `explain`. | v0.3 draft | | Interfaces | Mount semantics, the Git and S3 projections, the HTTP API, the MCP tool surface. | v0.4 draft | | Memory | Note conventions, derivatives and recipes, budgeted reads, evidence pointers. | v0.4 draft | | Guard | Labels, session taint, the policy profile, Gate Cards, the forget report. | v0.5 draft | | Sync | Handoff bundles, label thresholds, tombstones. | Later | | Conformance Suite | Executable acceptance tests for each level. | In step with each version | ## Conformance levels Levels are cumulative: to claim L2, you must also satisfy L0 and L1. | Level | Name | Concepts covered | In one line | | --- | --- | --- | --- | | L0 | Files | Agent Home, Agent Branch | A directory with history. | | L1 | Authority | Flight Recorder, Capability Lease, Human Gate | Who, on what authority, did what. | | L2 | Memory | Agent Memory, Budgeted Reads | Memory you can read and move. | | L3 | Guard | Trust Labels, Cascade Forget | Limiting consequences. | | L4 | Sync | None (optional) | Multiple nodes. | ## L0 Files: a directory with history 1. Changing files in a run branch leaves the protected main line unchanged. 2. A direct write to a protected tree is refused, even with valid credentials. 3. After a file in a protected tree is deleted, it can be restored from the recycle area. 4. Export followed by import yields a byte-identical tree and history. 5. At least two standard views are offered: mount and Git, or one of them plus S3. ## L1 Authority: who, on what authority, did what 1. A request without a lease is refused, and the refusal is recorded. 2. A request for a child lease wider than its parent is refused. 3. After a lease expires the mount becomes read-only; revocation takes effect within the time limit the implementation declares. 4. No lease can delete a snapshot. 5. Any commit can be `explain`ed back to a run, a lease and a read manifest. 6. Verification of the record chain passes; after one record is tampered with, verification fails. 7. When merging into a protected tree, the Gate Card shows a diff computed by the NAS, and the approval is bound to a digest: change the diff and the approval is void. ## L2 Memory: memory you can read and move 1. After all indexes are deleted and rebuilt, the golden recall tests pass. 2. Notes can be read without the Memory layer. 3. Every derivative carries a recipe and its inputs. 4. A budgeted read degrades when the budget is too small, and declares the view it actually returned. 5. Evidence pointers can be verified: after commits change, a pointer still points to the original content. ## L3 Guard: limiting consequences 1. Under a lease with B and C, when a session that read `external` content triggers a C-class action, it is refused or handed to a gate. 2. A derivative inherits the union of its inputs’ labels. 3. Notes written by a tainted session are not autoloaded. 4. A forget request produces a report that includes “what is not covered”; a legal hold can block forgetting. 5. Policy evaluation does not call an LLM: the policy engine makes no outbound calls to a model, so it can be audited. ## L4 Sync: multiple nodes 1. After two nodes synchronize, the trees are identical. 2. Highly sensitive objects are not sent to a node with a lower clearance. 3. Tombstones for forgetting propagate to the peer. 4. A handoff bundle can be executed on the peer, and leases only get narrower. ## The declaration format An implementation must publish a `conformance.json` stating the level it conforms to, the result of each test and any known deviations. A claim of “compatible” without this file is not accepted. *conformance.json* ```json { "implementation": "example-nas", "version": "0.1.0", "spec": "0.2", "level": "L1", "tests": { "L0.1": "pass", "L0.2": "pass", "L0.3": "pass", "L0.4": "pass", "L0.5": "pass", "L1.1": "pass", "L1.2": "pass", "L1.3": "pass", "L1.4": "pass", "L1.5": "pass", "L1.6": "pass", "L1.7": "pass" }, "deviations": ["L1.3: revocation takes effect within 60 seconds"] } ``` ## Versions and compatibility - Semantic versioning. No compatibility is guaranteed during 0.x. - New fields are backward compatible. - A deprecated field keeps a warning period of at least one version. ## What the specification does not cover yet Version details of transport protocols, a specific policy language, the signing algorithm for tokens, specific storage engines, and user interfaces. --- Canonical URL: https://agentnas.com/spec/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Roadmap > The roadmap is ordered as now, next, later and not planned, with no year-by-year promises: a three-year schedule written in 2026 would most likely be rewritten by facts within the first year. ## Now, next, later - **Now (Q4 2026)** · In progress · **Concept, draft specification and website**: The concept and draft specification v0.2, and the website in 8 languages. Gathering feedback: interview 3 to 5 real users who already combine `AGENTS.md` with Git, to test bets B1 to B7. - **Next (target: first half of 2027)** · Next · **Reference implementation v0 and specification v0.3**: Reference implementation v0 (Lite and Overlay): Git and file-system snapshot backends, lease issuance, records and read manifests, a CLI, and a conformance suite for L0 to L1; specification v0.3 (Core, Lease & Record). One demonstrable scenario: an agent works on a branch overnight, and in the morning you approve the merge on a Gate Card. - **Later (depends on feedback)** · Later · **Memory, Guard, the control room and Sync**: The Memory layer and the MCP tool surface (L2); Guard: labels, taint and cascade forgetting (L3); the control room; the Team and Cloud forms; Sync (L4). > **Not binding.** This is intent, not a promise. What defines “compatible” is the conformance levels, not the calendar. ## The stage gate (what would prove us wrong) The bar for finishing “next” is **not** a feature list. It is: running for a week in at least three real workflows; a gate approval rate below 95%; and at least one real problem caught. If we cannot meet it, we go back and change the concepts instead of piling on features. ## Not planned - Our own storage engine. - Our own vector database. - Model hosting. - A skill marketplace. - Tokens and blockchains. - Dedicated hardware. ## Questions left open on purpose - How does the free-text `purpose` in a lease evolve into structured intent that machines can check? - How are semantic mergers registered and trusted? - Should the granularity of labels be the file or the paragraph? - In multi-tenant settings, how is the label vocabulary governed? - How should the propagation delay of revocation between nodes be described to the outside world? - How do we measure memory quality? What is the regression standard when the model or the embeddings change? - For a fact inferred from several sources, how does Cascade Forget define the affected scope? - Under high throughput, how are the storage cost and granularity of read manifests traded off? - What is the best interface for batch and tiered review? How are the thresholds for automatic merging measured and tuned? - How are cross-organization roots of trust distributed and revoked? --- Canonical URL: https://agentnas.com/roadmap/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Design principles > Eight theses guide every trade-off in Agent NAS; seven bets say what it is wagering on and what happens if the wager is wrong. A design that hopes to hold for years should say when it will be wrong. ## 1. The unit of access is the run, not the account The current practice is to give an agent a long-lived token or a human account: the token in the April 2026 incident was “made for managing domains, yet could do anything”. A run has a start, an end, a purpose and a responsible party, which makes it a natural unit of authorization and accountability. *Rules out:* shared keys, long-lived tokens and borrowed human accounts. ## 2. Undo is cheaper than prevention Prevention (approvals, classifiers, rules in prompts) will always leak: classifiers miss things, people are worse, and models break principles written into their prompts. Making mistakes **undoable** (branches, soft delete, snapshots) is much easier than making every action correct, and easier to verify. A corollary: **the recovery path must lie outside the blast radius of what it protects**, so snapshots are held by the owner and are outside the power of any lease. *Rules out:* treating “a line in the prompt asking for confirmation” as a control. ## 3. Authority is lent per task, not granted per identity A run receives a narrow, time-limited lease with budgets; long-lived keys stay with the orchestrator or the owner, and the model never sees them. *Rules out:* long-lived, broad, standing permissions. ## 4. Notes are truth, intelligence is cache Memory should be files people can read and edit; indexes, embeddings and summaries are disposable, rebuildable derivatives. That way the retrieval algorithm can change without losing memory, and poisoning and deletion become tractable. *Rules out:* opaque memory stores that cannot be inspected or moved. ## 5. Provenance is the spine Every memory, every derivative and every merge can answer “where did it come from, and what influenced it?”. Provenance is the basis of audit and also of poisoning control, trust labels and forgetting. *Rules out:* memory without provenance. ## 6. Policy is deterministic, and models can only tighten Authorization decisions are made by code, not by a model’s “opinion”. A classifier or an LLM may suggest that “this step needs approval”, but can never approve. *Rules out:* letting a model decide for itself whether something may go through. ## 7. Keep storage boring, put innovation in the contract No new engine; files first, because the interface models know best is the file; protocols will change, the six nouns will not. *Rules out:* inventing a new storage engine in the name of AI. ## 8. What is scarce is tokens and human attention Reads get a budget; approvals are few and specific, and sit where a person can really judge: at plans and merges, not at every action. *Rules out:* returning whole files by default; a pop-up for every action. ## Seven bets and what would refute them A design that hopes to hold for years should say what it bets on and when it would be wrong. | Bet | Basis | If wrong | | --- | --- | --- | | B1 Agents will keep using the file system and Git as their main working medium | Several mainstream runtimes have already moved to files. | If they move to dedicated “memory APIs”, Agent Home degrades into an export format; the other concepts do not depend on files and still stand. | | B2 “A run” remains the natural unit of authorization and accountability | Orchestrators generally start sandboxes per task or per session. | If long-lived autonomous processes appear, leases become rolling renewals with budgets, and the concept stays. | | B3 Prompt injection will not be eradicated at the model layer in the foreseeable future | Meta’s own wording; classifier miss rates; several attack studies. | If it is eradicated, Trust Labels become one cheap layer of defence in depth. | | B4 Human attention remains scarce | Data disclosed by Anthropic. | If full automation becomes reliable enough, a Human Gate gives way to pre-authorizing policy, and the audit stays. | | B5 The storage layer is the right place to enforce provenance and taint | Memory-security research stresses provenance at write time; OpenClaw did the same inside one runtime. | If every runtime does it well itself, the NAS only needs to store labels, and its role gets thinner. | | B6 Memory shared across runtimes and agents will become a real need | Multi-agent collaboration; the cost of migrating frameworks. | If memory stays a private feature of each framework, Agent Memory’s value lies mainly in portability for individuals and small teams. | | B7 Protocols will change, but “files plus tools” as two ports will stay stable | MCP version migrations; A2A 1.0. | Swap the adapters; this is why adapters isolate the protocols. | ## What we expect to stay stable, and what to change | Expected to stay stable | Expected to change | | --- | --- | | The six nouns | Specific protocols and transports | | The directory convention of a Home | Embedding models and retrieval algorithms | | The four promises | Token formats | | The guarantee of “export means exit” | Agent frameworks and human-computer interfaces | --- Canonical URL: https://agentnas.com/principles/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # FAQ > Answers to the questions people ask first about Agent NAS: what it is, how it differs from existing storage and memory tools, how it deals with security and privacy, and where the project stands. ## The basics ### What is Agent NAS? Agent NAS is network-attached storage designed around the run: every agent run works in an isolated branch and reaches data through a short-lived, narrow lease; every change can be traced and undone; and memory is plain files with provenance. It is served through mounts, Git, S3 and MCP. ### Is Agent NAS a product I can buy or download? Not yet. It is currently a concept with a draft specification (v0.2, November 2026). L0 and L1 can be built today from existing parts; the target for reference implementation v0 is the first half of 2027, and the plan after that is on the [roadmap](https://agentnas.com/roadmap/). ### How is it different from the AI agents that NAS vendors ship? The agents from vendors such as QNAP, Synology and TrueNAS manage the box. Agent NAS specifies how other agents work on the data inside the box: branches, leases, memory and forgetting. The two complement each other; see the [comparison](https://agentnas.com/compare/). ### How is it different from a vector database or a memory framework? Those are tools for retrieval and consolidation, whereas the truth in Agent NAS is plain notes with provenance. A vector store or memory framework can sit under [Agent Memory](https://agentnas.com/concepts/agent-memory/) as an indexer, and the index can always be thrown away and rebuilt. ### Is it open source? The specification and this site are licensed under CC BY 4.0. The reference implementation is planned as open source under Apache-2.0. ## Design and security ### Why files and Git rather than a database? Agents are converging on files: instructions in `AGENTS.md`, skills in `SKILL.md`, memory as Markdown, history in Git. Any tool and any model can read files, they are easy to compare, and easy to take with you. Databases and indexes are still used, but as a derived layer that can be rebuilt. ### What is the worst that can happen when a run goes wrong? The worst case is losing a disposable branch: the protected main line changes only through reviewed merges, deletes are soft, and snapshots are outside every lease. That holds when the mistake happens inside the NAS; an email already sent or an external API already called is something the NAS cannot undo. ### How does a lease relate to an OAuth token? A lease is an OAuth access token: requested by token exchange (RFC 8693) and describing paths and actions with Rich Authorization Requests (RFC 9396). What Agent NAS adds is the run-level convention, including branches, budgets and Rule of Two properties. See [Capability Lease](https://agentnas.com/concepts/capability-lease/). ### Why “notes plus a cache” for memory? So that it can be inspected, corrected, moved and forgotten. Notes are files; indexes, embeddings and summaries are computed from them with a documented recipe. If you change the embedding model, the system recomputes in the background. Notes written by a tainted session go into quarantine first and are not autoloaded until reviewed. ### Can Agent NAS stop prompt injection? No. Nothing outside the model can stop it completely. Agent NAS limits what an injected agent can do: [Trust Labels](https://agentnas.com/concepts/trust-labels/) keep a session that read external content from also holding sensitive data and an outbound channel, and consequential actions need a [Human Gate](https://agentnas.com/concepts/human-gate/). The honest limits are on the [security](https://agentnas.com/security/) page. ### How does it handle the “right to be forgotten”? Through [Cascade Forget](https://agentnas.com/concepts/cascade-forget/): it deletes summaries, embeddings and notes derived from a source along lineage, handles history by retention class, and destroys keys for the `sensitive` class (crypto-shredding). Its report explicitly lists what it cannot cover: copies outside the NAS, model-provider logs and model weights. It cannot make a model forget anything. ### Do I have to use MCP? No. MCP is just one of the control-plane interfaces; files, Git and S3 do not need it, and the protocol layer is designed to be replaceable. ## Adoption and the future ### Will it replace my existing NAS or cloud storage? No. The Overlay deployment form puts a gateway in front of an existing NAS, object store or Git host and manages only one directory or bucket within it. Cloud storage can also serve as the Store. ### Which agent frameworks and runtimes work with it? Any runtime that can mount a directory or use Git, S3 or MCP. The layout of an Agent Home follows open conventions (`AGENTS.md`, Agent Skills, Markdown with YAML frontmatter), so Claude Code, Cursor, Codex, OpenHands, LangGraph and homegrown frameworks are all candidates. ### Can I leave at any time? Yes. Everything can be exported as plain files and Git history. This is one of the four promises, not a feature. ### When should I not use Agent NAS? When you have one agent and data you can happily redo: a Git repository with an `AGENTS.md` is enough. More cases are in [use cases](https://agentnas.com/use-cases/). ### How do I cite it or contribute? Every page lists its canonical URL and a suggested citation. To contribute, open an issue or start a discussion on GitHub. Details are on the [about page](https://agentnas.com/about/). --- Canonical URL: https://agentnas.com/faq/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Glossary > This glossary defines every term Agent NAS uses: the nine named concepts and the supporting vocabulary. The concept names are coined terms and stay in English in every language. ## The nine concepts - **[Agent Home](https://agentnas.com/concepts/agent-home/)**: **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. - **[Agent Branch](https://agentnas.com/concepts/agent-branch/)**: **An Agent Branch** lets each run work on a copy-on-write branch. Changes reach the protected main line only through a reviewed merge (an Agent PR), and you can checkpoint and restore at any time. - **[Flight Recorder](https://agentnas.com/concepts/flight-recorder/)**: **A Flight Recorder** is an append-only, hash-linked record kept per run: what the run read (the read manifest), what it wrote, what was allowed or denied, and who approved what. It sits beside the data and answers one question: “what may have influenced this change?” - **[Capability Lease](https://agentnas.com/concepts/capability-lease/)**: **A Capability Lease** is an authorization for specific data and specific operations, with an explicit expiry and budgets. It is issued to **one run** and is the only way a run touches the NAS. A child lease can only be narrower than its parent. - **[Human Gate](https://agentnas.com/concepts/human-gate/)**: **A Human Gate** is a policy-triggered checkpoint: before an **irreversible, outward-facing or privilege-raising** action takes effect, a person (or a designated approver) approves one fully rendered, concrete action. It is designed to be rare, specific and hard to rubber-stamp. - **[Trust Labels](https://agentnas.com/concepts/trust-labels/)**: **Trust Labels** are two very small label sets attached to data, **origin** (`owner`, `agent`, `external`) and **sensitivity** (`public`, `private`, `secret`), plus **session taint**. The NAS enforces the Rule of Two as a session invariant: a session cannot have all of [A] has read external content, [B] touches sensitive data and [C] changes protected state or communicates outward. Completing the third requires a [Human Gate](https://agentnas.com/concepts/human-gate/). - **[Agent Memory](https://agentnas.com/concepts/agent-memory/)**: **Agent Memory** = **notes you can read and edit** + **indexes you can throw away at any time**. Every note cites its sources; indexes (full-text, vector, graph, outline) are only derivatives of the notes; and background maintenance jobs only **propose** edits and never rewrite the raw journal. - **[Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/)**: **Budgeted Reads** are reads measured in a token budget: the same file can be read at different levels of detail, from outline and section to line range and full text. The agent asks for “the best view that fits in N tokens” and gets evidence pointers back to the exact source. - **[Cascade Forget](https://agentnas.com/concepts/cascade-forget/)**: **Cascade Forget** is deletion along lineage: when a source is deleted, or someone asks to be forgotten, the NAS finds everything derived from it, including summaries, embeddings, notes that cite it, caches and share links, deletes it or re-derives it without that source, and issues a **report**: what was done, and what could not be. ## Supporting terms - **Principal**: An entity that can be authenticated and held accountable: a human, an agent, a service or a node. - **Run**: One execution with a start, an end, a purpose and a responsible party. A run holds one root lease and owns one branch. - **Protected tree**: A tree that can only be updated through a reviewed merge and never accepts direct writes, for example `main`. - **Read manifest**: The aggregated record of the paths, commits, ranges and content hashes a run has read. It contains no content. - **Evidence pointer**: A verifiable reference of the form `nas:////@#L12-L18` to exact lines in one commit. - **Derived data**: Data computed from notes by a recipe, such as an index, an embedding or a summary. It can be discarded and rebuilt. - **Recipe**: Everything needed to produce a derived object: the model and its version, the chunker and the settings. - **Lineage**: The dependency graph between derived objects and the inputs they were computed from. - **Session taint**: The union of the labels of everything a session has read. It only grows within a session and decides what the session may do next. - **Rule of Two**: A heuristic from Meta: until prompt injection is reliably solved, a session should have at most two of three properties: [A] processes untrustworthy input, [B] accesses sensitive data, [C] changes state or communicates externally. - **Declassification**: Lowering the sensitivity of data, or raising the trust in its origin. Only through a Human Gate or a schema-validated structured handoff. - **Policy envelope**: A range set in advance by the owner within which leases are issued automatically. Requests outside it go to a Human Gate. - **Credential Broker**: A component that holds long-lived secrets and mints short-lived downstream tokens only for approved egress actions. Models and runs never see the long-lived secrets. - **Agent PR**: A structured proposal to merge a branch into a target, with the diff, provenance, check results and a label summary. - **Retention class**: One of `scratch`, `normal` or `sensitive`, chosen at write time. It decides backups, history and whether the data can be shredded. - **Crypto-shredding**: Destroying a key so that every copy encrypted with it becomes unreadable. - **Conformance level**: A level from L0 to L4. Each corresponds to a set of concepts and a set of executable acceptance tests. - **MCP**: Model Context Protocol: an open protocol between agents and tools or data sources. - **A2A**: The Agent2Agent protocol: an open protocol for agents to collaborate on tasks. --- Canonical URL: https://agentnas.com/glossary/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # About > agentnas.com is the home of the Agent NAS concept and its draft specification. It is an open project that aims to give people and agents a shared vocabulary, and a testable contract that several independent implementations can follow. ## Status As of November 2026, Agent NAS is a concept with a draft specification (v0.2). There is no reference implementation yet and no runnable conformance suite. v0.2 is a grounding revision: thirteen concepts were reduced to nine, and each states how to start small and what its honest limits are. This website is the first thing the project has published. See the [roadmap](https://agentnas.com/roadmap/) for the plan. ## License The text and diagrams of this site and the specification are licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): share and adapt, as long as you give credit. The reference implementation is planned to be released under Apache-2.0. ## How to cite Please cite the page you used, and quote its definition verbatim where you can. Every page ends with its canonical URL and a suggested citation. To cite the project as a whole: *Citation* ```text Agent NAS project. “Agent NAS: network-attached storage for AI agents.” Specification v0.2 (draft), November 2026. https://agentnas.com/what-is-agent-nas/ ``` *BibTeX* ```bibtex @misc{agentnas2026, title = {Agent NAS: network-attached storage for AI agents}, author = {{Agent NAS project}}, year = {2026}, howpublished = {Specification v0.2 (draft)}, url = {https://agentnas.com/what-is-agent-nas/} } ``` ## Governance - **Specification and implementations are separate.** Many implementations are welcome; what defines “compatible” is the conformance tests and `conformance.json`, not a brand. - **Process.** Public proposals (issues and PRs); significant changes must state their motivation, evidence and counter-examples. - **Naming.** “Agent NAS” is a descriptive name for the concept; claiming a level of conformance requires publishing a `conformance.json`. - **Disagreement is welcome.** Challenges to any thesis are valuable, especially the [seven bets](https://agentnas.com/principles/). ## Take part Corrections, critique and implementation notes are welcome. Open an issue or a discussion in the [project repository](https://github.com/xwzy/agentnas.com). This site does not publish an email address; security reports about the specification use the same channel. ## For agents and crawlers - Every page has a Markdown twin: append `index.md` to the URL, or send `Accept: text/markdown`. - [/llms.txt](https://agentnas.com/llms.txt) is a curated index, and [/llms-full.txt](https://agentnas.com/llms-full.txt) is the full text. - An MCP server for this documentation runs at `https://agentnas.com/mcp`, described by its [server card](https://agentnas.com/mcp/server-card). - A search endpoint, `POST /api/search`, is described in [/openapi.json](https://agentnas.com/openapi.json). - The [AI Catalog](https://agentnas.com/.well-known/ai-catalog.json) and the [sitemap](https://agentnas.com/sitemap.xml) list everything. - The content is free to index, quote and use as answer input. See [/robots.txt](https://agentnas.com/robots.txt). --- Canonical URL: https://agentnas.com/about/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # 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 --- # Agent Branch *Each run works on a copy-on-write branch. Only a reviewed merge reaches the main line.* > **An Agent Branch** lets each run work on a copy-on-write branch. Changes reach the protected main line only through a reviewed merge (an Agent PR), and you can checkpoint and restore at any time. **AN-02** · Conformance level: L0 Files · Cluster: Work ## The problem Agents make mistakes at machine speed, and shared data has no way to “try it, see the diff, review, undo”. Parallel agents also step on each other. In an April 2026 incident, an agent used an over-broad token to delete a production volume and the backups on the same volume within 9 seconds. If it could only have written to a branch, if deletes were soft, and if snapshots were outside its authority, that would have been far smaller. ## How it works - **Branches are cheap** (depending on the engine, ideally close to O(1)). A lease grants writes **inside the branch** and `propose` towards the target. - **Protected trees.** The main line can only be updated through a merge: even a leaked credential cannot write to it directly. - **Agent PR.** The diff, intent, provenance (a read-manifest summary), check results and a label summary. If checks pass and policy allows, it merges automatically; otherwise it goes to a [Human Gate](https://agentnas.com/concepts/human-gate/). - **Soft delete.** Deletes in a protected tree go to a recycle area, kept for 7 days by default; snapshots are owned by the owner and are **outside the authority of any lease**. - **Checkpoints.** Named snapshots; `restore` rolls files back to a checkpoint. - **Merging.** Text uses a three-way merge and other files merge per file. On conflict it stops and **never overwrites silently**; structured data needs a registered merger, or a person. - **TTL and quota,** to prevent branch bombs. - **Parallel attempts.** Open N branches for one task, merge the best and recycle the rest. ## Start small - Git branches and worktrees, plus a **protected main** on Forgejo, Gitea or GitHub. - For big directories use btrfs or ZFS snapshots and clones; for object storage use Tigris or lakeFS forks. - Get “deletes go to the recycle area” and “snapshots belong to the owner” right first. They are the cheapest and prevent the most damage. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *nas cli* ```bash nas branch create cleo/release-notes --from main --ttl 48h nas checkpoint create before-refactor nas propose --into main --checks links,schema nas restore before-refactor nas trash list # recycle area, kept 7 days by default nas trash restore ``` ## What the specification asks for - A protected tree MUST be updatable only through a merge; no credential may write to it directly. - A merge MUST produce a commit that carries provenance (run, lease, principal). - No lease MAY allow deleting a snapshot or a backup. - A delete in a protected tree MUST be soft and recoverable within the configured window (7 days by default). - A conflict MUST NOT be resolved silently; the merge MUST stop and report. - A branch MUST have a TTL and a quota. ## Borrowed, and what is new What follows is all established practice. **What is new:** binding the branch to a **run and a lease**, so the branch is the unit of authorization and the merge is the unit of review. Branches and snapshots themselves are not new. - [Git worktree](https://git-scm.com/docs/git-worktree) - [lakeFS for agents](https://lakefs.io/agentic-ai/) - [Tigris Agent Kit](https://www.tigrisdata.com/docs/ai/agent-kit/) - [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/) ## Honest limits - A branch only protects data inside the NAS. It **does not undo external side effects**: an email already sent, an API already called. - Large binary files and database files are hard to merge. - Review fatigue can still happen, so low-risk paths may merge automatically and the approval rate is measured. ## Open questions - How are semantic mergers registered and trusted? - How should interaction around binary conflicts work? ## Questions ### How is this different from a Git branch? Mechanically it is not magic: you can build it on Git. The difference is that it ties the branch to one run and one lease, so “can only write its own branch” becomes an authorization rule and the merge becomes the single review point. ### Does a branch prevent every accident? No. It only protects data inside the NAS: an email already sent or an external API already called is not undone by rolling back a branch. Such actions should go through `egress` in the lease and a Human Gate. ### Does every merge need a person to approve it? No. A merge whose checks pass, whose run read no external content and that does not involve deleting or sharing can go through automatically. A person is needed only in a few cases; see [Human Gate](https://agentnas.com/concepts/human-gate/). ## Related concepts - [Human Gate](https://agentnas.com/concepts/human-gate/): Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff. - [Agent Home](https://agentnas.com/concepts/agent-home/): A directory per role, with history. Plain files you can take with you. - [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read. --- Canonical URL: https://agentnas.com/concepts/agent-branch/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Flight Recorder *A per-run, hash-linked record that includes what the run read.* > **A Flight Recorder** is an append-only, hash-linked record kept per run: what the run read (the read manifest), what it wrote, what was allowed or denied, and who approved what. It sits beside the data and answers one question: “what may have influenced this change?” **AN-03** · Conformance level: L1 Authority · Cluster: Work ## The problem In a post-mortem, logs are scattered; there is no link between a “read” and the action that followed; and logs can be edited by the same administrator, or even the same agent. More fundamentally: when a merge or a memory is suspected of being contaminated, there is no way to answer “what did that run read?”. ## How it works - **Two kinds of content.** *Events* are recorded one by one: commits, lease issuance and revocation, gate requests and decisions, policy denials, derivations, forgetting. The *read manifest* is aggregated per run: which paths@commit, which ranges and which content hashes were read. It does not record every read call, and it never records content. - **Every commit carries provenance metadata:** `principal`, `on_behalf_of`, `run`, `lease`, `purpose` and a reference to the read manifest. - **A hash chain** (per day), with optional signatures and external anchoring (a second node, a bucket with object lock). The goal is “**tampering can be detected**”, not “tampering is impossible”. - **Export:** OpenTelemetry GenAI spans, JSON Lines, or into a SIEM. - **Privacy:** metadata only by default, no content; retention of records is independent of deletion of content; the records themselves are access-controlled. - **`explain(commit)`:** returns the run, lease, gate decisions, read manifest and inputs behind that commit. - **Record first, then act:** a consequential operation must first write an intent record. ## Start small - An append-only SQLite table plus a daily hash. - Git trailers such as `Run:` and `Lease:` in every commit message. - Export OpenTelemetry spans into the observability stack you already have. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *record.json* ```json { "seq": 18211, "time": "2026-11-12T09:14:22Z", "kind": "commit", "run": "run_91ab", "principal": "agt_cleo", "on_behalf_of": "usr_wei", "lease": "lse_7Qk3", "purpose": "Draft the Q4 release notes", "subject": { "path": "/shared/launch/notes.md", "commit": "91ce3a7" }, "read_manifest": "rm_5d2e", "decision": { "effect": "allow", "rule": "r-17" }, "taint": { "external": true, "sensitivity": "private" }, "prev_hash": "sha256:b3a0..." } ``` ## What the specification asks for - A consequential operation MUST write an intent record before taking effect; if the write fails, the operation MUST fail. - Every run MUST have a read manifest recording the paths, commits and ranges read (not the content). - Records MUST be hash-linked and MUST be verifiable with a published command. - `explain(commit)` MUST return the run, the lease, the gate decisions and a reference to the read manifest. - Retention of records MUST be independent of deletion of content. ## Borrowed, and what is new What follows is all established parts. **What is new is the read manifest:** it turns “reading” into a traceable set of inputs, so that “a contaminated merge” and “poisoned memory” can be investigated after the fact. - [OpenTelemetry GenAI conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) - [Certificate Transparency](https://certificate.transparency.dev) - [Sigstore Rekor](https://docs.sigstore.dev/logging/overview/) - [Git trailers](https://git-scm.com/docs/git-interpret-trailers) ## Honest limits - Without external anchoring, an administrator with root can still destroy the log. - The records themselves contain sensitive metadata and must be controlled. - The granularity of the read manifest is a trade-off between storage cost and traceability. ## Open questions - How is the storage cost of read manifests kept under control at high throughput? - How are records from several nodes merged and verified? ## Questions ### Does it record the content the agent read? Not by default. A record holds paths, commits, ranges and content hashes: enough to point back to the original data without copying sensitive content into a log. The content stays in the Store, protected by leases and labels. ### What does “tamper-evident” mean here? We promise only that **tampering can be detected**: records are hash-linked, so changing one breaks chain verification; with external anchoring (a second node or a bucket with object lock) it also holds up against an administrator with root. Without anchoring, an administrator can still destroy the whole log. ### Why record reads? Because risk often comes from reading: a session that read a web page may then write a contaminated note. The read manifest lets you answer afterwards “what influenced this change?”. ## Related concepts - [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. - [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two. - [Cascade Forget](https://agentnas.com/concepts/cascade-forget/): Delete derivatives along lineage, handle history by retention class, and report what it could not do. --- Canonical URL: https://agentnas.com/concepts/flight-recorder/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Capability Lease *A narrow authorization for one run, with an expiry and budgets. Child leases can only be narrower.* > **A Capability Lease** is an authorization for specific data and specific operations, with an explicit expiry and budgets. It is issued to **one run** and is the only way a run touches the NAS. A child lease can only be narrower than its parent. **AN-04** · Conformance level: L1 Authority · Cluster: Authority ## The problem RBAC and ACLs assume stable users with broad, lasting permissions. An agent needs permissions cut to the task that stop when the task ends. Worse, long-lived credentials often sit where the agent can reach them: in the April 2026 incident the token was in an unrelated file, created to manage domains but able to do anything. ## How it works - **Who holds the key.** Long-lived credentials stay with the orchestrator or the owner; a run receives a lease, not a key. The model never sees a long-lived credential. - **A lease is an access token.** Its `authorization_details` ([RFC 9396](https://www.rfc-editor.org/rfc/rfc9396)) describe paths, actions and the branch; it is requested by the owner or orchestrator through [token exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693), the `act` claim records the delegation chain, and the NAS keeps state for revocation and budget counting. - **Only narrowing.** A child lease must be a subset of its parent, checked by the NAS at minting time. - **Budgets.** Bytes read and written, request counts and optionally egress bytes and a spending cap, counted at the gateway. They are a **circuit breaker**, not exact billing. - **Policy envelope.** The owner sets a range in advance; leases inside it are issued automatically and anything outside goes to a [Human Gate](https://agentnas.com/concepts/human-gate/). Long-lived access is expressed as an envelope, not as a long-lived lease. - **B and C are declared explicitly.** A lease states the highest sensitivity it may read and whether it may write to protected trees or send data out. These are inputs to [Trust Labels](https://agentnas.com/concepts/trust-labels/). - **Revocation.** A short TTL (4 hours by default, 24 at most) plus immediate revocation, which cascades to child leases. - **`purpose` is recorded, not enforced:** free text cannot be checked by a machine. ## Start small - Write a `nas lease create` command: for each role, issue a token with a path prefix, actions and a TTL, hand it to the sandbox in an environment variable, and have the NAS enforce prefix and actions. - This already stops the first half of that kind of incident: the token cannot do anything outside the lease. - Budgets, delegation chains and policy envelopes can come later. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *lease.json* ```json { "lease_id": "lse_7Qk3", "run": "run_91ab", "principal": "agt_cleo", "on_behalf_of": "usr_wei", "parent": null, "purpose": "Draft the Q4 release notes", "paths": ["/shared/launch/**", "/agents/cleo/workspace/**"], "actions": ["read", "write", "propose"], "branch": "cleo/run_91ab", "sensitivity_max": "private", "egress": false, "requires_gate": ["merge", "delete", "share"], "budgets": { "bytes_read": 200000000, "bytes_written": 5000000, "requests": 5000 }, "expires_at": "2026-11-12T16:00:00Z" } ``` ## What the specification asks for - A lease MUST have an expiry and MUST NOT be renewed beyond the maximum TTL; renewal requires a new issuance. - A child lease MUST be a subset of its parent, and the NAS MUST verify this when minting. - Revoking a lease MUST cascade to all of its child leases. - Long-lived access MUST be expressed as a policy envelope and MUST NOT be made a long-lived lease. - A lease MUST declare its sensitivity ceiling and whether it allows egress and protected writes. - Long-lived credentials MUST NOT be exposed to a model or a run. ## Borrowed, and what is new What follows is all established parts. **What is new:** taking the **shape of a run and a task** as the unit and putting the branch, budgets and the Rule of Two properties into one lease. Tokens and capability models themselves are not new. - [OAuth Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693) - [OAuth Rich Authorization Requests (RFC 9396)](https://www.rfc-editor.org/rfc/rfc9396) - [Biscuit](https://github.com/biscuit-auth/biscuit) - [UCAN](https://ucan.xyz/specification/) - [IETF attenuating agent tokens draft](https://datatracker.ietf.org/doc/draft-niyikiza-oauth-attenuating-agent-tokens/) ## Honest limits - It only covers operations inside the NAS and cannot govern what an agent does elsewhere. - `purpose` cannot be enforced, and budgets are approximate. - A lease cannot prevent misuse **within legitimate authority**; that is the work of branches and gates. ## Open questions - How can `purpose` move from free text to structured intent a machine can check? - How are budgets accounted for under federation? ## Questions ### How is a lease different from an API key? An API key is a long-lived shared secret, and its holder can do whatever the account can. A lease is bound to one run, limits paths, actions and time, and can only be narrowed; it stops working at expiry and can be revoked at any time. ### Why not just use OAuth? It is OAuth: a lease is an access token, requested through token exchange (RFC 8693) and described with rich authorization requests (RFC 9396). Agent NAS only adds what OAuth does not specify: the run as the unit, and putting the branch, budgets and Rule of Two properties into one authorization. ### What happens to a run when its lease expires? The mount turns read-only and is then unmounted; new requests are refused and recorded. The branch is kept until its own TTL expires, so finished work is not lost and can still be merged after review. ## Related concepts - [Human Gate](https://agentnas.com/concepts/human-gate/): Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff. - [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two. - [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read. --- Canonical URL: https://agentnas.com/concepts/capability-lease/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Human Gate *Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff.* > **A Human Gate** is a policy-triggered checkpoint: before an **irreversible, outward-facing or privilege-raising** action takes effect, a person (or a designated approver) approves one fully rendered, concrete action. It is designed to be rare, specific and hard to rubber-stamp. **AN-05** · Conformance level: L1 Authority · Cluster: Authority ## The problem Today’s “human in the loop” is either an endless stream of prompts or nothing at all. Anthropic reports that Claude Code users approve 93% to 97% of permission prompts; in its controlled experiment, people caught only 13.6% of planted dangerous commands, and did worse as sessions got longer. This is vendor research done to promote auto mode, and it measures spotting planted prompts rather than production incident rates, but the direction is clear. The same data holds another number: users reject 39% of plans but only 3% of individual permission requests. What people judge seriously are plans and merges, not every tool call. ## How it works - **It appears in few places:** merging into a protected tree, deleting from a protected tree, sharing or publishing externally, egress, widening a lease and lowering a label. Writes on a branch need no approval. - **The granularity is a plan or a merge.** Review one PR, not fifty prompts. - **The Gate Card is rendered by the NAS:** the real diff, a read-manifest summary, the lease and the session taint, never the agent’s own account. Options: approve, approve narrowed, deny; a timeout defaults to deny. - **An approval is bound to the action digest:** it binds the diff hash and the lease and cannot be replayed. - **Delivery:** push, chat, email or CLI; it can be delegated; passkeys are an optional strong authentication. - **Escalate only.** An optional risk classifier (including an LLM) may only **escalate** an action to a gate and never **approve** one. A model can only tighten, never loosen. - **Fatigue is measured:** approval rate and time to approve; when the approval rate is unusually high, that suggests merging gates or tightening policy. ## Start small - A protected main plus PR review (any Git platform will do) and a push notification. - Or a CLI: `nas gate approve `. - Make the Gate Card show the “real diff” first; do not rush into fancy interfaces. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *gate-card.json* ```json { "gate_id": "gt_2Mx4", "run": "run_91ab", "action": { "op": "merge", "from": "cleo/run_91ab", "into": "main", "files_changed": 4, "diff_sha256": "7d2a..." }, "why": "Release notes are ready for review", "risk": { "session_taint": ["external"], "sources": ["web:example.com/changelog"], "destructive": false, "egress": false }, "options": ["approve", "approve_narrowed", "deny"], "default": "deny", "expires_at": "2026-11-12T12:00:00Z" } ``` ## What the specification asks for - A Gate Card MUST show the real diff computed by the NAS, not the agent’s description of it. - An approval MUST be bound to the action digest and the lease and MUST NOT be replayable. - The default outcome of a timeout MUST be denial. - A classifier or an LLM MUST NOT grant approval; it MAY escalate an action to a gate. - Merging into a protected tree, deleting from a protected tree, external sharing, egress, widening a lease and lowering a label MUST go through a gate. - The NAS SHOULD report the approval rate and the time to approve. ## Borrowed, and what is new What follows is all established practice. **What is new:** anchoring approval on **the merge at the storage layer** and having the NAS (not the agent) render the content. Approval and PRs themselves are not new. - [How we built Claude Code auto mode](https://www.anthropic.com/research/claude-code-auto-mode) - [Anthropic: approval data behind auto mode](https://claude.com/resources/articles/auto-mode-default-in-claude-code) - [CaMeL](https://arxiv.org/abs/2503.18813) - [WebAuthn](https://www.w3.org/TR/webauthn-3/) - [OpenID CIBA](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) ## Honest limits - A person can still approve the wrong action; batch review also causes fatigue. - Notification channels can be phished. - An approval cannot stop something **outside what was approved**; that is the lease’s job. ## Open questions - What is the best interface for batch and tiered review? - How is the threshold for automatic merging measured and tuned? ## Questions ### Isn’t this just another “confirm” dialog? Deliberately not. A dialog fires on every tool call and people soon click “approve”. A gate appears only before a few irreversible or outward-facing actions, shows the real diff computed by the NAS, and the approval binds the diff hash: if the diff changes, the approval is void. ### Can an LLM decide whether to let something through? It can suggest “a person should look at this step”; it cannot approve. The decision to let something through must be a deterministic rule or a person’s approval. This keeps security from depending on any model’s judgment. ### What happens on timeout? Deny by default. The run receives a clear refusal and can take another path, or leave the proposal on its branch for a person to deal with. ## Related concepts - [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. - [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two. - [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. --- Canonical URL: https://agentnas.com/concepts/human-gate/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Trust Labels *Two small labels plus session taint enforce the Rule of Two.* > **Trust Labels** are two very small label sets attached to data, **origin** (`owner`, `agent`, `external`) and **sensitivity** (`public`, `private`, `secret`), plus **session taint**. The NAS enforces the Rule of Two as a session invariant: a session cannot have all of [A] has read external content, [B] touches sensitive data and [C] changes protected state or communicates outward. Completing the third requires a [Human Gate](https://agentnas.com/concepts/human-gate/). **AN-06** · Conformance level: L3 Guard · Cluster: Authority ## The problem Prompt injection works because a model cannot tell “instructions” from “data”. Defences at the model layer (classifiers, prompt hardening) leak, and attackers can adapt. At the end of October 2025 Meta proposed the [Agents Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/): until injection is reliably solved, a session should have at most two of three properties. The more dependable approach is to bound the consequences **outside** the model. Storage is exactly where every read and write passes, so it is a natural place to turn this rule into a testable invariant. ## How it works - **Labels.** Three origins, three sensitivities and a `reviewed` flag (set by a gate approval). Import points (web pages, email, uploads) default to `external`; when a secret scanner finds credentials, it labels them `secret` automatically. - **Session taint.** The summary of everything a run has read (from the read manifest); within a session it only grows, and a new session starts clean. - **The invariant.** A = the session has read `external`; B = the lease may read `private` or above (threshold configurable); C = the lease may propose a merge into a protected tree, share, delete or send data out. When all three hold in one session, the call that triggers C is denied or sent to a gate. - **In practice:** under a lease that has both B and C, once a session has read external content, every later C-type action needs a person. To avoid that friction, do the “read external content” work in a separate session without B and pass results on through a structured handoff only. - **Propagation.** Derivations made by the NAS itself (indexes, summaries) deterministically inherit the union of their input labels; files a run writes inherit the run’s session taint (the conservative choice). - **Declassification.** Only through a Human Gate, or a **structured handoff:** the output of the tainted session is restricted to fields validated by a JSON Schema (enums, IDs, bounded strings), and only after validation may a privileged session read it. Only what can be validated deterministically can be trusted. - **Enforcement is at the gateway and the mount** (which know the lease and the session), not inside the model. ## Start small - Do just two things: label files in the import directory `external`, and by default give a run that has read `external` no egress and no protected merge without a gate. - Write the policy as deterministic rules in Cedar or Rego, and give readable reasons on denial. - Run in “log only” mode for a week to see what it would block by mistake, then switch enforcement on. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *policy.yaml* ```yaml # Deterministic policy (Cedar- or Rego-style rules can express the same thing) session_invariant: rule_of_two properties: A: session.read_origin includes "external" B: lease.sensitivity_max >= "private" C: lease allows propose_protected | share | delete | egress on_would_complete_ABC: gate # never "allow" rules: - id: r-merge-1 when: session.A and op == "merge" and target.protected then: gate - id: r-secret-1 when: session.read_sensitivity == "secret" and op == "egress" then: deny ``` ## What the specification asks for - Every import point MUST assign a default label; external content MUST be labelled `external`. - Session taint MUST only grow within a session. - Policy evaluation MUST be deterministic and MUST NOT call an LLM. - A call that would let a session complete A+B+C MUST be denied or sent to a gate. - Declassification MUST go through a gate or a schema-validated structured handoff. - Derived data MUST inherit the union of its input labels. ## Borrowed, and what is new What follows is all established thinking. **What is new:** implementing session taint at the **storage boundary** with the read manifest, and applying labels to memory writes and derived data. We deliberately keep the label lattice to 3×3 because fine-grained lattices lead to label explosion in practice. OpenClaw already does origin labels and isolation inside a single runtime; our difference is only to put this in shared storage. - [Agents Rule of Two (Meta)](https://ai.meta.com/blog/practical-ai-agent-security/) - [The lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) - [CaMeL](https://arxiv.org/abs/2503.18813) - [Fides](https://arxiv.org/abs/2505.23643) - [Design Patterns for Securing LLM Agents against Prompt Injections](https://arxiv.org/abs/2506.08837) - [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture) ## Honest limits - This is **not** a defence against prompt injection; it limits consequences. - The NAS cannot see tools outside it (a browser, email), so it needs the runtime’s cooperation. - Taint is conservative and brings friction and false positives; free text outside structured schemas can still carry an attacker’s words. - Covert channels cannot be eliminated. ## Open questions - Should the granularity of a label be the file or the paragraph? - How is the label vocabulary governed across tenants? - How can false positives be reduced? ## Questions ### Does the Rule of Two stop prompt injection? It does not stop injection from happening. It makes an injected session **unable to have all three** of “has read untrusted content, touches sensitive data, can change protected state or send data out”, which bounds the consequences. Meta itself stresses that it is a risk-reduction heuristic that does not replace least privilege. ### Why only three origins and three sensitivities? Because fine-grained label lattices tend to bloat and get switched off in practice. 3×3 is enough to say “who wrote it, how sensitive it is” and makes the reason for a refusal easy to understand. Finer partitions can be done with paths and leases. ### Will session taint leave the agent unable to do anything? It only restricts three kinds of action: changing a protected tree, sharing or deleting, and sending data out. Reads and writes inside a branch are unaffected. To avoid friction, put the work of reading external content into a session without sensitive data and pass back only results validated against a schema. ## Related concepts - [Human Gate](https://agentnas.com/concepts/human-gate/): Appears only before irreversible, outward-facing or privilege-raising actions, and shows the real diff. - [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/trust-labels/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Agent Memory *Notes you can read and edit are the truth. Indexes are a cache you can throw away.* > **Agent Memory** = **notes you can read and edit** + **indexes you can throw away at any time**. Every note cites its sources; indexes (full-text, vector, graph, outline) are only derivatives of the notes; and background maintenance jobs only **propose** edits and never rewrite the raw journal. **AN-07** · Conformance level: L2 Memory · Cluster: Knowledge ## The problem Memory frameworks put memory in opaque databases: you cannot inspect, diff, migrate or correct it, deleting it reliably is hard, and the index and the embedding model are locked in. And memory itself is an attack surface: in one [2026 study](https://arxiv.org/abs/2606.04329) persistent-memory poisoning reached an average attack success rate of 50.46% across two agents, and [another study](https://arxiv.org/abs/2607.05189) used one carefully crafted email to succeed against both file-system and vector memory backends. Meanwhile, “which memory architecture is best” is nowhere near settled: benchmarks contradict each other. A design that bets on no particular retrieval algorithm is the one that can survive three years of change. ## How it works - **Notes are the truth.** Markdown with YAML frontmatter: `kind` (episodic, semantic, procedural, preference), `subject`, `sources`, `confidence`, `valid_from`, `valid_to`, `supersedes`, `origin`, `reviewed`. - **Update, do not overwrite.** A new fact `supersedes` the old one; valid time and record time are kept apart, because facts change and common benchmarks barely test that. - **Indexes are a cache.** BM25 (for example SQLite FTS5), vectors (several can coexist) and an optional graph; every derivative carries its **recipe** and **inputs**. Changing the embedding model is a background recomputation, and the old index is kept until the new one meets the golden recall tests. - **Two kinds of derivation.** Deterministic ones (chunking, BM25, embeddings from a fixed model) are reproducible; generative ones (LLM summaries, extracted facts) can only be “regenerated and compared”, so they are marked `generated: true` and never serve as the only copy. - **Write path.** `nas_remember` writes a note (with sources) to the current branch, and taint is inherited. A note from a session with `external` taint goes into **quarantine**, marked unreviewed: it can be recalled but is **not autoloaded** and does not enter `MEMORY.md`. - **Read path.** `nas_recall` = search, candidates, a budgeted view plus evidence pointers, and it shows each note’s source and review state. - **Maintenance jobs** (overnight or when idle): deduplicate, consolidate episodes into semantic facts, flag contradictions, retire outdated facts, rebuild indexes. Jobs produce proposals on a branch for a person or an agent to review; they **never delete the raw journal**; the “regret rate” (the share of proposals that get rolled back) is measured. - **Golden recall tests.** For each Home, a set of “question, expected note” pairs that run automatically when the model or the indexer changes. ## Start small - `memory/notes/*.md` with frontmatter, and SQLite FTS5 for search. - Run ten golden questions in CI. - Vector indexes and maintenance jobs can come later; get “provenance” and “only reviewed notes autoload” right first. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *memory/notes/customer-acme.md* ```markdown --- id: mem_4kq2 kind: semantic subject: customer/acme valid_from: 2026-10-02 valid_to: null confidence: 0.8 origin: agent reviewed: true sources: - nas://home-box/agents/cleo/journal/2026-10-02.md@9f2c1de#L12-L18 supersedes: [mem_1xa9] --- Acme renewed for 24 months; the champion moved from Dana to Luis. ``` ## What the specification asks for - Notes MUST be readable without the Memory layer (they are plain files in the Store). - Every derivative MUST carry its recipe and inputs; an index MUST be disposable and rebuildable. - Notes written by a tainted session MUST NOT be autoloaded before they are reviewed. - A new fact MUST replace an old one with `supersedes` instead of overwriting. - Maintenance jobs MUST work on a branch and only propose; they MUST NOT delete the raw journal. - Every Home SHOULD carry golden recall tests and run them whenever the model or the indexer changes. ## Borrowed, and what is new What follows is all established thinking, and OpenClaw’s memory architecture already does provenance labels, per-tier quarantine and taint propagation during consolidation. **What is new:** OpenClaw does it **inside one runtime**; we propose doing it **in shared storage** so any runtime benefits, and demoting the index to a disposable cache so the retrieval algorithm can change without losing memory. - [Letta Context Repositories](https://www.letta.com/blog/context-repositories/) - [Letta: is a filesystem all you need?](https://www.letta.com/blog/benchmarking-ai-agent-memory/) - [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture) - [Long-term memory security survey](https://arxiv.org/abs/2604.16548) - [Graphiti](https://github.com/getzep/graphiti) - [MemGPT](https://arxiv.org/abs/2310.08560) ## Honest limits - Generative derivatives can never be reproduced bit for bit. - A maintenance job can “harden” a mistake into a fact, which is why it only proposes and never edits directly. - Which memory architecture is best remains unsettled. ## Open questions - When should an agent write memory itself, and when should a maintenance job? - What is the regression standard across model versions? ## Questions ### Why files rather than a vector database? Files are the truth you can read, edit, diff and take with you; a vector index is a derived cache that can coexist in several versions and be rebuilt at any time. Letta’s benchmark showed that an agent with just `grep` and file tools is competitive, but benchmarks contradict each other, so the design does not bet on one retrieval algorithm. ### How is memory poisoning prevented? It cannot be guaranteed that nothing bad is ever written, but the consequences can be bounded: content from outside carries the `external` label; notes written by a tainted session go to quarantine and are not autoloaded; merges are reviewed; and when something goes wrong you can follow the provenance chain to the affected notes and roll back. ### Do I have to migrate memory when I change the embedding model? No. The notes do not change; only the indexes are recomputed in the background with the new recipe, and the old index is kept until the new one meets the golden recall tests. ## Related concepts - [Budgeted Reads](https://agentnas.com/concepts/budgeted-reads/): Read a file as an outline, a section, a line range or in full, degrading to fit the budget. - [Cascade Forget](https://agentnas.com/concepts/cascade-forget/): Delete derivatives along lineage, handle history by retention class, and report what it could not do. - [Trust Labels](https://agentnas.com/concepts/trust-labels/): Two small labels plus session taint enforce the Rule of Two. --- Canonical URL: https://agentnas.com/concepts/agent-memory/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Budgeted Reads *Read a file as an outline, a section, a line range or in full, degrading to fit the budget.* > **Budgeted Reads** are reads measured in a token budget: the same file can be read at different levels of detail, from outline and section to line range and full text. The agent asks for “the best view that fits in N tokens” and gets evidence pointers back to the exact source. **AN-08** · Conformance level: L2 Memory · Cluster: Knowledge ## The problem Agents burn their context on whole files and repeated reads, and naive RAG chunking loses structure. Models are already good at `grep`, `tail` and reading by line: Cursor writes over-long tool output to files for agents to read on demand, and in runs that called an MCP tool, [dynamic discovery](https://cursor.com/blog/dynamic-context-discovery) of tool descriptions cut total tokens by 46.9%. So the problem is not “build another retrieval system”, but to give reading on top of files a **budgeted, checkable** contract. ## How it works - **Files first.** Standard reads (including line ranges) are always available; Budgeted Reads is an optional extension on top and does not replace the file system. - **Deterministic outlines (free):** the heading tree of Markdown, code symbols (tree-sitter), keys of JSON and YAML, headers and row counts of CSV. No LLM is needed. - **Budget and degradation.** A request carries `budget_tokens`; if it does not fit, it degrades to a coarser view **instead of truncating silently**; the response states the actual view, the token count and whether it is `generated`. - **Search returns snippets and pointers,** not whole files. - **Evidence pointers:** `nas:////@#L12-L18`, stable and verifiable against a commit; `dereference` returns the exact content. - **What changed since last time:** returns the diff between two commits instead of the whole file. - **An optional LLM summary layer:** as a cache, marked `generated: true` and with a staleness marker. ## Start small - Add nothing beyond `nas_read`: let the agent read the old way, with `rg` and `sed -n`. - Then add a small outline tool for Markdown and code. - Start evidence pointers as “path@commit#line”; no new service is needed. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *POST /v1/files/read* ```http POST /v1/files/read { "path": "/agents/cleo/memory/notes/customer-acme.md", "view": "outline", "budget_tokens": 400 } 200 OK { "view": "outline", "tokens": 212, "generated": false, "truncated": false, "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)", "evidence": [ { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" } ] } ``` ## What the specification asks for - A response MUST state the view actually returned and its token count; generative views MUST be marked. - When the budget is too small, the NAS MUST degrade to a coarser view and MUST NOT truncate silently. - Standard file reads (including ranges) MUST remain available. - Evidence pointers MUST be verifiable against a commit. - Search MUST by default return snippets and pointers instead of whole files. ## Borrowed, and what is new Progressive disclosure and grep are not new in themselves. **What is new:** making budgets and evidence pointers a **read contract at the storage layer**, so answers can be checked: you can get from a sentence back to the lines of the commit it came from. - [Cursor: dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery) - [Agent Skills (progressive disclosure)](https://agentskills.io/specification) - [Letta Context Repositories](https://www.letta.com/blog/context-repositories/) - [RAPTOR](https://arxiv.org/abs/2401.18059) ## Honest limits - Tokenizers differ between models, so token counts are estimates. - It only works if clients adopt it. - Summaries go stale and can be wrong, so they are only a cache and always marked. ## Open questions - How should budget error across different model tokenizers be handled? - How is summary quality evaluated? ## Questions ### How is this different from RAG? RAG returns the snippets closest to a question. Budgeted Reads lets a reader pick the level of detail for an object it already knows, degrades honestly when the budget is short, and gives verifiable pointers. They stack: search results can also come back as budgeted views. ### Do I have to use it to read files? No. Mounts and Git always give you plain files; Budgeted Reads is an optional read for agents that care about tokens. ### Can an evidence pointer stop “invented citations”? It makes citations checkable: a pointer names specific lines in a commit and its content hash can be verified. It does not stop a model from inventing things, but it turns “does the passage it quotes actually exist?” into a machine check. ## Related concepts - [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. - [Agent Home](https://agentnas.com/concepts/agent-home/): A directory per role, with history. Plain files you can take with you. - [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read. --- Canonical URL: https://agentnas.com/concepts/budgeted-reads/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0 --- # Cascade Forget *Delete derivatives along lineage, handle history by retention class, and report what it could not do.* > **Cascade Forget** is deletion along lineage: when a source is deleted, or someone asks to be forgotten, the NAS finds everything derived from it, including summaries, embeddings, notes that cite it, caches and share links, deletes it or re-derives it without that source, and issues a **report**: what was done, and what could not be. **AN-09** · Conformance level: L3 Guard · Cluster: Knowledge ## The problem Deleting a file does not delete its embeddings, its summaries or the facts memory inferred from it; snapshots and backups remain; and the content is still in version history. “Recoverable” and “forgettable” are two ends of one axis, and most systems do not hand that choice to a person. If you only think about forgetting after the write, it is usually too late. ## How it works - **Lineage.** Every derivative records its inputs; a reverse index answers “everything that depends on X”; a note’s `sources` field is lineage too. - **Retention class, decided at write time** (because history cannot be rewritten afterwards): `scratch` (short TTL, not in backups, can be cleaned when the run ends), `normal` (versioned, recoverable) and `sensitive` (its own key domain, which can be shredded by destroying the key). - **The tension between recovery and forgetting.** Recoverable inside the soft-delete window; hard-deleted only after it; a forget request may skip the window. - **Process.** A request (raised by a person or an operator; an agent can only ask, not execute), lineage traversal, deleting derivatives and re-deriving facts of mixed origin, rewriting the history of affected paths and cleaning snapshots for the `normal` class, destroying keys for the `sensitive` class, and finally the report. - **The report:** the number of files deleted, derivatives removed, whether history was rewritten, keys destroyed, snapshots not yet expired, and an **explicit list of what it does not cover:** copies outside the NAS, model-provider logs and model weights. - It always goes through a [Human Gate](https://agentnas.com/concepts/human-gate/) (or a pre-authorizing policy); a **legal hold** blocks forgetting and is recorded. ## Start small - Start with retention classes and soft delete, and record the inputs of every derivative. - First reach “when a source file is deleted, list and delete all of its derivatives”. - Leave crypto-shredding for the `sensitive` class; it need not be done everywhere at the start. ## Interface sketch Illustrative only. Field names may change before specification v0.3. *forget-report.json* ```json { "forget_id": "fgt_3b7c", "selector": { "paths": ["/shared/crm/acme/**"], "subject": "customer/acme" }, "retention_class": "sensitive", "report": { "files_removed": 142, "derived_removed": { "embeddings": 3621, "summaries": 210, "notes_rewritten": 6 }, "history": "rewritten (3 commits)", "keys_destroyed": ["key_acme"], "snapshots_pending": ["nightly-2026-11-10 (expires 2026-11-17)"], "not_covered": ["copies outside the NAS", "model provider logs", "model weights"] }, "state": "pending_expiry" } ``` ## What the specification asks for - Forgetting MUST propagate along lineage from the source to every derivative. - The retention class MUST be assigned at write time (`normal` by default). - A forget report MUST list what it does not cover: copies outside the NAS, provider logs and model weights. - A legal hold MUST block forgetting and MUST be recorded. - An agent MAY request forgetting but MUST NOT execute it. - A report MUST NOT claim that a model has “forgotten” anything. ## Borrowed, and what is new What follows is all established. **What is new:** treating the **retention class** as an explicit property of storage, and admitting that “recoverable” and “forgettable” are a trade-off on one axis. - [OpenLineage](https://openlineage.io) - [GDPR Article 17](https://gdpr-info.eu/art-17-gdpr/) - [Long-term memory security survey (forget and rollback)](https://arxiv.org/abs/2604.16548) ## Honest limits - Backups, copies outside the NAS and model-provider logs are out of scope. - For facts inferred from several sources, the “affected scope” is hard to define. - Rewriting history is expensive and carries risk. ## Open questions - How is the affected scope of a mixed-origin fact defined? - What should the process be when a legal hold conflicts with a forget request? ## Questions ### Can it make a model forget? No, and it will not claim to. What it can do is delete files and derivatives inside the NAS and, for the `sensitive` class, history and keys; model-provider logs and model weights are out of scope, and the report says so explicitly. ### Why choose a retention class at write time? Because history is hard to rewrite afterwards: what has already entered backups and history can only be rewritten or wait to expire. Deciding at write time whether something is `scratch`, `normal` or `sensitive` is the precondition for being able to delete cleanly later. ### Can an agent ask to forget something by itself? It can raise a request but not execute it. Forgetting is irreversible and must go through a person or a pre-authorizing policy, and a legal hold can block it. ## Related concepts - [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. - [Flight Recorder](https://agentnas.com/concepts/flight-recorder/): A per-run, hash-linked record that includes what the run read. - [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. --- Canonical URL: https://agentnas.com/concepts/cascade-forget/ Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0