@cad0p/napkin 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Liv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,342 @@
+# napkin
+
+🧻 Knowledge system for agents. Local-first, file-based, progressively disclosed.
+
+Every great idea started on a napkin.
+
+```bash
+npm install -g napkin-ai
+```
+
+---
+
+## Quick Start
+
+```bash
+# 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"
+```
+
+---
+
+## SDK
+
+napkin is also a library. No CLI, no stdout - just data:
+
+```typescript
+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:
+
+```typescript
+Napkin.scaffold("/path/to/project", { template: "coding" });
+Napkin.vaultTemplates(); // list available templates
+```
+
+All SDK methods return typed data and throw errors on failure. No `console.log`, no `process.exit`.
+
+---
+
+## Progressive Disclosure
+
+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 |
+
+## Benchmarks
+
+napkin includes agentic retrieval benchmarks in `bench/`. The headline result is [LongMemEval](https://arxiv.org/abs/2410.10813) (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`](bench/README.md) for details and usage.
+
+---
+
+## Vault Structure
+
+`.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)
+```
+
+## Templates
+
+Scaffold a vault with a domain-specific structure:
+
+```bash
+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.
+
+---
+
+## For Agents
+
+Every command supports `--json` for structured output and `-q` for raw output:
+
+```bash
+napkin overview --json          # Structured vault map
+napkin search "auth" --json     # Ranked results as JSON
+napkin read "Note" -q           # Raw markdown, nothing else
+```
+
+---
+
+## CLI Reference
+
+### Global Flags
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON |
+| `-q, --quiet` | Suppress output |
+| `--vault <path>` | Vault path (default: auto-detect from cwd) |
+| `--copy` | Copy output to clipboard |
+
+### Core
+
+```bash
+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 support
+```
+
+### Files & Folders - `napkin file`
+
+```bash
+napkin 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 count
+```
+
+### Daily Notes - `napkin daily`
+
+```bash
+napkin 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"
+```
+
+### Tags - `napkin tag`
+
+```bash
+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 aliases
+```
+
+### Properties - `napkin property`
+
+```bash
+napkin 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 status
+```
+
+### Tasks - `napkin task`
+
+```bash
+napkin 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 --toggle
+```
+
+### Links - `napkin link`
+
+```bash
+napkin 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 links
+```
+
+### Bases - `napkin base`
+
+```bash
+napkin 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"
+```
+
+### Canvas - `napkin canvas`
+
+```bash
+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 abc1
+```
+
+### Templates - `napkin template`
+
+```bash
+napkin template list                  # List note templates
+napkin template read --name "Daily Note"
+napkin template insert --file "note" --name "Template"
+```
+
+### Bookmarks - `napkin bookmark`
+
+```bash
+napkin bookmark list                  # List bookmarks
+napkin bookmark add --file "note"     # Bookmark a file
+```
+
+### Config - `napkin config`
+
+```bash
+napkin config show                    # Show full config
+napkin config get --key search.limit  # Get a value
+napkin config set --key search.limit --value 50
+```
+
+### Graph - `napkin graph`
+
+```bash
+napkin graph                          # Interactive vault graph
+```
+
+Force-directed graph of vault notes and wikilinks. Click nodes to read content in a sidebar.
+
+---
+
+## File Resolution
+
+Files can be referenced two ways:
+- **By name** (wikilink-style): `"Active Projects"` - searches all `.md` files by basename
+- **By path**: `"Projects/Active Projects.md"` - exact path from vault root
+
+---
+
+## Architecture
+
+```
+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.
+
+---
+
+## Pi Integration
+
+For [pi](https://github.com/badlogic/pi) users, install [pi-napkin](https://github.com/Michaelliv/pi-napkin) — vault context injection, `kb_search`/`kb_read` tools, and automatic distillation.
+
+```bash
+pi install git:github.com/Michaelliv/pi-napkin
+```
+
+---
+
+## Development
+
+```bash
+bun install
+bun run dev -- vault --json
+bun test
+bun run check
+```
+
+## License
+
+MIT

package/dist/commands/aliases.d.ts

@@ -0,0 +1,7 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function aliases(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    total?: boolean;
+    verbose?: boolean;
+}): Promise<void>;

package/dist/commands/aliases.js

@@ -0,0 +1,25 @@
+import { Napkin } from "../sdk.js";
+import { dim, output } from "../utils/output.js";
+export async function aliases(opts) {
+    const n = new Napkin(opts.vault || process.cwd());
+    const result = n.aliases(opts.file);
+    output(opts, {
+        json: () => {
+            if (opts.total)
+                return { total: result.length };
+            if (opts.verbose)
+                return { aliases: result };
+            return { aliases: result.map((r) => r.alias) };
+        },
+        human: () => {
+            if (opts.total) {
+                console.log(result.length);
+            }
+            else {
+                for (const r of result) {
+                    console.log(opts.verbose ? `${r.alias}\t${dim(r.file)}` : r.alias);
+                }
+            }
+        },
+    });
+}

package/dist/commands/bases.d.ts

@@ -0,0 +1,23 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function bases(opts: OutputOptions & {
+    vault?: string;
+}): Promise<void>;
+export declare function baseViews(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+}): Promise<void>;
+export declare function baseQuery(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+    view?: string;
+    format?: string;
+}): Promise<void>;
+export declare function baseCreate(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+    name?: string;
+    content?: string;
+}): Promise<void>;

package/dist/commands/bases.js

@@ -0,0 +1,139 @@
+import { Napkin } from "../sdk.js";
+import { EXIT_USER_ERROR } from "../utils/exit-codes.js";
+import { bold, dim, error, output, success, } from "../utils/output.js";
+export async function bases(opts) {
+    const n = new Napkin(opts.vault || process.cwd());
+    const files = n.bases();
+    output(opts, {
+        json: () => ({ bases: files }),
+        human: () => {
+            if (files.length === 0) {
+                console.log("No .base files found");
+            }
+            else {
+                for (const f of files)
+                    console.log(f);
+            }
+        },
+    });
+}
+export async function baseViews(opts) {
+    const n = new Napkin(opts.vault || process.cwd());
+    let views;
+    try {
+        views = n.baseViews(opts);
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_USER_ERROR);
+    }
+    output(opts, {
+        json: () => ({ views }),
+        human: () => {
+            for (const view of views) {
+                console.log(`${bold(view.name)}  ${dim(view.type)}`);
+            }
+        },
+    });
+}
+export async function baseQuery(opts) {
+    const n = new Napkin(opts.vault || process.cwd());
+    let result;
+    try {
+        result = await n.baseQuery(opts, opts.view);
+    }
+    catch (e) {
+        error(e.message);
+        process.exit(EXIT_USER_ERROR);
+    }
+    const fmt = opts.format || "json";
+    const displayCols = result.columns.map((c) => result.displayNames?.[c] || c);
+    output(opts, {
+        json: () => {
+            if (fmt === "paths") {
+                const pathIdx = result.columns.indexOf("path");
+                return { paths: result.rows.map((r) => r[pathIdx]) };
+            }
+            // Convert to array of objects
+            const rows = result.rows.map((row) => {
+                const obj = {};
+                for (let i = 0; i < result.columns.length; i++) {
+                    obj[result.columns[i]] = row[i];
+                }
+                return obj;
+            });
+            const out = { columns: result.columns, rows };
+            if (result.displayNames && Object.keys(result.displayNames).length > 0) {
+                out.displayNames = result.displayNames;
+            }
+            if (result.groups) {
+                out.groups = result.groups.map((g) => ({
+                    key: g.key,
+                    rows: g.rows.map((row) => {
+                        const obj = {};
+                        for (let i = 0; i < result.columns.length; i++) {
+                            obj[result.columns[i]] = row[i];
+                        }
+                        return obj;
+                    }),
+                }));
+            }
+            if (result.summaries)
+                out.summaries = result.summaries;
+            return out;
+        },
+        human: () => {
+            if (result.rows.length === 0) {
+                console.log("No results");
+                return;
+            }
+            if (fmt === "paths") {
+                const pathIdx = result.columns.indexOf("path");
+                for (const row of result.rows)
+                    console.log(row[pathIdx]);
+                return;
+            }
+            if (fmt === "csv" || fmt === "tsv") {
+                const sep = fmt === "csv" ? "," : "\t";
+                console.log(displayCols.join(sep));
+                for (const row of result.rows) {
+                    console.log(row.map((v) => (v === null ? "" : String(v))).join(sep));
+                }
+                return;
+            }
+            if (fmt === "md") {
+                console.log(`| ${displayCols.join(" | ")} |`);
+                console.log(`| ${displayCols.map(() => "---").join(" | ")} |`);
+                for (const row of result.rows) {
+                    console.log(`| ${row.map((v) => (v === null ? "" : String(v))).join(" | ")} |`);
+                }
+                return;
+            }
+            // Default: table-like
+            for (const row of result.rows) {
+                const obj = {};
+                for (let i = 0; i < result.columns.length; i++) {
+                    if (row[i] !== null)
+                        obj[result.columns[i]] = row[i];
+                }
+                console.log(JSON.stringify(obj));
+            }
+        },
+    });
+}
+export async function baseCreate(opts) {
+    const n = new Napkin(opts.vault || process.cwd());
+    if (!opts.name) {
+        error("No name specified. Use --name <name>");
+        process.exit(EXIT_USER_ERROR);
+    }
+    const result = n.baseCreate({
+        name: opts.name,
+        path: opts.path,
+        content: opts.content,
+    });
+    output(opts, {
+        json: () => result,
+        human: () => success(`Created ${result.path}`),
+    });
+}

package/dist/commands/bookmarks.d.ts

@@ -0,0 +1,15 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function bookmarks(opts: OutputOptions & {
+    vault?: string;
+    total?: boolean;
+    verbose?: boolean;
+}): Promise<void>;
+export declare function bookmark(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    subpath?: string;
+    folder?: string;
+    search?: string;
+    url?: string;
+    title?: string;
+}): Promise<void>;

package/dist/commands/bookmarks.js

@@ -0,0 +1,51 @@
+import { Napkin } from "../sdk.js";
+import { EXIT_USER_ERROR } from "../utils/exit-codes.js";
+import { dim, error, output, success, } from "../utils/output.js";
+export async function bookmarks(opts) {
+    const n = new Napkin(opts.vault || process.cwd());
+    const flat = n.bookmarks();
+    output(opts, {
+        json: () => (opts.total ? { total: flat.length } : { bookmarks: flat }),
+        human: () => {
+            if (opts.total) {
+                console.log(flat.length);
+            }
+            else {
+                for (const b of flat) {
+                    const label = b.title || b.path || b.query || b.url || "(untitled)";
+                    console.log(opts.verbose ? `${label}\t${dim(b.type)}` : label);
+                }
+            }
+        },
+    });
+}
+export async function bookmark(opts) {
+    const n = new Napkin(opts.vault || process.cwd());
+    let entry;
+    if (opts.file) {
+        entry = {
+            type: "file",
+            path: opts.file,
+            title: opts.title,
+            subpath: opts.subpath,
+        };
+    }
+    else if (opts.folder) {
+        entry = { type: "folder", path: opts.folder, title: opts.title };
+    }
+    else if (opts.search) {
+        entry = { type: "search", query: opts.search, title: opts.title };
+    }
+    else if (opts.url) {
+        entry = { type: "url", url: opts.url, title: opts.title };
+    }
+    else {
+        error("Specify --file, --folder, --search, or --url to bookmark");
+        process.exit(EXIT_USER_ERROR);
+    }
+    const result = n.bookmarkAdd(entry);
+    output(opts, {
+        json: () => result,
+        human: () => success(`Bookmarked ${result.added.path || result.added.query || result.added.url}`),
+    });
+}

package/dist/commands/canvas.d.ts

@@ -0,0 +1,49 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function canvases(opts: OutputOptions & {
+    vault?: string;
+    total?: boolean;
+}): Promise<void>;
+export declare function canvasRead(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+}): Promise<void>;
+export declare function canvasNodes(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    type?: string;
+}): Promise<void>;
+export declare function canvasCreate(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    path?: string;
+}): Promise<void>;
+export declare function canvasAddNode(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    type?: string;
+    text?: string;
+    noteFile?: string;
+    subpath?: string;
+    url?: string;
+    label?: string;
+    x?: string;
+    y?: string;
+    width?: string;
+    height?: string;
+    color?: string;
+}): Promise<void>;
+export declare function canvasAddEdge(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    from?: string;
+    to?: string;
+    fromSide?: string;
+    toSide?: string;
+    label?: string;
+    color?: string;
+}): Promise<void>;
+export declare function canvasRemoveNode(opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    id?: string;
+}): Promise<void>;