quilltap 4.8.0-dev → 4.8.0-dev.103

package/README.md

@@ -241,6 +241,18 @@ quilltap memory-diff <chatId> --out /tmp/diff --concurrency 8
 
 Needs a running server (`--port`, default 3000) to reach the extraction pipeline. `--out <dir>` sets the report destination (default: cwd); `--concurrency N` bounds parallel turns (default 4, max 32).
 
+## Recall Replay
+
+`quilltap recall-replay <chatId>` replays a turn's memory recall against the running server and prints the candidate table twice — the pre-overhaul ranking vs. the episodic (retrospective / time-window / entity-anchored) ranking — with cosine, blend, every multiplier fired, and head selection per row. Read-only; used to tune the recall constants against real "the character forgot" turns.
+
+```bash
+quilltap recall-replay <chatId>                 # Replay the last turn
+quilltap recall-replay <chatId> --turn 42       # Replay at interchange 42 (its own clock)
+quilltap recall-replay <chatId> --json          # Raw JSON for scripting
+```
+
+Flags: `--turn <n>` (default: last), `--char <characterId>` (default: first LLM-controlled participant), `--limit <n>` (default 25), `--port <n>` (default 3000), `--json`.
+
 ## Maintenance & Cleanup
 
 `quilltap maintenance` is the manual trigger for the retention sweeps that otherwise run on the server's daily maintenance tick. It reaps data with no bearing on characters, stories, or memories.
@@ -278,6 +290,18 @@ quilltap migrations run --dry-run # List what would run (refuses without --dry-r
 
 `--json` works on all three. "Not yet recorded" includes migrations whose `shouldRun()` is `false` on this instance — the CLI doesn't evaluate the predicate, so it can't distinguish "would skip" from "would run."
 
+## File Verification
+
+`quilltap file-verify` force-downloads an instance's cloud-evicted (dataless) top-level data files so the databases are fully local before anything opens them. It reads each placeholder, which faults it in through the cloud provider (iCloud Drive, etc.). Safe to run repeatedly — a no-op when nothing is evicted. macOS only for now.
+
+```bash
+quilltap file-verify --instance Ignite        # Fault in only the dataless top-level files
+quilltap file-verify --instance Friday --all  # Read every top-level file, not just dataless ones
+quilltap file-verify --instance Friday --json # Machine-readable report
+```
+
+Only the **top-level** files of the data directory are considered; the `backups/` subdirectory is left alone. Flags: `--all` (read every top-level file, not just dataless ones), `--stall-ms <ms>` (treat a download as stalled after this many ms with no bytes per chunk; default 30000), `--json`. Resolves the instance via the usual `--instance` / `--data-dir` plumbing.
+
 ## Theme Management
 
 The CLI includes theme management commands:

package/bin/quilltap.js

@@ -99,6 +99,7 @@ Subcommands:
   maintenance                   Run retention / cleanup sweeps (status / run)
   file-verify                   Force-download cloud-evicted data files (iCloud, etc.)
   memory-diff <chatId>          Dump existing memories and dry-run re-extraction for a chat
+  recall-replay <chatId>        Replay a turn's memory recall, old vs episodic ranking
   completion <shell>            Generate a shell completion script (bash / zsh / fish)
 
 Options:
@@ -1108,7 +1109,7 @@ async function dbCommand(args) {
 // to the subcommand. Each subcommand parses these flags position-independently,
 // so they behave the same before or after the verb.
 const SUBCOMMANDS = new Set([
-  'db', 'themes', 'docs', 'memories', 'instances', 'memory-diff', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
+  'db', 'themes', 'docs', 'memories', 'instances', 'memory-diff', 'recall-replay', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
 ]);
 // Global flags that consume the following token as their value.
 const GLOBAL_VALUE_FLAGS = new Set(['-p', '--port', '-d', '--data-dir', '-i', '--instance', '--passphrase']);
@@ -1168,6 +1169,12 @@ if (subName === 'db') {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
+} else if (subName === 'recall-replay') {
+  const { recallReplayCommand } = require('../lib/recall-replay-command');
+  recallReplayCommand(subArgs).catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
 } else if (subName === 'completion') {
   const { completionCommand } = require('../lib/completion-commands');
   completionCommand(subArgs).catch(err => {

package/lib/completion/bash.template

@@ -15,7 +15,7 @@ _quilltap_complete() {
   local global_opts="-d --data-dir -i --instance -p --port -o --open -v --version -h --help --update --passphrase"
 
   # Top-level subcommands
-  local top_cmds="db docs themes instances memories memory-diff logs migrations maintenance file-verify completion"
+  local top_cmds="db docs themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion"
 
   # Get the subcommand (first non-option word after quilltap)
   local subcommand=""
@@ -209,6 +209,10 @@ _quilltap_complete() {
       local md_flags="--instance --data-dir --passphrase --port --concurrency --out --help"
       COMPREPLY=($(compgen -W "$md_flags" -- "$cur"))
       ;;
+    recall-replay)
+      local rr_flags="--turn --char --limit --port --json --help"
+      COMPREPLY=($(compgen -W "$rr_flags" -- "$cur"))
+      ;;
     logs)
       local logs_flags="--stream --tail -f --follow --grep \
         --instance --data-dir --passphrase --help"

package/lib/completion/fish.template

@@ -15,7 +15,7 @@ function __quilltap_no_subcommand
   end
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs themes instances memories memory-diff logs migrations maintenance file-verify completion
+      case db docs themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
         return 1
     end
   end
@@ -27,7 +27,7 @@ function __quilltap_using_subcommand
   set -l cmd (commandline -opc)
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs themes instances memories memory-diff logs migrations maintenance file-verify completion
+      case db docs themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
         test "$cmd[$i]" = "$target"
         return $status
     end

package/lib/completion/zsh.template

@@ -26,6 +26,7 @@ _quilltap() {
     'instances:Register or inspect named Quilltap instances'
     'memories:Search, browse, and graph memories'
     'memory-diff:Dump existing memories and dry-run re-extraction'
+    'recall-replay:Replay a turn'\''s memory recall, old vs episodic ranking'
     'logs:Tail or print an instance log file'
     'migrations:Inspect migration status'
     'maintenance:Run retention/cleanup sweeps'
@@ -72,6 +73,9 @@ _quilltap_subcommand() {
     memory-diff)
       _quilltap_memory_diff
       ;;
+    recall-replay)
+      _arguments '--turn[interchange to replay]:turn:' '--char[character id]:char:' '--limit[rows per path]:limit:' '--port[server port]:port:' '--json[raw JSON output]' '--help[show help]'
+      ;;
     logs)
       _quilltap_logs
       ;;

package/lib/recall-replay-command.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * `quilltap recall-replay <chatId>` — replay a turn's memory recall against
+ * the running server and print the candidate table, old path (episodic
+ * signals inert) vs. new path (retrospective flip + time window + entity
+ * anchors + multi-probe) side by side.
+ *
+ * Thin wrapper over POST /api/v1/chats/<chatId>?action=recall-replay.
+ * Read-only; nothing is persisted server-side.
+ */
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+
+function printRecallReplayHelp() {
+  console.log(`
+Quilltap recall-replay Tool
+
+Usage: quilltap recall-replay <chatId> [options]
+
+Replays the per-turn memory recall for a chat turn against the running
+Quilltap server and prints the full candidate table twice — the pre-overhaul
+ranking and the episodic (retrospective/time-window/entity) ranking — so the
+recall constants can be tuned against real "the character forgot" turns.
+
+Options:
+      --turn <number>        1-based interchange to replay at (default: last)
+      --char <characterId>   Character whose memories are searched
+                             (default: first LLM-controlled participant)
+      --limit <number>       Candidate rows per path (default: 25, max: 100)
+      --port <number>        Server port for API calls (default: 3000)
+      --json                 Print the raw JSON result instead of tables
+  -h, --help                 Show this help
+
+Examples:
+  quilltap recall-replay <chatId>
+  quilltap recall-replay <chatId> --turn 42
+  quilltap recall-replay <chatId> --turn 42 --json > replay.json
+`);
+}
+
+function parseFlags(args) {
+  const flags = { turn: undefined, char: undefined, limit: undefined, port: 3000, json: false, help: false };
+  const positional = [];
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    switch (a) {
+      case '--turn': {
+        const n = parseInt(args[++i], 10);
+        if (isNaN(n) || n < 1) {
+          console.error('Error: --turn must be a positive integer');
+          process.exit(1);
+        }
+        flags.turn = n;
+        break;
+      }
+      case '--char':
+        flags.char = args[++i];
+        break;
+      case '--limit': {
+        const n = parseInt(args[++i], 10);
+        if (isNaN(n) || n < 1 || n > 100) {
+          console.error('Error: --limit must be between 1 and 100');
+          process.exit(1);
+        }
+        flags.limit = n;
+        break;
+      }
+      case '--port': {
+        const p = parseInt(args[++i], 10);
+        if (isNaN(p) || p < 1 || p > 65535) {
+          console.error('Error: --port must be between 1 and 65535');
+          process.exit(1);
+        }
+        flags.port = p;
+        break;
+      }
+      case '--json':
+        flags.json = true;
+        break;
+      case '-h':
+      case '--help':
+        flags.help = true;
+        break;
+      default:
+        if (a.startsWith('-')) {
+          console.error(`Unknown option: ${a}`);
+          process.exit(1);
+        }
+        positional.push(a);
+    }
+    i++;
+  }
+  return { flags, positional };
+}
+
+function fmt(n, digits = 3) {
+  if (n === null || n === undefined) return DIM + '—' + RESET;
+  return n.toFixed(digits);
+}
+
+function printPath(label, rows) {
+  console.log(`\n${BOLD}${label}${RESET} (${rows.length} candidates)`);
+  if (rows.length === 0) {
+    console.log(`  ${DIM}(none)${RESET}`);
+    return;
+  }
+  const header = ['sel', 'cosine', 'blend', '×mult', 'after', 'kind', 'occurredAt', 'fired', 'summary'];
+  console.log(
+    `  ${DIM}${header[0].padEnd(4)}${header[1].padEnd(8)}${header[2].padEnd(8)}${header[3].padEnd(7)}${header[4].padEnd(8)}${header[5].padEnd(9)}${header[6].padEnd(12)}${header[7].padEnd(24)}${header[8]}${RESET}`
+  );
+  for (const row of rows) {
+    const sel = row.selected ? `${GREEN}✓${RESET}  ` : '   ';
+    const occurred = row.occurredAt ? row.occurredAt.slice(0, 10) : '—';
+    const fired = (row.fired || []).join(' ') || '—';
+    const summary = (row.summary || '').slice(0, 60);
+    console.log(
+      `  ${sel} ${fmt(row.cosine).padEnd(8)}${fmt(row.blendedBefore).padEnd(8)}${fmt(row.multiplier, 2).padEnd(7)}${fmt(row.blendedAfter).padEnd(8)}${(row.kind || 'semantic').padEnd(9)}${occurred.padEnd(12)}${fired.padEnd(24).slice(0, 24)}${summary}`
+    );
+  }
+}
+
+async function recallReplayCommand(args) {
+  const { flags, positional } = parseFlags(args);
+
+  if (flags.help || positional.length === 0) {
+    printRecallReplayHelp();
+    process.exit(flags.help ? 0 : 1);
+  }
+  if (positional.length > 1) {
+    console.error('Error: only one chatId may be specified');
+    process.exit(1);
+  }
+  const chatId = positional[0];
+
+  const url = `http://localhost:${flags.port}/api/v1/chats/${encodeURIComponent(chatId)}?action=recall-replay`;
+  const body = {};
+  if (flags.turn !== undefined) body.turnIndex = flags.turn;
+  if (flags.char) body.characterId = flags.char;
+  if (flags.limit !== undefined) body.limit = flags.limit;
+
+  process.stderr.write(`${BOLD}Replaying recall${RESET} for chat ${DIM}${chatId}${RESET} via ${DIM}${url}${RESET}\n`);
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    console.error(`${RED}Could not reach Quilltap server at http://localhost:${flags.port}: ${err.message}${RESET}`);
+    console.error('Start the server (npm run dev) or pass --port to match a non-default port.');
+    process.exit(1);
+  }
+
+  let payload;
+  try {
+    payload = await res.json();
+  } catch {
+    console.error(`${RED}Server returned a non-JSON response (status ${res.status})${RESET}`);
+    process.exit(1);
+  }
+  if (!res.ok || payload?.success === false) {
+    console.error(`${RED}Replay failed (status ${res.status}): ${payload?.error || payload?.message || 'unknown error'}${RESET}`);
+    process.exit(1);
+  }
+
+  const result = payload.data ?? payload;
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`\n${BOLD}Chat${RESET}      ${result.chatId}`);
+  console.log(`${BOLD}Character${RESET} ${result.characterName} ${DIM}(${result.characterId})${RESET}`);
+  console.log(`${BOLD}Turn${RESET}      ${result.turnIndex} of ${result.totalTurns}  ${DIM}(clock ${result.clockIso})${RESET}`);
+  console.log(`${BOLD}Query${RESET}     ${result.query}`);
+  const s = result.signals;
+  if (s) {
+    const retro = s.retrospective ? `${GREEN}retrospective${RESET}` : `${DIM}not retrospective${RESET}`;
+    const range = s.timeRange ? `${s.timeRange.from.slice(0, 10)} → ${s.timeRange.to.slice(0, 10)}` : '—';
+    const entities = (s.entities || []).join(', ') || '—';
+    console.log(`${BOLD}Signals${RESET}   ${retro} · timeRange ${CYAN}${range}${RESET} · entities ${CYAN}${entities}${RESET}`);
+  } else {
+    console.log(`${BOLD}Signals${RESET}   ${YELLOW}distillation failed — new path ran inert${RESET}`);
+  }
+
+  printPath('OLD PATH (episodic signals inert)', result.oldPath || []);
+  printPath('NEW PATH (retrospective/window/entities live)', result.newPath || []);
+  console.log('');
+}
+
+module.exports = { recallReplayCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.8.0-dev",
+  "version": "4.8.0-dev.103",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",
@@ -40,7 +40,7 @@
     "better-sqlite3-multiple-ciphers": "^12.11.1",
     "node-pty": "^1.1.0",
     "sharp": "^0.34.5",
-    "tar": "^7.5.16",
+    "tar": "^7.5.20",
     "yauzl": "^3.4.0"
   },
   "engines": {