quilltap 4.10.0-dev.99 → 4.10.0

package/lib/__tests__/server-port-resolution.test.js

@@ -0,0 +1,122 @@
+/**
+ * Universal-flag parsing and server-port resolution for the HTTP diagnostic
+ * tools (anchor-probe, recall-replay, memory-diff).
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { resolveServerPort } = require('../lock-helpers');
+const tools = {
+  'anchor-probe': require('../anchor-probe-command').parseFlags,
+  'recall-replay': require('../recall-replay-command').parseFlags,
+  'memory-diff': require('../memory-diff-command').parseFlags,
+};
+
+describe.each(Object.keys(tools))('%s flag parsing', (name) => {
+  const parseFlags = tools[name];
+
+  it.each([
+    [['--instance', 'V4test', 'ID']],
+    [['ID', '--instance', 'V4test']],
+    [['-i', 'V4test', 'ID']],
+    [['ID', '-i', 'V4test']],
+  ])('accepts the instance flag around the positional id (%j)', (args) => {
+    const { flags, positional } = parseFlags(args);
+    expect(flags.instance).toBe('V4test');
+    expect(positional).toEqual(['ID']);
+  });
+
+  it.each([
+    [['--data-dir', '/x/y', 'ID']],
+    [['ID', '-d', '/x/y']],
+  ])('accepts the data-dir flag (%j)', (args) => {
+    const { flags, positional } = parseFlags(args);
+    expect(flags.dataDir).toBe('/x/y');
+    expect(positional).toEqual(['ID']);
+  });
+
+  it('accepts --passphrase without treating its value as the id', () => {
+    const { positional } = parseFlags(['--passphrase', 'hunter2', 'ID']);
+    expect(positional).toEqual(['ID']);
+    expect(parseFlags(['ID', '--passphrase', 'hunter2']).positional).toEqual(['ID']);
+  });
+
+  it('leaves the port undefined unless --port is given', () => {
+    expect(parseFlags(['ID']).flags.port).toBeUndefined();
+    expect(parseFlags(['ID', '--port', '3005']).flags.port).toBe(3005);
+  });
+});
+
+describe('resolveServerPort', () => {
+  let root;
+  let lockPath;
+
+  function writeLock(overrides = {}) {
+    const now = new Date().toISOString();
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: process.pid,
+      hostname: os.hostname(),
+      startedAt: now,
+      lastHeartbeat: now,
+      environment: 'local',
+      processTitle: 'node',
+      processArgv0: process.argv[0],
+      history: [],
+      ...overrides,
+    }));
+  }
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'qtap-port-test-'));
+    fs.mkdirSync(path.join(root, 'data'));
+    lockPath = path.join(root, 'data', 'quilltap.lock');
+  });
+
+  afterEach(() => fs.rmSync(root, { recursive: true, force: true }));
+
+  it('defaults to 3000 with no flags at all', () => {
+    expect(resolveServerPort({})).toMatchObject({ port: 3000, source: 'default', note: null });
+  });
+
+  it('lets an explicit --port win over a live lock', () => {
+    writeLock({ port: 3005 });
+    expect(resolveServerPort({ port: 4000, dataDir: root })).toMatchObject({ port: 4000, source: 'flag' });
+  });
+
+  it('uses the port from a live lock and says so', () => {
+    writeLock({ port: 3005 });
+    const r = resolveServerPort({ dataDir: root });
+    expect(r).toMatchObject({ port: 3005, source: 'lock' });
+    expect(r.note).toContain('3005');
+  });
+
+  it('falls back to 3000 when the live lock records no port', () => {
+    writeLock();
+    const r = resolveServerPort({ dataDir: root });
+    expect(r).toMatchObject({ port: 3000, source: 'default', note: null });
+    expect(r.hint).toContain('records no port');
+  });
+
+  it('ignores the port of a stale lock', () => {
+    writeLock({ pid: 2 ** 22 + 12345, port: 3005 });
+    const r = resolveServerPort({ dataDir: root });
+    expect(r.port).toBe(3000);
+    expect(r.hint).toContain('stale');
+  });
+
+  it('falls back to 3000 when there is no lock', () => {
+    const r = resolveServerPort({ dataDir: root });
+    expect(r.port).toBe(3000);
+    expect(r.hint).toContain('no instance lock');
+  });
+
+  it('rejects --instance together with --data-dir', () => {
+    expect(() => resolveServerPort({ instance: 'x', dataDir: root })).toThrow(/not both/);
+  });
+});

package/lib/anchor-probe-command.js

@@ -0,0 +1,222 @@
+'use strict';
+
+const { resolveServerPort } = require('./lock-helpers');
+
+/**
+ * `quilltap anchor-probe <characterId>` — measure whether the episodic anchor
+ * line embedded with each memory suppresses reinforcement at admission.
+ *
+ * Thin wrapper over POST /api/v1/memories?action=anchor-gate-probe.
+ * Read-only; nothing is persisted server-side, but it costs embedding calls.
+ */
+
+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 printAnchorProbeHelp() {
+  console.log(`
+Quilltap anchor-probe Tool
+
+Usage: quilltap anchor-probe <characterId> [options]
+
+Measures whether the episodic anchor line embedded with each memory suppresses
+reinforcement at admission. Re-embeds the character's most recent memories with
+and without the anchor line, compares each against older rows, asks admission's
+own decider what it would do each way, and reports how many rows would fold
+into an older one (reinforce or better) and how many would be absorbed as
+near-duplicates.
+
+Read-only, but it costs embedding calls (roughly up to 7 per sampled row).
+
+Options:
+  -d, --data-dir <path>      Instance root; used to find the server's port
+  -i, --instance <name>      Registered instance whose server to call (see 'quilltap instances')
+      --passphrase <pass>    Accepted and ignored (this tool never opens the database)
+      --limit <number>       Recent memories to sample (default: 50, max: 200)
+      --port <number>        Server port for API calls. Default: the port recorded in the
+                             --instance/--data-dir server's lock file, else 3000
+      --json                 Print the raw JSON result instead of tables
+  -h, --help                 Show this help
+
+Examples:
+  quilltap anchor-probe <characterId>
+  quilltap anchor-probe <characterId> --limit 20
+  quilltap anchor-probe <characterId> --json > probe.json
+`);
+}
+
+function parseFlags(args) {
+  const flags = { limit: undefined, port: undefined, dataDir: '', instance: '', json: false, help: false };
+  const positional = [];
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    switch (a) {
+      case '--limit': {
+        const n = parseInt(args[++i], 10);
+        if (isNaN(n) || n < 1 || n > 200) {
+          console.error('Error: --limit must be between 1 and 200');
+          process.exit(1);
+        }
+        flags.limit = n;
+        break;
+      }
+      case '-d':
+      case '--data-dir':
+        flags.dataDir = args[++i];
+        break;
+      case '-i':
+      case '--instance':
+        flags.instance = args[++i];
+        break;
+      case '--passphrase':
+        // Accepted so universal flags never error; these tools talk to the
+        // running server and never open the database themselves.
+        i++;
+        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);
+}
+
+// Pad a possibly colour-wrapped string to a visible width.
+function pad(s, width) {
+  const visible = String(s).replace(/\x1b\[[0-9;]*m/g, '').length;
+  return String(s) + ' '.repeat(Math.max(0, width - visible));
+}
+
+function printRows(rows, thresholds) {
+  console.log(`\n${BOLD}Rows${RESET} (${rows.length})`);
+  if (rows.length === 0) {
+    console.log(`  ${DIM}(none)${RESET}`);
+    return;
+  }
+  console.log(
+    `  ${DIM}${'anchored'.padEnd(10)}${'free'.padEnd(10)}${'delta'.padEnd(9)}${'anchor'.padEnd(8)}summary${RESET}`
+  );
+  const folds = (kind) => kind === 'reinforce' || kind === 'absorb' || kind === 'promote-and-reinforce';
+  for (const row of rows) {
+    const a = row.anchoredBest;
+    const f = row.anchorFreeBest;
+    const delta = typeof a === 'number' && typeof f === 'number' ? f - a : null;
+    const onlyFree = folds(row.anchorFreeAction) && !folds(row.anchoredAction);
+    const deltaStr = delta === null ? DIM + '—' + RESET : (delta >= 0 ? '+' : '') + delta.toFixed(3);
+    const anchorStr = row.hasAnchorLine ? 'yes' : `${DIM}no${RESET}`;
+    const summary = (row.summary || '').replace(/\s+/g, ' ').slice(0, 60);
+    const line = `${pad(fmt(a), 10)}${pad(fmt(f), 10)}${pad(deltaStr, 9)}${pad(anchorStr, 8)}${summary}`;
+    console.log(onlyFree ? `${YELLOW}▸ ${RESET}${line}` : `  ${line}`);
+  }
+  console.log(`\n  ${YELLOW}▸${RESET} ${DIM}= would fold into an older row only without the anchor line (reinforce ≥ ${fmt(thresholds?.reinforce, 2)})${RESET}`);
+}
+
+async function anchorProbeCommand(args) {
+  const { flags, positional } = parseFlags(args);
+
+  if (flags.help || positional.length === 0) {
+    printAnchorProbeHelp();
+    process.exit(flags.help ? 0 : 1);
+  }
+  if (positional.length > 1) {
+    console.error('Error: only one characterId may be specified');
+    process.exit(1);
+  }
+  const characterId = positional[0];
+
+  let target;
+  try {
+    target = resolveServerPort({ port: flags.port, instance: flags.instance, dataDir: flags.dataDir });
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+  const port = target.port;
+  if (target.note) process.stderr.write(`${DIM}${target.note}${RESET}\n`);
+
+  const url = `http://localhost:${port}/api/v1/memories?action=anchor-gate-probe`;
+  const body = { characterId };
+  if (flags.limit !== undefined) body.limit = flags.limit;
+
+  process.stderr.write(`${BOLD}Probing anchor gate${RESET} for character ${DIM}${characterId}${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:${port}: ${err.message}${RESET}`);
+    console.error(target.hint);
+    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}Probe 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;
+  }
+
+  const t = result.thresholds || {};
+  const anchored = result.anchored || {};
+  const free = result.anchorFree || {};
+  console.log(`\n${BOLD}Character${RESET}  ${result.characterId}`);
+  console.log(`${BOLD}Sampled${RESET}    ${result.sampled} rows, ${result.anchoredRows} with an anchor line`);
+  console.log(`${BOLD}Embeddings${RESET} ${result.embeddingsGenerated} generated`);
+  if (result.note) console.log(`${YELLOW}${result.note}${RESET}`);
+  console.log(`\n${DIM}${''.padEnd(22)}${'anchored'.padEnd(11)}anchor-free${RESET}`);
+  console.log(`${BOLD}${'would fold'.padEnd(22)}${RESET}${String(anchored.reinforce).padEnd(11)}${CYAN}${free.reinforce}${RESET}`);
+  console.log(`${BOLD}${'near-dup absorbed'.padEnd(22)}${RESET}${String(anchored.nearDuplicate).padEnd(11)}${CYAN}${free.nearDuplicate}${RESET}`);
+  const only = result.crossedOnlyWithoutAnchors;
+  console.log(`${BOLD}Fold only without anchors${RESET}  ${only > 0 ? YELLOW : GREEN}${only}${RESET}`);
+
+  printRows(result.rows || [], t);
+  console.log('');
+}
+
+module.exports = { anchorProbeCommand, printAnchorProbeHelp, parseFlags };

package/lib/completion/bash.template

@@ -61,7 +61,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 sync themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion"
+  local top_cmds="db docs sync themes instances memories memory-diff recall-replay anchor-probe logs migrations maintenance file-verify completion"
 
   # Flags that swallow the word after them. A flat list will not do: -o is the
   # valueless global --open but themes' valued --output, and `memories`
@@ -69,14 +69,15 @@ _quilltap_complete() {
   # makes a flag's value look like the subcommand's verb, which is how
   # `quilltap docs --limit 5 <TAB>` used to lose the verb list.
   local vf_global=" -d --data-dir -i --instance -p --port --passphrase "
-  local vf_db=" --limit --grep --character --project --about --source --chat --message --field --tail --last --from --type --out --id --count "
+  local vf_db=" --limit --grep --character --project --about --source --tier --chat --message --field --tail --last --from --type --out --id --count "
   local vf_docs=" --mount --folder --type --ext --limit --max --context --top --threshold --sort --depth --max-nodes --format "
   local vf_sync=" --direction --prefer "
   local vf_themes=" -o --output -k --key -n --name "
-  local vf_memories=" -d --data-dir --instance --passphrase --port --character --about --source --chat --project --since --until --min-importance --min-reinforced --sort --limit --in --max --context --depth --max-nodes --top --threshold "
+  local vf_memories=" -d --data-dir --instance --passphrase -p --port --phases --cap --character --about --source --tier --chat --project --since --until --min-importance --min-reinforced --sort --limit --in --max --context --depth --max-nodes --top --threshold "
   local vf_logs=" --stream --tail --grep "
   local vf_memory_diff=" --concurrency --out "
-  local vf_recall_replay=" --turn --char --limit --port "
+  local vf_recall_replay=" --turn --char --limit --memory-budget --tuning --tuning-file --signals-from --port "
+  local vf_anchor_probe=" --limit --port "
   local vf_file_verify=" --stall-ms "
 
   # Get the subcommand (first non-option word after quilltap)
@@ -100,6 +101,7 @@ _quilltap_complete() {
       logs)          valued="$vf_global$vf_logs" ;;
       memory-diff)   valued="$vf_global$vf_memory_diff" ;;
       recall-replay) valued="$vf_global$vf_recall_replay" ;;
+      anchor-probe)  valued="$vf_global$vf_anchor_probe" ;;
       file-verify)   valued="$vf_global$vf_file_verify" ;;
     esac
 
@@ -176,7 +178,15 @@ _quilltap_complete() {
       return
       ;;
     --source)
-      COMPREPLY=($(compgen -W "AUTO MANUAL" -- "$cur"))
+      COMPREPLY=($(compgen -W "AUTO MANUAL CONSOLIDATED" -- "$cur"))
+      return
+      ;;
+    --tier)
+      COMPREPLY=($(compgen -W "hot cold" -- "$cur"))
+      return
+      ;;
+    --phases)
+      COMPREPLY=($(compgen -W "fold-near-duplicates consolidate demote retire mirror" -- "$cur"))
       return
       ;;
     --sort)
@@ -214,7 +224,7 @@ _quilltap_complete() {
     db)
       local db_verbs="schema find chats messages logs message log memories characters optimize backup integrity"
       local db_flags="--instance --data-dir --passphrase --json --limit --grep \
-        --character --project --about --source --chat --message --rendered --field \
+        --character --project --about --source --tier --chat --message --rendered --field \
         --tail --last --full --from --type --out --id --diverged --blocked --help \
         --tables --count --repl --write --llm-logs --mount-points \
         --lock-status --lock-clean --lock-override"
@@ -311,13 +321,13 @@ _quilltap_complete() {
       fi
       ;;
     memories)
-      local mem_verbs="ls find grep show tree status validate"
-      local mem_flags="--character --about --source --chat --project --since --until \
+      local mem_verbs="ls find grep show tree status validate maintain"
+      local mem_flags="--character --about --source --tier --chat --project --since --until \
         --min-importance --min-reinforced --has-embedding --no-embedding \
         --sort -r --reverse --limit --full-titles --in --no-related --list \
         --ignore-case -i --paths-only -l --max --context --depth --max-nodes \
-        --semantic --top --threshold \
-        --instance --data-dir --passphrase --port --json --help"
+        --semantic --top --threshold --dry-run --phases --cap --repair --write \
+        --instance --data-dir --passphrase -p --port --json --help"
       if [[ -z "$subverb" ]]; then
         if [[ "$cur" == -* ]]; then
           COMPREPLY=($(compgen -W "$mem_flags" -- "$cur"))
@@ -333,9 +343,13 @@ _quilltap_complete() {
       COMPREPLY=($(compgen -W "$md_flags" -- "$cur"))
       ;;
     recall-replay)
-      local rr_flags="--turn --char --limit --port --json --help"
+      local rr_flags="--instance --data-dir --passphrase --turn --char --limit --memory-budget --tuning --tuning-file --signals-from --as-of --port --json --help"
       COMPREPLY=($(compgen -W "$rr_flags" -- "$cur"))
       ;;
+    anchor-probe)
+      local ap_flags="--instance --data-dir --passphrase --limit --port --json --help"
+      COMPREPLY=($(compgen -W "$ap_flags" -- "$cur"))
+      ;;
     logs)
       local logs_flags="--stream --tail -f --follow --grep \
         --instance --data-dir --passphrase --help"

package/lib/completion/fish.template

@@ -19,7 +19,7 @@ function __quilltap_no_subcommand
   end
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs sync themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
+      case db docs sync themes instances memories memory-diff recall-replay anchor-probe logs migrations maintenance file-verify completion
         return 1
     end
   end
@@ -31,7 +31,7 @@ function __quilltap_using_subcommand
   set -l cmd (commandline -opc)
   for i in (seq 2 (count $cmd))
     switch $cmd[$i]
-      case db docs sync themes instances memories memory-diff recall-replay logs migrations maintenance file-verify completion
+      case db docs sync themes instances memories memory-diff recall-replay anchor-probe logs migrations maintenance file-verify completion
         test "$cmd[$i]" = "$target"
         return $status
     end
@@ -61,6 +61,7 @@ complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'instances' -d 'Registe
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'memories' -d 'Search and browse memories'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'memory-diff' -d 'Memory extraction dry-run'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'recall-replay' -d 'Replay memory recall for a turn'
+complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'anchor-probe' -d 'Probe anchor-line effect on admission'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'logs' -d 'Tail or print log files'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'migrations' -d 'Inspect migration status'
 complete -c quilltap -n '__quilltap_no_subcommand' -f -a 'maintenance' -d 'Run retention/cleanup sweeps'
@@ -112,7 +113,8 @@ complete -c quilltap -n '__quilltap_using_subcommand db' -l 'grep' -d 'Substring
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'character' -d 'Character name or id' -x
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'project' -d 'Project name or id' -x
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'about' -d 'Subject character' -x
-complete -c quilltap -n '__quilltap_using_subcommand db' -l 'source' -d 'Memory source' -x -a 'AUTO MANUAL'
+complete -c quilltap -n '__quilltap_using_subcommand db' -l 'source' -d 'Memory source' -x -a 'AUTO MANUAL CONSOLIDATED'
+complete -c quilltap -n '__quilltap_using_subcommand db' -l 'tier' -d 'Memory tier' -x -a 'hot cold'
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'chat' -d 'Chat name or id' -x
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'message' -d 'Message id' -x
 complete -c quilltap -n '__quilltap_using_subcommand db' -l 'rendered' -d 'Render rich content'
@@ -271,11 +273,18 @@ complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'show' -d '
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'tree' -d 'Graph walk'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'status' -d 'Memory status'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'validate' -d 'Health check'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'maintain' -d 'Run memory maintenance'
 
 # memories flags
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'character' -d 'Character name or id' -x
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'about' -d 'Subject of memory' -x
-complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'source' -d 'Memory source' -x -a 'AUTO MANUAL'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'source' -d 'Memory source' -x -a 'AUTO MANUAL CONSOLIDATED'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'tier' -d 'Memory tier' -x -a 'hot cold'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'dry-run' -d 'Maintain: rehearse and print the report, write nothing'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'phases' -d 'Maintain: comma-separated phases' -x -a 'fold-near-duplicates consolidate demote retire mirror'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'cap' -d 'Maintain: hot-row cap for demotion' -x
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'repair' -d 'Validate: repair the graph on the running server'
+complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'write' -d 'Validate --repair: apply the repair'
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'chat' -d 'Chat id or title' -x
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'project' -d 'Project name or id' -x
 complete -c quilltap -n '__quilltap_using_subcommand memories' -l 'since' -d 'Since timestamp' -x
@@ -311,8 +320,18 @@ complete -c quilltap -n '__quilltap_using_subcommand memory-diff' -l 'out' -d 'O
 complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'turn' -d 'Interchange to replay (1-based)' -x
 complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'char' -d 'Character whose memories are searched' -x
 complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'limit' -d 'Candidate rows per path' -x
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'memory-budget' -d 'Memory token budget' -x
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'tuning' -d 'New-path tuning JSON' -x
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'tuning-file' -d 'New-path tuning JSON file' -r -F
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'signals-from' -d 'Reuse signals from a saved replay' -r -F
+complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'as-of' -d 'Search the corpus as it stood at the turn'
 complete -c quilltap -n '__quilltap_using_subcommand recall-replay' -l 'port' -d 'Server port' -x
 
+# ---------- anchor-probe flags ----------
+complete -c quilltap -n '__quilltap_using_subcommand anchor-probe' -l 'limit' -d 'Recent memories to sample' -x
+complete -c quilltap -n '__quilltap_using_subcommand anchor-probe' -l 'port' -d 'Server port' -x
+complete -c quilltap -n '__quilltap_using_subcommand anchor-probe' -l 'json' -d 'Raw JSON output'
+
 # ---------- file-verify flags ----------
 complete -c quilltap -n '__quilltap_using_subcommand file-verify' -l 'all' -d 'Read every top-level file, not just dataless ones'
 complete -c quilltap -n '__quilltap_using_subcommand file-verify' -l 'stall-ms' -d 'Per-chunk stall threshold (ms)' -x

package/lib/completion/zsh.template

@@ -43,6 +43,7 @@ _quilltap() {
     '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'
+    'anchor-probe:Probe whether episodic anchor lines suppress reinforcement at admission'
     'logs:Tail or print an instance log file'
     'migrations:Inspect migration status'
     'maintenance:Run retention/cleanup sweeps'
@@ -99,6 +100,9 @@ _quilltap_subcommand() {
     recall-replay)
       _quilltap_recall_replay
       ;;
+    anchor-probe)
+      _quilltap_anchor_probe
+      ;;
     logs)
       _quilltap_logs
       ;;
@@ -147,7 +151,8 @@ _quilltap_db() {
     '--character[Character name or id]:character:'
     '--project[Project name or id]:project:'
     '--about[Subject character]:character:'
-    '--source[Memory source]:source:(AUTO MANUAL)'
+    '--source[Memory source]:source:(AUTO MANUAL CONSOLIDATED)'
+    '--tier[Memory tier]:tier:(hot cold)'
     '--chat[Chat name or id]:chat:'
     '--message[Message id]:id:'
     '--rendered[Render rich content]'
@@ -534,17 +539,24 @@ _quilltap_memories() {
     'tree:ASCII walk of graph'
     'status:Per-character rollup'
     'validate:Health check'
+    'maintain:Run memory maintenance (fold, consolidate, demote, retire, mirror)'
   )
 
   mem_opts=(
     '--instance[Registered instance name]:instance:_quilltap_instance_names'
     '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories'
     '--passphrase[Database passphrase]:passphrase:'
-    '--port[Server port]:port:'
+    '(-p --port)'{-p,--port}'[Server port]:port:'
     '--json[JSON output]'
     '--character[Character name or id]:character:'
     '--about[Subject of memory]:character:'
-    '--source[Memory source]:source:(AUTO MANUAL)'
+    '--source[Memory source]:source:(AUTO MANUAL CONSOLIDATED)'
+    '--tier[Memory tier]:tier:(hot cold)'
+    '--dry-run[Maintain: rehearse and print the report, write nothing]'
+    '--phases[Maintain: comma-separated phases]:phases:_sequence compadd - fold-near-duplicates consolidate demote retire mirror'
+    '--cap[Maintain: hot-row cap for demotion]:n:'
+    '--repair[Validate: repair the graph on the running server (dry run without --write)]'
+    '--write[Validate --repair: apply the repair]'
     '--chat[Chat id or title]:chat:'
     '--project[Project name or id]:project:'
     '--since[Since timestamp]:date:'
@@ -604,6 +616,23 @@ _quilltap_recall_replay() {
     '--turn[interchange to replay]:turn:' \
     '--char[character id]:char:' \
     '--limit[rows per path]:limit:' \
+    '--memory-budget[memory token budget]:tokens:' \
+    '--tuning[new-path tuning JSON]:json:' \
+    '--tuning-file[new-path tuning JSON file]:file:_files' \
+    '--signals-from[reuse signals from a saved replay]:file:_files' \
+    '--as-of[search the corpus as it stood at the turn]' \
+    '--port[server port]:port:' \
+    '--json[raw JSON output]' \
+    '*: :'
+}
+
+_quilltap_anchor_probe() {
+  _arguments \
+    '(-h --help)'{-h,--help}'[Show help]' \
+    '(-i --instance)'{-i,--instance}'[Use instance]:instance:_quilltap_instance_names' \
+    '(-d --data-dir)'{-d,--data-dir}'[Data directory]:directory:_directories' \
+    '--passphrase[Database passphrase]:passphrase:' \
+    '--limit[recent memories to sample]:limit:' \
     '--port[server port]:port:' \
     '--json[raw JSON output]' \
     '*: :'

package/lib/db-commands.js

@@ -658,10 +658,20 @@ function cmdMemories(args, ctx) {
   const { flags } = parseSubArgs(args);
   const json = asBool(flags.json);
   const limit = asInt(flags.limit, 50);
-  if (!flags.character) throw new Error('Usage: quilltap db memories --character <id|name> [--about <id|name>] [--source AUTO|MANUAL] [--limit N]');
+  if (!flags.character) throw new Error('Usage: quilltap db memories --character <id|name> [--about <id|name>] [--source AUTO|MANUAL|CONSOLIDATED] [--tier hot|cold] [--limit N]');
+  const tier = flags.tier === undefined ? null : String(flags.tier).toLowerCase();
+  if (tier !== null && tier !== 'hot' && tier !== 'cold') {
+    throw new Error(`--tier must be hot or cold (got '${flags.tier === true ? '' : flags.tier}')`);
+  }
 
   const db = ctx.openMain();
   try {
+    // Instances that predate the memory tiers have no `tier` column: every
+    // row reads as hot there.
+    let hasTier = false;
+    try {
+      hasTier = db.prepare("PRAGMA table_info('memories')").all().some((c) => c.name === 'tier');
+    } catch { /* treat as absent */ }
     const holder = resolveCharacter(db, String(flags.character), ctx.openMounts);
     const conditions = ['characterId = ?'];
     const params = [holder.id];
@@ -674,8 +684,13 @@ function cmdMemories(args, ctx) {
       conditions.push('source = ?');
       params.push(String(flags.source).toUpperCase());
     }
+    if (tier) {
+      if (hasTier) conditions.push(tier === 'hot' ? "COALESCE(tier, 'hot') = 'hot'" : "tier = 'cold'");
+      else if (tier === 'cold') conditions.push('0');
+    }
+    const tierSelect = hasTier ? "COALESCE(tier, 'hot') AS tier" : "'hot' AS tier";
     const rows = db.prepare(`
-      SELECT id, createdAt, source, importance, reinforcementCount,
+      SELECT id, createdAt, source, ${tierSelect}, importance, reinforcementCount,
              aboutCharacterId, chatId, summary
       FROM memories WHERE ${conditions.join(' AND ')}
       ORDER BY createdAt DESC LIMIT ?
@@ -685,11 +700,12 @@ function cmdMemories(args, ctx) {
 
     if (json) return printJson({ holder, total: totalRow.n, returned: rows.length, memories: rows });
 
-    console.log(`Memories held by ${holder.name} (${holder.id}) — ${rows.length} of ${totalRow.n}`);
+    console.log(`Memories held by ${holder.name} (${holder.id})${tier ? ` [${tier}]` : ''} — ${rows.length} of ${totalRow.n}`);
     printTable(rows.map(r => ({
       createdAt: r.createdAt,
       id: r.id,
       src: r.source,
+      tier: r.tier,
       imp: r.importance,
       rein: r.reinforcementCount,
       about: r.aboutCharacterId === holder.id ? 'self' : (r.aboutCharacterId || ''),