swarmvault

# SwarmVault

Use when the agent has a SwarmVault MCP server enabled (transport `stdio`, command `npx -y @swarmvaultai/cli mcp`) pointed at a vault directory.

A SwarmVault workspace is a three-layer knowledge system:

- `raw/` — immutable source inputs (PDFs, transcripts, code, emails, URLs, sheets). Never edit.
- `wiki/` — generated markdown owned by the agent and the SwarmVault compiler. Pages carry frontmatter (`page_id`, `source_ids`, `node_ids`, `freshness`, `source_hashes`).
- `state/` — generated indexes, graphs, and approvals. Treat as opaque output of `compile`.

The vault contract lives in `swarmvault.schema.md` at the workspace root. The vault config lives in `swarmvault.config.json`.

## Rules

1. **Read `swarmvault.schema.md` first** before any compile or query work. It defines categories, naming, freshness rules, and grounding conventions for this specific vault.
2. **Read `wiki/graph/report.md` before broad file searching** when it exists; otherwise start with `wiki/index.md`. Both summarize the vault structure so you don't re-scan everything.
3. **Treat `raw/` as immutable.** Never edit, rename, or delete files there. New sources go through `ingest`.
4. **Treat `wiki/` as compiler-owned.** Edits should preserve frontmatter fields exactly: `page_id`, `source_ids`, `node_ids`, `freshness`, `source_hashes`. If those drift, the next `compile` will overwrite or flag the page.
5. **Prefer graph queries over grep/glob** for "how does X relate to Y" or "what depends on Z" questions. The vault's typed graph is more reliable than text search.
6. **Save high-value answers** to `wiki/outputs/` (use the `query` or `explore` tools) instead of leaving them only in chat. That way they become first-class vault content for next time.

## Tool Palette

The SwarmVault MCP server exposes the following tools (names are prefixed by SwarmClaw with `mcp_<sanitized server name>_`, e.g. `mcp_SwarmVault_query_vault`). Match the user's intent to the closest tool:

Vault inspection:
- `workspace_info` — return current vault paths and high-level counts. Use this first when you've never seen this vault.
- `list_sources` — list source manifests under `raw/`.
- `search_pages` — full-text search across compiled wiki pages.
- `read_page` — read a specific wiki page by its `wiki/`-relative path.

Graph (prefer over grep for relational questions):
- `graph_report` — machine-readable graph report and trust artifact. Read this before broad searching.
- `query_graph` — traverse the graph from search seeds without calling an LLM provider.
- `get_node` — explain a graph node, its page, community, neighbors, and group patterns.
- `get_neighbors` — neighbors of a node or page target.
- `get_hyperedges` — list graph hyperedges, optionally filtered.
- `shortest_path` — shortest path between two graph targets.
- `god_nodes` — highest-connectivity nodes (the vault's hubs).
- `blast_radius` — impact analysis: what depends on this file or module?

Question answering:
- `query_vault` — natural-language question against the vault. Returns grounded citations. Pass `save: true` to persist the answer to `wiki/outputs/`.

Ingest and maintenance:
- `ingest_input` — add a file path or URL to `raw/` and register it as a managed source.
- `compile_vault` — re-derive `wiki/` pages, graph, and search index. Run after ingest, after schema changes, or when freshness is stale.
- `lint_vault` — anti-drift and vault health checks.

If the MCP server is unavailable but the agent has a `shell` or `execute` tool, the same operations are available via `swarmvault <subcommand>` (or `npx -y @swarmvaultai/cli <subcommand>`) with the working directory set to the vault root.

## Workflow

For a fresh question against the vault:

1. Call `workspace_info` if you haven't already, then read `swarmvault.schema.md`. If `wiki/graph/report.md` or `wiki/index.md` exists, skim it.
2. Use `query_vault` (or `query_graph` / `get_node` / `shortest_path` for relational questions). Cite returned `source_ids` and `node_ids`.
3. If the answer reveals a gap, propose `ingest_input` for the missing source, then `compile_vault`.
4. Save the final answer with `query_vault` `save: true` so it becomes vault content under `wiki/outputs/`.

For a new source the user mentions:

1. `ingest_input` the file/URL.
2. `compile_vault` to derive new wiki pages, graph, and search index.
3. `lint_vault` to check frontmatter and links.
4. Skim the new pages in `wiki/sources/` and confirm provenance.

## Boundaries

- Don't run `compile` against an unreviewed change to `swarmvault.schema.md` — `lint` first.
- Don't promote candidate pages (`wiki/candidates/`) to `wiki/concepts/` or `wiki/entities/` without the user's confirmation; the approval flow exists for a reason.
- Don't push the vault graph to Neo4j or export to Obsidian without an explicit ask.