Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cad0p/pi-napkin/llms.txt

Use this file to discover all available pages before exploring further.

Vault resolution is the mechanism napkin uses to determine which vault a command (or pi session) operates on. Both napkin-context and napkin-distill rely on the same resolution logic, and getting it wrong can silently create an empty vault in an unexpected location. Understanding the resolution order is especially important when working across multiple vaults or in directories unrelated to any vault.

​
Resolution Order

Every napkin command and pi-napkin session resolves the vault in this exact order, stopping at the first match:
1

--vault flag

If you pass --vault <path> to a napkin CLI command, that path is used unconditionally. This overrides everything else and is the safest option when you need to target a specific vault from an arbitrary directory.
napkin --vault ~/projects/my-notes overview
2

Nearest ancestor with .napkin/

napkin walks upward from your current working directory, checking each ancestor for a .napkin/ subdirectory (or .obsidian/.napkin/ for Obsidian vaults). The first match is used as the vault. This is how local project vaults are detected automatically — running pi inside a project directory that contains a .napkin/ folder resolves to that vault without any extra configuration.
3

Global fallback

If no .napkin/ ancestor is found, napkin reads the vault field from the global config file at $XDG_CONFIG_HOME/napkin/config.json (defaults to ~/.config/napkin/config.json).
{
  "vault": "~/path/to/vault"
}
The vault value supports ~ expansion. Paths without ~ are resolved relative to the config file’s own directory. You can override the config location entirely by setting XDG_CONFIG_HOME in your environment.
4

Bare vault auto-created at cwd

If none of the above match, napkin silently creates a new bare vault in the current directory — it writes .napkin/, NAPKIN.md, and .obsidian/ with no prompt and no confirmation. This is the last resort fallback and is almost never what you want outside of a deliberate new-vault workflow.
Step 4 is a footgun. Running any napkin command (including napkin vault) from a random directory with no ancestor .napkin/ and no global config will silently create an empty vault there. This can happen in your home directory, a project root, or any other directory you happen to be in. Always confirm vault resolution before first use (see below) and configure the global fallback if you work from multiple locations.

​
Configuring the Global Fallback

Set the vault key in ~/.config/napkin/config.json to point at your primary vault. This ensures that napkin commands run from arbitrary directories always resolve to the right vault rather than triggering step 4. 
{
  "vault": "~/path/to/vault"
}
Supports ~ expansion; paths without ~ are resolved relative to the config file’s directory. Override the config location with XDG_CONFIG_HOME: 
export XDG_CONFIG_HOME=~/.config   # default; change to taste

​
Confirm Resolution Before First Use

Before running any distill command or starting a pi session in an unfamiliar directory, confirm which vault will be used: 
napkin vault --json | jq -r .path
This should print the absolute path of the vault napkin resolved. If it prints your current working directory or $HOME, napkin may have just created a bare vault there — delete the stray .napkin/, NAPKIN.md, and .obsidian/ it generated and configure the global fallback before continuing.
Run napkin vault --json before every new project or directory to confirm vault resolution. It’s a fast, read-only check that tells you exactly which vault will receive your distilled knowledge. Making this a habit prevents accidental bare-vault creation and misrouted distills.

​
Local Project Vaults vs Global Fallback

Local project vaults (the nearest .napkin/ ancestor) always take priority over the global fallback. This means:
  • Running pi inside a project directory with a .napkin/ folder auto-discovers that vault, even if your global config points somewhere else.
  • Switching between projects means switching vaults automatically — no --vault flag needed.
  • The global fallback only fires when there is no local vault in the ancestor chain. It serves as your personal knowledge base for conversations that happen outside any specific project.

​
Migrating from ~/.pi/agent/napkin.json

If you previously configured your vault path in the old location (~/.pi/agent/napkin.json), move it to the current location: 
mkdir -p ~/.config/napkin
cp ~/.pi/agent/napkin.json ~/.config/napkin/config.json
After moving the file, verify that resolution picks up the new location: 
napkin vault --json | jq -r .path

Build docs developers (and LLMs) love

Get started for freeTalk to us