nexusmem 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -9,6 +9,21 @@ built from, matched by publish timestamp: `v0.1.0` → `67a4776`, `v0.1.1` → `
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-08-17
+
+### Added
+
+- **`nexusmem forget --export <path>` / `forget --import <path>`: carry a deny-list across a clone or
+  restore.** `.nexusmem/` is gitignored by design, so `deny_list` never traveled with `git clone`/
+  `git push` — confirmed live 2026-08-17 that a fresh clone of the exact same repo resurrected a value
+  already forgotten elsewhere, with zero deny-list protection, because git history (what a fresh `sync`
+  re-derives from) is fully portable while the deny-list that would have blocked it was not. `--export`
+  writes the active entries to a plaintext JSON file (loudly warned as exactly as sensitive as the
+  values it holds — never meant for git, moved through whatever secure channel the user already
+  trusts); `--import` re-applies each new entry through `forget` itself, so an imported value is
+  deleted from the new checkout's nodes too, not just blocked going forward. Same dry-run-by-default /
+  `--yes` convention as the rest of `forget`. See `docs/forget-mechanism.md`.
+
 ## [0.5.0] — 2026-08-17
 
 ### Added
@@ -337,7 +352,8 @@ First public release.
   there is no local-model summarization pass, and the conversation collector has never been audited
   for the stale-node bug that was found and fixed in the docs collector.
 
-[Unreleased]: https://github.com/yaminbkk/NexusMem/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/yaminbkk/NexusMem/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/yaminbkk/NexusMem/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/yaminbkk/NexusMem/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/yaminbkk/NexusMem/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/yaminbkk/NexusMem/compare/v0.3.2...v0.3.3

package/README.md

@@ -322,6 +322,15 @@ optimizing, and it is somebody else's process.
   ran against (plus that repo's stale prior identities, same scope `--prune-source` already uses). A
   value that leaked into shell history from several repositories needs `forget` run once per repo —
   there is no shared, machine-wide deny-list across every project you have synced.
+- **A deny-list doesn't survive a clone or restore on its own.** `.nexusmem/` is gitignored by design,
+  so `deny_list` never travels with `git clone`/`git push` — while git history itself, the thing a
+  fresh `sync` re-derives from, is fully portable and copied by every clone. A teammate's fresh
+  checkout, a new machine, or a restored backup starts with zero protection: the forgotten value comes
+  right back on the first sync. Confirmed live 2026-08-17, not just a theoretical read of the code.
+  `forget --export <path>` / `forget --import <path>` close this: export writes the active entries to
+  a plaintext JSON file you move through a channel you control (never git — the file is exactly as
+  sensitive as the value it holds), and import re-applies them in the new checkout, deleting any
+  copies that already synced back in. It is deliberately manual, not automatic on every `sync`.
 
 ## Commands
 
@@ -344,8 +353,9 @@ is the finer-grained complement — it deletes every node matching one exact str
 pattern) *and* writes a standing deny-list entry so the value can never be re-ingested, even by a
 later `sync --rebuild` re-reading the append-only shell-hook log or a full transcript scan. Every
 removal leaves a hash-only tombstone, never the forgotten content itself. Both are dry-run by
-default; `--yes` confirms. See [`docs/forget-mechanism.md`](docs/forget-mechanism.md) for why this
-exists.
+default; `--yes` confirms. `forget --list` shows active entries; `forget --export <path>` /
+`forget --import <path>` carry them to another checkout of the same repo (see the limitation above).
+See [`docs/forget-mechanism.md`](docs/forget-mechanism.md) for why this exists.
 
 ## Recall across projects
 

package/dist/cli/index.js

@@ -726,6 +726,12 @@ function insertDenyListEntry(db, input) {
     createdAt
   };
 }
+function denyListEntryExists(db, projectId, input) {
+  const row = db.prepare(
+    `SELECT 1 FROM deny_list WHERE project_id = ? AND match_type = ? AND pattern = ? AND ignore_case = ? LIMIT 1`
+  ).get(projectId, input.matchType, input.pattern, input.ignoreCase ? 1 : 0);
+  return row !== void 0;
+}
 function matchableText(node) {
   return `${node.title}
 ${node.body}
@@ -748,7 +754,9 @@ function firstMatchingEntry(entries, node) {
 }
 
 // src/cli/commands/forget.ts
+import { readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
 import pc from "picocolors";
+import { z as z2 } from "zod";
 
 // src/store/store.ts
 import Database from "better-sqlite3";
@@ -1348,6 +1356,59 @@ var MemoryStore = class _MemoryStore {
   listDenyList(projectId) {
     return listDenyListEntries(this.db, projectId);
   }
+  /**
+   * What `importDenyList` with these same entries would do, without writing
+   * anything -- `forget --import`'s dry-run default, same convention as
+   * `previewForget`.
+   */
+  previewImportDenyList(projectId, otherProjectIds, entries) {
+    return entries.map((input) => {
+      validatePattern(input);
+      if (denyListEntryExists(this.db, projectId, input)) {
+        return { matchType: input.matchType, pattern: input.pattern, alreadyPresent: true, wouldRemove: 0 };
+      }
+      const preview = this.previewForget(projectId, otherProjectIds, input);
+      return {
+        matchType: input.matchType,
+        pattern: input.pattern,
+        alreadyPresent: false,
+        wouldRemove: preview.reduce((sum, p) => sum + p.count, 0)
+      };
+    });
+  }
+  /**
+   * Re-apply a previously-exported deny-list against this project.
+   *
+   * This is the fix for `forget`'s per-checkout gap: `deny_list` lives in
+   * `.nexusmem/memory.db`, which is gitignored and never travels with `git
+   * clone`/`git push`, while the things a fresh `sync` re-derives from --
+   * git history and the user-home shell-hook log -- both travel or persist
+   * independently of any one checkout. A fresh clone or a restored backup
+   * starts with an empty deny_list and no memory of what was forgotten. See
+   * docs/forget-mechanism.md.
+   *
+   * Entries already active (same matchType+pattern+ignoreCase) are left
+   * untouched. Every new one goes through `forget` itself, so an imported
+   * value is deleted from this checkout's nodes too, not just blocked going
+   * forward -- exactly what running `nexusmem forget <value>` fresh in this
+   * checkout would have done.
+   */
+  importDenyList(projectId, otherProjectIds, entries) {
+    let imported = 0;
+    let skipped = 0;
+    let removedNodes = 0;
+    for (const input of entries) {
+      validatePattern(input);
+      if (denyListEntryExists(this.db, projectId, input)) {
+        skipped += 1;
+        continue;
+      }
+      const result = this.forget(projectId, otherProjectIds, input);
+      imported += 1;
+      removedNodes += result.removed;
+    }
+    return { imported, skipped, removedNodes };
+  }
   /**
    * Replace this project's entire `file_edges` snapshot in one transaction.
    *
@@ -1509,6 +1570,17 @@ async function loadContext(cwd) {
 }
 
 // src/cli/commands/forget.ts
+var ExportPayloadSchema = z2.object({
+  version: z2.literal(1),
+  entries: z2.array(
+    z2.object({
+      matchType: z2.enum(["literal", "regex"]),
+      pattern: z2.string(),
+      ignoreCase: z2.boolean(),
+      reason: z2.string().nullable()
+    })
+  )
+});
 async function runForget(opts) {
   const { ws, projectId } = await loadContext(opts.cwd);
   const out = opts.out ?? ((chunk2) => void process.stdout.write(chunk2));
@@ -1532,8 +1604,75 @@ async function runForget(opts) {
       );
       return 0;
     }
+    if (opts.export) {
+      const entries = store.listDenyList(projectId);
+      const payload = {
+        version: 1,
+        entries: entries.map((e) => ({ matchType: e.matchType, pattern: e.pattern, ignoreCase: e.ignoreCase, reason: e.reason }))
+      };
+      await writeFile4(opts.export, `${JSON.stringify(payload, null, 2)}
+`, "utf8");
+      out(
+        [
+          `${pc.green("exported")} ${entries.length} deny-list entrie(s) to ${opts.export}`,
+          pc.yellow(
+            "this file contains the raw forgotten value(s) in plaintext -- store it somewhere secure (password manager, encrypted note) and never commit it to git or share it publicly."
+          ),
+          ""
+        ].join("\n")
+      );
+      return 0;
+    }
+    if (opts.import) {
+      let raw;
+      try {
+        raw = await readFile4(opts.import, "utf8");
+      } catch (err) {
+        throw new DenyListError(`could not read ${opts.import}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        throw new DenyListError(`${opts.import} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      const validated = ExportPayloadSchema.safeParse(parsed);
+      if (!validated.success) {
+        throw new DenyListError(
+          `${opts.import} is not a valid deny-list export: ${validated.error.issues.map((i) => i.message).join("; ")}`
+        );
+      }
+      const entries = validated.data.entries;
+      const otherProjectIds2 = store.listOtherProjectIds(projectId);
+      if (!opts.yes) {
+        const preview = store.previewImportDenyList(projectId, otherProjectIds2, entries);
+        const toImport = preview.filter((p) => !p.alreadyPresent);
+        const totalRemove = toImport.reduce((sum, p) => sum + p.wouldRemove, 0);
+        if (toImport.length === 0) {
+          out(`${pc.dim("forget --import")} all ${preview.length} entrie(s) in ${opts.import} are already active -- nothing to do
+`);
+          return 0;
+        }
+        const describe = (p) => `  ${p.matchType === "regex" ? pc.dim("/") + p.pattern + pc.dim("/") : JSON.stringify(p.pattern)}: ${p.wouldRemove} node(s)`;
+        out(
+          [
+            `${pc.yellow("would import")} ${toImport.length} new deny-list entrie(s)${preview.length > toImport.length ? ` (${preview.length - toImport.length} already active)` : ""}, removing ${totalRemove} node(s):`,
+            ...toImport.map(describe),
+            pc.dim("re-run with --yes to permanently deny-list these value(s) and delete matching node(s) -- this cannot be undone"),
+            ""
+          ].join("\n")
+        );
+        return 0;
+      }
+      const result2 = store.importDenyList(projectId, otherProjectIds2, entries);
+      out(
+        `${pc.green("imported")} ${result2.imported} deny-list entrie(s)${result2.skipped > 0 ? ` (${result2.skipped} already active)` : ""}, ${result2.removedNodes} node(s) deleted
+`
+      );
+      return 0;
+    }
     if (!opts.value) {
-      throw new DenyListError("a value is required (or pass --list to see active deny-list entries)");
+      throw new DenyListError("a value is required (or pass --list/--export/--import)");
     }
     const input = {
       matchType: opts.regex ? "regex" : "literal",
@@ -1663,20 +1802,20 @@ import pc4 from "picocolors";
 
 // src/config/registry.ts
 import { existsSync as existsSync2 } from "fs";
-import { mkdir as mkdir4, readFile as readFile4, rename, writeFile as writeFile4 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile5, rename, writeFile as writeFile5 } from "fs/promises";
 import { join as join5 } from "path";
-import { z as z2 } from "zod";
-var ENTRY_SCHEMA = z2.object({
-  projectId: z2.string().min(1),
-  root: z2.string().min(1),
-  dbPath: z2.string().min(1),
-  originUrl: z2.string().nullable().default(null),
+import { z as z3 } from "zod";
+var ENTRY_SCHEMA = z3.object({
+  projectId: z3.string().min(1),
+  root: z3.string().min(1),
+  dbPath: z3.string().min(1),
+  originUrl: z3.string().nullable().default(null),
   /** Epoch ms of the last `init`/`sync` that recorded this entry. */
-  lastSeenAt: z2.number().int().nonnegative()
+  lastSeenAt: z3.number().int().nonnegative()
 });
-var REGISTRY_SCHEMA = z2.object({
-  version: z2.literal(1),
-  projects: z2.array(ENTRY_SCHEMA).default([])
+var REGISTRY_SCHEMA = z3.object({
+  version: z3.literal(1),
+  projects: z3.array(ENTRY_SCHEMA).default([])
 });
 function registryPath() {
   return join5(globalWorkspaceDir(), "projects.json");
@@ -1684,7 +1823,7 @@ function registryPath() {
 async function readRegistry() {
   let raw;
   try {
-    raw = await readFile4(registryPath(), "utf8");
+    raw = await readFile5(registryPath(), "utf8");
   } catch {
     return [];
   }
@@ -1724,7 +1863,7 @@ async function writeRegistry(projects) {
   const path = registryPath();
   const tmp = `${path}.${process.pid}.tmp`;
   await mkdir4(globalWorkspaceDir(), { recursive: true });
-  await writeFile4(tmp, `${JSON.stringify({ version: 1, projects }, null, 2)}
+  await writeFile5(tmp, `${JSON.stringify({ version: 1, projects }, null, 2)}
 `, "utf8");
   await rename(tmp, path);
 }
@@ -1849,7 +1988,7 @@ ${pc5.yellow(`${missing.length} registered project(s) have no database on disk`)
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/mcp/tools.ts
 import { basename as basename3 } from "path";
@@ -3378,7 +3517,7 @@ function collectShellHistory(entries, projectId, opts = {}) {
 }
 
 // src/conversation/claude-code-reader.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import { basename as basename2 } from "path";
 
 // src/conversation/paths.ts
@@ -3471,14 +3610,14 @@ async function collectClaudeCodeTranscripts(repoRoot) {
   const files = await listTranscriptFiles(repoRoot);
   const turns = [];
   for (const file of files) {
-    const raw = await readFile5(file, "utf8");
+    const raw = await readFile6(file, "utf8");
     turns.push(...parseClaudeCodeTranscript(raw, { sessionId: basename2(file, ".jsonl") }));
   }
   return turns;
 }
 
 // src/docs/read.ts
-import { readFile as readFile6, stat } from "fs/promises";
+import { readFile as readFile7, stat } from "fs/promises";
 import { join as join7 } from "path";
 var DEFAULT_PATHSPECS = ["*.md"];
 async function listDocFiles(repoRoot, opts = {}) {
@@ -3496,7 +3635,7 @@ async function readDocFiles(repoRoot, opts = {}) {
     let content;
     let mtime;
     try {
-      [content, { mtime }] = await Promise.all([readFile6(absPath, "utf8"), stat(absPath)]);
+      [content, { mtime }] = await Promise.all([readFile7(absPath, "utf8"), stat(absPath)]);
     } catch {
       unreadable.push(path);
       continue;
@@ -3508,10 +3647,10 @@ async function readDocFiles(repoRoot, opts = {}) {
 
 // src/shell/detect.ts
 import { existsSync as existsSync4 } from "fs";
-import { readFile as readFile8, stat as stat2 } from "fs/promises";
+import { readFile as readFile9, stat as stat2 } from "fs/promises";
 
 // src/shell/hook-log.ts
-import { appendFile, mkdir as mkdir5, readFile as readFile7 } from "fs/promises";
+import { appendFile, mkdir as mkdir5, readFile as readFile8 } from "fs/promises";
 import { dirname as dirname4 } from "path";
 function parseHookLogLine(line) {
   const trimmed = line.trim();
@@ -3536,7 +3675,7 @@ function parseHookLogLine(line) {
 async function readHookLog(path, fromLine) {
   let raw;
   try {
-    raw = await readFile7(path, "utf8");
+    raw = await readFile8(path, "utf8");
   } catch {
     return { entries: [], totalLines: fromLine };
   }
@@ -3670,7 +3809,7 @@ function hookEntryToRaw(e) {
 }
 async function tryReadScrapeSource(path, parse, tailLines) {
   if (!existsSync4(path)) return null;
-  const [raw, stats] = await Promise.all([readFile8(path, "utf8"), stat2(path)]);
+  const [raw, stats] = await Promise.all([readFile9(path, "utf8"), stat2(path)]);
   return parse(raw, stats.mtimeMs, { tailLines });
 }
 async function collectAvailableShellHistory(opts = {}) {
@@ -3824,7 +3963,7 @@ function reconcileProjectId(db, oldProjectId, newProjectId) {
 }
 
 // src/structure/collect.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 import { join as join8 } from "path";
 
 // src/structure/extract.ts
@@ -3901,7 +4040,7 @@ async function collectFileEdges(repoRoot) {
   for (const path of paths) {
     let content;
     try {
-      content = await readFile9(join8(repoRoot, path), "utf8");
+      content = await readFile10(join8(repoRoot, path), "utf8");
     } catch {
       unreadable.push(path);
       continue;
@@ -4453,10 +4592,10 @@ function createServer() {
       title: "Search remembered project history",
       description: "Search a NexusMem-tracked repository's remembered history: git commits, code diffs (the patch of each changed file), shell commands, tracked markdown docs, and (if enabled) conversation transcripts and per-session summaries. Returns a token-budgeted, ranked context block -- not raw search results.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root"),
-        query: z3.string().describe("Free-text question or search terms"),
-        budget: z3.number().int().positive().optional().describe("Max tokens in the returned context block. Default 2000."),
-        allProjects: z3.boolean().optional().describe(
+        projectRoot: z4.string().describe("Absolute path to the repository root"),
+        query: z4.string().describe("Free-text question or search terms"),
+        budget: z4.number().int().positive().optional().describe("Max tokens in the returned context block. Default 2000."),
+        allProjects: z4.boolean().optional().describe(
           "Search every repository NexusMem has been run in on this machine, not just projectRoot. Use when the answer may live in a different project (a pattern solved elsewhere, a tool that failed the same way before). Each result is tagged with its repository."
         )
       }
@@ -4483,10 +4622,10 @@ function createServer() {
       title: "Sync remembered history",
       description: "Ingest new git, diff, shell, docs and (if enabled) conversation history for a NexusMem-tracked repository into its local database. Pass pruneSource or pruneStaleShell instead to delete a dead source's nodes (e.g. the pre-hook shell scrape) rather than syncing -- dry-run unless yes is also true, since this is an irreversible full wipe of that source.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root"),
-        pruneSource: z3.string().optional().describe('Delete every node from this exact source (e.g. "shell:pwsh") instead of syncing'),
-        pruneStaleShell: z3.boolean().optional().describe("Shortcut for pruneSource on shell:pwsh, shell:bash and shell:zsh at once -- the dead pre-hook scrape sources"),
-        yes: z3.boolean().optional().describe("Confirms the delete. Without it, pruneSource/pruneStaleShell only report the matching count.")
+        projectRoot: z4.string().describe("Absolute path to the repository root"),
+        pruneSource: z4.string().optional().describe('Delete every node from this exact source (e.g. "shell:pwsh") instead of syncing'),
+        pruneStaleShell: z4.boolean().optional().describe("Shortcut for pruneSource on shell:pwsh, shell:bash and shell:zsh at once -- the dead pre-hook scrape sources"),
+        yes: z4.boolean().optional().describe("Confirms the delete. Without it, pruneSource/pruneStaleShell only report the matching count.")
       }
     },
     async ({ projectRoot, pruneSource, pruneStaleShell, yes }) => {
@@ -4500,7 +4639,7 @@ function createServer() {
       title: "Show what is remembered",
       description: "Report how many nodes NexusMem currently remembers for a repository, broken down by kind and source.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root")
+        projectRoot: z4.string().describe("Absolute path to the repository root")
       }
     },
     async ({ projectRoot }) => {
@@ -4517,8 +4656,8 @@ function createServer() {
       title: "List recently remembered items",
       description: "List the most recently remembered items for a NexusMem-tracked repository -- git commits, code diffs, shell commands, tracked docs, and (if enabled) conversation transcripts and session summaries -- newest first. Chronological, not relevance-ranked: use search_memory instead for a specific question.",
       inputSchema: {
-        projectRoot: z3.string().describe("Absolute path to the repository root"),
-        limit: z3.number().int().positive().optional().describe("Max items to return, newest first. Default 20.")
+        projectRoot: z4.string().describe("Absolute path to the repository root"),
+        limit: z4.number().int().positive().optional().describe("Max items to return, newest first. Default 20.")
       }
     },
     async ({ projectRoot, limit }) => {
@@ -5254,7 +5393,7 @@ program.command("query").description("Search remembered history and print a toke
 );
 program.command("forget").description(
   "Permanently deny-list a value: deletes matching nodes now and blocks it from ever being re-ingested (irreversible)"
-).argument("[value]", "exact text to forget (see --regex); omit with --list").option("-C, --cwd <path>", "repository path", process.cwd()).option("--regex", "treat <value> as a regular expression instead of a literal substring", false).option("--ignore-case", "case-insensitive match", false).option("--reason <text>", "free-text note stored with the deny-list entry").option("--list", "list active deny-list entries instead of forgetting a new value", false).option("--yes", "confirm the irreversible delete + deny-list write", false).action(
+).argument("[value]", "exact text to forget (see --regex); omit with --list").option("-C, --cwd <path>", "repository path", process.cwd()).option("--regex", "treat <value> as a regular expression instead of a literal substring", false).option("--ignore-case", "case-insensitive match", false).option("--reason <text>", "free-text note stored with the deny-list entry").option("--list", "list active deny-list entries instead of forgetting a new value", false).option("--export <path>", "write this project's deny-list to a JSON file, for --import in another checkout").option("--import <path>", "re-apply a deny-list JSON file (from --export) against this project").option("--yes", "confirm the irreversible delete + deny-list write", false).action(
   (value, options) => guard(
     () => runForget({
       cwd: options.cwd,
@@ -5263,6 +5402,8 @@ program.command("forget").description(
       ignoreCase: options.ignoreCase,
       reason: options.reason,
       list: options.list,
+      export: options.export,
+      import: options.import,
       yes: options.yes
     })
   )()