# 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 `<role>/<run_id>` 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/<user>/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