SwarmVault
The local-first LLM Wiki: compiles docs, code, transcripts, and notes into a queryable knowledge graph and RAG base, giving Claude Code, Codex, and other agents durable memory — fully offline with no API keys required.
Good least privilege: hooks advisory by default, agent rule files not written by default, API keys referenced only via apiKeyEnv, raw/ sources immutable. Deductions: hooks trigger background graph update after Edit/Write and install mutates .gitignore/tsconfig (with exemptions, but still host-file edits); dependency manifests not visible so supply chain cannot be verified statically; rollback rests only on git --commit and doctor --repair; secret masking during ingest/voice is a README claim with no implementation shown.
Real tests exist (notices, chat/export, chunking) and CI uses frozen-lockfile, perf budgets, and packaged smoke. Deductions: tests cover peripheral behavior, not core graph compilation; failure messaging is largely described in the README rather than evidenced in code.
Audience/scenarios are thoroughly covered (PKM, research, code docs, agent memory) with an offline heuristic default and progressive provider upgrades. Deductions: several capabilities depend on external binaries (whisper.cpp, ffmpeg, yt-dlp) and experimental labels live in an STABILITY.md not provided; graph-first hook interception precision is described in detail but unverifiable statically.
Excellent information architecture (raw/wiki/schema/state layers, directory tree, multilingual README, install/update instructions, FAQ-style section, MIT LICENSE present). Deductions: no CHANGELOG or version-history file visible; maintenance responsibility only implicit in npm release scripts; known limitations are scattered (local-whisper experimental, R parser diagnostics) not consolidated.
Outputs are durable artifacts (save-first query, context packs, task ledger, share kit); offline heuristic provider lowers cost of entry. Deductions: token-savings and quality benefits are documentation claims without measured data; the very large command surface raises learning and maintenance cost for ordinary users.
Edges carry extracted/inferred/ambiguous tags and citations, partly confirmed in tests (citation: source:long#chunk-1); README and package. are mutually consistent on versions/commands. Deductions: the comparison table vs the Karpathy gist is self-asserted without checkable evidence; fact/inference separation depends on LLM output quality and its enforcement is not statically confirmable.
- This is a static review; no commands were executed, and performance/token-savings claims are unverified.
- install --agent writes project configs and edits .gitignore/tsconfig; review diffs before committing.
- Dependency manifests were not among the provided files; audit the @swarmvaultai/cli npm dependency tree before installing.
- The speech transcription model (~147MB) downloads to ~/.swarmvault/models/; verify the network source is trusted.
- Features depending on external binaries (whisper.cpp, ffmpeg, yt-dlp) are marked experimental; validate before production use.
- No CHANGELOG or maintainer governance files; long-term maintenance commitment lacks written backing.
What does this agent do, and when should you use it?
SwarmVault is an open-source, local-first knowledge tool that turns almost any input — PDFs, code repositories, transcripts, URLs, email, audio, and 30+ other formats — into a durable markdown wiki plus a machine-readable knowledge graph. It implements Andrej Karpathy's three-layer pattern: an immutable raw/ source layer, an LLM- and human-authored wiki/ layer, and a co-evolved swarmvault.schema.md schema layer. It ships as the @swarmvaultai/cli global command line (plus a desktop app), with core commands like quickstart, ingest, compile, query, graph serve, and doctor, and all artifacts live on disk under raw/, wiki/, and state/. The built-in heuristic provider runs entirely offline; Ollama local models or OpenAI, Anthropic, Gemini, and other cloud providers are optional. It doubles as an MCP server and installs rules and graph-first hooks for 40+ coding agents including Claude Code and Codex, making it usable as durable agent memory.
SwarmVault ingests local files, directories, public GitHub repos, URLs, arXiv/DOI papers, YouTube transcripts, and audio/video, processing them with local parsers (tree-sitter, the TypeScript compiler API, a SQL parser) plus optional LLM providers. Compilation produces wiki markdown pages, a state/graph. knowledge graph with provenance-tagged edges (extracted/inferred/ambiguous), a hybrid SQLite FTS + semantic embedding retrieval index, graph reports, and share cards. Contradiction detection, approval bundles (compile --approve), and a candidates queue (wiki/candidates/) keep LLM output reviewable. swarmvault context build writes cited, token-bounded context packs for coding agents; swarmvault task start records an agent task ledger; swarmvault mcp exposes graph stats, context-pack, task-ledger, and doctor tools over stdio MCP; swarmvault install --agent claude --hook --mcp wires session hooks and an MCP registration into .mcp.; and swarmvault graph export --neo4j emits Cypher for pushing the graph into Neo4j.
- A personal researcher compiling journal entries, podcast transcripts, and papers into a dashboards-equipped private Memex (the worked/personal-knowledge-base example targets exactly this)
- A Claude Code or Codex user who wants the agent to answer code questions from a local graph first, cutting repo-wide greps and token spend
- A software team generating module pages, call-edge analysis, and blast-radius reports (graph blast, graph callers) for a codebase
- A book reader building a chapter-by-chapter fan wiki with auto-cross-referenced character and theme pages that compound as reading progresses
- A consultant or analyst who needs offline transcription of meeting recordings and customer-call subtitles folded into the knowledge base (whisper.cpp local Whisper)
- An Obsidian user migrating to an auto-compiled graph workflow while keeping Obsidian export compatibility
What are this agent's strengths and limitations?
- Fully offline by default: the heuristic provider and local parsers need no API keys or network, and source code contents are never sent to external APIs
- Every graph edge is tagged extracted/inferred/ambiguous with automatic contradiction detection, so LLM output is auditable rather than silently trusted
- MCP server plus rule/hook installs for 40+ coding agents make it a drop-in durable memory layer for Claude Code, Codex, and peers
- Hybrid retrieval (SQLite FTS + semantic embeddings) and compile --max-token budgeting are explicitly designed to scale past 100 pages
- Approval queues, candidates staging, and
swarmvault diffmake every compile reviewable and graph changes comparable
- The CLI requires Node.js >= 24, a recent runtime that may force upgrades in some environments
- Heuristic-mode extraction quality is limited; sharp concept/entity/claim extraction requires configuring Ollama or a cloud LLM provider yourself
- The local-whisper audio transcription provider is documented as experimental in STABILITY.md for 1.1.0 and may change
- The feature surface is very large (graph subcommands, source sessions, profiles, task ledger), creating a real learning curve despite quickstart/next guidance
- Website documentation is English-first, and translated READMEs may drift from the canonical English wording
How do you install or deploy this agent?
Requires Node.js >= 24. Install globally: npm install -g @swarmvaultai/cli, verify with swarmvault --version. Alternatively, download the desktop app (macOS/Windows/Linux) from swarmvault.ai/download — no Node.js needed. First vault: mkdir my-vault && cd my-vault && swarmvault quickstart ../your-repo. No API keys are required — the built-in heuristic provider runs offline. Optional upgrades: install Ollama and ollama pull gemma4 for sharper local extraction, or run swarmvault provider setup --local-whisper --apply (requires whisper.cpp) for offline audio transcription.
How do you use this agent?
Core loop: swarmvault next (read-only suggestion of the next step), swarmvault ingest ./src --repo-root . to ingest sources, swarmvault compile to build wiki and graph, swarmvault query "What is the auth flow?" (answers save to wiki/outputs/ by default), and swarmvault graph serve to open the local graph viewer. Managed recurring sources: swarmvault source add https://github.com/owner/repo, then source reload --all to refresh. Agent setup: in the repo run swarmvault init && swarmvault ingest ., then swarmvault install --agent claude --hook --mcp --graph-first, and swarmvault hook install for git-hook refreshes; build an agent handoff with swarmvault context build "Implement the auth refactor" --target ./src --budget 8000. Health check: swarmvault doctor --repair.
How does this agent compare with similar options?
The README explicitly positions SwarmVault as the production-grade implementation of Karpathy's LLM Wiki gist, and directly compares itself with Obsidian: where Obsidian requires manual note upkeep, SwarmVault auto-compiles the wiki, builds a typed knowledge graph, and detects contradictions, while graph export --obsidian emits an Obsidian-compatible bundle with Dataview dashboards and Breadcrumbs/Juggl typed links — an alternative or companion to Obsidian.
FAQ
Do I need to pay or configure API keys?
Will my code and data be uploaded?
Is this exclusive of Obsidian?
--obsidian for workspace config, graph export --obsidian produces a full bundle with typed links and Dataview dashboards, and the wiki itself is plain markdown.Does the LLM write new concepts straight into the wiki?
compile --approve stages changes into reviewable approval bundles, and lint --conflicts audits contradictions — nothing mutates silently.