SwarmVault知识图谱引擎

Install

Agent and MCP Setup

Set up your coding agent so it knows about the vault:

swarmvault install --agent claude --hook --mcp  # Claude Code + graph-first hook + MCP server
swarmvault install --agent codex --hook     # Codex + graph-first hook
swarmvault install --agent cursor           # Cursor
swarmvault install --agent copilot --hook   # GitHub Copilot CLI + hook
swarmvault install --agent gemini --hook    # Gemini CLI + hook
swarmvault install --agent trae             # Trae
swarmvault install --agent claw             # Claw / OpenClaw skill target
swarmvault install --agent droid            # Droid / Factory rules target
swarmvault install --agent kiro             # Kiro IDE + always-on steering
swarmvault install --agent kilo --hook       # Kilo project rules + plugin
swarmvault install --agent hermes           # Hermes user-scope skill
swarmvault install --agent antigravity      # Google Antigravity rules + /swarmvault workflow
swarmvault install --agent vscode           # VS Code Copilot Chat chatmode
swarmvault install status --agent kilo --hook

For hook-capable agents, the installed hooks guide graph-first reads, with enforcement as an opt-in. For Claude Code, --hook injects graph-first instructions at session start — answer code-understanding questions with the plain swarmvault graph query|explain|path commands (avoid --json, which produces much larger output), swarmvault query, swarmvault context build, or wiki/graph/report.md, and read source files only when editing them — along with a graph staleness note. swarmvault graph query "<seed>" prints the top matches with page paths plus an inline excerpt of the best-matching wiki page, so one command usually answers where-is/what-calls questions without follow-up file reads. For who-calls and impact-of-change questions, the hook guidance recommends swarmvault graph callers <symbol>, which lists every caller from graph call edges with exact file:line call-site evidence — scanning only the files the graph identifies as callers — instead of a repo-wide grep. By default the hook runs in advisory mode (context): the first broad Grep/Glob/Bash search per session gets a one-time guidance note pointing at those plain graph commands, and nothing is denied. Pass --graph-first at install time to opt in to enforcement, where the first broad search per session is denied once with a guided redirect to those plain graph commands and the inline excerpt they return (repeating the same search is then allowed, so work is never blocked). The flag accepts an optional value — deny (the default when the flag is passed), context, or off — and persists the chosen mode as hooks.graphFirst in swarmvault.config.json; SWARMVAULT_GRAPH_FIRST=deny|context|off still overrides per session. After Edit/Write tools the hook spawns a background swarmvault graph update --file <path> refresh so the graph tracks your edits. Searches scoped to vault artifact directories (wiki/, raw/, state/) or a single file are never intercepted, and search tools that merely filter piped output (e.g. some-command | grep …) do not count as broad searches. The Codex, Gemini, Copilot, OpenCode, and Kilo hooks carry the same graph-first guidance — a session note plus a one-time search redirect appropriate to each tool's hook API.

swarmvault install --agent claude --mcp also registers the SwarmVault MCP server in the project's .mcp.json ({"mcpServers":{"swarmvault":{"command":"swarmvault","args":["mcp"]}}}). Claude installs additionally write a project skill bundle at .claude/skills/swarmvault/SKILL.md, and --scope user installs the skill, hook, and settings once under ~/.claude for all repos — the hook no-ops in repos without a compiled graph report.

swarmvault install --agent <agent> also keeps the host project clean: in git repos the vault artifact directories are appended to .gitignore, strict-JSON tsconfig.json files get the artifact directories added to "exclude" so stored source copies under raw/ do not break the host typecheck (commented JSONC tsconfigs are left untouched with a warning, linter configs that still cover the artifact directories get an advisory warning, and everything is skipped when SWARMVAULT_OUT keeps artifacts outside the repo).

Recommended per-repo onboarding for token-saving agent workflows:

cd <repo>
swarmvault init && swarmvault ingest .
swarmvault install --agent claude --hook --mcp --graph-first
swarmvault hook install        # git-hook refresh on commit/checkout; accepts an optional repo path (e.g. `swarmvault hook install packages/app`) when the tracked repo lives below the vault root

SwarmVault never writes these project-local rule files during init, quickstart, scan, or clone unless you explicitly opt into configured installs. Use swarmvault install --agent <agent> [--scope project|user] for one target at a time, or list agents in swarmvault.config.json and run swarmvault init --install-agent-rules or swarmvault quickstart <input> --install-agent-rules when you want configured targets installed together. install status reports the files SwarmVault expects for a target without mutating the workspace.

Or expose the vault directly over MCP:

swarmvault mcp

Using OpenClaw or ClawHub? Install the packaged skill with:

clawhub install swarmvault

That installs the published SKILL.md plus a ClawHub README, examples, references, troubleshooting notes, and validation prompts. Keep the CLI itself updated with npm install -g @swarmvaultai/cli@latest.

Quickstart

Worked Examples

Each folder has real input files and actual output so you can run it yourself and verify.

See the examples guide for step-by-step walkthroughs.

Optional: Add a Model Provider

You do not need API keys or an external model provider to start using SwarmVault. The built-in heuristic provider supports local/offline vault setup, ingest, compile, graph/report/search workflows, and lightweight query or lint defaults.

Cloud API Providers

For cloud-hosted models, add a provider block with your API key:

{
  "providers": {
    "primary": {
      "type": "openai",
      "model": "gpt-4o",
      "apiKeyEnv": "OPENAI_API_KEY"
    }
  },
  "tasks": {
    "compileProvider": "primary",
    "queryProvider": "primary",
    "embeddingProvider": "primary"
  }
}

See the provider docs for optional backends, task routing, and capability-specific configuration examples.

You can also manage provider routing from the CLI without hand-editing JSON:

swarmvault provider add router --type openrouter --model openrouter/auto --api-key-env OPENROUTER_API_KEY --capability chat --capability structured --task queryProvider
swarmvault provider list
swarmvault provider show router
swarmvault provider remove router --fallback local

Provider commands preserve unknown swarmvault.config.json fields and store secret references through apiKeyEnv; they do not accept literal API key values.

Packages