Tusk's Vault

Ask your D&D, Pathfinder, or TTRPG campaign anything — accurate, source-cited answers from your own lore documents, in Discord, Foundry VTT, or any MCP client.

Local-first AI lore assistant. Open source. MIT-licensed. Free forever.

Like NotebookLM for Dungeons & Dragons — except it runs on your machine, and it refuses to make things up.

What it is, in one page →  ·  See real cited answers  ·  Setup walkthrough  ·  Foundry VTT  ·  How it compares

Why this exists

My campaign notes were spread across six documents, two of which contradicted the other four. Players asked me the same questions between sessions — who was that merchant, what did we agree to, whose brother is the king — and I answered from memory, badly, and sometimes differently than last time.

The obvious fix is to ask an AI. That fails in a specific and infuriating way: a general chatbot given your setting will answer every question confidently, including the ones your documents say nothing about. It invents a plausible duke. It gives your NPC a motive you never wrote. And because the invented answer reads exactly like the real one, you only find out at the table, in front of everyone.

So the whole design of this project is one idea: the bot may only tell you what your documents say, and it must show you where it got it. Every answer carries a citation. When the answer is not in your sources, it says so in a fixed phrase — and logs the question so you can answer it once, properly, and have that answer reused forever after.

It runs on your machine. Your campaign documents never leave it; only the question and the matched snippets go to whichever model you pick — Gemini, ~400 models via OpenRouter, a Claude subscription you already pay for, or fully offline through Ollama.

You'll probably get on with this if…

• You're a GM who has answered "wait, who was that again?" more times than you'd like, and would rather your players asked something that has actually read the notes.

• You want to check your own worldbuilding for contradictions — query your setting like an outsider and see what surfaces.

• You have a player joining a 30-session campaign and would rather point them at a bot than write them a primer.

• You're a player who missed a session and doesn't want to DM the GM at 1am.

• You play on Foundry VTT and want answers in the chat bar mid-session, with per-world control over what players can pull out of the archive.

• You stream or make actual-play content and want to answer chat questions without breaking the scene.

• You are not willing to upload your campaign to somebody's cloud to get this. Nothing here leaves your machine except the question and the snippets that answer it.

• You'd rather own the tool than rent it — a free Gemini tier covers most home games, and a local model costs nothing at all.

A fair warning: this is one person's project. It expects you to be comfortable installing Node.js and running a script. Known issues lists the known limitations and the trade-offs that are deliberate.

What Tusk's Vault does

It is the assistant that has read every word of your campaign — and only those words. Drop your lore into a shared Tusks-Lore/ folder, then ask from wherever you already are: @-mention it in Discord, type /tusk in Foundry's chat bar, or use the dashboard.

Answers come back with one of three citation flavours — [filename], [clarification: ID], [D&D 5e] — so you can always see whether a claim came from your canon, from a ruling you made earlier, or from the rules.

It never invents campaign lore. A canonical seven-rule block is appended to every prompt at assembly time, so citation discipline and the no-invention contract are structurally guaranteed rather than configured — you cannot turn them off by editing a system prompt.

When the answer genuinely isn't in your sources, the bot emits a fixed refusal phrase and the question lands in the dashboard's Lore Gaps tab. Answer it once and it is remembered forever, including when a future player phrases the question completely differently.

How Tusk's Vault compares

The column that matters is the fourth. Most tools will answer anything you ask; the useful behaviour is knowing when to stop.

The fifth matters for a different reason. This is one person's project, so it is fair to ask what happens if it stops. Local-first and MIT bound the answer:

• Your campaign stays the folder of files it always was. Vault never converted or imported anything, so there is no export step.

• Your install keeps working. Nothing runs on anyone else's server, so there is no switch for anyone to flip.

• The code is yours to fork — MIT.

• What you would lose is upkeep, not material.

The full version, including what genuinely breaks, is under What happens if this project dies in the Comparison.

Full, honest breakdown — including where the alternatives are better: Comparison

Prerequisites

• Node.js 20 or newer — download from nodejs.org. The LTS build is fine.

• Git — download from git-scm.com. Required for the in-app updater.

You don't need Python, Docker, a database, admin rights, or a paid LLM key.

Quick start

Mac / Linux

git clone https://github.com/KochiTusker/Tusks-Vault.git
cd Tusks-Vault && ./run.sh

Windows — clone the repo, open the folder, and double-click run.bat. Or download install-tusks-vault.bat and run that instead; it prints the whole plan and confirms before it touches anything.

The launcher checks your Node version and installs dependencies against the committed lockfile (~1 minute, no global tools, no admin rights), then starts the server and opens http://localhost:3000 automatically. If port 3000 is busy it walks up to 3019 and opens whichever it got.

Cost

Vault itself is free, forever, MIT-licensed. No subscription, no account, no telemetry, no paywalled features. The only money involved is the LLM key of whichever connection you pick:

• Google Gemini — a generous free tier that comfortably covers most home games. Kept as a direct connection because it is cheaper called directly than through an aggregator.

• OpenRouter — pay-as-you-go, typically $0.60–$4 per three-hour session, and one key reaches Claude, GPT and ~400 other models.

• Claude Code — no API key at all; answers through a Claude Pro or Max subscription you already pay for.

• Ollama — zero ongoing cost. Runs on your machine, fully offline once a model is pulled.

Per-session breakdown, the work going into bringing costs down, and how to set spending caps: docs/FAQ.md → Costs.

Where the answers come from

Four connections, and only two of them take a key.

Vault probes which models a key can actually call — catalogues advertise models that a given key or privacy policy will refuse — and marks the picker accordingly, so you find out before a session rather than during one.

Where you can ask from: Discord, Foundry VTT's chat bar via a companion module that pairs in one click — it lives in its own repository, Tusks-Vault-VTT — and any MCP client. The dashboard is where you configure and inspect Vault; questions are asked from the surfaces your table already uses.

Personas swap the bot's voice without weakening citation discipline — seven presets, or author your own from a template or a description.

Full guide: Choosing a provider · Foundry VTT

The Tusk's trio — Vault, Tomes, and Lore

Drop them side-by-side on disk and they find each other automatically: Tomes writes chronicles into Tusks-Lore/, Vault answers questions about them. Each works perfectly on its own.

Pairing details: Tusk's Tomes

Documentation

The full docs live under docs/ so this page stays readable. They are also published, with search-friendly pages and an index, at kochitusker.github.io/Tusks-Vault/docs/.

Project meta: Roadmap · Contributing · Code of Conduct · License

Community & feedback

A dedicated Discord community for Tusk's Vault and Tusk's Tomes is on the roadmap — if there's enough interest, a server will be spun up for setup help, feature ideas, campaign showcases, and dev talk. For now, GitHub issues are the fastest way to ask a question, report a bug, request a feature, or signal that you'd like to see a community Discord exist.

Security issues go through private vulnerability reporting, not public issues.

Tech stack

• TypeScript end-to-end, ESM-only, Node 20+.

• One HTTP socket — Express 4 and Vite middleware share it. No separate frontend dev server, no build step in development.

• React 19 + Tailwind 4 on the dashboard.

• discord.js 14 for Discord; a hand-rolled Streamable HTTP MCP server for Foundry and other clients, bearer tokens stored only as SHA-256 hashes.

• MiniLM-L6-v2 on CPU via @huggingface/transformers for clarification matching — no embedding text is ever sent anywhere.

• AES-256-GCM key store with a machine-bound scrypt key.

• No database — JSON on disk, split by what should survive a reinstall.

Full architectural breakdown: How it's built

Support the project

Free (30 seconds): star the repo · tell another GM · open an issue with what you'd want it to do.

Free (a bit more): file bug reports · send PRs · vote on roadmap items.

With money: buy me a coffee.

Tusk's Vault is MIT-licensed and free forever. Nothing here is paywalled, ever.

License

MIT — fully open source, OSI-approved. Use it, fork it, modify it, redistribute it, ship it inside your own product, sell support around it. The only requirement is that the original copyright notice and licence text travel with the code.

Just don't blame me if your party ends up in Avernus.

What problems does this solve? "How do I search my D&D campaign notes" · "AI that won't make up lore" · "Self-hosted NotebookLM alternative for TTRPG" · "Discord bot that answers questions about my campaign" · "How to stop my players asking me the same question twice" · "Foundry VTT lore assistant" · "Local AI for Dungeon Masters" · "Cited answers from my own worldbuilding documents"