Schema

Every SwarmVault workspace carries a root markdown file named swarmvault.schema.md.

This file is the vault-specific instruction layer. It tells SwarmVault how this vault should be organized without introducing a separate schema DSL or extra config block.

What It Controls

Use swarmvault.schema.md to define:

  • naming rules for generated pages
  • concept and entity categories
  • expected relationship types
  • grounding and citation rules
  • exclusions and scope boundaries

Lifecycle

  • swarmvault init creates a default swarmvault.schema.md
  • swarmvault compile reads the schema and uses it to guide provider analysis
  • swarmvault query reads the same schema so answers follow the vault's own structure and grounding rules
  • generated pages record a schema_hash in frontmatter
  • swarmvault lint marks generated pages stale when the schema changes

Example

# SwarmVault Schema

## Purpose

This vault tracks research on local-first AI tools and agent workflows.

## Naming Rules

- Prefer singular concept names
- Use product names for tool entities

## Categories

- Concepts: workflow, architecture, evaluation, deployment
- Entities: product, company, person, repository, dataset

## Grounding Rules

- Prefer source-backed claims over inferred summaries
- Call out uncertainty explicitly
- Do not invent citations

Notes

  • swarmvault.schema.md is the canonical filename
  • Legacy schema.md is still read when the canonical file is absent
  • The schema is markdown guidance in the current release, not a structured config format