imprnt 0.1.4-edge.74 → 0.1.4-edge.88

package/README.md

@@ -5,19 +5,19 @@
 [![CI](https://github.com/aleksandr-bogdanov/imprnt/actions/workflows/ci.yml/badge.svg?event=pull_request)](https://github.com/aleksandr-bogdanov/imprnt/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![npm](https://img.shields.io/npm/v/imprnt.svg)](https://www.npmjs.com/package/imprnt)
 
 Your assistant starts every chat blank. You re-explain your projects, your people, and your
 decisions every time, and whatever it learns dies with the session. imprnt fixes that. You talk,
 your assistant files what matters into plain text files on your disk, and weeks later it answers
 from your real history. You can read every note with your own eyes, and no company can switch
-them off.
+them off. Sibling to [Whenful](https://whenful.com): Whenful answers *when* do I do my tasks,
+imprnt holds *what* I know.
 
-> "You can think of the model as the brain, the harness as the body, and the tools it uses working
-> in a runtime."
-> - Jensen Huang, NVIDIA (GTC Taipei keynote, June 2026)
+<picture><source media="(prefers-color-scheme: dark)" srcset=".github/assets/recall-dark.svg"><img src=".github/assets/recall-light.svg" alt="imprnt recall: ranked results from a local BM25 search" width="830"></picture>
 
-imprnt is the tool layer Huang is pointing at, holding the part that lasts. Sibling to
-[Whenful](https://whenful.com): Whenful answers *when* do I do my tasks, imprnt holds *what* I know.
+That is the whole read path. Term frequencies and a bit of arithmetic over a folder, with no model
+in the loop.
 
 ## See it work
 
@@ -41,6 +41,8 @@ plain, cheap, local code.
 
 ## Why plain files win
 
+<picture><source media="(prefers-color-scheme: dark)" srcset=".github/assets/lanes-dark.svg"><img src=".github/assets/lanes-light.svg" alt="The write path runs once per source and uses the model. The read path runs thousands of times and uses grep plus BM25." width="830"></picture>
+
 A vector database or a hidden memory feature could hold your knowledge too. Plain files make your
 assistant cheap, honest, and yours:
 
@@ -59,6 +61,44 @@ assistant cheap, honest, and yours:
 - **Yours, in the strongest sense.** Plain text on your disk. It opens in any editor, graphs in
   [Obsidian](https://obsidian.md), and cannot 404, bloat, or hold your context hostage.
 
+## The numbers, including the one we lose
+
+LoCoMo is the benchmark this category is rated on, 1,540 questions about conversations that ran
+for months. On the same answering model Letta published with, imprnt scores 58.6 against their
+74.0. We lose that comparison by about fifteen points, and the confidence intervals do not
+overlap.
+
+Running it turned up something worth more than the score. Take one fixed set of imprnt's answers,
+change only the LLM judge, and the result moves 9 points: 68.4 with Claude grading, 77.6 with
+gpt-4.1. That single swap is wider than the entire published spread in the category (mem0 68.44,
+Letta 74.0, Zep 75.14). A LoCoMo number without a named judge is close to meaningless, ours
+included.
+
+On the paper's own scorer, token F1 across all five categories, imprnt gets 64.2%. The human
+baseline on the same questions is 87.9%, and the paper's own GPT-4-turbo baseline is 32.1%.
+
+imprnt also ships a retrieval eval over the two example vaults: the right note comes back first
+for 89.7% of questions and appears in the top five for 97.4%, across 39 hand-written questions.
+Small corpus, and we wrote the questions, so run it yourself with `bun run eval`.
+
+Every run, interval, and reproduction step is written up in
+[`docs/benchmark-2026-08.md`](docs/benchmark-2026-08.md). The tool-by-tool read lives at
+[imprnt.dev/comparison](https://imprnt.dev/comparison/).
+
+Prior art, by name: Letta/MemGPT, mem0, and Zep run memory as a service with their own store and
+their own retrieval. Khoj indexes your files with embeddings. Obsidian gives you the plain-file
+vault without an agent contract on top. PAI wires an assistant into a fixed personal structure.
+imprnt keeps both halves: plain markdown you own, and an agent contract that files into it and reads it back with grep and BM25.
+
+## Known limits
+
+BM25 is lexical. It ranks on the words a note actually contains, so imprnt bridges vocabulary at
+ingest: the model assigns tags, proposes aliases, and records synonyms once per note, and every
+later search rides on that one pass. Embeddings pay that cost per query instead. The bridge has
+holes. Ask "what do I do for work" when the note says "freelance designer" and nothing connects
+the two, and you can miss. The vault is single-user by design. That is the trade for a read path
+that is free, local, and identical every time you run it.
+
 ## The robot does the work. You stay the boss.
 
 The current crop of AI tools wants the wheel. Resident agents (OpenClaw and friends) read your

package/dist/cli.js

@@ -2821,19 +2821,177 @@ all plugin checks passed.`);
   }
 });
 
-// scripts/cli.ts
-var exports_cli = {};
-import { cpSync as cpSync3, mkdirSync as mkdirSync5, chmodSync, existsSync as existsSync13, readFileSync as readFileSync14, lstatSync as lstatSync4, statSync as statSync9, realpathSync as realpathSync2 } from "node:fs";
+// scripts/vault.ts
+var exports_vault = {};
 import { spawnSync as spawnSync4 } from "node:child_process";
-import { join as join15, dirname as dirname4, resolve as resolve6, basename as basename6 } from "node:path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync5, readdirSync as readdirSync9, statSync as statSync9 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
+import { basename as basename6, dirname as dirname4, join as join15, resolve as resolve6 } from "node:path";
+function noteCount(project) {
+  const root = join15(project, "vault");
+  if (!existsSync13(root))
+    return 0;
+  let n = 0;
+  const walk3 = (dir2, atRoot) => {
+    for (const e of readdirSync9(dir2, { withFileTypes: true })) {
+      if (e.name.startsWith(".") || e.name.startsWith("_"))
+        continue;
+      if (e.isSymbolicLink())
+        continue;
+      if (atRoot && CONTROL3.has(e.name))
+        continue;
+      if (e.isDirectory())
+        walk3(join15(dir2, e.name), false);
+      else if (e.name.endsWith(".md"))
+        n++;
+    }
+  };
+  try {
+    walk3(root, true);
+  } catch {}
+  return n;
+}
+function resolveTarget(token) {
+  const reg = readRegistry();
+  if (token) {
+    if (reg.vaults[token])
+      return { name: token, path: reg.vaults[token] };
+    const p = expand(token);
+    if (isVaultProject(p)) {
+      const named = Object.entries(reg.vaults).find(([, v]) => v === p)?.[0];
+      return { name: named ?? basename6(p), path: p };
+    }
+    console.error(`no vault called "${token}", and ${p} is not a vault project`);
+    console.error(`known: ${Object.keys(reg.vaults).join(", ") || "(none registered — run `imprnt init`)"}`);
+    process.exit(1);
+  }
+  const name = reg.default ?? Object.keys(reg.vaults)[0];
+  const path = name ? reg.vaults[name] : undefined;
+  if (!name || !path) {
+    console.error("no vault registered — run `imprnt init`");
+    process.exit(1);
+  }
+  return { name, path };
+}
+function tar(...a) {
+  const r = spawnSync4("tar", a, { stdio: ["ignore", "inherit", "inherit"] });
+  if (r.error) {
+    console.error(`tar is not available: ${r.error.message}`);
+    process.exit(1);
+  }
+  return r.status ?? 1;
+}
+var args5, sub, flag = (name) => {
+  const i = args5.indexOf(name);
+  return i >= 0 ? args5[i + 1] : undefined;
+}, positionals, expand = (p) => resolve6(p.startsWith("~/") ? join15(homedir4(), p.slice(2)) : p), CONTROL3;
+var init_vault = __esm(() => {
+  init_registry();
+  args5 = process.argv.slice(2);
+  sub = args5[0];
+  positionals = args5.slice(1).filter((a, i, all2) => !a.startsWith("--") && !(i > 0 && all2[i - 1]?.startsWith("--")));
+  CONTROL3 = new Set(["index.md", "hot.md", "log.md", "_tags.md"]);
+  switch (sub) {
+    case "list": {
+      const reg = readRegistry();
+      const names = Object.keys(reg.vaults);
+      if (!names.length) {
+        console.log("no vaults registered — run `imprnt init`");
+        break;
+      }
+      const def = reg.default ?? names[0];
+      for (const n of names) {
+        const p = reg.vaults[n];
+        const live = isVaultProject(p);
+        const mark = n === def ? "*" : " ";
+        const detail = live ? `${noteCount(p)} notes` : "MISSING — the path is registered but holds no vault";
+        console.log(`${mark} ${n.padEnd(12)} ${p}  (${detail})`);
+      }
+      console.log("\n* = default (what `imp` and `imprnt context` resolve to)");
+      break;
+    }
+    case "archive": {
+      const { name, path } = resolveTarget(positionals[0]);
+      if (!isVaultProject(path)) {
+        console.error(`${path} is not a vault project`);
+        process.exit(1);
+      }
+      const outDir = expand(flag("--out") ?? ".");
+      mkdirSync5(outDir, { recursive: true });
+      const stamp = new Date().toISOString().slice(0, 10);
+      const out = join15(outDir, `${name}-${stamp}.tar.gz`);
+      if (tar("czf", out, "-C", dirname4(path), basename6(path)) !== 0) {
+        console.error("archive failed");
+        process.exit(1);
+      }
+      if (tar("tzf", out) !== 0) {
+        console.error(`${out} does not read back — treat it as no archive at all`);
+        process.exit(1);
+      }
+      const size = (statSync9(out).size / 1024 / 1024).toFixed(1);
+      console.log(`archived ${name} (${noteCount(path)} notes) → ${out}  ${size} MB, verified`);
+      console.log(`restore with: imprnt vault restore ${out} <dir>`);
+      break;
+    }
+    case "restore": {
+      const src3 = expand(positionals[0] ?? "");
+      const dest2 = expand(positionals[1] ?? "");
+      if (!positionals[0] || !positionals[1]) {
+        console.error("usage: imprnt vault restore <archive.tar.gz> <dir>");
+        process.exit(1);
+      }
+      if (!existsSync13(src3)) {
+        console.error(`no archive at ${src3}`);
+        process.exit(1);
+      }
+      if (existsSync13(dest2) && readdirSync9(dest2).length) {
+        console.error(`${dest2} is not empty — restore into a new directory, then move it`);
+        process.exit(1);
+      }
+      mkdirSync5(dest2, { recursive: true });
+      if (tar("xzf", src3, "-C", dest2) !== 0) {
+        console.error("restore failed");
+        process.exit(1);
+      }
+      const inner = readdirSync9(dest2).map((e) => join15(dest2, e)).filter((p) => statSync9(p).isDirectory());
+      const project = inner.find((p) => isVaultProject(p)) ?? (isVaultProject(dest2) ? dest2 : undefined);
+      if (!project) {
+        console.error(`extracted, but ${dest2} holds no vault project — check the archive`);
+        process.exit(1);
+      }
+      console.log(`restored ${noteCount(project)} notes → ${project}`);
+      console.log(`register it with: cd ${project} && imprnt init`);
+      break;
+    }
+    default:
+      console.log(`imprnt vault — the vault as its own object
+
+  imprnt vault list                        vaults registered on this machine
+  imprnt vault archive [name|path]         one verified tarball  (--out <dir>)
+  imprnt vault restore <archive> <dir>     put one back
+
+Create one with \`imprnt init\`. There is no \`vault delete\`: removing knowledge is a
+human act with rm and a path, not a subcommand a script or an agent can reach.
+
+A vault means something with no agent attached. An agent with no vault is a process
+pointed at nothing — so the vault outlives whatever reads it.`);
+      process.exit(sub && sub !== "help" && sub !== "--help" ? 1 : 0);
+  }
+});
+
+// scripts/cli.ts
+var exports_cli = {};
+import { cpSync as cpSync3, mkdirSync as mkdirSync6, chmodSync, existsSync as existsSync14, readFileSync as readFileSync14, lstatSync as lstatSync4, statSync as statSync10, realpathSync as realpathSync2 } from "node:fs";
+import { spawnSync as spawnSync5 } from "node:child_process";
+import { join as join16, dirname as dirname5, resolve as resolve7, basename as basename7 } from "node:path";
+import { homedir as homedir5 } from "node:os";
 import { fileURLToPath } from "node:url";
 import { createInterface as createInterface2 } from "node:readline/promises";
 function pluginRoot() {
   const local = projectRoot();
   if (process.env.IMPRNT_ROOT || process.env.IMPRINT_ROOT)
     return local;
-  if (existsSync13(join15(local, "vault")) || existsSync13(join15(local, "CLAUDE.local.md")))
+  if (existsSync14(join16(local, "vault")) || existsSync14(join16(local, "CLAUDE.local.md")))
     return local;
   return registeredRoot() ?? local;
 }
@@ -2857,29 +3015,29 @@ function requireVaultHome() {
   }
   return home;
 }
-function resolvePath(input, base = process.cwd(), home = homedir4()) {
+function resolvePath(input, base = process.cwd(), home = homedir5()) {
   let p = input;
   if (p === "~")
     p = home;
   else if (p.startsWith("~/"))
-    p = join15(home, p.slice(2));
-  return resolve6(base, p);
+    p = join16(home, p.slice(2));
+  return resolve7(base, p);
 }
-function initPositional(args5) {
-  return args5.find((a) => !a.startsWith("-"));
+function initPositional(args6) {
+  return args6.find((a) => !a.startsWith("-"));
 }
 function physicalTarget(target) {
   let existing = target;
   const tail = [];
-  while (!existsSync13(existing)) {
-    const parent = dirname4(existing);
+  while (!existsSync14(existing)) {
+    const parent = dirname5(existing);
     if (parent === existing)
       return target;
-    tail.unshift(basename6(existing));
+    tail.unshift(basename7(existing));
     existing = parent;
   }
   try {
-    return tail.length ? join15(realpathSync2(existing), ...tail) : realpathSync2(existing);
+    return tail.length ? join16(realpathSync2(existing), ...tail) : realpathSync2(existing);
   } catch {
     return target;
   }
@@ -2895,7 +3053,7 @@ function controlSlot(dst) {
     return "blocked-directory";
   if (st.isSymbolicLink()) {
     try {
-      return statSync9(dst).isFile() ? "keep" : "blocked-symlink";
+      return statSync10(dst).isFile() ? "keep" : "blocked-symlink";
     } catch {
       return "blocked-symlink";
     }
@@ -2914,11 +3072,11 @@ var init_cli = __esm(async () => {
   init_moc();
   init_registry();
   init_launch();
-  here = dirname4(fileURLToPath(import.meta.url));
-  pkgRoot = join15(here, "..");
+  here = dirname5(fileURLToPath(import.meta.url));
+  pkgRoot = join16(here, "..");
   [cmd, ...rest] = process.argv.slice(2);
   asImp = globalThis.__IMPRNT_IMP__ === true;
-  if (["ingest", "recall", "snapshot", "check"].includes(cmd))
+  if (["ingest", "recall", "snapshot", "check", "vault"].includes(cmd))
     process.argv.splice(2, 1);
   switch (cmd) {
     case "ingest":
@@ -2933,6 +3091,9 @@ var init_cli = __esm(async () => {
     case "check":
       await Promise.resolve().then(() => (init_check(), exports_check));
       break;
+    case "vault":
+      await Promise.resolve().then(() => (init_vault(), exports_vault));
+      break;
     case "hot": {
       const vault5 = vaultArg();
       const review2 = openNeedsReview(vault5);
@@ -2942,8 +3103,8 @@ var init_cli = __esm(async () => {
           console.log(r);
         console.log("");
       }
-      const p = join15(vault5, "hot.md");
-      if (!existsSync13(p)) {
+      const p = join16(vault5, "hot.md");
+      if (!existsSync14(p)) {
         console.error(`no hot.md at ${p} — run \`imprnt init\``);
         process.exit(1);
       }
@@ -2959,8 +3120,8 @@ var init_cli = __esm(async () => {
     }
     case "context": {
       const home = requireVaultHome();
-      const contract = join15(home, "CLAUDE.md");
-      if (!existsSync13(contract)) {
+      const contract = join16(home, "CLAUDE.md");
+      if (!existsSync14(contract)) {
         console.error(`no CLAUDE.md at ${home} — run \`imprnt init\` there to drop the contract`);
         process.exit(1);
       }
@@ -3043,8 +3204,8 @@ var init_cli = __esm(async () => {
       const proj = pluginRoot();
       if (proj !== process.cwd())
         console.error(`(targeting vault project: ${proj})`);
-      const [sub, ...specs] = rest;
-      if (sub === "list") {
+      const [sub2, ...specs] = rest;
+      if (sub2 === "list") {
         const dirs = listPluginDirs(proj);
         console.log("plugins:");
         if (!dirs.length)
@@ -3059,7 +3220,7 @@ available to add: ${available.join(", ")}`);
 enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         break;
       }
-      if (sub === "add") {
+      if (sub2 === "add") {
         let from;
         let force = false;
         const names = [];
@@ -3123,7 +3284,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
           process.exit(1);
         break;
       }
-      if (sub === "rm") {
+      if (sub2 === "rm") {
         let purge = false;
         const names = [];
         for (const s of specs) {
@@ -3163,9 +3324,9 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       process.exit(1);
     }
     case "global": {
-      const globalDir = process.env.CLAUDE_CONFIG_DIR || join15(homedir4(), ".claude");
-      const [sub, ...gargs] = rest;
-      if (sub === "list") {
+      const globalDir = process.env.CLAUDE_CONFIG_DIR || join16(homedir5(), ".claude");
+      const [sub2, ...gargs] = rest;
+      if (sub2 === "list") {
         const enabled = listGlobalModules(globalDir);
         const onDisk = installedGlobalDirs(globalDir);
         console.log(`global modules (in ${globalDir}/imprnt/):`);
@@ -3179,7 +3340,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         console.log("\nthese load in every imp session (not a plain `claude`). enable: imprnt global add <name>   disable: imprnt global rm <name> [--purge]");
         break;
       }
-      if (sub === "add") {
+      if (sub2 === "add") {
         let from;
         const names = [];
         for (let i = 0;i < gargs.length; i++) {
@@ -3198,8 +3359,8 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         }
         const name = names[0];
         const proj = pluginRoot();
-        const srcDir = from ? resolve6(from) : join15(proj, "plugins", name);
-        if (!existsSync13(srcDir)) {
+        const srcDir = from ? resolve7(from) : join16(proj, "plugins", name);
+        if (!existsSync14(srcDir)) {
           console.error(`global add ${name}: no source - ${from ? `--from path not found: ${srcDir}` : `no plugins/${name}/ to promote; pass --from <dir>`}`);
           process.exit(1);
         }
@@ -3211,7 +3372,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         console.log(r.changed ? `enabled ${name} globally → loads in every imp session (copied to ${globalDir}/imprnt/${name}/)` : `${name} already enabled globally (refreshed the copy)`);
         break;
       }
-      if (sub === "rm") {
+      if (sub2 === "rm") {
         let purge = false;
         const names = [];
         for (const a of gargs) {
@@ -3243,7 +3404,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       } else if (process.stdin.isTTY && process.stdout.isTTY) {
         const inPlace = isVaultProject(process.cwd());
         const display = inPlace ? process.cwd() : "~/imprnt";
-        const fallback = inPlace ? process.cwd() : join15(homedir4(), "imprnt");
+        const fallback = inPlace ? process.cwd() : join16(homedir5(), "imprnt");
         const rl = createInterface2({ input: process.stdin, output: process.stdout });
         const answer = (await rl.question(`vault location [${display}]: `)).trim();
         rl.close();
@@ -3252,7 +3413,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         target = process.cwd();
       }
       const toCwd = target === process.cwd();
-      const rel = (sub) => toCwd ? `./${sub}` : join15(target, sub);
+      const rel = (sub2) => toCwd ? `./${sub2}` : join16(target, sub2);
       const lexicalEnclosing = projectRoot(target);
       const physical = physicalTarget(target);
       const physicalEnclosing = projectRoot(physical);
@@ -3265,15 +3426,15 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       const domains = ["identity", "health", "finances", "work", "life", "projects"];
       const forms = ["events", "mistakes"];
       const vaultDirs = [...entities, ...domains, ...forms];
-      const vaultPath = join15(target, "vault");
-      const vaultExisted = existsSync13(vaultPath);
+      const vaultPath = join16(target, "vault");
+      const vaultExisted = existsSync14(vaultPath);
       let createdDirs = 0;
       for (const d of ["", "vault", ...vaultDirs.map((t) => `vault/${t}`), "raw"]) {
-        const abs = d ? join15(target, d) : target;
-        if (!existsSync13(abs))
+        const abs = d ? join16(target, d) : target;
+        if (!existsSync14(abs))
           createdDirs++;
         try {
-          mkdirSync5(abs, { recursive: true });
+          mkdirSync6(abs, { recursive: true });
         } catch (e) {
           console.error(`cannot create ${d ? rel(d) : target}: ${e instanceof Error ? e.message : String(e)}`);
           process.exit(1);
@@ -3285,29 +3446,29 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       };
       const added = [];
       for (const f of ["index.md", "hot.md", "log.md", "_tags.md"]) {
-        const dst = join15(vaultPath, f);
+        const dst = join16(vaultPath, f);
         const slot = controlSlot(dst);
         if (slot.startsWith("blocked")) {
           console.error(blockedMsg(`vault/${f}`, slot));
           process.exit(1);
         }
         if (slot === "create") {
-          cpSync3(join15(pkgRoot, "templates", f), dst);
+          cpSync3(join16(pkgRoot, "templates", f), dst);
           added.push(`vault/${f}`);
         }
       }
-      const claudeMd = join15(target, "CLAUDE.md");
+      const claudeMd = join16(target, "CLAUDE.md");
       const cmSlot = controlSlot(claudeMd);
       if (cmSlot.startsWith("blocked")) {
         console.error(blockedMsg("CLAUDE.md", cmSlot));
         process.exit(1);
       }
-      if (cmSlot === "create" && existsSync13(join15(pkgRoot, "CLAUDE.md"))) {
-        cpSync3(join15(pkgRoot, "CLAUDE.md"), claudeMd);
+      if (cmSlot === "create" && existsSync14(join16(pkgRoot, "CLAUDE.md"))) {
+        cpSync3(join16(pkgRoot, "CLAUDE.md"), claudeMd);
         added.push("CLAUDE.md");
       }
       try {
-        const prevMode = statSync9(target).mode & 511;
+        const prevMode = statSync10(target).mode & 511;
         chmodSync(target, 448);
         if (prevMode !== 448)
           console.log(`locked ${target} to owner-only (chmod 700, was ${prevMode.toString(8).padStart(3, "0")})`);
@@ -3329,8 +3490,8 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         console.log(`  + ${rel("raw")} for immutable by-source snapshots`);
         console.log("next: type `imp` to talk, or ingest a source (`imprnt ingest <file>`), then `imprnt check`.");
       } else {
-        const noteCount = collectNotes(vaultPath).length;
-        console.log(`found existing vault at ${rel("vault")} — ${noteCount} note${noteCount === 1 ? "" : "s"}, left untouched`);
+        const noteCount2 = collectNotes(vaultPath).length;
+        console.log(`found existing vault at ${rel("vault")} — ${noteCount2} note${noteCount2 === 1 ? "" : "s"}, left untouched`);
         if (added.length)
           console.log(`  added missing control file${added.length === 1 ? "" : "s"}: ${added.join(", ")}`);
         else if (createdDirs)
@@ -3345,9 +3506,9 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       const isHelp = cmd === "help" || cmd === "--help" || cmd === "-h";
       const bare = cmd === undefined;
       if (cmd && !isHelp && !bare && !cmd.startsWith("-")) {
-        const modScript = join15(pluginRoot(), "plugins", cmd, `${cmd}.js`);
-        if (existsSync13(modScript)) {
-          const proc = spawnSync4(process.execPath, [modScript, ...rest], { stdio: "inherit" });
+        const modScript = join16(pluginRoot(), "plugins", cmd, `${cmd}.js`);
+        if (existsSync14(modScript)) {
+          const proc = spawnSync5(process.execPath, [modScript, ...rest], { stdio: "inherit" });
           process.exit(proc.status ?? 1);
         }
       }
@@ -3390,6 +3551,7 @@ engine (same subcommands under \`imp\` or \`imprnt\`):
   imprnt global add <name> [--from D]      enable a behavior module (e.g. anti-slop) in EVERY imp session (imp injects it; ~/.claude/CLAUDE.md is never touched); bare name promotes a project plugin
   imprnt global rm <name> [--purge]        disable a global module; --purge deletes the global copy
   imprnt global list                       show globally-enabled modules
+  imprnt vault list|archive|restore        the vault as its own object — outlives any agent
   imprnt <module> <command> [...]          run an installed module's command (e.g. \`imprnt session-host login\`, \`imprnt kleinanzeigen sync\`) — no \`node\` paths
 
 layout: entities (people · orgs · holdings) · domains (identity · health · finances · work · life · projects) · forms (events · mistakes)

package/dist/imp.js

@@ -2821,19 +2821,177 @@ all plugin checks passed.`);
   }
 });
 
-// scripts/cli.ts
-var exports_cli = {};
-import { cpSync as cpSync3, mkdirSync as mkdirSync5, chmodSync, existsSync as existsSync13, readFileSync as readFileSync14, lstatSync as lstatSync4, statSync as statSync9, realpathSync as realpathSync2 } from "node:fs";
+// scripts/vault.ts
+var exports_vault = {};
 import { spawnSync as spawnSync4 } from "node:child_process";
-import { join as join15, dirname as dirname4, resolve as resolve6, basename as basename6 } from "node:path";
+import { existsSync as existsSync13, mkdirSync as mkdirSync5, readdirSync as readdirSync9, statSync as statSync9 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
+import { basename as basename6, dirname as dirname4, join as join15, resolve as resolve6 } from "node:path";
+function noteCount(project) {
+  const root = join15(project, "vault");
+  if (!existsSync13(root))
+    return 0;
+  let n = 0;
+  const walk3 = (dir2, atRoot) => {
+    for (const e of readdirSync9(dir2, { withFileTypes: true })) {
+      if (e.name.startsWith(".") || e.name.startsWith("_"))
+        continue;
+      if (e.isSymbolicLink())
+        continue;
+      if (atRoot && CONTROL3.has(e.name))
+        continue;
+      if (e.isDirectory())
+        walk3(join15(dir2, e.name), false);
+      else if (e.name.endsWith(".md"))
+        n++;
+    }
+  };
+  try {
+    walk3(root, true);
+  } catch {}
+  return n;
+}
+function resolveTarget(token) {
+  const reg = readRegistry();
+  if (token) {
+    if (reg.vaults[token])
+      return { name: token, path: reg.vaults[token] };
+    const p = expand(token);
+    if (isVaultProject(p)) {
+      const named = Object.entries(reg.vaults).find(([, v]) => v === p)?.[0];
+      return { name: named ?? basename6(p), path: p };
+    }
+    console.error(`no vault called "${token}", and ${p} is not a vault project`);
+    console.error(`known: ${Object.keys(reg.vaults).join(", ") || "(none registered — run `imprnt init`)"}`);
+    process.exit(1);
+  }
+  const name = reg.default ?? Object.keys(reg.vaults)[0];
+  const path = name ? reg.vaults[name] : undefined;
+  if (!name || !path) {
+    console.error("no vault registered — run `imprnt init`");
+    process.exit(1);
+  }
+  return { name, path };
+}
+function tar(...a) {
+  const r = spawnSync4("tar", a, { stdio: ["ignore", "inherit", "inherit"] });
+  if (r.error) {
+    console.error(`tar is not available: ${r.error.message}`);
+    process.exit(1);
+  }
+  return r.status ?? 1;
+}
+var args5, sub, flag = (name) => {
+  const i = args5.indexOf(name);
+  return i >= 0 ? args5[i + 1] : undefined;
+}, positionals, expand = (p) => resolve6(p.startsWith("~/") ? join15(homedir4(), p.slice(2)) : p), CONTROL3;
+var init_vault = __esm(() => {
+  init_registry();
+  args5 = process.argv.slice(2);
+  sub = args5[0];
+  positionals = args5.slice(1).filter((a, i, all2) => !a.startsWith("--") && !(i > 0 && all2[i - 1]?.startsWith("--")));
+  CONTROL3 = new Set(["index.md", "hot.md", "log.md", "_tags.md"]);
+  switch (sub) {
+    case "list": {
+      const reg = readRegistry();
+      const names = Object.keys(reg.vaults);
+      if (!names.length) {
+        console.log("no vaults registered — run `imprnt init`");
+        break;
+      }
+      const def = reg.default ?? names[0];
+      for (const n of names) {
+        const p = reg.vaults[n];
+        const live = isVaultProject(p);
+        const mark = n === def ? "*" : " ";
+        const detail = live ? `${noteCount(p)} notes` : "MISSING — the path is registered but holds no vault";
+        console.log(`${mark} ${n.padEnd(12)} ${p}  (${detail})`);
+      }
+      console.log("\n* = default (what `imp` and `imprnt context` resolve to)");
+      break;
+    }
+    case "archive": {
+      const { name, path } = resolveTarget(positionals[0]);
+      if (!isVaultProject(path)) {
+        console.error(`${path} is not a vault project`);
+        process.exit(1);
+      }
+      const outDir = expand(flag("--out") ?? ".");
+      mkdirSync5(outDir, { recursive: true });
+      const stamp = new Date().toISOString().slice(0, 10);
+      const out = join15(outDir, `${name}-${stamp}.tar.gz`);
+      if (tar("czf", out, "-C", dirname4(path), basename6(path)) !== 0) {
+        console.error("archive failed");
+        process.exit(1);
+      }
+      if (tar("tzf", out) !== 0) {
+        console.error(`${out} does not read back — treat it as no archive at all`);
+        process.exit(1);
+      }
+      const size = (statSync9(out).size / 1024 / 1024).toFixed(1);
+      console.log(`archived ${name} (${noteCount(path)} notes) → ${out}  ${size} MB, verified`);
+      console.log(`restore with: imprnt vault restore ${out} <dir>`);
+      break;
+    }
+    case "restore": {
+      const src3 = expand(positionals[0] ?? "");
+      const dest2 = expand(positionals[1] ?? "");
+      if (!positionals[0] || !positionals[1]) {
+        console.error("usage: imprnt vault restore <archive.tar.gz> <dir>");
+        process.exit(1);
+      }
+      if (!existsSync13(src3)) {
+        console.error(`no archive at ${src3}`);
+        process.exit(1);
+      }
+      if (existsSync13(dest2) && readdirSync9(dest2).length) {
+        console.error(`${dest2} is not empty — restore into a new directory, then move it`);
+        process.exit(1);
+      }
+      mkdirSync5(dest2, { recursive: true });
+      if (tar("xzf", src3, "-C", dest2) !== 0) {
+        console.error("restore failed");
+        process.exit(1);
+      }
+      const inner = readdirSync9(dest2).map((e) => join15(dest2, e)).filter((p) => statSync9(p).isDirectory());
+      const project = inner.find((p) => isVaultProject(p)) ?? (isVaultProject(dest2) ? dest2 : undefined);
+      if (!project) {
+        console.error(`extracted, but ${dest2} holds no vault project — check the archive`);
+        process.exit(1);
+      }
+      console.log(`restored ${noteCount(project)} notes → ${project}`);
+      console.log(`register it with: cd ${project} && imprnt init`);
+      break;
+    }
+    default:
+      console.log(`imprnt vault — the vault as its own object
+
+  imprnt vault list                        vaults registered on this machine
+  imprnt vault archive [name|path]         one verified tarball  (--out <dir>)
+  imprnt vault restore <archive> <dir>     put one back
+
+Create one with \`imprnt init\`. There is no \`vault delete\`: removing knowledge is a
+human act with rm and a path, not a subcommand a script or an agent can reach.
+
+A vault means something with no agent attached. An agent with no vault is a process
+pointed at nothing — so the vault outlives whatever reads it.`);
+      process.exit(sub && sub !== "help" && sub !== "--help" ? 1 : 0);
+  }
+});
+
+// scripts/cli.ts
+var exports_cli = {};
+import { cpSync as cpSync3, mkdirSync as mkdirSync6, chmodSync, existsSync as existsSync14, readFileSync as readFileSync14, lstatSync as lstatSync4, statSync as statSync10, realpathSync as realpathSync2 } from "node:fs";
+import { spawnSync as spawnSync5 } from "node:child_process";
+import { join as join16, dirname as dirname5, resolve as resolve7, basename as basename7 } from "node:path";
+import { homedir as homedir5 } from "node:os";
 import { fileURLToPath } from "node:url";
 import { createInterface as createInterface2 } from "node:readline/promises";
 function pluginRoot() {
   const local = projectRoot();
   if (process.env.IMPRNT_ROOT || process.env.IMPRINT_ROOT)
     return local;
-  if (existsSync13(join15(local, "vault")) || existsSync13(join15(local, "CLAUDE.local.md")))
+  if (existsSync14(join16(local, "vault")) || existsSync14(join16(local, "CLAUDE.local.md")))
     return local;
   return registeredRoot() ?? local;
 }
@@ -2857,29 +3015,29 @@ function requireVaultHome() {
   }
   return home;
 }
-function resolvePath(input, base = process.cwd(), home = homedir4()) {
+function resolvePath(input, base = process.cwd(), home = homedir5()) {
   let p = input;
   if (p === "~")
     p = home;
   else if (p.startsWith("~/"))
-    p = join15(home, p.slice(2));
-  return resolve6(base, p);
+    p = join16(home, p.slice(2));
+  return resolve7(base, p);
 }
-function initPositional(args5) {
-  return args5.find((a) => !a.startsWith("-"));
+function initPositional(args6) {
+  return args6.find((a) => !a.startsWith("-"));
 }
 function physicalTarget(target) {
   let existing = target;
   const tail = [];
-  while (!existsSync13(existing)) {
-    const parent = dirname4(existing);
+  while (!existsSync14(existing)) {
+    const parent = dirname5(existing);
     if (parent === existing)
       return target;
-    tail.unshift(basename6(existing));
+    tail.unshift(basename7(existing));
     existing = parent;
   }
   try {
-    return tail.length ? join15(realpathSync2(existing), ...tail) : realpathSync2(existing);
+    return tail.length ? join16(realpathSync2(existing), ...tail) : realpathSync2(existing);
   } catch {
     return target;
   }
@@ -2895,7 +3053,7 @@ function controlSlot(dst) {
     return "blocked-directory";
   if (st.isSymbolicLink()) {
     try {
-      return statSync9(dst).isFile() ? "keep" : "blocked-symlink";
+      return statSync10(dst).isFile() ? "keep" : "blocked-symlink";
     } catch {
       return "blocked-symlink";
     }
@@ -2914,11 +3072,11 @@ var init_cli = __esm(async () => {
   init_moc();
   init_registry();
   init_launch();
-  here = dirname4(fileURLToPath(import.meta.url));
-  pkgRoot = join15(here, "..");
+  here = dirname5(fileURLToPath(import.meta.url));
+  pkgRoot = join16(here, "..");
   [cmd, ...rest] = process.argv.slice(2);
   asImp = globalThis.__IMPRNT_IMP__ === true;
-  if (["ingest", "recall", "snapshot", "check"].includes(cmd))
+  if (["ingest", "recall", "snapshot", "check", "vault"].includes(cmd))
     process.argv.splice(2, 1);
   switch (cmd) {
     case "ingest":
@@ -2933,6 +3091,9 @@ var init_cli = __esm(async () => {
     case "check":
       await Promise.resolve().then(() => (init_check(), exports_check));
       break;
+    case "vault":
+      await Promise.resolve().then(() => (init_vault(), exports_vault));
+      break;
     case "hot": {
       const vault5 = vaultArg();
       const review2 = openNeedsReview(vault5);
@@ -2942,8 +3103,8 @@ var init_cli = __esm(async () => {
           console.log(r);
         console.log("");
       }
-      const p = join15(vault5, "hot.md");
-      if (!existsSync13(p)) {
+      const p = join16(vault5, "hot.md");
+      if (!existsSync14(p)) {
         console.error(`no hot.md at ${p} — run \`imprnt init\``);
         process.exit(1);
       }
@@ -2959,8 +3120,8 @@ var init_cli = __esm(async () => {
     }
     case "context": {
       const home = requireVaultHome();
-      const contract = join15(home, "CLAUDE.md");
-      if (!existsSync13(contract)) {
+      const contract = join16(home, "CLAUDE.md");
+      if (!existsSync14(contract)) {
         console.error(`no CLAUDE.md at ${home} — run \`imprnt init\` there to drop the contract`);
         process.exit(1);
       }
@@ -3043,8 +3204,8 @@ var init_cli = __esm(async () => {
       const proj = pluginRoot();
       if (proj !== process.cwd())
         console.error(`(targeting vault project: ${proj})`);
-      const [sub, ...specs] = rest;
-      if (sub === "list") {
+      const [sub2, ...specs] = rest;
+      if (sub2 === "list") {
         const dirs = listPluginDirs(proj);
         console.log("plugins:");
         if (!dirs.length)
@@ -3059,7 +3220,7 @@ available to add: ${available.join(", ")}`);
 enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         break;
       }
-      if (sub === "add") {
+      if (sub2 === "add") {
         let from;
         let force = false;
         const names = [];
@@ -3123,7 +3284,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
           process.exit(1);
         break;
       }
-      if (sub === "rm") {
+      if (sub2 === "rm") {
         let purge = false;
         const names = [];
         for (const s of specs) {
@@ -3163,9 +3324,9 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       process.exit(1);
     }
     case "global": {
-      const globalDir = process.env.CLAUDE_CONFIG_DIR || join15(homedir4(), ".claude");
-      const [sub, ...gargs] = rest;
-      if (sub === "list") {
+      const globalDir = process.env.CLAUDE_CONFIG_DIR || join16(homedir5(), ".claude");
+      const [sub2, ...gargs] = rest;
+      if (sub2 === "list") {
         const enabled = listGlobalModules(globalDir);
         const onDisk = installedGlobalDirs(globalDir);
         console.log(`global modules (in ${globalDir}/imprnt/):`);
@@ -3179,7 +3340,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         console.log("\nthese load in every imp session (not a plain `claude`). enable: imprnt global add <name>   disable: imprnt global rm <name> [--purge]");
         break;
       }
-      if (sub === "add") {
+      if (sub2 === "add") {
         let from;
         const names = [];
         for (let i = 0;i < gargs.length; i++) {
@@ -3198,8 +3359,8 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         }
         const name = names[0];
         const proj = pluginRoot();
-        const srcDir = from ? resolve6(from) : join15(proj, "plugins", name);
-        if (!existsSync13(srcDir)) {
+        const srcDir = from ? resolve7(from) : join16(proj, "plugins", name);
+        if (!existsSync14(srcDir)) {
           console.error(`global add ${name}: no source - ${from ? `--from path not found: ${srcDir}` : `no plugins/${name}/ to promote; pass --from <dir>`}`);
           process.exit(1);
         }
@@ -3211,7 +3372,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         console.log(r.changed ? `enabled ${name} globally → loads in every imp session (copied to ${globalDir}/imprnt/${name}/)` : `${name} already enabled globally (refreshed the copy)`);
         break;
       }
-      if (sub === "rm") {
+      if (sub2 === "rm") {
         let purge = false;
         const names = [];
         for (const a of gargs) {
@@ -3243,7 +3404,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       } else if (process.stdin.isTTY && process.stdout.isTTY) {
         const inPlace = isVaultProject(process.cwd());
         const display = inPlace ? process.cwd() : "~/imprnt";
-        const fallback = inPlace ? process.cwd() : join15(homedir4(), "imprnt");
+        const fallback = inPlace ? process.cwd() : join16(homedir5(), "imprnt");
         const rl = createInterface2({ input: process.stdin, output: process.stdout });
         const answer = (await rl.question(`vault location [${display}]: `)).trim();
         rl.close();
@@ -3252,7 +3413,7 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         target = process.cwd();
       }
       const toCwd = target === process.cwd();
-      const rel = (sub) => toCwd ? `./${sub}` : join15(target, sub);
+      const rel = (sub2) => toCwd ? `./${sub2}` : join16(target, sub2);
       const lexicalEnclosing = projectRoot(target);
       const physical = physicalTarget(target);
       const physicalEnclosing = projectRoot(physical);
@@ -3265,15 +3426,15 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       const domains = ["identity", "health", "finances", "work", "life", "projects"];
       const forms = ["events", "mistakes"];
       const vaultDirs = [...entities, ...domains, ...forms];
-      const vaultPath = join15(target, "vault");
-      const vaultExisted = existsSync13(vaultPath);
+      const vaultPath = join16(target, "vault");
+      const vaultExisted = existsSync14(vaultPath);
       let createdDirs = 0;
       for (const d of ["", "vault", ...vaultDirs.map((t) => `vault/${t}`), "raw"]) {
-        const abs = d ? join15(target, d) : target;
-        if (!existsSync13(abs))
+        const abs = d ? join16(target, d) : target;
+        if (!existsSync14(abs))
           createdDirs++;
         try {
-          mkdirSync5(abs, { recursive: true });
+          mkdirSync6(abs, { recursive: true });
         } catch (e) {
           console.error(`cannot create ${d ? rel(d) : target}: ${e instanceof Error ? e.message : String(e)}`);
           process.exit(1);
@@ -3285,29 +3446,29 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       };
       const added = [];
       for (const f of ["index.md", "hot.md", "log.md", "_tags.md"]) {
-        const dst = join15(vaultPath, f);
+        const dst = join16(vaultPath, f);
         const slot = controlSlot(dst);
         if (slot.startsWith("blocked")) {
           console.error(blockedMsg(`vault/${f}`, slot));
           process.exit(1);
         }
         if (slot === "create") {
-          cpSync3(join15(pkgRoot, "templates", f), dst);
+          cpSync3(join16(pkgRoot, "templates", f), dst);
           added.push(`vault/${f}`);
         }
       }
-      const claudeMd = join15(target, "CLAUDE.md");
+      const claudeMd = join16(target, "CLAUDE.md");
       const cmSlot = controlSlot(claudeMd);
       if (cmSlot.startsWith("blocked")) {
         console.error(blockedMsg("CLAUDE.md", cmSlot));
         process.exit(1);
       }
-      if (cmSlot === "create" && existsSync13(join15(pkgRoot, "CLAUDE.md"))) {
-        cpSync3(join15(pkgRoot, "CLAUDE.md"), claudeMd);
+      if (cmSlot === "create" && existsSync14(join16(pkgRoot, "CLAUDE.md"))) {
+        cpSync3(join16(pkgRoot, "CLAUDE.md"), claudeMd);
         added.push("CLAUDE.md");
       }
       try {
-        const prevMode = statSync9(target).mode & 511;
+        const prevMode = statSync10(target).mode & 511;
         chmodSync(target, 448);
         if (prevMode !== 448)
           console.log(`locked ${target} to owner-only (chmod 700, was ${prevMode.toString(8).padStart(3, "0")})`);
@@ -3329,8 +3490,8 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
         console.log(`  + ${rel("raw")} for immutable by-source snapshots`);
         console.log("next: type `imp` to talk, or ingest a source (`imprnt ingest <file>`), then `imprnt check`.");
       } else {
-        const noteCount = collectNotes(vaultPath).length;
-        console.log(`found existing vault at ${rel("vault")} — ${noteCount} note${noteCount === 1 ? "" : "s"}, left untouched`);
+        const noteCount2 = collectNotes(vaultPath).length;
+        console.log(`found existing vault at ${rel("vault")} — ${noteCount2} note${noteCount2 === 1 ? "" : "s"}, left untouched`);
         if (added.length)
           console.log(`  added missing control file${added.length === 1 ? "" : "s"}: ${added.join(", ")}`);
         else if (createdDirs)
@@ -3345,9 +3506,9 @@ enable: imprnt plugin add <name>   disable: imprnt plugin rm <name> [--purge]`);
       const isHelp = cmd === "help" || cmd === "--help" || cmd === "-h";
       const bare = cmd === undefined;
       if (cmd && !isHelp && !bare && !cmd.startsWith("-")) {
-        const modScript = join15(pluginRoot(), "plugins", cmd, `${cmd}.js`);
-        if (existsSync13(modScript)) {
-          const proc = spawnSync4(process.execPath, [modScript, ...rest], { stdio: "inherit" });
+        const modScript = join16(pluginRoot(), "plugins", cmd, `${cmd}.js`);
+        if (existsSync14(modScript)) {
+          const proc = spawnSync5(process.execPath, [modScript, ...rest], { stdio: "inherit" });
           process.exit(proc.status ?? 1);
         }
       }
@@ -3390,6 +3551,7 @@ engine (same subcommands under \`imp\` or \`imprnt\`):
   imprnt global add <name> [--from D]      enable a behavior module (e.g. anti-slop) in EVERY imp session (imp injects it; ~/.claude/CLAUDE.md is never touched); bare name promotes a project plugin
   imprnt global rm <name> [--purge]        disable a global module; --purge deletes the global copy
   imprnt global list                       show globally-enabled modules
+  imprnt vault list|archive|restore        the vault as its own object — outlives any agent
   imprnt <module> <command> [...]          run an installed module's command (e.g. \`imprnt session-host login\`, \`imprnt kleinanzeigen sync\`) — no \`node\` paths
 
 layout: entities (people · orgs · holdings) · domains (identity · health · finances · work · life · projects) · forms (events · mistakes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprnt",
-  "version": "0.1.4-edge.74",
+  "version": "0.1.4-edge.88",
   "stable": true,
   "description": "Deterministic-first, plain-markdown knowledge vault. Code does the bulk transform. The LLM only touches the irreducibly-semantic 20%. Native grep plus BM25 retrieval, zero MCP on the vault.",
   "type": "module",