SwarmVault

SwarmVault

Use this skill when the user wants a local-first knowledge vault built on the LLM Wiki pattern — three layers (raw sources, wiki, schema) where the LLM maintains a durable wiki between you and raw sources. Also use it when the project already contains swarmvault.config.json or swarmvault.schema.md.

For onboarding, examples, command references, or troubleshooting, read the bundled README.md, examples/, references/, and TROUBLESHOOTING.md before improvising workflow advice.

Quick checks

• Work from the vault root.
• Use swarmvault next when you need a read-only orientation command before deciding whether to initialize, ingest, compile, query, review, or refresh.
• If the vault does not exist yet, run swarmvault init.
• Use swarmvault demo --no-serve when the user wants the fastest zero-config walkthrough before pointing SwarmVault at their own sources.
• Use swarmvault quickstart <file-or-directory-or-github-url> as the beginner-friendly first-run path when the user wants init + ingest + compile + graph viewer in one command.
• Use swarmvault scan <file-or-directory-or-github-url> --no-serve, swarmvault scan <file-or-directory-or-github-url> --no-viz, or swarmvault clone <file-or-directory-or-github-url> --no-viz when the user wants the fastest scratch pass over a local file, local repo, public GitHub repo, or docs tree without manually stepping through init + ingest + compile first; for GitHub URLs add --branch, --ref, or --checkout-dir when the user needs a pinned checkout. Use scan --mcp or clone --mcp when the next step should be an MCP stdio server. Use swarmvault graph share --post for copyable text, swarmvault graph share --svg [path] for a visual card, or swarmvault graph share --bundle [dir] for a portable folder with markdown, post text, SVG, HTML preview, and JSON metadata.
• Use swarmvault context build "<goal>" --target <path-or-node> --budget <tokens> when the next agent, review, or handoff needs a bounded evidence pack instead of a broad vault search.
• Use swarmvault chat "question" when a multi-turn conversation should survive handoff; resume with swarmvault chat --resume <id> "follow-up" and inspect saved transcripts under wiki/outputs/chat-sessions/.
• Use swarmvault export ai --out <dir> when another agent, crawler, or static workflow needs llms.txt, full text, JSON-LD graph data, a manifest, and per-page siblings without starting graph serve.
• Use swarmvault task start "<goal>" --target <path-or-node> when agent work should leave a durable task ledger with decisions, linked context packs, changed paths, outcomes, and follow-ups. The older memory command remains a compatibility alias.
• Use swarmvault doctor before broad troubleshooting or agent handoff; add --repair when the retrieval index can be safely rebuilt. In swarmvault graph serve, the workbench shows prioritized next actions, every doctor check with details, copyable suggested commands, and safe direct repair where available.
• Read swarmvault.schema.md before compile or query work. It is the vault's operating contract.
• If wiki/graph/report.md exists, use it before broad repo search.
• If SWARMVAULT_OUT is set, resolve generated artifacts from that output root: raw/, wiki/, state/, agent/, and inbox/ live there while swarmvault.config.json and swarmvault.schema.md stay in the project root.

Core loop

1. Run swarmvault next when the current vault state is unclear; it is read-only and returns paths, checks, and recommended commands.
2. Initialize a vault with swarmvault init when needed.
3. Update swarmvault.schema.md before a serious compile. Use it for naming rules, categories, grounding, freshness expectations, and exclusions.
4. Use swarmvault source add <input> when the input is a recurring local file, local directory, public GitHub repo root, or docs hub that should stay registered. For public GitHub repos, use --branch, --ref, or --checkout-dir when a branch, tag, commit, or reusable checkout matters.
5. Ingest one-off inputs with swarmvault ingest <path-or-url>, or ingest a whole repo tree with swarmvault ingest <directory>. Audio and video files use tasks.audioProvider when configured; local video needs ffmpeg, public video URLs use swarmvault ingest --video <url> / swarmvault add --video <url> with yt-dlp, and supported YouTube URLs go through direct transcript capture instead of generic URL ingest.
6. Use swarmvault ingest --guide, swarmvault source add --guide, swarmvault source reload --guide, swarmvault source guide <id>, or swarmvault source session <id> when the human should integrate one source at a time before canonical pages change. Set profile.guidedIngestDefault: true in swarmvault.config.json to make guided mode the default; use --no-guide to override. Profiles using guidedSessionMode: "canonical_review" stage approval-queued canonical edits; insights_only profiles keep exploratory synthesis in wiki/insights/. Use --review only for the lighter review-only path.
7. Use swarmvault inbox import for capture-style batches, then swarmvault watch --lint --repo when the workflow should stay automated. Add --code-only when the refresh should stay AST-only and defer non-code semantic re-analysis to a later compile. On tracked repos, code-only changes take that faster compile path automatically. Install swarmvault hook install when git checkouts and commits should trigger the same repo-aware code-only refresh automatically.
8. Compile with swarmvault compile, use compile --max-tokens <n> when the generated wiki must stay inside a bounded context budget, or use compile --approve when changes should go through the local review queue first.
9. Resolve staged work with swarmvault review list|show|accept|reject and swarmvault candidate list|promote|archive.
10. Ask questions with swarmvault query "<question>". It saves durable answers into wiki/outputs/ by default; add --no-save only for ephemeral checks. When an embedding provider is configured, query can merge semantic page matches into local search; retrieval.rerank: true lets the current queryProvider rerank the merged top hits before answering.
11. Use swarmvault chat "question" for a persisted multi-turn conversation over the compiled wiki, then resume or manage it with swarmvault chat --resume <id>, chat --list, and chat --delete <id>.
12. Build agent handoff bundles with swarmvault context build "<goal>" --target <path-or-node> --budget <tokens>. Use --format markdown|json|llms for the printed shape, and inspect swarmvault context list|show|delete for saved packs.
13. Start a task ledger with swarmvault task start "<goal>" --target <path-or-node>, update it with swarmvault task update <id> --note|--decision|--changed-path|--context-pack, finish it with swarmvault task finish <id> --outcome <text>, and use swarmvault task resume <id> --format markdown|json|llms for the next-agent handoff. query, explore, and context build can attach work with --task <id>; --memory <id> remains a compatibility alias.
14. Run swarmvault export ai --out <dir> when the compiled wiki should be handed to another agent or static crawler as llms.txt, full text, JSON-LD, manifest metadata, and per-page .txt/.json siblings.
15. Run swarmvault doctor [--repair] when the vault needs one health summary across graph, retrieval, review queues, watch state, migrations, managed sources, and task state before deeper troubleshooting.