SwarmVault: turning Karpathy's LLM Wiki pattern into a local CLI toolchain
The local-first LLM Wiki: open-source knowledge graph builder, RAG knowledge base, and agent memory store. Built on Andrej Karpathy's pattern. An Obsidian alternative for personal knowledge management, AI second brain, and durable Claude Code / Codex / OpenClaw memory.
At a glance
- What is it?
- SwarmVault is an MIT-licensed TypeScript CLI that ingests sources into an immutable raw/ folder, compiles a markdown wiki and a typed graph, and exposes both to agents over MCP. The design is sound for local-first knowledge work; the open questions are provider quality and scale.
- Who is it for?
- Adopt SwarmVault if you already accumulate sources faster than you can index them and you want the index to live as markdown on your own disk. Skip it if you need a hosted, multi-tenant knowledge service or you expect the offline heuristic provider to produce publication-grade entity extraction.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 77 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem SwarmVault addresses is maintenance, not retrieval
Most personal knowledge tools fail at the same point. Collecting is easy. Keeping the collection linked, deduplicated and current is the part that decays. The README frames this directly, borrowing Vannevar Bush's Memex idea of associative trails and then naming the unsolved half: "The part Bush couldn't solve was who does the maintenance. The LLM handles that." SwarmVault is aimed at people who already have a pile of material (books, transcripts, mail exports, slide decks, screenshots, URLs, source code) and want it compiled into something navigable rather than left as a folder of files. The stated use cases are personal knowledge management, research deep-dives, book companions, code documentation and business intelligence. It is also pitched as durable memory for coding agents, which is a different audience: someone running Claude Code or Codex who wants project facts to survive between sessions instead of being re-derived each time.
Three layers on disk, and what each one is allowed to do
The architecture is the Karpathy three-layer pattern made concrete. Layer one is raw/, described as immutable copies of ingested material; SwarmVault reads from it and never writes back. Layer two is wiki/, holding generated and human-authored markdown: source summaries, entity pages, concept pages, cross-references, dashboards and outputs. Layer three is swarmvault.schema.md, a file you and the model co-evolve that defines wiki structure and domain conventions. That third layer is the interesting one, because it is where the tool admits that structure is a judgement call rather than a default. Alongside the wiki, the tool writes state/graph.json for the machine-readable graph and state/retrieval/ for the local search index. The separation matters operationally: you can delete and regenerate wiki/ and state/ from raw/ plus the schema, but you cannot regenerate raw/ if you lose it. Treat raw/ as the thing worth backing up.
Typed edges and approval queues are the answer to compounding errors
The strongest design decision documented in the README is that every graph edge carries a tag: extracted, inferred or ambiguous. That is a cheap mechanism with real consequences. It means a query can distinguish a relationship the model read off a page from one it guessed, and it gives you a filter for review. Contradiction detection is described as flagging conflicting claims, with lint --conflicts available as an on-demand audit. New concepts do not go straight into the wiki; they land in wiki/candidates/ first, and compile --approve stages changes into reviewable approval bundles. Read together, these choices say the project expects the model to be wrong sometimes and has built the pipeline around human review rather than around trusting output. Whether that review load is tolerable in practice depends on corpus size and on which provider you run, and the README does not give numbers for either.
Getting a vault running, and the commands that follow
Installation is a global npm package requiring Node 24 or later, according to the badge in the README: npm install -g @swarmvaultai/cli. The first run is swarmvault quickstart ./your-repo, which the README says initializes a vault in the current directory, ingests a local file, directory or public GitHub repo, compiles the wiki and graph, writes share artifacts and opens the local graph viewer. quickstart is described as a beginner-friendly alias for swarmvault scan. If you have nothing to ingest, swarmvault demo exists. After a first compile the README points at swarmvault next, swarmvault query "What are the key concepts?", swarmvault graph serve, swarmvault doctor and swarmvault candidate list. The state-inspection command is worth noting: swarmvault next is read-only and reports whether the vault needs initializing, ingesting, compiling, querying, reviewing or refreshing. A desktop app for macOS, Windows and Linux is also offered that bundles its own runtime, so Node.js is not required on that path.
Offline by default, and the quality ceiling that implies
No API keys are needed for the first run. The built-in heuristic provider runs locally and offline, and the README suggests pairing with a free local model via Ollama for sharper extraction, with cloud providers optional. This is the central trade-off of the project and it should be stated plainly: the zero-configuration path is a heuristic, not a language model, so the wiki it produces on a first pass reflects pattern-based extraction rather than synthesis. The README's own framing is that you start with one command and "learn the deeper graph, review, context-pack, and automation workflows when you need them." The honest reading is that the offline default gets you a working vault and a graph skeleton, and the interesting output requires either a local model through Ollama or a cloud provider you configure yourself. Anyone evaluating this on a single quickstart run without a model provider is evaluating the weakest configuration.
Where the toolchain stops: scale, judgement and the wrong corpus
The README addresses scale head-on, saying hybrid search merges SQLite full-text with semantic embeddings so queries work without fitting every page into context, and that compile --max-tokens trims output to bounded windows. It also offers graph query, graph path, graph explain and graph callers for traversal instead of search. What it does not provide is a number: no corpus size, no page count, no index build time. The claim that it scales past 100 pages appears only as a quoted community concern, not as a measurement. Two other limits are visible in the design. First, the schema layer is a manual commitment. A vault with a vague swarmvault.schema.md will produce a vague wiki, and nothing in the README suggests the tool will infer your domain conventions for you. Second, review is a real cost. Approval bundles and a candidates folder are the right mechanism, but they assume a human who will actually read them. If you want a system that ingests a thousand documents and produces trustworthy entity pages with no oversight, this is not that, and the README does not claim it is.
Against Obsidian, and where the difference actually lies
The repository topics list obsidian-alternative, so the comparison is invited. The difference is not in the file format. Both leave you with markdown on disk. The difference is who writes the pages and how links get made. In Obsidian, you create notes and you create links, and plugins can suggest connections but the graph is a view over your own authoring. In SwarmVault, ingestion and compilation produce the pages and the edges, with a schema file steering the conventions and a review queue gating what enters the wiki. That inverts the workflow: you curate sources rather than notes. It also means the quality of your vault is bounded by extraction quality in a way that a hand-authored Obsidian vault is not. If you enjoy writing notes and want a graph over them, Obsidian is the better fit and SwarmVault adds little. If you have sources you will never get around to summarizing, the compile step is the entire point.
Licence, release cadence and what maintenance looks like
SwarmVault is MIT licensed, which permits commercial and private use and modification, with the usual requirement to preserve the licence notice. That is a permissive choice and it removes the licensing question from most adoption decisions; it is not legal advice, and if you redistribute a modified version you should read the LICENSE file in the repository yourself. On cadence, the release list shows v3.18.0, v3.19.0 and v3.20.0 all dated 2026-06-12, and the last push to main is 2026-06-30. Three minor releases in one day suggests either a burst of fixes or a release pipeline that publishes frequently; the material does not say which, and it is worth checking the release notes before you pin a version. The practical upgrade cost is low if you keep raw/ intact, since wiki/ and state/ are derived artifacts you can regenerate. The cost that is not low is re-review: if you have accumulated approval decisions in wiki/candidates/ and a recompile changes extraction output, some of that review work may need repeating. Pin your CLI version in CI for that reason.
Editorial conclusion
Adopt SwarmVault if you already accumulate sources faster than you can index them and you want the index to live as markdown on your own disk. Skip it if you need a hosted, multi-tenant knowledge service or you expect the offline heuristic provider to produce publication-grade entity extraction. Before committing, run swarmvault quickstart on a real corpus, then read state/graph.json and wiki/candidates/ to check how many edges are tagged inferred or ambiguous and how much still needs approval.
Community notes