SwarmVault — Summary

SwarmVault is a local-first LLM Wiki CLI and knowledge graph builder that implements Andrej Karpathy's three-layer pattern (raw sources → wiki → schema) as a production-grade tool. It ingests books, articles, notes, code, URLs, transcripts, and datasets into a durable markdown wiki plus a local SQLite + semantic graph, with MCP server, desktop app, git-based automation, and agent-facing context-pack and task-ledger workflows. The swarmvault CLI has 30+ subcommands covering init, ingest, compile, query, review, graph operations, chat sessions, context builds, task ledgers, and AI export. An OpenClaw-compatible skill file ships in skills/swarmvault/SKILL.md.

SwarmVault is most similar to ccmemory from the seeds (both are graph-based agent memory stores), but differs fundamentally: ccmemory uses Neo4j + vector embeddings for agent memory of code; SwarmVault is a local SQLite + markdown wiki for personal knowledge management across all content types (books, papers, URLs, code, audio, video), with a full CLI, desktop app, MCP server, and an approval queue for LLM-generated changes.

SwarmVault — Overview

Origin

Built by SwarmClaw AI (swarmvault.ai). Ships under MIT license. Inspired by Andrej Karpathy's LLM Wiki gist (https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). The README explicitly positions against the original gist:

"If you liked Karpathy's LLM Wiki gist, SwarmVault is the production-grade version."

Philosophy

From the README:

"SwarmVault turns docs, code, transcripts, notes, and URLs into a durable markdown wiki plus a local graph you can inspect, query, and hand to agents."

"In the tradition of Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents — SwarmVault treats the connections between sources as valuable as the sources themselves. The part Bush couldn't solve was who does the maintenance. The LLM handles that."

Three-Layer Architecture (Karpathy's Pattern)

1. Raw sources (raw/) — immutable, curated source documents. Never modified by SwarmVault.
2. The wiki (wiki/) — LLM-generated + human-authored markdown. Compounding artifact.
3. The schema (swarmvault.schema.md) — conventions, grounding, what matters in this domain.

Addressing Community Concerns (from README)

• "Won't hallucinations compound?" → Every edge tagged extracted, inferred, or ambiguous. Contradiction detection. Approval queues (compile --approve).
• "Does it scale past 100 pages?" → Hybrid search (SQLite FTS + semantic embeddings). compile --max-tokens.
• "Do I need API keys?" → No. Built-in heuristic provider is fully offline.

Release Cadence

SKILL.md version 3.15.0 — active development with frequent releases.

SwarmVault — Architecture

Distribution

• CLI: npm install -g @swarmvaultai/cli
• Desktop app: Download from swarmvault.ai/download (macOS, Windows, Linux — bundles own runtime)
• Obsidian plugin: packages/obsidian-plugin/

Directory Structure

packages/
  cli/              # @swarmvaultai/cli Node.js package
  engine/           # Core vault engine
  obsidian-plugin/  # Obsidian plugin
  viewer/           # Graph viewer package
skills/
  swarmvault/
    SKILL.md        # OpenClaw-compatible skill file
    README.md
    TROUBLESHOOTING.md
    examples/
    references/
    validation/
templates/
  llm-wiki-schema.md  # Standalone schema template (zero install)
docs/
scripts/
smoke/              # Smoke tests
validation/
worked/

Required Runtime

• Node.js >= 24 (CLI)
• Desktop app bundles own runtime (no Node.js required)

Install Complexity

One-liner npm install. Desktop app: download binary.

Vault Artifacts (on disk)

raw/               # Immutable source documents
wiki/              # Generated markdown + saved outputs
  outputs/         # Query results, chat sessions, context packs
  dashboards/      # Automated dashboards
  graph/           # Share cards, reports
state/
  graph.json       # Machine-readable knowledge graph
  retrieval/       # Local search index
swarmvault.config.json
swarmvault.schema.md

Output Directory Override

SWARMVAULT_OUT — override root for generated artifact directories.

MCP Server

swarmvault mcp — starts MCP server for agent consumption of vault tools.

SwarmVault — Components

CLI Subcommands (30+)

Init/Setup

• swarmvault init — Initialize vault
• swarmvault quickstart <path> — Init + ingest + compile + graph viewer
• swarmvault demo [--no-serve] — Zero-config walkthrough
• swarmvault scan <path> — Fast scratch pass
• swarmvault clone <github-url> — Clone + ingest GitHub repo

Ingestion

• swarmvault ingest <path> — Ingest source
• swarmvault source add <input> — Register recurring source
• swarmvault source reload — Refresh registered sources
• swarmvault inbox import — Batch capture import

Compilation + Review

• swarmvault compile [--approve] [--max-tokens N] — Generate wiki
• swarmvault review list|show|accept|reject — Manage approval queue
• swarmvault candidate list|promote|archive — Manage new concept candidates

Query + Exploration

• swarmvault query "<question>" — Saved query with answer
• swarmvault chat "<question>" — Persisted multi-turn conversation
• swarmvault chat --resume <id> — Resume prior conversation
• swarmvault explore "<question>" [--steps N] — Research loops

Context + Tasks

• swarmvault context build "<goal>" --target --budget — Agent handoff bundle
• swarmvault context list|show|delete — Manage context packs
• swarmvault task start|update|finish|resume — Task ledger

Graph Operations

• swarmvault graph serve — Live workspace + workbench
• swarmvault graph query "<seed>" — Graph traversal
• swarmvault graph share --post|--svg|--bundle — Share artifacts
• swarmvault graph merge — Merge multiple graphs
• swarmvault graph cluster — Community detection
• swarmvault graph blast <target> — Reverse-import impact analysis
• swarmvault graph export --html|--json|--obsidian|--canvas|--neo4j

Maintenance

• swarmvault doctor [--repair] — Health check + repair
• swarmvault lint [--conflicts] [--web] — Schema validation
• swarmvault diff — Graph change summary vs. baseline
• swarmvault watch — Watch mode with git hooks

Export + Integration

• swarmvault export ai --out <dir> — llms.txt, JSON-LD, manifest
• swarmvault mcp — Start MCP server

Skill File

skills/swarmvault/SKILL.md — Full OpenClaw-compatible skill with 3.15.0 metadata. Registers with swarmvault or vault binary via OpenClaw's anyBins requirement.

Standalone Template

templates/llm-wiki-schema.md — Zero-install schema template for any LLM agent.

Desktop App

packages/viewer/ + downloadable desktop binary — includes graph viewer with interactive web app.

Obsidian Plugin

packages/obsidian-plugin/ — Obsidian integration.

SwarmVault — Uniqueness

Differs From Seeds

SwarmVault is most similar to ccmemory from the seeds (both are graph-based agent memory stores with MCP servers). Differences: ccmemory uses Neo4j + vector embeddings for agent memory of code context; SwarmVault uses SQLite FTS + optional embeddings for personal knowledge management across all content types (30+ formats), with a full CLI (30+ subcommands), desktop app, Obsidian plugin, approval queues, task ledgers, and context packs. SwarmVault's offline-first heuristic provider (no API keys needed) contrasts with ccmemory's Neo4j infrastructure requirement. The evidence-class tagging (extracted/inferred/ambiguous) and contradiction detection are not found in any seed. The llms.txt AI export format and swarmvault context build bounded handoff bundles are unique.

Positioning

Production-grade implementation of Karpathy's LLM Wiki pattern — the knowledge vault for individuals and teams who want compounding knowledge rather than ephemeral chat. Positioned explicitly against Karpathy's original gist and Obsidian (as an alternative with AI-maintained connections).

Observable Failure Modes

1. Node >= 24 requirement: Strict version requirement may create friction on older systems
2. LLM hallucination compounding: Despite approval queues, continuous compile + accept could let errors accumulate in wiki
3. Schema complexity: swarmvault.schema.md must be well-defined to get useful output; poor schema = poor wiki
4. 30+ subcommands: Steep learning curve; swarmvault next helps but complexity is real
5. Watch mode + git hooks: Background daemon adds complexity for simpler use cases

What Makes It Extraordinary

The evidence-class tagging system (extracted/inferred/ambiguous) with approval queues — the framework explicitly accounts for LLM hallucination compounding, which is the most common criticism of wiki-style knowledge systems. The context build bounded handoff for agents (token-limited evidence packs) is the most agent-aware handoff mechanism in the corpus.