swarmvault graph tools

SwarmVault ships a local graph-navigation surface that works directly from state/graph.json, including semantic-similarity edges and group-pattern hyperedges. These commands do not save pages.

For a copyable, visual, or portable first-run summary, use `swarmvault graph share`. It prints the generated wiki/graph/share-card.md, the short post text with --post, the 1200x630 SVG with --svg [path], or the complete share kit with --bundle [dir].

graph query

swarmvault graph query "<question>" [--dfs] [--budget <n>] [--relation <name>] [--context <group>] [--evidence <class>] [--node-type <type>] [--language <lang>]

Use this to seed a graph traversal from semantic matches, local search hits, aliases, node labels, and matching group patterns.

  • default traversal is breadth-first
  • --dfs biases toward a path-like explanation
  • --budget limits how many graph nodes and edges are summarized
  • --relation, --context, --evidence, --node-type, and --language narrow traversal before graph walking; repeat them to combine filters
  • --context accepts calls, imports, types, data, rationale, or evidence
  • if an embedding-capable provider is available, semantic graph matches are tried first and cached under state/embeddings.json
  • if no embedding provider is configured, SwarmVault falls back to lexical graph matching automatically

graph path

swarmvault graph path <from> <to>

Return the shortest high-confidence path between two graph targets.

Targets can be page ids, graph node ids, or labels that resolve to graph nodes.

graph explain

swarmvault graph explain <target>

Inspect graph metadata for one target:

  • community membership
  • neighbors
  • group-pattern membership
  • linked pages
  • provenance-backed edges
  • evidence class and confidence

graph god-nodes

swarmvault graph god-nodes [--limit <n>]

List the most connected bridge-heavy nodes in the current graph.

graph blast

swarmvault graph blast <target> [--depth <n>]

Show the blast radius of changing one module by tracing reverse imports edges.

  • accepts a file path, module label, or module id
  • uses breadth-first traversal over reverse imports, so changing dependency B surfaces modules that depend on B
  • --depth limits the reverse-import traversal depth and defaults to 3
  • useful for local impact checks before large refactors or approval-bundled code updates

graph update

swarmvault graph update [path]
swarmvault graph refresh [path]
swarmvault update [path]
swarmvault graph update [path] --force

Run the same code-only repo refresh cycle as swarmvault watch --repo --code-only --once.

  • without path, SwarmVault uses configured or auto-discovered watched repo roots
  • with path, SwarmVault refreshes that repo root instead of the tracked set
  • aborts if nodes or edges drop by more than 25% compared with the existing graph; pass --force or set SWARMVAULT_FORCE_UPDATE=1 when the shrink is expected
  • --json returns the same shape as the watch one-shot result, including repo import/update/remove counts and pending semantic refresh entries
  • swarmvault update [path] is the top-level compatibility alias for the same code-only refresh path

graph tree

swarmvault graph tree [--output <html>] [--root <path>] [--label <name>] [--max-children <n>]
swarmvault tree [--output <html>] [--root <path>] [--label <name>] [--max-children <n>]

Write a collapsible source/module/symbol tree for the compiled graph.

  • defaults to wiki/graph/tree.html
  • groups sources by path, then nests module, symbol, and rationale nodes under each source
  • includes expand/collapse/reset controls, count badges, selected-node metadata, and top connected edges
  • --root reads a different vault root without changing directories
  • --max-children caps very wide folders or modules with a +N more row
  • --json returns the output path, counts, and tree payload
  • swarmvault tree is the top-level compatibility alias for the same output

graph merge

swarmvault graph merge <graph...> --out <path> [--label <name>]
swarmvault merge-graphs <graph...> --out <path> [--label <name>]

Merge graph JSON artifacts into one namespaced graph.

  • accepts native SwarmVault graph JSON payloads
  • accepts NetworkX/node-link style JSON with nodes plus links or edges
  • prefixes ids from every input to avoid collisions
  • maps extracted/inferred/ambiguous edge evidence into SwarmVault edge semantics
  • --json returns the merged graph, input summaries, and warnings
  • swarmvault merge-graphs is the top-level compatibility alias for the same merge path

graph status

swarmvault graph status [path]
swarmvault check-update [path]

Check whether graph artifacts are fresh without writing watch status.

  • reports graph and graph-report presence
  • lists tracked repo roots and changed files
  • separates code-only changes from semantic refresh changes
  • recommends swarmvault graph update when code-only graph artifacts can be refreshed safely
  • recommends swarmvault compile when graph/report artifacts are missing, non-code tracked sources changed, or semantic refresh work is already pending
  • supports global --json for automation
  • swarmvault check-update [path] is the top-level compatibility alias for the same read-only check

watch path

swarmvault watch [path] --once --code-only

Refresh one explicit repo root without first writing watch.repoRoots.

  • positional [path] turns on repo mode for that one root
  • --once runs a single refresh cycle and exits
  • --code-only keeps the refresh parser-backed and defers non-code semantic refreshes to compile
  • repeated --root <path> remains available for multiple roots

graph stats

swarmvault graph stats

Summarize the compiled graph without opening the viewer.

  • reports source, page, node, edge, hyperedge, and community counts
  • breaks down node types, evidence classes, source classes, edge relations, and hyperedge relations
  • mirrors the lightweight MCP graph_stats shape
  • supports global --json for automation

graph validate

swarmvault graph validate [graph] [--strict]

Validate graph artifact integrity before exporting, merging, pushing, or publishing generated graph evidence.

  • defaults to the current vault's compiled state/graph.json
  • accepts an explicit graph JSON path for exported or merged graph artifacts
  • checks duplicate ids, dangling node/page/community/hyperedge references, confidence bounds, empty critical fields, and conflicted-edge evidence consistency
  • exits non-zero when errors are present; with --strict, warnings also fail the command
  • supports global --json for automation

graph cluster

swarmvault graph cluster [--resolution <n>]
swarmvault cluster-only [vault] [--resolution <n>]

Recompute graph communities, node degree, bridge scores, god-node flags, and graph report artifacts from the existing compiled graph.

  • does not re-ingest sources or rerun semantic analysis
  • updates state/graph.json, wiki/graph/report.md, wiki/graph/report.json, share artifacts, and per-community pages
  • uses graph.communityResolution by default
  • --resolution <n> overrides Louvain resolution for one recompute
  • splits oversized or low-cohesion communities after the initial Louvain pass so large-repo reports stay scannable
  • --json returns refreshed counts plus graph/report paths
  • swarmvault cluster-only [vault] is the top-level compatibility alias and can target another vault root

graph export --neo4j

swarmvault graph export --neo4j ./exports/graph.cypher

--neo4j is a compatibility alias for --cypher. It writes the same Neo4j-ready Cypher import file and can be combined with other graph export formats in one run.

Notes

  • These commands are local and deterministic.
  • They are useful when you want graph structure without a provider-backed synthesis step.
  • The same graph surfaces are also available over MCP through query_graph, graph_report, graph_stats, cluster_graph, get_node, get_community, get_neighbors, get_hyperedges, shortest_path, god_nodes, and blast_radius.