Compounding Loop

SwarmVault is designed so useful work compounds over time instead of resetting every session. Each operation writes durable artifacts that feed into the next.

Save-First Queries

swarmvault query writes answers into wiki/outputs/ by default. Saved outputs are immediately:

  • Indexed into local search
  • Registered in the graph page registry
  • Used to refresh related source, concept, and entity pages

Use --no-save when you want an ephemeral answer that does not enter the vault.

Chat Sessions

swarmvault chat writes multi-turn conversations over the compiled wiki into state/chat-sessions/ and markdown transcripts under wiki/outputs/chat-sessions/. Resume a prior conversation with swarmvault chat --resume <id> "follow-up".

Use chat sessions when follow-up questions need prior turns and the transcript should remain inspectable.

Context Packs

swarmvault context build writes bounded agent handoff packs into state/context-packs/ and markdown companions into wiki/context/. Each pack records the goal, optional target, token budget, included pages/nodes/edges/hyperedges, citations, and explicit omitted items.

Use context packs before handing a scoped task to another agent, reviewing a PR, or preserving the evidence behind a decision.

Static AI Exports

swarmvault export ai writes static handoff files under wiki/exports/ai/ by default: llms.txt, llms-full.txt, graph.jsonld, manifest.json, ai-readme.md, and optional page siblings.

Use AI exports when another agent, crawler, or documentation system should consume the compiled wiki without a running viewer or MCP server.

Agent Task Ledger

swarmvault task start writes durable task records into state/memory/tasks/ with markdown companions in wiki/memory/tasks/. A task records the goal, target, agent, linked context packs, sessions, source/page/node ids, changed paths, git refs, decisions, outcome, and follow-ups.

Use task ledgers when work needs to survive a handoff, branch switch, or future follow-up. query, explore, and context build can attach artifacts with --task <id>, and task resume <id> prints a compact next-agent briefing. Existing memory commands and --memory <id> remain compatibility aliases.

Explore Chains

swarmvault explore runs a multi-step research loop. Each step saves its output, and the loop writes a hub page that links the root question and generated follow-up questions. This creates a navigable trail of research that any agent or human can revisit.

Visual Outputs

chart and image format saves write both a wrapper markdown page and local assets into wiki/outputs/assets/<slug>/. These are indexed like any other output page.

Candidate Promotion

Compile may discover new concepts and entities that do not yet have wiki pages. Instead of creating them immediately, they land in wiki/candidates/:

  • swarmvault candidate list shows what is staged
  • swarmvault candidate promote <target> moves a candidate to an active page
  • swarmvault candidate archive <target> removes it from the queue
  • The next matching compile also promotes candidates automatically based on evidence thresholds

Reviewable Compilation

swarmvault compile --approve stages all changes into an approval bundle instead of applying them directly:

  • swarmvault review list shows pending bundles
  • swarmvault review show <id> inspects entries in a bundle
  • swarmvault review accept <id> applies the changes
  • swarmvault review reject <id> discards them

Scheduled query and explore jobs also stage their output through approvals instead of activating immediately.

Graph and Report Refresh

Compile automatically keeps trust and orientation artifacts current:

  • wiki/graph/report.md, wiki/graph/share-card.md, wiki/graph/share-card.svg, wiki/graph/share-kit/, and wiki/graph/report.json with god nodes, surprising connections, share text, a visual card, a portable HTML-preview bundle, and community summaries
  • wiki/graph/index.md and per-community graph summary pages
  • state/benchmark.json with context-reduction metrics

Deep Lint Feedback

swarmvault lint --deep provides LLM-powered advisory feedback without mutating the vault:

  • Missing citations and coverage gaps
  • Candidate page suggestions
  • Follow-up questions worth exploring
  • With --web, external evidence gathering for fact-checking

Orchestration Roles

Role orchestration maps research, audit, context, and safety work onto providers or external commands. Orchestrated feedback flows through the same approval pipeline, so no role can bypass the review process.

Session Artifacts

Every compile, query, explore, lint, and watch run writes a session artifact to state/sessions/. Ingest and inbox import also append to the canonical wiki/log.md activity log. This creates an auditable history of all vault operations.

Human-Only Insights

Pages placed in wiki/insights/ are indexed into search and available to query, but SwarmVault never rewrites them. This is the space for manual notes, editorial decisions, and curated context that should persist unchanged.