Configuration

SwarmVault uses two root-level configuration surfaces:

swarmvault.config.json for runtime and provider configuration
swarmvault.schema.md for vault-specific compile and query guidance

A legacy vault.config.json filename is also supported.

Full Schema

{
  "workspace": {
    "rawDir": "raw",
    "wikiDir": "wiki",
    "stateDir": "state",
    "agentDir": "agent",
    "inboxDir": "inbox"
  },
  "providers": {
    "local": {
      "type": "heuristic",
      "model": "heuristic-v1",
      "capabilities": ["chat", "structured", "vision", "local"]
    }
  },
  "tasks": {
    "compileProvider": "local",
    "queryProvider": "local",
    "lintProvider": "local",
    "visionProvider": "local"
  },
  "viewer": {
    "port": 4123
  },
  "agents": ["codex", "claude", "cursor"]
}

Sections

`workspace`

Controls the directory layout. All paths are relative to the workspace root.

Field	Default	Description
`rawDir`	`"raw"`	Root directory for canonical source and asset storage
`wikiDir`	`"wiki"`	Compiled markdown output
`stateDir`	`"state"`	Manifests, extracts, analyses, graph, search, and jobs
`agentDir`	`"agent"`	Agent-specific files
`inboxDir`	`"inbox"`	Capture staging area for inbox import and watch mode

`providers`

Named provider definitions. SwarmVault supports built-in providers plus generic OpenAI-compatible and custom module adapters. See Provider Config.

`tasks`

Maps each engine task to a named provider from the providers object.

Field	Description
`compileProvider`	Provider used during compile
`queryProvider`	Provider used for natural-language answers
`lintProvider`	Provider used for lint and health checks
`visionProvider`	Provider used for image-aware extraction

`viewer`

Field	Default	Description
`port`	`4123`	Port used by `swarmvault graph serve`

`agents`

Array of agent types to install rules for. Supported values are "codex", "claude", and "cursor".

Schema File

swarmvault.schema.md is the vault-specific markdown instruction layer. It is how you teach one vault to behave differently from another without changing code or adding a custom parser.

Use it to define:

naming rules
concept and entity categories
relationship expectations
grounding and citation rules
exclusions

See Schema for examples and behavior details.