Quickstart

This guide walks through the core SwarmVault workflow: initialize a workspace, shape it with the schema file, ingest material, compile the vault, query it, and inspect the results.

1. Initialize a Workspace

mkdir my-vault
cd my-vault
swarmvault init

This creates inbox/, raw/, wiki/, state/, agent/, a default swarmvault.config.json, and a default swarmvault.schema.md.

2. Review the Vault Schema

sed -n '1,120p' swarmvault.schema.md

Edit the schema before a serious compile if you want the vault to follow domain-specific naming rules, categories, grounding rules, or exclusions.

3. Ingest Sources

swarmvault ingest ./research-paper.pdf
swarmvault ingest https://example.com/article
swarmvault ingest ./notes.md

Each source is copied into canonical storage and tracked by a manifest in state/manifests/.

4. Compile the Vault

swarmvault compile

This builds:

  • Markdown wiki pages in wiki/
  • A graph artifact in state/graph.json
  • A local search index in state/search.sqlite

5. Query and Save Useful Results

swarmvault query "What are the main concepts?"
swarmvault query "Summarize the key findings" --save

With --save, answers are written into wiki/outputs/ so they become part of the vault. Generated pages also record a schema_hash, which is how SwarmVault tracks whether schema changes should mark them stale.

6. Explore the Graph

swarmvault graph serve

Open http://localhost:4123 unless you changed the configured viewer port.

7. Automate Capture Workflows

If you are collecting markdown clips or other files into inbox/, you can import and automate them:

swarmvault inbox import
swarmvault watch --lint

8. Expose the Vault to Agents

swarmvault mcp

This starts a local stdio MCP server so compatible clients can search pages, read pages, query the vault, ingest inputs, compile, and lint.

Next Steps