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.

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 and wiki/graph/report.json with god nodes, surprising connections, 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.