napkin-ai 0.3.0 → 0.4.1

package/.pi/extensions/distill/README.md

@@ -0,0 +1,50 @@
+# napkin-distill
+
+Pi extension that automatically distills knowledge from conversations into your napkin vault.
+
+## How it works
+
+1. Runs on a configurable interval (default: 60 minutes)
+2. Checks if the conversation changed since last distill
+3. Sends the new conversation to a model
+4. The model extracts structured notes using your vault's templates
+5. Notes are written directly into the vault
+
+## Setup
+
+Enable distill in your vault config:
+
+```bash
+napkin config set --key distill.enabled --value true
+```
+
+Or edit `.napkin/config.json` directly:
+
+```json
+{
+  "distill": {
+    "enabled": true,
+    "intervalMinutes": 60,
+    "model": {
+      "provider": "anthropic",
+      "id": "claude-sonnet-4-6"
+    }
+  }
+}
+```
+
+## Configuration
+
+All distill settings live in `.napkin/config.json` under the `distill` key:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `distill.enabled` | `false` | Enable automatic distillation |
+| `distill.intervalMinutes` | `60` | How often to check for new content |
+| `distill.model.provider` | `"anthropic"` | LLM provider |
+| `distill.model.id` | `"claude-sonnet-4-6"` | Model for distillation |
+| `distill.templates` | `[]` | Which templates to use (empty = all in Templates/) |
+
+## Manual trigger
+
+Use `/distill` in pi to manually trigger distillation of the full conversation.

package/.pi/extensions/distill/index.ts

@@ -0,0 +1,304 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { SessionManager } from "@mariozechner/pi-coding-agent";
+
+interface DistillConfig {
+  enabled: boolean;
+  intervalMinutes: number;
+  model: { provider: string; id: string };
+}
+
+const DEFAULT_CONFIG: DistillConfig = {
+  enabled: false,
+  intervalMinutes: 60,
+  model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+};
+
+function loadDistillConfig(vaultPath: string): DistillConfig {
+  const configPath = path.join(vaultPath, "config.json");
+  if (!fs.existsSync(configPath)) return DEFAULT_CONFIG;
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    const distill = raw.distill || {};
+    return { ...DEFAULT_CONFIG, ...distill };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+}
+
+function findVaultPath(cwd: string): string | null {
+  let dir = cwd;
+  while (dir !== path.dirname(dir)) {
+    const napkinDir = path.join(dir, ".napkin");
+    if (fs.existsSync(napkinDir)) {
+      return napkinDir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+const DISTILL_PROMPT = `Distill this conversation into the napkin vault.
+
+1. \`napkin overview\` — learn the vault structure and what exists
+2. \`napkin template list\` and \`napkin template read\` — learn the note formats
+3. Identify what's worth capturing. The vault structure and templates tell you what kinds of notes belong.
+4. For each note:
+   a. \`napkin search\` for the topic — if a note already covers it, \`napkin append\` instead of creating a duplicate
+   b. Create new notes with \`napkin create\`, following the template format
+   c. Add \`[[wikilinks]]\` to related notes
+
+Be selective. Only capture knowledge useful to someone working on this project later. Skip meta-discussion, tool output, and chatter.`;
+
+export default function (pi: ExtensionAPI) {
+  let intervalHandle: ReturnType<typeof setInterval> | null = null;
+  let countdownHandle: ReturnType<typeof setInterval> | null = null;
+  let lastDistillTimestamp = Date.now();
+  let lastSessionSize = 0;
+  let isRunning = false;
+  let activeProcess: ReturnType<typeof spawn> | null = null;
+
+  pi.on("session_start", async (_event, ctx) => {
+    const vaultPath = findVaultPath(ctx.cwd);
+    if (!vaultPath) return;
+
+    const config = loadDistillConfig(vaultPath);
+    if (!config.enabled) {
+      if (ctx.hasUI) {
+        const theme = ctx.ui.theme;
+        ctx.ui.setStatus(
+          "napkin-distill",
+          theme.fg("dim", "distill: off"),
+        );
+      }
+      return;
+    }
+
+    lastDistillTimestamp = Date.now();
+    const intervalMs = config.intervalMinutes * 60 * 1000;
+
+    if (ctx.hasUI) {
+      const theme = ctx.ui.theme;
+      const updateCountdown = () => {
+        if (isRunning) return;
+        const remaining = Math.max(0, intervalMs - (Date.now() - lastDistillTimestamp));
+        const mins = Math.floor(remaining / 60000);
+        const secs = Math.floor((remaining % 60000) / 1000);
+        const display = mins > 0 ? `${mins}m${secs.toString().padStart(2, "0")}s` : `${secs}s`;
+        ctx.ui.setStatus(
+          "napkin-distill",
+          theme.fg("dim", `distill: ${display}`),
+        );
+      };
+      updateCountdown();
+      countdownHandle = setInterval(updateCountdown, 1000);
+    }
+
+    intervalHandle = setInterval(
+      () => {
+        if (isRunning) return;
+        runDistill(ctx).catch((err) => {
+          if (ctx.hasUI) {
+            ctx.ui.notify(
+              `Distill error: ${err instanceof Error ? err.message : String(err)}`,
+              "error",
+            );
+          }
+        });
+      },
+      intervalMs,
+    );
+  });
+
+  pi.on("session_shutdown", async () => {
+    if (countdownHandle) {
+      clearInterval(countdownHandle);
+      countdownHandle = null;
+    }
+    if (intervalHandle) {
+      clearInterval(intervalHandle);
+      intervalHandle = null;
+    }
+    if (activeProcess) {
+      activeProcess.kill();
+      activeProcess = null;
+    }
+  });
+
+  async function runDistill(ctx: {
+    sessionManager: any;
+    hasUI: boolean;
+    ui: any;
+    cwd: string;
+  }) {
+    const vaultPath = findVaultPath(ctx.cwd);
+    if (!vaultPath) return;
+
+    const config = loadDistillConfig(vaultPath);
+    const sessionFile = ctx.sessionManager.getSessionFile?.();
+    if (!sessionFile) {
+      if (ctx.hasUI)
+        ctx.ui.notify(
+          "Distill: no session file (ephemeral session)",
+          "warning",
+        );
+      return;
+    }
+
+    // Skip if session hasn't changed since last distill
+    const currentSize = fs.existsSync(sessionFile)
+      ? fs.statSync(sessionFile).size
+      : 0;
+    if (currentSize > 0 && currentSize === lastSessionSize) {
+      lastDistillTimestamp = Date.now();
+      return;
+    }
+
+    isRunning = true;
+    const startTime = Date.now();
+    let timerHandle: ReturnType<typeof setInterval> | null = null;
+    const theme = ctx.hasUI ? ctx.ui.theme : null;
+
+    if (ctx.hasUI && theme) {
+      ctx.ui.setStatus(
+        "napkin-distill",
+        theme.fg("accent", "●") + theme.fg("dim", " distill"),
+      );
+      timerHandle = setInterval(() => {
+        const elapsed = Math.floor((Date.now() - startTime) / 1000);
+        ctx.ui.setStatus(
+          "napkin-distill",
+          theme.fg("accent", "●") +
+            theme.fg("dim", ` distill ${elapsed}s`),
+        );
+      }, 1000);
+    }
+
+    // Fork the session to a temp directory so the subprocess
+    // inherits the full conversation without modifying the original
+    const tmpSessionDir = fs.mkdtempSync(
+      path.join(os.tmpdir(), "napkin-distill-"),
+    );
+    let forkedSessionFile: string | null = null;
+
+    try {
+      // Fork: creates a new session file with the full conversation
+      const forkedSm = SessionManager.forkFrom(
+        sessionFile,
+        ctx.cwd,
+        tmpSessionDir,
+      );
+      forkedSessionFile = forkedSm.getSessionFile();
+
+      if (!forkedSessionFile) {
+        throw new Error("Failed to fork session");
+      }
+
+      // Spawn pi on the forked session
+      const args = [
+        "--session",
+        forkedSessionFile,
+        "-p",
+        "--model",
+        `${config.model.provider}/${config.model.id}`,
+        DISTILL_PROMPT,
+      ];
+
+      const exitCode = await new Promise<number>((resolve, reject) => {
+        const proc = spawn("pi", args, {
+          cwd: ctx.cwd,
+          shell: false,
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        activeProcess = proc;
+
+        let stderr = "";
+        proc.stderr.on("data", (data) => {
+          stderr += data.toString();
+        });
+
+        proc.on("error", (err) => {
+          activeProcess = null;
+          reject(err);
+        });
+
+        proc.on("close", (code) => {
+          activeProcess = null;
+          if (code !== 0 && stderr.trim()) {
+            reject(
+              new Error(
+                `pi exited with code ${code}: ${stderr.trim().slice(0, 200)}`,
+              ),
+            );
+          } else {
+            resolve(code ?? 0);
+          }
+        });
+      });
+
+      lastDistillTimestamp = Date.now();
+      lastSessionSize = currentSize;
+
+      const elapsed = Math.floor((Date.now() - startTime) / 1000);
+      if (ctx.hasUI && theme) {
+        ctx.ui.setStatus(
+          "napkin-distill",
+          theme.fg("success", "✓") +
+            theme.fg("dim", ` distill ${elapsed}s`),
+        );
+        ctx.ui.notify(`Distillation complete (${elapsed}s)`, "success");
+      }
+    } catch (err) {
+      if (ctx.hasUI && theme) {
+        ctx.ui.setStatus(
+          "napkin-distill",
+          theme.fg("error", "✗") + theme.fg("dim", " distill"),
+        );
+      }
+      throw err;
+    } finally {
+      if (timerHandle) clearInterval(timerHandle);
+      isRunning = false;
+      // Clean up forked session
+      fs.rmSync(tmpSessionDir, { recursive: true, force: true });
+    }
+  }
+
+  // Manual trigger
+  pi.registerCommand("distill", {
+    description: "Distill conversation knowledge into the vault",
+    handler: async (_args, ctx) => {
+      const vaultPath = findVaultPath(ctx.cwd);
+      if (!vaultPath) {
+        if (ctx.hasUI) ctx.ui.notify("No vault found", "error");
+        return;
+      }
+
+      if (isRunning) {
+        if (ctx.hasUI) ctx.ui.notify("Distill already running", "warning");
+        return;
+      }
+
+      const savedTimestamp = lastDistillTimestamp;
+      lastDistillTimestamp = 0;
+      lastSessionSize = 0; // bypass size check for manual trigger
+      runDistill(ctx)
+        .catch((err) => {
+          if (ctx.hasUI) {
+            ctx.ui.notify(
+              `Distill error: ${err instanceof Error ? err.message : String(err)}`,
+              "error",
+            );
+          }
+        })
+        .finally(() => {
+          if (lastDistillTimestamp === 0) {
+            lastDistillTimestamp = savedTimestamp;
+          }
+        });
+    },
+  });
+}

package/.pi/extensions/distill/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "napkin-distill",
+  "version": "0.1.0",
+  "description": "Automatic KB distillation for napkin vaults",
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}

package/.pi/extensions/napkin-context/index.ts

@@ -0,0 +1,79 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+function findVaultPath(cwd: string): string | null {
+  let dir = cwd;
+  while (dir !== path.dirname(dir)) {
+    const napkinDir = path.join(dir, ".napkin");
+    if (fs.existsSync(napkinDir)) {
+      return napkinDir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function getOverview(vaultPath: string): string | null {
+  try {
+    const output = execSync(`napkin overview --vault "${vaultPath}"`, {
+      encoding: "utf-8",
+      timeout: 10000,
+    }).trim();
+    return output || null;
+  } catch {
+    // Fallback to reading NAPKIN.md directly
+    const napkinPath = path.join(vaultPath, "NAPKIN.md");
+    if (!fs.existsSync(napkinPath)) return null;
+    return fs.readFileSync(napkinPath, "utf-8").trim();
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  let hasVault = false;
+
+  pi.on("session_start", async (_event, ctx) => {
+    const vaultPath = findVaultPath(ctx.cwd);
+    if (!vaultPath) return;
+
+    const overview = getOverview(vaultPath);
+    hasVault = !!overview;
+
+    if (overview) {
+      // Check if we already injected context in this session
+      const alreadyInjected = ctx.sessionManager
+        .getEntries()
+        .some(
+          (e) =>
+            e.type === "message" &&
+            e.message.role === "custom" &&
+            (e.message as any).customType === "napkin-context",
+        );
+
+      if (!alreadyInjected) {
+        ctx.sessionManager.appendCustomMessageEntry(
+          "napkin-context",
+          "## Napkin vault context\n" +
+            "You have access to a napkin vault (Obsidian-compatible knowledge base). " +
+            "Here is the vault overview. Use `napkin search <query>` to find specific content, " +
+            "`napkin read <file>` to open files.\n\n" +
+            overview,
+          true,
+        );
+      }
+    }
+
+    if (ctx.hasUI) {
+      const theme = ctx.ui.theme;
+      if (hasVault) {
+        ctx.ui.setStatus("napkin", "🧻" + theme.fg("dim", " napkin"));
+      } else {
+        ctx.ui.setStatus(
+          "napkin",
+          theme.fg("dim", "napkin: no NAPKIN.md"),
+        );
+      }
+    }
+  });
+}

package/.pi/extensions/napkin-context/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "napkin-context",
+  "version": "0.1.0",
+  "description": "Inject napkin vault overview into agent system prompt",
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}

package/README.md

@@ -1,8 +1,8 @@
 # napkin
 
-🧻 Obsidian-compatible CLI for agents.
+🧻 Knowledge system for AI agents. Local-first, file-based, progressively disclosed.
 
-Every great idea started on a napkin. This one reads your Obsidian vault.
+Every great idea started on a napkin.
 
 ## Install
 
@@ -10,21 +10,75 @@ Every great idea started on a napkin. This one reads your Obsidian vault.
 npm install -g napkin-ai
 ```
 
-## Usage
+As a pi package (includes extensions + skills):
 
-Run from inside an Obsidian vault (any directory containing `.obsidian/`):
+```bash
+pi install npm:napkin-ai
+```
+
+## Quick Start
+
+```bash
+# Initialize a vault with a template
+napkin init --template coding
+
+# See what's in it
+napkin overview
+
+# Search for something
+napkin search "authentication"
+
+# Read a file
+napkin read "Architecture"
+```
+
+## Vault Structure
+
+`.napkin/` is the vault root — all content lives inside it:
+
+```
+my-project/
+  .napkin/                  # The vault
+    NAPKIN.md               # Context note (Level 0)
+    config.json             # Unified config (syncs to .obsidian/)
+    decisions/              # Template-defined directories
+    architecture/
+    Templates/              # Note templates
+    .obsidian/              # Obsidian compatibility (auto-generated)
+  src/                      # Your project (not in vault)
+```
+
+## Progressive Disclosure
+
+napkin is designed as a memory system for AI 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 |
+
+## Templates
+
+Scaffold a vault with a domain-specific structure:
 
 ```bash
-cd ~/my-vault
-napkin vault
+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/
 ```
 
-Or specify the vault path:
+Each template includes directory structure, `_about.md` files, Obsidian note templates, and a `NAPKIN.md` skeleton.
 
 ```bash
-napkin --vault ~/my-vault vault
+napkin init --list               # List available templates
 ```
 
+## Commands
+
 ### Global flags
 
 | Flag | Description |
@@ -34,12 +88,11 @@ napkin --vault ~/my-vault vault
 | `--vault <path>` | Vault path (default: auto-detect from cwd) |
 | `--copy` | Copy output to clipboard |
 
-## Commands
-
 ### Core
 
 ```bash
 napkin vault                          # Vault info
+napkin overview                       # Vault map with keywords
 napkin read <file>                    # Read file contents
 napkin create --name "Note" --content "Hello"
 napkin append --file "Note" --content "More text"
@@ -47,8 +100,8 @@ napkin prepend --file "Note" --content "Top line"
 napkin move --file "Note" --to Archive
 napkin rename --file "Note" --name "Renamed"
 napkin delete --file "Note"           # Move to .trash
-napkin search "meeting"               # Full-text search
-napkin search "TODO" --context        # Grep-style output
+napkin search "meeting"               # Ranked search with snippets
+napkin search "TODO" --no-snippets    # Files only
 ```
 
 ### Files & folders — `napkin file`
@@ -60,6 +113,8 @@ 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 --file "note"     # Heading tree
+napkin file wordcount --file "note"   # Word + character count
 ```
 
 ### Daily notes — `napkin daily`
@@ -114,8 +169,6 @@ napkin link deadends                  # No outgoing links
 
 ### Bases — `napkin base`
 
-Query vault files using Obsidian Bases `.base` files.
-
 ```bash
 napkin base list                      # List .base files
 napkin base views --file "projects"   # List views
@@ -126,8 +179,6 @@ napkin base create --file "projects" --name "New Item"
 
 ### Canvas — `napkin canvas`
 
-Read and write JSON Canvas files (`.canvas`).
-
 ```bash
 napkin canvas list                    # List .canvas files
 napkin canvas read --file "Board"     # Dump canvas
@@ -141,7 +192,7 @@ napkin canvas remove-node --file "Board" --id abc1
 ### Templates — `napkin template`
 
 ```bash
-napkin template list                  # List templates
+napkin template list                  # List note templates
 napkin template read --name "Daily Note"
 napkin template insert --file "note" --name "Template"
 ```
@@ -153,23 +204,45 @@ napkin bookmark list                  # List bookmarks
 napkin bookmark add --file "note"     # Bookmark a file
 ```
 
-### Other
+### 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
+```
+
+See [docs/configuration.md](docs/configuration.md) for all config options.
+
+### Graph — `napkin graph`
 
 ```bash
-napkin outline --file "note"          # Heading tree
-napkin wordcount --file "note"        # Word + character count
-napkin onboard                        # Agent instructions for CLAUDE.md
+napkin graph                          # Interactive vault graph
 ```
 
-## File resolution
+Force-directed graph of vault notes and wikilinks. Click nodes to read content in a sidebar. On macOS, opens in a native window (Glimpse). On other platforms, opens in the browser. Configure with `graph.renderer` in config.
+
+## File Resolution
 
 Files can be referenced two ways:
 - **By name** (wikilink-style): `--file "Active Projects"` — searches all `.md` files by basename
 - **By path**: `--file "Projects/Active Projects.md"` — exact path from vault root
 
-## For AI agents
+## Pi Extensions
+
+napkin ships as a pi package with two extensions:
+
+### napkin-context
+Injects the vault overview (Level 0 + Level 1) into the agent's system prompt on session start. The agent gets NAPKIN.md and the vault map with keywords for free.
+
+### napkin-distill
+Forks the current session and spawns a sub-agent to distill knowledge into the vault. The sub-agent inherits the full conversation, uses napkin tools to read templates and create structured notes. Runs in the background.
+
+```bash
+napkin config set --key distill.enabled --value true    # Enable auto-distill
+```
 
-Every command supports `--json` for structured output. Run `napkin onboard` to get copy-paste instructions for your agent config.
+Or trigger manually in pi: `/distill`
 
 ## Development
 

package/dist/commands/config.d.ts

@@ -0,0 +1,13 @@
+import { type OutputOptions } from "../utils/output.js";
+export declare function configShow(opts: OutputOptions & {
+    vault?: string;
+}): Promise<void>;
+export declare function configSet(opts: OutputOptions & {
+    vault?: string;
+    key?: string;
+    value?: string;
+}): Promise<void>;
+export declare function configGet(opts: OutputOptions & {
+    vault?: string;
+    key?: string;
+}): Promise<void>;