Swarm vault

Skill AnmarHani/SwarmVault/skills/swarm-vault

A shared knowledge vault + full software-engineering workflow for AI coding agents — run Claude Code and Codex in parallel with one memory, one plan.

Install

npx -y skills add AnmarHani/SwarmVault --skill swarm-vault

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

19 days oldThe repository was created 19 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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.

SKILL.md

4.5 KB, as published. Nobody here has run it

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

Offload, don't carry — write durable state to the vault; reference notes by name instead of re-explaining them in context.
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.
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.
Tier models — top models for spec/design/review/complex logic; smaller for boilerplate (swarm-implement carries the table).
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.