Your Obsidian vault, read from Foundry.

Read where it sits, never copied across

The usual way to get Obsidian notes into a Foundry game is to import them: something walks the vault and writes a journal entry per note. That works, and then you own two copies of everything. Edit a note, re-import. Forget, and the AI is reading last month.

Familiar takes the other route. While Obsidian is open it talks to the vault directly and reads files on demand: list what is in a folder, open one note, search every note for a phrase, browse your tags by how often you use them. The vault stays the only copy. Nothing is cached either, so what comes back is what you saved a minute ago.

The cost of that is honest and small. Obsidian has to be running, normally on the machine you play from, and it has to have the right vault open. Close it and the notes are not there.

Read-only is not a setting you could switch the wrong way. There is no write path in the product at all, so nothing the AI does can change, move, or delete a note.

Connecting the vault

Obsidian has no API of its own, so the connection runs through a community plugin. You install it, turn on its plain HTTP server, and hand Familiar the key it prints. Five minutes of settings, once.

1. 1

   Install the plugin

   In Obsidian, open Settings and go to Community plugins. If you are still in Restricted mode, turn community plugins on. Then Browse, search for Local REST API, and install it. Check the author before you click: the one you want is published by coddingtonbear, and it now shows in the catalogue as "Local REST API with MCP". Enable it once it is installed.

2. 2

   Switch on the plain HTTP server

   In the plugin settings, enable the non-encrypted HTTP server. It is off by default, and the encrypted port it prefers instead carries a certificate the plugin signs itself, which a browser will refuse. The HTTP server listens on your own machine only, so nothing crosses the network.

3. 3

   Copy the API key

   The key sits on the plugin's main settings page with a copy button beside it. Treat it as a password: anything holding that key has full read and write over the entire vault, which is more than Familiar itself will ever use. It does not belong in a screenshot, a pasted config, or a shared repo.

4. 4

   Point Familiar at it

   In Foundry, open Familiar's settings and pick the Notes tab. Turn on the vault, then press Use default to fill in the local address: the field starts empty, and the address you can see in it is only a placeholder. Paste the key and press Test connection with Obsidian still running. The test makes the same call the AI's tools do, so a green result means the vault is genuinely reachable, not just that something is listening on the port.

5. 5

   Decide what it may read

   The Folders field takes a comma-separated list, something like Campaigns/Ravenloft, Session Notes. Name folders there and the vault outside them is out of reach: a read is refused and a search never returns it. Subfolders come along automatically. Capitalisation has to match what Obsidian shows, and the connection test does not check this field, so a typo here still tests green and then refuses every read.

• Notes Vault

Leave the Folders field empty and the whole vault is readable. That is the default, so it is worth the minute before your first session.

Where this works, and where it does not

One fact settles most of the questions here: Familiar reads the vault from your browser, not from the Foundry server. The request leaves the same machine your Foundry tab is open on, which is normally the machine Obsidian is running on too. Where Foundry itself is hosted matters much less than people expect.

What the AI actually sees

Obsidian shows you a rendered page. The file on disk is often a different thing, and the file is what gets read. That gap is where a vault surprises people. A session page that looks finished on screen can arrive nearly empty.

A note comes back as raw markdown, exactly as you typed it, with nothing parsed on the way. A very long note arrives a chunk at a time, and the AI is told there is more to fetch. What that includes and what it leaves out is worth knowing before you rely on it mid-scene.

One way to see all of this at once: open a note in Obsidian and switch to source mode. What is on that screen is what the AI gets.

Hiding a thing is not the same as excluding it

GMs hide things in a vault constantly. The twist goes inside a percent-sign comment, the reveal sits in a collapsed callout, the spoiler folder goes into Obsidian's Excluded files list. Every one of those hides text from your eyes in reading view. None of them takes it out of the file. The plugin reads the file. Obsidian's exclusion setting in particular is a search and display preference, not a fence.

So the boundary that actually holds is the one at file level: the Folders field. Name what it may read, and the rest of the vault cannot be listed, opened, or searched. If the twist has to stay off limits, it needs to be in a folder you left out, or in a different vault entirely.

Whichever way you set that, what the AI does read goes to the provider you connected, the same as anything else it reads in your world. If that is the sticking point, running the model on your own machine keeps your notes on your own machine.

• An empty Folders field means the whole vault. There is no implied default scope and no fence already standing.
• Setting a folder list switches off the tag browser. Obsidian reports tags for the whole vault or not at all, so Familiar refuses the tool rather than leaking counts from folders you excluded. Search still works normally.
• Provider keys are the one thing stripped out of anything the vault returns, on the reasoning that a personal vault is exactly where a pasted key ends up. Nothing else is filtered.

• Running a local LLMKeep the notes on your own hardware by running the model there too.

Writing notes it can find

The search is plain text. No operators, no fuzzy matching, no sense of what a note is about: it looks for the characters you typed, in the notes it is allowed to reach. The other half is quieter and matters more. When the AI lists a folder it gets file paths and nothing else, so your filenames are the only thing it has to go on when it decides which note to open.

Neither of those asks for a rebuilt vault. They ask for a handful of habits that make a note findable by something that cannot see your graph.

• Name a note by what is in it. "Session 12" says nothing. "Session 12, Harrowmoor, Kaelen turns on the party" says who, where, and what before the file is even opened.
• Spell names out in the prose. A line that reads "he finally admits it" is invisible to a search for the NPC. Put the name near the sentence that needs it.
• Keep load-bearing facts in the text, not only in properties. Frontmatter does come through, but it arrives as its own block, away from the paragraph that explains why it matters.
• Use the aliases property. It is stored in the file, which makes it a free synonym list: the nickname your players actually say will now find the note you filed under a formal title.
• One subject per note, with headings. A single page holding six locations returns one hit and a wall of text. Six pages return the right one.
• If you live in Dataview, write out the results you actually need at the table. A query that draws a perfect table on screen leaves an empty page on disk.

What still belongs in Foundry

A vault is where prep gets written. It is not where the game runs, and Familiar keeps the two apart on purpose.

The vault is read on demand and nothing more. Notes are not folded into the campaign search, they are not saved into the memory bank, and they do not carry between sessions on their own. Ask about your notes and the AI goes and reads them. It has not read them already, and it will not go looking unprompted.

Anything the table touches still has to be a real Foundry document. A monster the AI rolls for is an actor sheet, not a paragraph. A battlemap is a scene. A handout the players open is a journal page. The usual path from one to the other is to have the AI read the note and build the Foundry document from it, which is also the reason the vault tools never needed a write side.

• Notes Vault
• Journals & Notes

• Prepping a published adventure for AIThe three artefacts that have to be Foundry documents, and why.
• Staying consistent across sessionsWhat the campaign record holds, which is a different store from your vault.

When it comes back empty

Most vault problems are one of a handful, and the error Familiar shows usually names the right one. These are the ones that send people looking in the wrong place.

Try it on tonight's prep

Connect the vault, then ask for something you know is in there: what your notes say about the place the party is heading, or who they promised what to last week. One question tells you whether the plumbing works and whether the note you had in mind is written down at all.

If it comes back empty, the two likely reasons are both on this page. Obsidian is not running, or the note you were thinking of is drawn rather than written.

• Install Familiar in Foundry
• Every tool Familiar can runThe vault tools in full, alongside the rest of what it reaches.
• Stuck on the plugin? Ask in the Discord