SwarmVault Documentation

The SwarmVault ecosystem is divided into several core packages:

• @swarmvaultai/cli: Provides the global swarmvault and vault command-line interfaces.
• @swarmvaultai/engine: The core runtime library responsible for ingest, compile, query, lint, watch, and MCP functionality.
• @swarmvaultai/viewer: A graph viewer used to visualize data. It is included with the CLI and does not require a separate installation.

@swarmvaultai/viewer is the graph UI package for SwarmVault. It is responsible for rendering state/graph.json as an interactive graph visualization.

Key features include:

• Node Rendering: Visualizes source nodes, concept nodes, entity nodes, agent tasks, and decisions.
• Edge State Visualization: Displays extracted, inferred, conflicted, and stale edge states.
• Workflow Rail: Provides visibility into approvals, candidates, refresh state, lint findings, activity, and the Memory dashboard.
• Vault Workbench: Supports prioritized doctor recommendations, full doctor checks, suggested commands, safe repair, title/tag capture mode selection, budgeted context-pack creation, and task starts.

Note: If you are using the SwarmVault CLI, you do not need to install this package separately; the CLI and engine bundle the viewer assets automatically.

The @swarmvaultai/engine package is the core runtime library for SwarmVault. It is intended for developers who want to build custom interfaces, integrate vault operations into existing Node.js applications, or embed specific behaviors like MCP (Model Context Protocol) or watch cycles directly into their code without using the CLI.

When to use the engine vs the CLI:

• Use @swarmvaultai/engine if you are building a custom application or need fine-grained programmatic control.
• Use @swarmvaultai/cli if you only want to use SwarmVault as a standalone tool via the terminal.

SwarmVault provides a detailed breakdown of benchmark performance categorized by source class. This data is useful for understanding how different types of code (e.g., first-party vs. third-party) impact the vault's graph and analysis.

Data Locations

• JSON Data: The byClass payload is stored in state/benchmark.json.
• Markdown Report: A rendered table titled "Benchmark By Source Class" is available in wiki/graph/report.md.

Output Format

When running benchmarks, you can expect a summary output similar to this:

first_party   sources=3  pages=... nodes=... guided=... naive=... reduction=...
third_party   sources=1  pages=... nodes=... guided=... naive=... reduction=...
resource      sources=1  pages=... nodes=... guided=... naive=... reduction=...
generated     sources=1  pages=... nodes=... guided=... naive=... reduction=...

SwarmVault is designed with a privacy-first approach, processing most data locally:

• Code Files: Analyzed locally using TypeScript compiler API, tree-sitter, or SQL parsers. Source code content is never sent to external APIs.
• Documents and Text: Sent to the configured provider for semantic extraction. If using the heuristic provider, this remains entirely local.
• Images: Only sent to providers if a vision-capable provider is explicitly configured.
• Graph/Reports: All graph construction, community detection, and report generation are performed locally.

When using LLM providers (OpenAI, Anthropic, etc.), only non-code content (documents/text) is transmitted for analysis.

SwarmVault uses a multi-tiered testing strategy to catch regressions:

• Live Smoke Workflow: Triggered via workflow_dispatch (manual) or release.published (automated on package publication). This workflow includes a packaged smoke lane (installed via tarball) to catch regressions related to installed paths.
• Nightly Runs: Scheduled heuristic smoke tests run nightly.
• OSS Corpus Runner: An extended validation lane used before release candidate signoff and after any changes to repo ingest, graph quality, or query/report behavior. It should be run against the live published npm package.
• Tiny Fixture Matrix: A fast, controlled, and low-cost gate that catches regressions across the core code-language baseline and specific local file types.

Debugging: If a smoke test fails, artifacts are stored in the .live-smoke-artifacts/ directory.

The engine supports structured extraction for non-markdown sources:

• PDFs: Undergo a local text-extraction pass before being sent for analysis.
• Images: Use the configured visionProvider for structured OCR or diagram extraction.

Error Handling: If image extraction is unavailable (e.g., no multimodal provider configured), SwarmVault does not silently ignore the file. Instead, it records an explicit warning in the extraction sidecar and carries that warning into the analysis phase.

If the vault compiles but the output quality is low, you may be using the built-in heuristic provider. This provider is a lightweight, offline default that does not support advanced capabilities like embeddings, vision, or image generation.

To get richer synthesis, add a model provider in swarmvault.config.json. For local semantic graph queries, the embeddingProvider must point to an embedding-capable backend like ollama or an OpenAI-compatible service.

SwarmVault organizes data into specific directories. You can relocate these using the SWARMVAULT_OUT environment variable, but they will remain relative to the project root.

Core Directories:

• raw/: Contains sources/ (canonical input) and assets/.
• wiki/: The primary output, including outputs/ (briefs, sessions, reviews, guides), dashboards/, context/ (markdown companions), memory/ (task ledger), and candidates/ (staged pages).
• state/: Internal state, including graph.json, context-packs/, chat-sessions/, memory/tasks/, retrieval/ (index), sources.json, and approvals/.
• wiki/exports/ai/: Static AI handoff packs containing llms.txt, JSON-LD graph data, and manifests.