🧻 Knowledge system for agents. Local-first, file-based, progressively disclosed.
Every great idea started on a napkin.
npm install -g napkin-ai# Initialize a vault
napkin init --template coding
# See what's in it
napkin overview
# Search for something
napkin search "authentication"
# Read a file
napkin read "Architecture"
# Write
napkin create "Decision" --template Decision
napkin append "Decision" "We chose Postgres."
napkin daily append "- [ ] Review PR"napkin is also a library. No CLI, no stdout - just data:
import { Napkin } from "napkin-ai";
// Always works - creates bare vault if needed
const n = new Napkin("/path/to/project");
// Progressive disclosure
const overview = n.overview();
const results = n.search("authentication");
const file = n.read("Architecture");
// Write
n.create({ name: "New Note", content: "# Hello" });
n.append("New Note", "\nMore content");
// Daily notes
n.dailyEnsure();
n.dailyAppend("- Met with team");
// Everything else
n.tags();
n.tasks({ todo: true });
n.linksBack("Architecture");
n.outline("Architecture");
n.properties();
n.bookmarks();
n.config();Scaffold with a template:
Napkin.scaffold("/path/to/project", { template: "coding" });
Napkin.vaultTemplates(); // list available templatesAll SDK methods return typed data and throw errors on failure. No console.log, no process.exit.
napkin is designed as a memory system for agents. Instead of dumping the full vault into context, it reveals information gradually:
| Level | Command | Tokens | What it does |
|---|---|---|---|
| 0 | NAPKIN.md |
~200 | Project context note |
| 1 | napkin overview |
~1-2k | L0 + vault map with TF-IDF keywords |
| 2 | napkin search <query> |
~2-5k | Ranked results with snippets |
| 3 | napkin read <file> |
~5-20k | Full file content |
napkin includes agentic retrieval benchmarks in bench/. The headline result is LongMemEval (ICLR 2025), which tests long-term conversational memory across 500 questions.
| Dataset | Sessions | pi + napkin | Best prior system | GPT-4o full context |
|---|---|---|---|---|
| Oracle | 1-6 | 92.0% | 92.4% | 92.4% |
| S | ~40 | 91.0% | 86% | 64% |
| M | ~500 | 83.0% | 72% | n/a |
Zero preprocessing. No embeddings, no graphs, no summaries. Just BM25 search on markdown files.
See bench/README.md for details and usage.
.napkin/ holds config. Content lives in the project directory alongside .obsidian/:
my-project/
.napkin/ # napkin config
config.json # Unified config (syncs to .obsidian/)
.obsidian/ # Obsidian config (auto-generated)
NAPKIN.md # Context note (Level 0)
decisions/ # Template-defined directories
architecture/
Templates/ # Note templates
src/ # Your project (not in vault)
Scaffold a vault with a domain-specific structure:
napkin init --template coding # decisions/, architecture/, guides/, changelog/
napkin init --template company # people/, projects/, runbooks/, infrastructure/
napkin init --template product # features/, roadmap/, research/, specs/, releases/
napkin init --template personal # people/, projects/, areas/, references/
napkin init --template research # papers/, concepts/, questions/, experiments/Each template includes directory structure, _about.md files, Obsidian note templates, and a NAPKIN.md skeleton.
Every command supports --json for structured output and -q for raw output:
napkin overview --json # Structured vault map
napkin search "auth" --json # Ranked results as JSON
napkin read "Note" -q # Raw markdown, nothing else| Flag | Description |
|---|---|
--json |
Output as JSON |
-q, --quiet |
Suppress output |
--vault <path> |
Vault path (default: auto-detect from cwd) |
--copy |
Copy output to clipboard |
napkin vault # Vault info
napkin overview # Vault map with keywords
napkin read <file> # Read file contents
napkin create "Note" $'# Hello\nFirst note.' # Create with content
napkin append "Note" $'\n## Update\nNew info.' # Append to file
napkin prepend "Note" $'---\ntags: [new]\n---' # Prepend frontmatter
napkin move "Note" Archive # Move to folder
napkin rename "Note" "Renamed" # Rename file
napkin delete "Note" # Move to .trash
napkin search "meeting" # Ranked search with snippets
napkin search "TODO" --no-snippets # Files only
echo "piped content" | napkin append "Note" # Stdin supportnapkin file info <name> # File info (path, size, dates)
napkin file list # List all files
napkin file list --ext md # Filter by extension
napkin file list --folder Projects # Filter by folder
napkin file folder <path> # Folder info
napkin file folders # List all folders
napkin file outline "note" # Heading tree
napkin file wordcount "note" # Word + character countnapkin daily today # Create today's daily note
napkin daily path # Print daily note path
napkin daily read # Print daily note contents
napkin daily append "- [ ] Buy groceries"
napkin daily prepend "## Morning"napkin tag list # List all tags
napkin tag list --counts # With occurrence counts
napkin tag list --sort count # Sort by frequency
napkin tag info --name "project" # Tag info
napkin tag aliases # List all aliasesnapkin property list # List all properties
napkin property list --file "note" # Properties for a file
napkin property read --file "note" --name title
napkin property set --file "note" --name status --value done
napkin property remove --file "note" --name statusnapkin task list # List all tasks
napkin task list --todo # Incomplete only
napkin task list --done # Completed only
napkin task list --daily # Today's daily note tasks
napkin task show --file "note" --line 3 --togglenapkin link out --file "note" # Outgoing links
napkin link back --file "note" # Backlinks
napkin link unresolved # Broken links
napkin link orphans # No incoming links
napkin link deadends # No outgoing linksnapkin base list # List .base files
napkin base views --file "projects" # List views
napkin base query --file "projects" # Query default view
napkin base query --file "projects" --view "Active" --format csv
napkin base create --file "projects" --name "New Item"napkin canvas list # List .canvas files
napkin canvas read --file "Board" # Dump canvas
napkin canvas nodes --file "Board" # List nodes
napkin canvas create --file "Board" # Create empty canvas
napkin canvas add-node --file "Board" --type text --text "# Hello"
napkin canvas add-edge --file "Board" --from abc1 --to def2
napkin canvas remove-node --file "Board" --id abc1napkin template list # List note templates
napkin template read --name "Daily Note"
napkin template insert --file "note" --name "Template"napkin bookmark list # List bookmarks
napkin bookmark add --file "note" # Bookmark a filenapkin config show # Show full config
napkin config get --key search.limit # Get a value
napkin config set --key search.limit --value 50napkin graph # Interactive vault graphForce-directed graph of vault notes and wikilinks. Click nodes to read content in a sidebar.
Files can be referenced two ways:
- By name (wikilink-style):
"Active Projects"- searches all.mdfiles by basename - By path:
"Projects/Active Projects.md"- exact path from vault root
src/
index.ts # SDK exports: Napkin class + all types
sdk.ts # Napkin class wrapping core modules
main.ts # CLI entry (Commander) - thin wrapper
core/ # Pure logic, returns data, no stdout
commands/ # CLI wrappers: parse args → sdk → format + print
utils/ # Shared utilities (files, frontmatter, markdown, etc.)
Core modules never call console.log, process.exit, or import output utilities. They return typed data and throw errors. The CLI commands are thin wrappers that instantiate the SDK, call methods, and format the output.
For pi users, install pi-napkin — vault context injection, kb_search/kb_read tools, and automatic distillation.
pi install git:github.com/Michaelliv/pi-napkinbun install
bun run dev -- vault --json
bun test
bun run checkMIT
