WikiMoth

Connects the dots. The same way, every time.

wikimoth.com · pip install wikimoth

Deterministic, token-minimal, auditable memory for Claude and agents. Point WikiMoth at a folder of [[wikilink]] notes (an Obsidian vault, or Claude's own memory folder) and it follows the authored links to the answer flat search can't reach, shows you the exact note-chain behind it, and feeds the reader ~99% fewer tokens than pasting the whole vault. Pure markdown, no GPU, no vector DB, no LLM in the retrieval loop.

pip install wikimoth
wikimoth demo         # instant multi-hop recall over a bundled demo vault (no setup)

Already have a [[wikilink]] vault (an Obsidian vault, a notes folder)? Point WikiMoth at it and get the full connect-the-dots view in one command, no capture, no waiting:

wikimoth serve --vault /path/to/your/vault      # browse + "what memory fed this answer"
wikimoth recall --vault /path/to/your/vault "a connect-the-dots question"

Want it to build memory from your Claude Code sessions? Install the capture hooks; each session you run and close is written into a [[wikilink]] vault:

wikimoth install      # capture: turn your Claude Code sessions into a [[wikilink]] vault
wikimoth serve        # once you have captured sessions, browse them

Why not just let Claude manage its own context?

We benchmarked exactly that. An agent that browses the notes folder and prunes its own context reaches the same answers, multi-hop included (12/12 in our run). It just pays for it: 4 to 6 model round-trips and roughly 10x the billed tokens per question, because it re-sends a growing transcript every step. WikiMoth retrieves the same note-chain in one deterministic pass, no model in the loop, and shows you the exact notes behind the answer.

_{Real run, Claude Sonnet 4.6, 12 multi-hop questions on a reproducible vault. The ~10x counts a reader on both sides; it is corpus-specific, not a universal law. Reproduce it with python scripts/run_agentic_benchmark.py. Full breakdown in Honest limits.}

Why WikiMoth

Most agent memory is either paste the whole notes folder into context (expensive, and the model gets lost in the middle) or LLM-summarised similarity search (lossy, and non-deterministic: the same question can return different memory next week). WikiMoth takes a different bet: your notes are the store (plain markdown), the graph is authored (your [[wikilinks]], no embeddings to train or drift), and retrieval is code, not a model, so it's reproducible and you can read exactly why each note was chosen.

_{LLM Wiki follows links and skips the vector DB like WikiMoth, but an LLM writes and reads the wiki, so retrieval is agentic (an LLM call per recall, not reproducible), while its curated pages are richer. ~ = partial / not independently benchmarked.}

The edge is the combination, not higher recall: WikiMoth matches flat search on the basics and adds connect-the-dots + determinism + an audit trail + a plain-markdown store. See Honest limits for exactly where it ties and where it wins.

Compared to Karpathy's LLM Wiki

WikiMoth shares the substrate Andrej Karpathy's LLM Wiki pattern popularised: plain-markdown [[wikilink]] notes, no vector DB, but flips the engine. In the LLM-Wiki pattern an LLM writes and reads the wiki: rich, source-cited pages, but recall is agentic (it costs an LLM call and the path isn't reproducible). WikiMoth computes the edges in code and retrieves with a fixed algorithm, no LLM in the loop → the same note-chain every time, reproducible and auditable. They're complementary, not competing: point WikiMoth at a Karpathy-style wiki and you get deterministic multi-hop retrieval over it. (We don't claim to be "better" than the LLM Wiki: it curates richer pages; we retrieve deterministically.)

Quickstart (read)

from wikimoth import MemoryRAG, EchoReader

rag = MemoryRAG(reader=EchoReader())          # API-free default reader
rag.index("/path/to/your/wikilink/vault")     # notes → ~400-token chunks, graph built

chunks, tokens = rag.retrieve("a connect-the-dots question?", top_k=8)
print(f"{len(chunks)} chunks, {tokens} tokens to feed the reader")   # the headline win

# EchoReader is a deterministic stub for wiring/tests: it prints a diagnostic
# `[echo] ...` line, NOT a natural-language answer. Swap in ClaudeReader (below)
# for real prose. The retrieval + token numbers above are the same either way.
print(rag.answer("a connect-the-dots question?"))

Swap in a real Claude answer (only touches the API when constructed):

from wikimoth import MemoryRAG, ClaudeReader
rag = MemoryRAG(reader=ClaudeReader(model="claude-sonnet-4-6"))   # needs ANTHROPIC_API_KEY

See what memory fed an answer: wikimoth serve

wikimoth serve                 # serves http://127.0.0.1:8765 (local-only)
wikimoth serve --vault PATH --port 8080

A zero-dependency local web viewer (pure stdlib, no Flask, no JS framework, no network):

• browse + search your notes,
• the authored [[wikilink]] graph (the same edges the retriever walks),
• and the one that matters, "what memory fed this answer": type a question and see the exact note-chain WikiMoth would feed a reader, with per-chunk hop distance, token counts, and the −N% vs dumping the whole vault. Retrieval only: no LLM call, no API key, deterministic.

Because the store is plain markdown, you can equally open the same vault in Obsidian or VS Code; the viewer is a convenience, not a lock-in.

In the agent loop: wikimoth mcp

wikimoth serve is for you. The MCP server is for the model: it exposes the same deterministic retrieval over the Model Context Protocol, so Claude calls it itself instead of you fetching context by hand.

# 1. install into the Python that runs your Claude Code
python -m pip install wikimoth

# 2. verify the command resolves (prints status, then exits)
python -m wikimoth status

# 3. register the MCP server with Claude Code
claude mcp add wikimoth -- python -m wikimoth mcp

Step 2 is the check that matters: if python -m wikimoth status prints a status line, then python -m wikimoth mcp will run for Claude too. Use the same python in all three steps (it is python3 on some systems); that is the one thing that has to match.

Prefer the Node world, or no Python set up? One line, no toolchain matching:

claude mcp add wikimoth -- npx -y wikimoth-mcp

The wikimoth-mcp launcher finds a Python that has WikiMoth (or uvx-installs one on the fly), injects the vault path so the server never reads an empty folder from the client's working directory, and passes the MCP channel through untouched. The same npx -y wikimoth-mcp works as the server command in any mcpServers config (Claude Desktop, Cursor, Windsurf); set WIKIMOTH_VAULT to your vault.

Now Claude has a recall(query) tool. Ask it something that lives in your notes and it calls recall; WikiMoth walks the [[links]] and hands back the exact note-chain (no LLM call to retrieve, token-minimal, the same result every time), and Claude answers from it. A status tool reports the connected vault. For any other MCP client, use python -m wikimoth mcp as the server command (stdio transport); point it at a specific vault with --vault PATH.

python -m wikimoth mcp is the portable form (it runs wherever the package is installed). The bare wikimoth mcp works too when the console script is on your PATH. It is pure stdlib: a hand-rolled JSON-RPC 2.0 stdio server, no MCP SDK dependency.