/swarm-vault

name: swarm-vault
description: The vault contract — how any agent reads, writes, and queries the SwarmVault. Use at the start of work in any vault-connected project, before exploring the repo, when deciding where to record memory/plans/decisions/sessions, when handing off between sessions or agents, or whenever unsure how the vault works.

swarm-vault — the vault contract

The vault is the shared brain of every agent on this machine. Query it before exploring; write to it so parallel and future agents inherit what you learned. It is plain markdown — Obsidian is an optional viewer, never a dependency.

The CLI is `swarmvault.py` — your platform's SwarmVault section (CLAUDE.md / AGENTS.md) records its full path; default install is `~/.swarmvault/scripts/swarmvault.py`.

Reading (query first, explore second)

swarmvault.py query --search "auth flow"           # BM25, names + descriptions
swarmvault.py query --project X --type memory      # structured filters
swarmvault.py show <note-name>                     # one body, once found
swarmvault.py context .                            # the compact project brief

Descriptions are the payload — most questions are answered without opening a note. Open bodies (`show`) only for what you actually need. Reach for Glob/Grep on the repo only for what the vault cannot answer. If quality genuinely needs more context, take more — the budget curbs habit, not necessity.

Writing (own files only)

| What | Where | Lane | |---|---|---| | Memory (facts, footguns, decisions learned) | platform memory dir, or `<project>/.swarm/memory/` on Codex — sync mirrors both | machine | | Session journal (end of session) | `40 Sessions/<P>/YYYY-MM-DD <slug>.md` | machine | | Specs, plans, question queue | `30 Plans/<P>/` | human (specs) / machine (queue) | | Tickets + claims | `30 Plans/<P>/tickets/` — claim via CLI only (see swarm-implement) | machine | | ADRs | `50 Decisions/<P>/ADR-NNN-<slug>.md` | human | | Code-notes (deep reasoning for a hot file) | `10 Projects/<P>/code-notes/` | human |

Rules: frontmatter always (`name`, one-line `description` that carries the fact, `project`, `type`); `[[wikilinks]]` liberally; templates in `90 Templates/`. Never edit MOCs, Home, or `generated: true` notes — sync regenerates them. Never write another agent's session/claim files.

The two lanes

**Human lane** (specs, design docs, ADRs, README): full prose, complete sentences. **Machine lane** (tickets, claims, queue entries, session notes, memory descriptions): compact telegraphic style — imperative, no filler, quality content in minimal tokens:

> Verbose: "In this session we worked on the authentication system and managed to fix > the token refresh bug that was causing users to be logged out unexpectedly." > Compact: "DID: fixed token-refresh logout bug (src/auth.ts:142, race on expiry). > NEXT: add regression test for concurrent refresh. BLOCKED: nothing."

Never compress the human lane, and never compress away information a future agent needs — if compression costs precision, don't.

Token economy & state doctrine

1. **Offload, don't carry** — write durable state to the vault; reference notes by name instead of re-explaining them in context. 2. **Checkpoint continuously** — durable state is written *when it changes* (ticket claimed/progressed/done, question answered, phase advanced), never batched to session end. The compliance test: kill the session at any moment — a fresh session must resume correctly from the vault alone, no transcript needed. 3. **Handoff by vault** — still end sessions with a journal note (`DID/NEXT/BLOCKED`) as history; but it is journal, not required state — resume never depends on it. 4. **Tier models** — top models for spec/design/review/complex logic; smaller for boilerplate (swarm-implement carries the table). 5. All guidelines are quality-bounded: when quality needs tokens, spend them.

Isolation etiquette

Projects registered `isolated` are excluded from cross-project queries automatically. Never quote isolated-project content into another project's notes. This is cooperative filtering, not a security boundary.

Self-diagnosis

Vault not finding your project? `swarmvault.py doctor` — checks config (`~/.swarmvault.json` / `$SWARMVAULT_HOME`), the `.swarmvault` marker, and the registry. A moved project: `swarmvault.py register --repair` from its new path.

--- *Influences: the original Claude Vault design; caveman plugin (compression); Obsidian MOC practice — see CREDITS.md.*