SwarmVault

SwarmVault is a local-first knowledge vault. It ingests files, transcripts, code, URLs, and inboxes into an immutable raw/ layer, derives a curated wiki/ layer of markdown pages, and maintains a typed knowledge graph with provenance tracking. SwarmVault ships an MCP server (swarmvault mcp) that SwarmClaw connects to like any other MCP server.

SwarmClaw treats SwarmVault as one possible knowledge backend for an agent. There is no special storage path, no internal coupling. A SwarmVault vault is a directory the user owns, and the agent talks to it through MCP tools.

What You Get

One-click setup: a "SwarmVault" preset in the MCP server sheet pre-fills the command, args, and transport. You only enter the vault directory path.
Per-agent enablement: each agent independently picks which MCP servers it sees. One agent can target a research vault; another targets an engineering vault.
Bundled skill: a built-in swarmvault skill captures the schema-first / graph-query-first conventions so the agent uses the vault correctly without you re-explaining each turn.
Multi-vault support: nothing prevents you from registering several SwarmVault MCP servers (one per vault) and assigning different sets to different agents.

Setup

1. Create a vault

In a directory of your choice:

npx @swarmvaultai/cli init

This creates swarmvault.config.json and the raw/, wiki/, state/ layout. Note the absolute path; you will paste it into the MCP server form.

2. Register SwarmVault as an MCP server in SwarmClaw

Open MCP Servers in the sidebar.
Click New.
Under Quick Setup, click the SwarmVault chip. The form fills in:
- Transport: stdio
- Command: npx
- Arguments: -y, @swarmvaultai/cli, mcp
Paste the vault directory's absolute path into Working Directory.
Optionally rename the server to identify the vault (for example SwarmVault: Engineering).
Click Create, then open the server again and click Test Connection to confirm SwarmVault answers.

The Working Directory field exists because SwarmVault discovers its vault from the process working directory (swarmvault.config.json in cwd). Without it, the server would launch in SwarmClaw's own working directory and find the wrong vault (or no vault).

3. Enable on an agent

Open the agent in the Agents view.
In the agent sheet, find the MCP Servers section and check the SwarmVault server you registered.
In the Skills section, pin the bundled swarmvault skill (auto-discovered; appears alongside coding-agent, google-workspace, etc.).
Save.

The agent can now call <server>_compile, <server>_query, <server>_ingest, <server>_graph, and so on (tool names are prefixed with the sanitized MCP server name). The swarmvault skill teaches the agent to read swarmvault.schema.md first, treat raw/ as immutable, and prefer graph queries over grep when the question is relational.

4. Use the vault from chat

A few example prompts:

"Compile the vault and tell me what's new."
"Query the vault for our current pricing strategy."
"Ingest this URL and re-compile: https://…"
"Use a graph query to show every concept that depends on the auth-rewrite project."

The agent uses the SwarmVault MCP tools and cites source_ids and node_ids from the vault.

What the Skill Adds

The bundled skills/swarmvault/SKILL.md encodes the SwarmVault contract:

Read swarmvault.schema.md before any compile or query work.
Treat raw/ as immutable; new sources go through ingest.
Treat wiki/ as compiler-owned. Preserve page_id, source_ids, node_ids, freshness, and source_hashes frontmatter.
Read wiki/graph/report.md (or wiki/index.md) before broad file searching.
For relational questions, prefer graph query, graph path, graph explain over grep/glob.
Save high-value answers to wiki/outputs/ so they become first-class vault content.

The skill is independent of the MCP integration. It is useful when an agent uses the SwarmVault MCP server, when the agent uses the shell/execute tool to invoke swarmvault directly, or when the agent edits the vault by hand. It is harmless on agents that do neither.

API / CLI Reference

The MCP server APIs (/api/mcp-servers, etc.) accept the new optional cwd field on stdio transports:

curl -X POST http://localhost:3456/api/mcp-servers \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "SwarmVault: Engineering",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@swarmvaultai/cli", "mcp"],
    "cwd": "/Users/you/vaults/engineering"
  }'

Then test the connection:

curl -X POST http://localhost:3456/api/mcp-servers/<id>/test

A successful response returns { "ok": true, "tools": [...] } with the SwarmVault tool list.

The SwarmClaw CLI:

swarmclaw mcp-servers create --data '{
  "name": "SwarmVault: Engineering",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@swarmvaultai/cli", "mcp"],
  "cwd": "/Users/you/vaults/engineering"
}'

swarmclaw mcp-servers test <serverId>
swarmclaw mcp-servers tools <serverId>

Multiple Vaults

Each vault is a separate MCP server entry. Name them descriptively:

SwarmVault: Engineering → /Users/you/vaults/engineering
SwarmVault: Operations → /Users/you/vaults/ops
SwarmVault: Research → /Users/you/vaults/research

Then assign each vault to the agents that should see it. An agent can have several vaults attached; tools from each are namespaced by the sanitized server name.

Troubleshooting

"Connection test failed" on save — verify the vault directory exists and contains swarmvault.config.json. Run npx @swarmvaultai/cli init there if not.
Tools list is empty — the SwarmVault MCP server starts up only when a valid vault is found. Check the server logs (/api/mcp-servers/<id>/test returns the error in the error field).
Agent ignores the skill — confirm the skill is pinned on the agent's skillIds[]. Bundled skills are visible in the skills list; pinning is per-agent.
npx is slow on first run — the first invocation downloads the @swarmvaultai/cli package. Subsequent runs use the npm cache. To skip the cache lookup entirely, install globally with npm install -g @swarmvaultai/cli and set command to swarmvault instead of npx.