Swarmclaw swarmvault

Use when working with a SwarmVault knowledge vault (raw/, wiki/, swarmvault.schema.md). Establishes schema-first conventions and prefers graph queries over broad search.

install

source · Clone the upstream repo

git clone https://github.com/swarmclawai/swarmclaw

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/swarmclawai/swarmclaw "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/swarmvault" ~/.claude/skills/swarmclawai-swarmclaw-swarmvault && rm -rf "$T"

manifest: skills/swarmvault/SKILL.md

source content

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

Read
swarmvault.schema.md
first before any compile or query work. It defines categories, naming, freshness rules, and grounding conventions for this specific vault.
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.
Treat
raw/
as immutable. Never edit, rename, or delete files there. New sources go through
```
ingest
```
.
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.
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.
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

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:

Call

workspace_info

if you haven't already, then read

swarmvault.schema.md

. If

wiki/graph/report.md

wiki/index.md

exists, skim it.

Use

query_vault

(or

query_graph

get_node

shortest_path

for relational questions). Cite returned

source_ids

and

node_ids

If the answer reveals a gap, propose
```
ingest_input
```
for the missing source, then
```
compile_vault
```
.
Save the final answer with
```
query_vault
```
```
save: true
```
so it becomes vault content under
```
wiki/outputs/
```
.

For a new source the user mentions:

```
ingest_input
```
the file/URL.
```
compile_vault
```
to derive new wiki pages, graph, and search index.
```
lint_vault
```
to check frontmatter and links.
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.