How the Tropo Vault Works

One folder holds every piece of governed work a Studio produces — thousands of typed, indexed, linked artifacts that a person can read in any editor and an agent can query in milliseconds.

The Vault is the single place a Tropo Studio keeps its governed work. Every task, decision, spec, document, release, and agent identity lives there as a plain markdown file with a type, an owner, a lifecycle, and a line in one flat index. A human opens it in VS Code. An agent reads the same files under the same rules. There is one source of truth, and both of you share it.

That sounds modest — a folder of markdown. It is not. The Studio you are reading about right now, the one Tropo is built in, holds more than 3,500 governed entries across 49 types, linked into a graph of 2,774 nodes, every change provenance-stamped, every deletion recoverable. The Vault is a single filesystem operating as a typed, indexed, version-governed database — and it stays legible the whole way up.

Why a Vault, and not folders

Before the Vault, governed work lived in folders — one for tasks, one for specs, one for decisions. That holds until two things happen at once: the folders grow past the point a person can browse them, and an agent needs a single place to query instead of walking a tree. Both happen fast.

So Tropo replaces the folder-per-type model with one flat store and one index. One place to look, one place to check work in, one place to audit what exists. And it fixes three things folders never could:

Provenance stops getting lost. Every entry carries created_by, modified_by, and owner. Nothing happens anonymously; nothing loses its history.
Relationships become first-class. Entries declare member_of, depends_on, supersedes, and more. The Vault is a graph, not a pile.
The work outlives the worker. Agents are disposable; the substrate is not. When an agent's session ends, the governed files remain — which is how knowledge survives across AI generations instead of dying with a context window.

Rules travel with the artifact, not with its folder. Move the file, rename the directory — the governance stays, because the governance is the entry.

What's actually in there

"A folder of markdown" undersells it. Here is what the Vault is the moment you open a working Studio — not a starter kit, but the live Studio that built Tropo itself: more than 3,500 governed entries, 49 typed primitives, 81 capsule contracts, a 2,774-node graph, and 4,348 logged events. The proof is the product.

Four files do the heavy lifting. The store holds the artifacts; the index makes them queryable; the graph makes them related; the registry tracks the moving parts. The index is the authority — if an entry is not in the index, it does not exist in the Vault.

Diagram 1 — the four parts. One flat folder of typed files projects into one authoritative index; a graph carries the relationships; a registry tracks boards and pipelines. The ember box is the rule: the index is the truth.

How it works — rules travel with the artifact

Every entry opens with a few lines of YAML. Two of those lines carry all the governance. type: binds the entry to a capsule — a contract that says which fields are required, what counts as valid, and the legal states the entry can move through. status: says where the entry sits in that lifecycle right now.

That is the whole trick. The rules are not in a separate config, a database schema, or a folder convention. They ride inside the file. Change the status:, and you have moved the entry one legal step along its state machine. Try an illegal jump, and validation refuses it. The capsule is the law; the entry carries a pointer to it.

Diagram 2 — governance rides inside the file. The type: field points at the capsule that governs the entry; status: names its current place in that capsule's state machine. No external schema — the rules are part of the artifact.

One task, the whole system

Watch a single piece of work move through the Vault. You tell an agent:

"Create a task to send the Customer Summit save-the-date to our top 50 accounts."

You never touch the filesystem. The agent runs a five-step check-in: it resolves task.capsule, mints a fresh 8-character UID, writes the entry to vault/files/8f2a4c10.md, appends one line to the index, and verifies the result. What it wrote is just this:

# vault/files/8f2a4c10.md
type: task
status: active
title: Send the Customer Summit save-the-date to our top 50 accounts
owner: ada
member_of: [9c1d…]   # the "Customer Summit 2026" project
created_by: ada
verifier: mike

// …and one line appended to vault/00-index.jsonl
{"uid":"8f2a4c10","type":"task","status":"active","title":"Send the Customer Summit save-the-date…","owner":"ada","member_of":["9c1d…"]}

That one small file is now wired into the entire Studio. Because it has a type, a capsule governs it. Because it has an owner, an agent holds it. Because it declares member_of, it shows up on the Tropo Work board for the Customer Summit project. When the agent doing the work needs to hand off, it posts to a channel — an entry in the same event log. And the whole sequence can be driven by a playbook. Create one task, and six primitives engage at once. The Vault is the hub the other five plug into.

Diagram 3 — the Vault is the hub. A single typed entry plugs into the other five primitives at once, and every entry arrives through the same five-step check-in. This is what "an operating environment, not a notes folder" means in practice.

The human layer — collections

The Vault is flat and machine-first, which is great for an agent and disorienting for a person. So the human view lives one layer up, in collections: curated lists, organized however you like, that point at vault entries with [[uid]] links. If you have ever made a playlist or a bookmark folder, you have the shape — except here you own the underlying entries.

The Vault is flat, UID-named, queryable: one source of truth.
Collections are hierarchical folders of .collection.md files: the views you build on top.

One entry can appear in many collections. Remove it from a collection and it stays in the Vault. Remove it from the Vault and every collection that referenced it breaks visibly — no silent dead links. The Vault is the truth; collections are how you choose to see it.

What doesn't go in the Vault

The Vault is for governed work artifacts — anything with a type, an owner, a lifecycle, and a reason to be audited. Everything else has its own home:

Folder	What lives there
`vault/`	Governed work artifacts — tasks, specs, decisions, briefs, documents, releases
`collections/`	Human-organized views; hierarchical; `[[uid]]` links into the Vault
`agents/`	Agent identity — charters, memory, transfers
`channels/`	Rendered views of the inter-agent event log
`.tropo/`	OS infrastructure — capsule definitions, playbooks, actions

The test, when you're unsure: does it have a type, an owner, a lifecycle, and a reason to be audited? Yes → the Vault. No → probably elsewhere.

Built to be trusted at scale

A store you can't trust isn't a system of record. Three properties make the Vault one:

Nothing is destroyed. Deletes are soft by default — entries move to a recoverable recycle tree, never rm. In this Studio that tree holds 554 retired files, every one restorable.
Writes are scoped. Each entry has an owner; agents change what they own and propose changes to what they don't. Ownership is a governed field, not a convention.
It heals as it's read. Every agent that notices drift — a stale reference, a broken link — either fixes it in place or files it as tracked work. The substrate stays clean by construction, not by audit.

A single filesystem, operating as a typed, indexed, graph-linked, version-governed, event-sourced environment — at thousands of entries, and still a folder of markdown you can open in any editor.

Where to go next

The Vault is the foundation the other five primitives stand on. Once it clicks, read how each one plugs in:

Capsules — the contracts that govern every entry's shape and lifecycle.
Agents — who owns the work, and how identity survives across sessions.
Playbooks — the protocols that drive multi-step work through the Vault.
Channels — how agents coordinate over the shared event log.
Tropo Work — projects, tasks, and boards composed from vault entries.

And if you're operating the Vault directly, vault/AGENTS.md in any Studio is the full check-in protocol — the authoritative version of the five steps above.

How the Tropo Vault Works · Build with Tropo · the Vault. Scale figures measured in the live Studio that built Tropo.

Getting Started with Tropo