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.
The napkin-context extension gives every pi session first-class awareness of your Obsidian-compatible knowledge vault. When a session starts, it automatically injects a structured overview of your vault into the agent’s context window, and registers two tools — kb_search and kb_read — so the agent can discover and read notes on demand without leaving the conversation. This means the agent knows what’s already in your vault before it writes anything new, naturally avoiding duplicates and building on existing knowledge.
Vault overview injection
On session_start, the extension calls napkin overview(), formats the result as markdown, and appends it as a custom session message with the type napkin-context. The injected message is constructed as:
## Napkin vault context
You have access to a napkin vault (Obsidian-compatible knowledge base). Here is the vault overview. Use the kb_search tool to find specific content, and the kb_read tool to read files.
<vault overview here>
"## Napkin vault context\n" +
"You have access to a napkin vault (Obsidian-compatible knowledge base). " +
"Here is the vault overview. Use the kb_search tool to find specific content, " +
"and the kb_read tool to read files.\n\n" +
overview
📜 napkin vault context — Ctrl+O to expand — to keep the conversation clean. Press Ctrl+O to expand it and read the full overview inline.
Idempotency
If vault context has already been injected earlier in the same session (for example, after a session resume or reload), the extension checks the session entries for an existing napkin-context custom message and skips re-injection. The context is always present exactly once.
kb_search
Searches the vault for notes matching a query string. The agent uses this to check whether a topic is already covered before creating a new note.
| Parameter | Type | Description |
|---|
query | string | Keyword or topic to search for |
{ file: string, snippets: [{ text: string }] } — the file path and one or more snippet strings showing where the query appears. Returns "No results found." when nothing matches.
kb_read
Reads the full content of a note by name or path.
| Parameter | Type | Description |
|---|
file | string | File name or path to read (e.g. auth/oauth-flow.md) |
result.content) as the tool text, and includes the resolved file path (result.path) in the tool details. Use this to read an existing note in full before appending to it or linking from it.
# Agent uses kb_search to find relevant notes before writing
kb_search("authentication patterns")
# Then reads a specific note
kb_read("auth/oauth-flow.md")
Status bar
When napkin-context loads, it sets an entry in the pi status bar:
| Vault state | Status bar text |
|---|
| Vault found and overview loaded | 📜 napkin |
No vault resolved (no NAPKIN.md) | napkin: no NAPKIN.md |
Controlling the status bar entry
The showStatus key in your vault’s .napkin/config.json controls whether the status bar entry appears at all. It defaults to true.
Set it to false to hide both the 📜 napkin and napkin: no NAPKIN.md entries from the status bar. All other napkin-context behavior (vault overview injection, kb_search, kb_read) is unaffected.