swarmvault query

Query the compiled wiki with a natural language question.

Usage

swarmvault query <question> [--no-save] [--commit] [--format markdown|report|slides|chart|image] [--task <id>] [--memory <id>]

Arguments

  • <question> — The question to ask

Options

  • --no-save — Skip persistence and print an ephemeral answer only
  • --commit — Stage wiki/ and state/ changes and commit them when the vault root is inside a git worktree
  • --format markdown|report|slides|chart|image — Choose the saved output format
  • --task <id> — Attach the saved output page, graph ids, and session to an active task
  • --memory <id> — Compatibility alias for --task

Examples

swarmvault query "What are the main concepts?"
swarmvault query "Summarize the relationship between X and Y" --no-save
swarmvault query "Turn this into slides" --format slides
swarmvault query "Show the current vault context as a chart" --format chart
swarmvault query "Show the current vault context as an image" --format image
swarmvault query "What changed in auth?" --task <task-id>

How It Works

  1. Searches the retrieval index for relevant wiki pages, including human-authored insight pages in wiki/insights/
  2. When an embedding-capable provider is available and retrieval.hybrid is not disabled, fuses semantic page hits into the same candidate set before answer generation
  3. When retrieval.rerank is true, asks the configured queryProvider to rerank the merged top hits before generating the answer
  4. Starts with the root schema, then appends any project-specific schemas from retrieved project-scoped pages
  5. Uses the configured queryProvider to generate an answer with context in the requested format
  6. Prints the answer to stdout
  7. Saves the answer to wiki/outputs/ unless --no-save is set
  8. For chart and image, generates local assets under wiki/outputs/assets/<slug>/ plus a wrapper markdown page in wiki/outputs/
  9. Updates wiki/index.md, wiki/outputs/index.md, state/graph.json, state/retrieval/, and related source/concept/entity pages immediately

Saved output pages also record:

  • schema_hash
  • status, created_at, updated_at, compiled_from, and managed_by
  • related page ids
  • related node ids
  • related source ids
  • the originating question
  • the saved output format
  • local output_assets metadata for chart and image outputs

That metadata is how the lightweight artifact sync path refreshes Related Outputs sections immediately.

Each query also writes a canonical session artifact to state/sessions/.

When --commit is set, SwarmVault creates a git commit only when saved wiki/ or state/ changes exist. Combined with --no-save, that usually becomes a no-op.