quilltap 4.8.0-dev.92 → 4.8.0-dev.97

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.

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.92",
+  "version": "4.8.0-dev.97",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",