quilltap 4.10.0-dev.117 → 4.10.0-dev.139

package/README.md

@@ -342,9 +342,13 @@ quilltap memories tree <id|prefix> [--depth N] [--max-nodes N]         # ASCII w
 quilltap memories status [--character <name|id>]                       # Per-holder rollup + dangling-edge check
 quilltap memories validate [--character <name|id>] [--list]            # Dangling-edge health check; exit 1 if any remain
 quilltap memories grep --semantic --character Ariadne "the argument"   # Embedding search (server required, one holder)
+quilltap memories consolidate --character Ariadne --dry-run            # Rehearse consolidation, print proposed digests (server required)
+quilltap memories consolidate --character Ariadne [--max N]            # Queue a real consolidation job (server required)
 ```
 
-Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source`, `--chat` (with `none` for manual entries), `--project`, `--since`, `--until`, `--min-importance`, `--min-reinforced`, `--has-embedding` / `--no-embedding`. Sort flags (`--sort reinforced|importance|created|accessed|reinforcement-count|links`, plus `-r` to reverse) apply to `ls`, `find`, and `grep`. Names accept fuzzy substrings; ambiguous names print candidates and exit 2. `--json` is supported by every verb. `validate` is `status`'s terse twin — read-only, exit 1 if any dangling related-memory edge remains, `--list` to print the offending source IDs and their dangling targets. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, `--port 3000`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains undisturbed.
+Shared filter flags apply to `ls`, `find`, `grep`, and `status` where they make sense: `--character`, `--about` (with `self` / `none` shortcuts), `--source` (AUTO / MANUAL / CONSOLIDATED), `--tier` (hot / cold; both by default, cold rows are starred in the `src` column), `--chat` (with `none` for manual entries), `--project`, `--since`, `--until`, `--min-importance`, `--min-reinforced`, `--has-embedding` / `--no-embedding`. Sort flags (`--sort reinforced|importance|created|accessed|reinforcement-count|links`, plus `-r` to reverse) apply to `ls`, `find`, and `grep`. Names accept fuzzy substrings; ambiguous names print candidates and exit 2. `--json` is supported by every verb. `validate` is `status`'s terse twin — read-only, exit 1 if any dangling related-memory edge remains, `--list` to print the offending source IDs and their dangling targets. `grep --semantic` defaults to `--top 20`, `--threshold 0.5`, `--port 3000`, and scopes to **one holder at a time**: `--character all` is rejected. The legacy `quilltap db memories --character <name>` verb remains undisturbed.
+
+`consolidate` folds clusters of near-duplicate hot memories into denser digests and sends the originals to the cold tier. It resolves `--character <name|id>` locally (required; `all` is rejected) and then asks the running server (`--port`, default 3000) — the model and embedding provider live there, not in the CLI. With `--dry-run` the server rehearses a bounded run (default 10 clusters, at most 40; `--max N` sets the bound, `--threshold 0..1` overrides the cluster similarity for this run), writes nothing, and the CLI prints each cluster as its member notes followed by the proposed digest(s), standalones, contradictions, and run stats. Without `--dry-run` it queues a background `MEMORY_CONSOLIDATION` job (`--max N` overrides `maxClustersPerRun`; a real run uses the stored settings, so `--threshold` is honoured only by dry runs) and prints the job id; manual runs ignore the master `enabled` switch. `--json` prints the raw API payload.
 
 ## Memory Extraction Dry-Run
 
@@ -365,9 +369,33 @@ Needs a running server (`--port`, default 3000) to reach the extraction pipeline
 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
+quilltap recall-replay <chatId> --memory-budget 4000  # Budget-sized dynamic head
+quilltap recall-replay <chatId> --turn 42 --json > t42.json
+quilltap recall-replay <chatId> --turn 42 --signals-from t42.json --as-of \
+  --tuning '{"boostGateAbs":0.45,"boostGateMargin":0.15,"boostGateRamp":0.1}'
+```
+
+Flags: `--turn <n>` (default: last), `--char <characterId>` (default: first LLM-controlled participant), `--limit <n>` (default: the larger of 25 and the new path's head size + 10), `--memory-budget <tokens>` (positive integer; the new path's selected rows then follow the budget-sized dynamic head, which scales with the model's memory budget, while the old path keeps the historical fixed 5-entry head; each path header prints its head size), `--port <n>` (default 3000), `--json`.
+
+Tuning and comparable runs:
+
+- `--tuning '<json>'` / `--tuning-file <path>` — retuning constants for the new path only (the old path stays the reference): `boostGateAbs`, `boostGateMargin`, `boostGateRamp` (relevance gate on boosts), `boostCap`, `freshBypassesGate`, `windowBypassesGate`, `multipliers` (`{ "freshEvent24h": 1.3, … }`), `specificAnchors`, `anchorMinHits`, `anchorOrder`, `backgroundReserve`. Unknown keys are rejected. The header's `Tuning` line shows what is active.
+- `--signals-from <replay.json>` — reuse the signals saved in an earlier `--json` replay of the same chat and turn. The distillation is a cheap-LLM call and words the same turn differently each time, so runs you mean to compare should share it.
+- `--as-of` — search only memories created before the turn's opening message, with weights decayed to the turn's own clock: the corpus as it stood then. The header's `Harness` line shows the cutoff and how many later memories were left out.
+
+The server memoises the replay's embeddings by text until it restarts, so repeat runs embed identical vectors.
+
+## Anchor Probe
+
+`quilltap anchor-probe <characterId>` measures whether the episodic anchor line embedded with each memory suppresses Memory Gate reinforcement. It re-embeds the character's most recent memories with and without the anchor line, compares each against older rows, and reports how many would cross the reinforce (0.85) and near-duplicate (0.90) thresholds each way, plus a per-row table (rows that cross 0.85 only without anchors are highlighted). Read-only, but it costs embedding calls (roughly up to 7 per sampled row).
+
+```bash
+quilltap anchor-probe <characterId>             # Sample the 50 most recent memories
+quilltap anchor-probe <characterId> --limit 20  # Smaller, cheaper sample
+quilltap anchor-probe <characterId> --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`.
+Flags: `--limit <n>` (1–200, default 50), `--port <n>` (default 3000), `--json`.
 
 ## Maintenance & Cleanup
 

package/bin/quilltap.js

@@ -103,6 +103,7 @@ Subcommands:
   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
+  anchor-probe <characterId>    Probe whether episodic anchor lines suppress Memory Gate reinforcement
   completion <shell>            Generate a shell completion script (bash / zsh / fish)
 
 Options:
@@ -1170,7 +1171,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', 'sync', 'memories', 'instances', 'memory-diff', 'recall-replay', 'completion', 'logs', 'migrations', 'maintenance', 'file-verify',
+  'db', 'themes', 'docs', 'sync', 'memories', 'instances', 'memory-diff', 'recall-replay', 'anchor-probe', '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']);
@@ -1242,6 +1243,12 @@ if (subName === 'db') {
     console.error(`Error: ${err.message}`);
     process.exit(1);
   });
+} else if (subName === 'anchor-probe') {
+  const { anchorProbeCommand } = require('../lib/anchor-probe-command');
+  anchorProbeCommand(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/__tests__/completion-coverage.test.js

@@ -118,6 +118,7 @@ const HELP_SOURCES = {
   'file-verify': ['lib/file-verify-commands.js', 'printHelp'],
   'memory-diff': ['lib/memory-diff-command.js', 'printMemoryDiffHelp'],
   'recall-replay': ['lib/recall-replay-command.js', 'printRecallReplayHelp'],
+  'anchor-probe': ['lib/anchor-probe-command.js', 'printAnchorProbeHelp'],
   completion: ['lib/completion-commands.js', 'printCompletionHelp'],
 };
 

package/lib/__tests__/memories-consolidate-command.test.js

@@ -0,0 +1,66 @@
+/**
+ * `quilltap memories consolidate`: flag parsing, request body, report rendering.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const { parseFlags } = require('../memories-commands');
+const { buildConsolidateBody, renderReport } = require('../memories-consolidate-command');
+
+describe('memories consolidate flags', () => {
+  it('parses verb, character, dry-run, max, threshold and port', () => {
+    const { flags, positional } = parseFlags([
+      'consolidate', '--instance', 'Friday', '--character', 'Friday',
+      '--dry-run', '--max', '12', '--threshold', '0.8', '--port', '3005', '--json',
+    ]);
+    expect(positional).toEqual(['consolidate']);
+    expect(flags).toMatchObject({
+      instance: 'Friday', character: 'Friday', dryRun: true, max: 12, threshold: 0.8, port: 3005, json: true,
+    });
+  });
+
+  it('defaults to a real run with no overrides', () => {
+    const { flags } = parseFlags(['consolidate', '--character', 'X']);
+    expect(flags.dryRun).toBe(false);
+    expect(buildConsolidateBody('id', flags)).toEqual({ characterId: 'id', dryRun: false });
+  });
+
+  it('builds the request body from the flags', () => {
+    const { flags } = parseFlags(['consolidate', '--dry-run', '--max', '5', '--threshold', '0.65']);
+    expect(buildConsolidateBody('abc', flags)).toEqual({
+      characterId: 'abc', dryRun: true, maxClustersPerRun: 5, clusterThreshold: 0.65,
+    });
+  });
+});
+
+describe('renderReport', () => {
+  it('prints cluster, members and the proposed digest', () => {
+    let out = '';
+    renderReport({
+      characterName: 'Ariadne', dryRun: true,
+      clusters: [{
+        bucket: { kind: 'other', subjectName: 'Calvin', subjectCharacterId: 'c' },
+        clusterKind: 'semantic', status: 'planned',
+        memberIds: ['aaaaaaaa-1', 'bbbbbbbb-2'], memberContents: ['Calvin likes tea', 'Calvin drinks tea daily'],
+        keepStandalone: ['bbbbbbbb-2'], contradictions: [{ olderId: 'aaaaaaaa-1', newerId: 'bbbbbbbb-2', note: 'tea vs coffee' }],
+        digests: [{ id: 'd1', action: 'create', content: 'Calvin is a devoted tea drinker', importance: 0.6, memberIds: ['aaaaaaaa-1'] }],
+      }],
+      stats: { candidates: 40, clustersFound: 3, clustersAttempted: 1, clustersDeferred: 2, durationMs: 1500 },
+    }, (s) => { out += s; });
+    expect(out).toContain('Ariadne');
+    expect(out).toContain('about Calvin');
+    expect(out).toContain('Calvin likes tea');
+    expect(out).toContain('[kept standalone]');
+    expect(out).toContain('Calvin is a devoted tea drinker');
+    expect(out).toContain('tea vs coffee');
+    expect(out).toContain('candidates 40');
+  });
+
+  it('reports a skipped run', () => {
+    let out = '';
+    renderReport({ dryRun: true, skippedReason: 'no-llm', clusters: [], stats: {} }, (s) => { out += s; });
+    expect(out).toContain('Skipped: no-llm');
+  });
+});

package/lib/anchor-probe-command.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * `quilltap anchor-probe <characterId>` — measure whether the episodic anchor
+ * line embedded with each memory suppresses Memory Gate reinforcement.
+ *
+ * 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
+Memory Gate reinforcement. Re-embeds the character's most recent memories with
+and without the anchor line, compares each against older rows, and reports how
+many would cross the reinforce (0.85) and near-duplicate (0.90) thresholds
+each way.
+
+Read-only, but it costs embedding calls (roughly up to 7 per sampled row).
+
+Options:
+      --limit <number>       Recent memories to sample (default: 50, max: 200)
+      --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 anchor-probe <characterId>
+  quilltap anchor-probe <characterId> --limit 20
+  quilltap anchor-probe <characterId> --json > probe.json
+`);
+}
+
+function parseFlags(args) {
+  const flags = { limit: undefined, port: 3000, 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 '--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 reinforce = thresholds?.reinforce ?? 0.85;
+  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 = typeof f === 'number' && f >= reinforce && !(typeof a === 'number' && a >= reinforce);
+    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}= crosses ${reinforce} only without the anchor line${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];
+
+  const url = `http://localhost:${flags.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:${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}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`);
+  console.log(`\n${DIM}${''.padEnd(22)}${'anchored'.padEnd(11)}anchor-free${RESET}`);
+  console.log(`${BOLD}${('reinforce ≥ ' + fmt(t.reinforce, 2)).padEnd(22)}${RESET}${String(anchored.reinforce).padEnd(11)}${CYAN}${free.reinforce}${RESET}`);
+  console.log(`${BOLD}${('near-dup ≥ ' + fmt(t.nearDuplicate, 2)).padEnd(22)}${RESET}${String(anchored.nearDuplicate).padEnd(11)}${CYAN}${free.nearDuplicate}${RESET}`);
+  const only = result.crossedOnlyWithoutAnchors;
+  console.log(`${BOLD}Crossed only without anchors${RESET}  ${only > 0 ? YELLOW : GREEN}${only}${RESET}`);
+
+  printRows(result.rows || [], t);
+  console.log('');
+}
+
+module.exports = { anchorProbeCommand, printAnchorProbeHelp };

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`
@@ -73,10 +73,11 @@ _quilltap_complete() {
   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 --port --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,11 @@ _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
       ;;
     --sort)
@@ -311,12 +317,12 @@ _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 consolidate"
+      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 \
+        --semantic --top --threshold --dry-run \
         --instance --data-dir --passphrase --port --json --help"
       if [[ -z "$subverb" ]]; then
         if [[ "$cur" == -* ]]; then
@@ -333,9 +339,13 @@ _quilltap_complete() {
       COMPREPLY=($(compgen -W "$md_flags" -- "$cur"))
       ;;
     recall-replay)
-      local rr_flags="--turn --char --limit --port --json --help"
+      local rr_flags="--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="--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 Memory Gate'
 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,7 @@ 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 '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 +272,14 @@ 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 'consolidate' -d 'Fold memory clusters into digests'
 
 # 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 'Consolidate: rehearse and print the report, write nothing'
 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 +315,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 Memory Gate reinforcement'
     '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,7 @@ _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)'
     '--chat[Chat name or id]:chat:'
     '--message[Message id]:id:'
     '--rendered[Render rich content]'
@@ -534,6 +538,7 @@ _quilltap_memories() {
     'tree:ASCII walk of graph'
     'status:Per-character rollup'
     'validate:Health check'
+    'consolidate:Fold memory clusters into digests'
   )
 
   mem_opts=(
@@ -544,7 +549,9 @@ _quilltap_memories() {
     '--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[Consolidate: rehearse and print the report, write nothing]'
     '--chat[Chat id or title]:chat:'
     '--project[Project name or id]:project:'
     '--since[Since timestamp]:date:'
@@ -604,6 +611,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/memories-commands.js

@@ -12,6 +12,7 @@ const {
   resolveProject,
 } = require('./db-helpers');
 const { scanDanglingEdges } = require('./graph-integrity');
+const { cmdConsolidate } = require('./memories-consolidate-command');
 
 // ---------- colour & marker helpers ----------
 
@@ -93,6 +94,8 @@ function parseFlags(args) {
     top: 0,
     threshold: -1,
     port: 3000,
+    // consolidate
+    dryRun: false,
   };
   const positional = [];
   let i = 0;
@@ -108,6 +111,7 @@ function parseFlags(args) {
       case '--character': flags.character = args[++i]; break;
       case '--about': flags.about = args[++i]; break;
       case '--source': flags.source = args[++i]; break;
+      case '--tier': flags.tier = args[++i]; break;
       case '--chat': flags.chat = args[++i]; break;
       case '--project': flags.project = args[++i]; break;
       case '--since': flags.since = args[++i]; break;
@@ -136,6 +140,7 @@ function parseFlags(args) {
       case '--list': flags.list = true; break;
 
       case '--semantic': flags.semantic = true; break;
+      case '--dry-run': flags.dryRun = true; break;
       case '--top': flags.top = parseInt(args[++i], 10) || 0; break;
       case '--threshold': {
         const v = parseFloat(args[++i]);
@@ -220,13 +225,22 @@ function buildWhereClause(db, flags, openMounts = null) {
 
   if (flags.source) {
     const s = String(flags.source).toUpperCase();
-    if (s !== 'AUTO' && s !== 'MANUAL') {
-      throw new Error(`--source must be AUTO or MANUAL (got '${flags.source}')`);
+    if (s !== 'AUTO' && s !== 'MANUAL' && s !== 'CONSOLIDATED') {
+      throw new Error(`--source must be AUTO, MANUAL or CONSOLIDATED (got '${flags.source}')`);
     }
     clauses.push('m.source = ?');
     params.push(s);
   }
 
+  if (flags.tier) {
+    const t = String(flags.tier).toLowerCase();
+    if (t !== 'hot' && t !== 'cold') {
+      throw new Error(`--tier must be hot or cold (got '${flags.tier}')`);
+    }
+    // Legacy instances without the column read every row as hot.
+    clauses.push(t === 'hot' ? "COALESCE(m.tier, 'hot') = 'hot'" : "m.tier = 'cold'");
+  }
+
   if (flags.chat) {
     if (flags.chat === 'none') {
       clauses.push('m.chatId IS NULL');
@@ -313,7 +327,7 @@ function buildOrderBy(sortFlag, reverse) {
 // SELECT fragment that pulls every column the renderers need, including the
 // joined-in character / chat names. `m.*` is followed by aliases for the joins
 // so callers don't have to re-resolve UUIDs.
-const SELECT_BASE = `
+const SELECT_BASE_TEMPLATE = `
   SELECT
     m.id,
     m.characterId,
@@ -331,6 +345,7 @@ const SELECT_BASE = `
     m.lastReinforcedAt,
     m.lastAccessedAt,
     m.source,
+    __TIER_COLUMNS__
     m.relatedMemoryIds,
     m.createdAt,
     m.updatedAt,
@@ -346,6 +361,20 @@ const SELECT_BASE = `
   LEFT JOIN projects ON projects.id = m.projectId
 `;
 
+// Instances that haven't yet run add-memory-tiers-v1 lack the tier columns;
+// substitute constants so the CLI still reads them (rows read as hot).
+function selectBase(db) {
+  let hasTier = false;
+  try {
+    hasTier = db.prepare("PRAGMA table_info('memories')").all().some((c) => c.name === 'tier');
+  } catch { /* fall through: treat as legacy */ }
+  const cols = hasTier
+    ? 'm.tier, m.supersededById, m.consolidatedFrom, m.consolidatedAt,'
+    : "'hot' AS tier, NULL AS supersededById, '[]' AS consolidatedFrom, NULL AS consolidatedAt,";
+  return SELECT_BASE_TEMPLATE.replace('__TIER_COLUMNS__', cols);
+}
+
+
 // ---------- output helpers ----------
 
 function truncate(str, n) {
@@ -404,7 +433,7 @@ async function cmdLs(flags) {
     const { where, params, meta } = buildWhereClause(db, flags, openMounts);
     const { order, impField } = buildOrderBy(flags.sort, flags.reverse);
     const limit = flags.limit > 0 ? flags.limit : 50;
-    const sql = `${SELECT_BASE} ${where} ORDER BY ${order} LIMIT ?`;
+    const sql = `${selectBase(db)} ${where} ORDER BY ${order} LIMIT ?`;
     const rows = db.prepare(sql).all(...params, limit);
 
     if (flags.json) {
@@ -441,6 +470,10 @@ function rowToJson(row) {
     projectName: row.projectName,
     sourceMessageId: row.sourceMessageId,
     source: row.source,
+    tier: row.tier || 'hot',
+    supersededById: row.supersededById || null,
+    consolidatedFrom: (() => { try { return JSON.parse(row.consolidatedFrom || '[]'); } catch { return []; } })(),
+    consolidatedAt: row.consolidatedAt || null,
     importance: row.importance,
     reinforcedImportance: row.reinforcedImportance,
     reinforcementCount: row.reinforcementCount,
@@ -469,7 +502,7 @@ function renderTable(rows, { showHolder, impField, fullTitles }) {
     showHolder ? 'holder'.padEnd(14) : null,
     impHeader.padStart(4),
     'rein'.padStart(4),
-    'src'.padEnd(6),
+    'src'.padEnd(7),
     'about'.padEnd(20),
     'chat'.padEnd(fullTitles ? 24 : 32),
     'links'.padStart(5),
@@ -483,7 +516,7 @@ function renderTable(rows, { showHolder, impField, fullTitles }) {
     const impVal = impField === 'importance' ? row.importance : row.reinforcedImportance;
     const impStr = colorize(formatImportance(impVal), importanceColor(impVal));
     const rein = String(row.reinforcementCount ?? 0).padStart(4);
-    const src = (row.source || '').padEnd(6);
+    const src = ((row.source || '') + (row.tier === 'cold' ? '*' : '')).padEnd(7);
     const about = truncate(aboutLabel(row), 20).padEnd(20);
     const chat = truncate(chatLabel(row, fullTitles), fullTitles ? 24 : 32).padEnd(fullTitles ? 24 : 32);
     const links = String(linkCount(row)).padStart(5);
@@ -556,7 +589,7 @@ async function cmdFind(flags, positional) {
 
     const limit = flags.limit > 0 ? flags.limit : 50;
     const fullWhere = where ? `${where} AND ${matchSql}` : `WHERE ${matchSql}`;
-    const sql = `${SELECT_BASE} ${fullWhere} ORDER BY ${order} LIMIT ?`;
+    const sql = `${selectBase(db)} ${fullWhere} ORDER BY ${order} LIMIT ?`;
     const allParams = [...params, ...matchParams, ...orderParams, limit];
     const rows = db.prepare(sql).all(...allParams);
 
@@ -691,7 +724,7 @@ async function cmdGrep(flags, positional) {
     const fullWhere = where ? `${where} AND ${contentClause}` : `WHERE ${contentClause}`;
 
     const limit = flags.limit > 0 ? flags.limit : 50;
-    const sql = `${SELECT_BASE} ${fullWhere}
+    const sql = `${selectBase(db)} ${fullWhere}
                  ORDER BY m.reinforcedImportance DESC, m.createdAt DESC
                  LIMIT ?`;
     const rows = db.prepare(sql).all(...params, likeNeedle, limit);
@@ -805,7 +838,7 @@ async function cmdShow(flags, positional) {
   const { db } = await openDb(flags);
   try {
     const id = resolveMemoryId(db, idArg);
-    const row = db.prepare(`${SELECT_BASE} WHERE m.id = ?`).get(id);
+    const row = db.prepare(`${selectBase(db)} WHERE m.id = ?`).get(id);
     if (!row) {
       throw new Error(`Memory ${id} not found`);
     }
@@ -878,6 +911,7 @@ function renderShowText(row, graph, depth) {
   console.log(`  Holder:        ${holderName}    (${shortId(row.characterId)})`);
   console.log(`  About:         ${aboutName}${row.aboutCharacterId && row.aboutCharacterId !== row.characterId ? `    (${shortId(row.aboutCharacterId)})` : ''}`);
   console.log(`  Source:        ${row.source || '(?)'}`);
+  console.log(`  Tier:          ${row.tier || 'hot'}${row.supersededById ? `    (superseded by ${shortId(row.supersededById)})` : ''}`);
   const reinf = row.reinforcedImportance != null ? Number(row.reinforcedImportance).toFixed(2) : '?';
   const baseImp = row.importance != null ? Number(row.importance).toFixed(2) : '?';
   console.log(`  Importance:    ${reinf} (reinforced from ${baseImp}, count: ${row.reinforcementCount ?? 0})`);
@@ -1115,6 +1149,19 @@ function computeHolderStats(db, characterId) {
     WHERE characterId = ?
   `).get(characterId);
 
+  // Tier rollup — guarded so pre-tier instances still report.
+  let tiers = { hot: counts.total || 0, cold: 0, consolidated: 0 };
+  try {
+    const t = db.prepare(`
+      SELECT
+        SUM(CASE WHEN COALESCE(tier, 'hot') = 'hot' THEN 1 ELSE 0 END) AS hot,
+        SUM(CASE WHEN tier = 'cold' THEN 1 ELSE 0 END) AS cold,
+        SUM(CASE WHEN source = 'CONSOLIDATED' THEN 1 ELSE 0 END) AS consolidated
+      FROM memories WHERE characterId = ?
+    `).get(characterId);
+    tiers = { hot: t.hot || 0, cold: t.cold || 0, consolidated: t.consolidated || 0 };
+  } catch { /* tier column absent: everything is hot */ }
+
   const graph = scanDanglingEdges(db, { characterId });
 
   const topMemories = db.prepare(`
@@ -1131,6 +1178,7 @@ function computeHolderStats(db, characterId) {
       auto: counts.auto || 0,
       manual: counts.manual || 0,
     },
+    tiers,
     aboutDistribution: {
       selfReferential: counts.selfRef || 0,
       aboutOthers: counts.aboutOthers || 0,
@@ -1156,6 +1204,10 @@ function renderStatusBlock(holder, stats) {
   console.log(`  Total memories:        ${stats.counts.total}`);
   console.log(`    AUTO:                ${stats.counts.auto}`);
   console.log(`    MANUAL:              ${stats.counts.manual}`);
+  console.log(`  Tiers:`);
+  console.log(`    hot:                 ${stats.tiers.hot}`);
+  console.log(`    cold:                ${stats.tiers.cold}`);
+  console.log(`    digests (CONSOLIDATED): ${stats.tiers.consolidated}`);
   console.log(`  About-distribution:`);
   console.log(`    self-referential:    ${stats.aboutDistribution.selfReferential}`);
   console.log(`    about-others:        ${stats.aboutDistribution.aboutOthers}`);
@@ -1292,11 +1344,19 @@ Subcommands:
   validate [--character <name|id>] [--list]  Read-only memory-graph health
                                   [--json]   check. Exits 1 if any
                                              dangling edges remain.
+  consolidate --character <name|id> [--dry-run] [--max N] [--threshold 0..1]
+                                  [--port N] Fold clusters of hot memories
+                                             into digests (cold originals).
+                                             Asks the running server: a dry
+                                             run prints the proposed digests
+                                             and writes nothing; otherwise a
+                                             background job is queued.
 
 Shared filter flags:
   --character <name|id|all>   Holder. Default: all.
   --about <name|id|self|none> Subject (aboutCharacterId).
-  --source AUTO|MANUAL        Restrict by source.
+  --source AUTO|MANUAL|CONSOLIDATED  Restrict by source.
+  --tier hot|cold             Restrict by recall tier (default: both).
   --chat <id|title|none>      Source chat ('none' for manual memories).
   --project <id|name>         Project context.
   --since <date>              ISO date floor on createdAt.
@@ -1324,7 +1384,8 @@ Note: -i is reserved here for 'grep --ignore-case'. Use the long --instance
 form to target a registered instance.
 
 All memories verbs are read-only. They open the main encrypted database
-(quilltap.db) and never write to it.
+(quilltap.db) and never write to it; 'consolidate' leaves the writing to the
+running server.
 
 Examples:
   quilltap memories ls
@@ -1337,11 +1398,23 @@ Examples:
   quilltap memories status --character Ariadne
   quilltap memories validate
   quilltap memories validate --list
+  quilltap memories consolidate --instance Friday --character Friday --dry-run
+  quilltap memories consolidate --instance Friday --character Friday --max 100
 `);
 }
 
 // ---------- dispatcher ----------
 
+/** Resolve --character locally to a UUID, for verbs that call the running server. */
+async function resolveCharacterIdForServer(flags) {
+  const { db, openMounts } = await openDb(flags);
+  try {
+    return resolveCharacter(db, flags.character, openMounts).id;
+  } finally {
+    db.close();
+  }
+}
+
 async function memoriesCommand(args) {
   if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
     printMemoriesHelp();
@@ -1365,6 +1438,7 @@ async function memoriesCommand(args) {
     case 'tree': await cmdTree(flags, positional); break;
     case 'status': await cmdStatus(flags); break;
     case 'validate': await cmdValidate(flags); break;
+    case 'consolidate': await cmdConsolidate(flags, resolveCharacterIdForServer); break;
     default:
       console.error(`Unknown memories subcommand: ${verb}`);
       console.error("Run 'quilltap memories --help' for a list.");
@@ -1376,6 +1450,7 @@ module.exports = {
   memoriesCommand,
   // Exported for unit tests:
   parseFlags,
+  resolveCharacterIdForServer,
   buildWhereClause,
   buildOrderBy,
   traverseMemoryGraph,

package/lib/memories-consolidate-command.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * `quilltap memories consolidate` — fold clusters of hot memories into
+ * digests. The CLI's database access is read-only and cannot call a model, so
+ * this resolves the character locally and then asks the running server
+ * (POST /api/v1/memories?action=consolidate). A dry run is rehearsed in the
+ * server process and prints the proposed digests; a real run is queued as a
+ * background job.
+ */
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+
+function clip(text, n) {
+  const flat = String(text || '').replace(/\s+/g, ' ').trim();
+  return flat.length > n ? flat.slice(0, n - 1) + '…' : flat;
+}
+
+function bucketLabel(bucket) {
+  if (bucket.kind === 'self') return 'about self';
+  if (bucket.kind === 'other') return `about ${bucket.subjectName}`;
+  return 'about no one';
+}
+
+/** Pretty-print a ConsolidationReport as cluster → members → digests. */
+function renderReport(report, write = (s) => process.stdout.write(s)) {
+  const stats = report.stats || {};
+  write(`${BOLD}Consolidation ${report.dryRun ? 'dry run' : 'report'}${RESET}` +
+    `${report.characterName ? ` for ${report.characterName}` : ''}\n`);
+  if (report.skippedReason) {
+    write(`${YELLOW}Skipped: ${report.skippedReason}${RESET}\n`);
+    return;
+  }
+  const clusters = report.clusters || [];
+  clusters.forEach((cluster, idx) => {
+    write(`\n${BOLD}Cluster ${idx + 1}${RESET} ${DIM}(${bucketLabel(cluster.bucket)}, ${cluster.clusterKind}, ${cluster.status})${RESET}\n`);
+    if (cluster.error) write(`  ${YELLOW}${cluster.error}${RESET}\n`);
+    const standalone = new Set(cluster.keepStandalone || []);
+    (cluster.memberIds || []).forEach((id, i) => {
+      const tag = standalone.has(id) ? ` ${DIM}[kept standalone]${RESET}` : '';
+      write(`  ${DIM}-${RESET} ${DIM}${String(id).slice(0, 8)}${RESET} ${clip(cluster.memberContents[i], 160)}${tag}\n`);
+    });
+    for (const d of cluster.digests || []) {
+      write(`  ${GREEN}=>${RESET} ${CYAN}${d.action === 'update' ? 'update digest' : 'new digest'}${RESET} ` +
+        `${DIM}(imp ${Number(d.importance).toFixed(2)}, from ${(d.memberIds || []).length})${RESET}\n`);
+      write(`     ${clip(d.content, 400)}\n`);
+    }
+    for (const c of cluster.contradictions || []) {
+      write(`  ${YELLOW}contradiction${RESET}: ${clip(c.note, 200)} ${DIM}(${String(c.olderId).slice(0, 8)} -> ${String(c.newerId).slice(0, 8)})${RESET}\n`);
+    }
+  });
+  if (clusters.length === 0) write('\n(no clusters worth folding)\n');
+  write(`\n${DIM}candidates ${stats.candidates ?? 0}, clusters found ${stats.clustersFound ?? 0}, ` +
+    `attempted ${stats.clustersAttempted ?? 0}, deferred ${stats.clustersDeferred ?? 0}, ` +
+    `${((stats.durationMs ?? 0) / 1000).toFixed(1)}s${stats.budgetExhausted ? ', time budget exhausted' : ''}${RESET}\n`);
+}
+
+/** Build the request body for the consolidate action from parsed CLI flags. */
+function buildConsolidateBody(characterId, flags) {
+  const body = { characterId, dryRun: flags.dryRun === true };
+  if (flags.max > 0) body.maxClustersPerRun = flags.max;
+  if (flags.threshold >= 0) body.clusterThreshold = flags.threshold;
+  return body;
+}
+
+/**
+ * @param {object} flags parsed memories flags
+ * @param {(flags: object) => Promise<string>} resolveCharacterId resolves --character to a UUID
+ */
+async function cmdConsolidate(flags, resolveCharacterId) {
+  if (!flags.character || flags.character === 'all') {
+    console.error('Error: memories consolidate requires --character <name|id>.');
+    process.exit(1);
+  }
+  const characterId = await resolveCharacterId(flags);
+  if (!/^[0-9a-fA-F-]{36}$/.test(characterId)) {
+    console.error(`Error: could not resolve --character to a UUID (got "${characterId}").`);
+    process.exit(1);
+  }
+
+  const port = flags.port || 3000;
+  const url = `http://localhost:${port}/api/v1/memories?action=consolidate`;
+  const body = buildConsolidateBody(characterId, flags);
+
+  if (!flags.json) {
+    process.stderr.write(`${BOLD}${body.dryRun ? 'Rehearsing' : 'Queuing'} consolidation${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(`Could not reach Quilltap server at http://localhost:${port}: ${err.message}`);
+    console.error('Consolidation requires the running server (the model and embeddings live there).');
+    console.error('Start it with: npm run dev');
+    process.exit(1);
+  }
+
+  let payload = null;
+  try {
+    const text = await res.text();
+    payload = text ? JSON.parse(text) : null;
+  } catch { /* leave payload null */ }
+
+  if (!res.ok) {
+    console.error(`Error: ${(payload && payload.error) || `HTTP ${res.status}`}`);
+    process.exit(1);
+  }
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    return;
+  }
+
+  if (body.dryRun) {
+    renderReport(payload.report);
+  } else {
+    console.log(`Consolidation queued as job ${payload.jobId}. It runs in the background; watch logs/combined.log.`);
+  }
+}
+
+module.exports = { cmdConsolidate, renderReport, buildConsolidateBody };

package/lib/recall-replay-command.js

@@ -33,7 +33,30 @@ 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)
+      --limit <number>       Candidate rows per path (default: the larger of 25
+                             and the new path's head size + 10; max: 100)
+      --memory-budget <tokens>
+                             Memory token budget (positive integer). The new
+                             path's selected rows then follow the budget-sized
+                             dynamic head (the head scales with the model's
+                             memory budget); the old path keeps the historical
+                             fixed 5-entry head.
+      --tuning '<json>'      Retuning constants for the NEW path only, e.g.
+                             '{"boostGateAbs":0.45,"boostGateMargin":0.15,
+                             "boostGateRamp":0.1,"boostCap":1.6}'. Keys:
+                             boostGateAbs, boostGateMargin, boostGateRamp,
+                             boostCap, freshBypassesGate, windowBypassesGate,
+                             multipliers
+                             {RECALL_MULTIPLIERS key:
+                             value}, specificAnchors, anchorMinHits,
+                             anchorOrder, backgroundReserve.
+                             Unknown keys are rejected.
+      --tuning-file <path>   Read the --tuning JSON from a file
+      --signals-from <path>  Reuse the signals saved in a previous --json
+                             replay of the same chat and turn, instead of a
+                             fresh (non-deterministic) distillation
+      --as-of                Search only memories created before the turn's
+                             opening message (the corpus as it stood then)
       --port <number>        Server port for API calls (default: 3000)
       --json                 Print the raw JSON result instead of tables
   -h, --help                 Show this help
@@ -41,12 +64,19 @@ Options:
 Examples:
   quilltap recall-replay <chatId>
   quilltap recall-replay <chatId> --turn 42
+  quilltap recall-replay <chatId> --turn 42 --memory-budget 4000
   quilltap recall-replay <chatId> --turn 42 --json > replay.json
+  quilltap recall-replay <chatId> --turn 42 --signals-from replay.json --as-of \
+    --tuning-file tuning-r1.json
 `);
 }
 
 function parseFlags(args) {
-  const flags = { turn: undefined, char: undefined, limit: undefined, port: 3000, json: false, help: false };
+  const flags = {
+    turn: undefined, char: undefined, limit: undefined, memoryBudget: undefined,
+    tuning: undefined, tuningFile: undefined, signalsFrom: undefined, asOf: false,
+    port: 3000, json: false, help: false,
+  };
   const positional = [];
   let i = 0;
   while (i < args.length) {
@@ -73,6 +103,27 @@ function parseFlags(args) {
         flags.limit = n;
         break;
       }
+      case '--memory-budget': {
+        const n = Number(args[++i]);
+        if (!Number.isInteger(n) || n < 1) {
+          console.error('Error: --memory-budget must be a positive integer');
+          process.exit(1);
+        }
+        flags.memoryBudget = n;
+        break;
+      }
+      case '--tuning':
+        flags.tuning = args[++i];
+        break;
+      case '--tuning-file':
+        flags.tuningFile = args[++i];
+        break;
+      case '--signals-from':
+        flags.signalsFrom = args[++i];
+        break;
+      case '--as-of':
+        flags.asOf = true;
+        break;
       case '--port': {
         const p = parseInt(args[++i], 10);
         if (isNaN(p) || p < 1 || p > 65535) {
@@ -106,8 +157,9 @@ function fmt(n, digits = 3) {
   return n.toFixed(digits);
 }
 
-function printPath(label, rows) {
-  console.log(`\n${BOLD}${label}${RESET} (${rows.length} candidates)`);
+function printPath(label, rows, headSize) {
+  const head = typeof headSize === 'number' ? `, head ${headSize}` : '';
+  console.log(`\n${BOLD}${label}${RESET} (${rows.length} candidates${head})`);
   if (rows.length === 0) {
     console.log(`  ${DIM}(none)${RESET}`);
     return;
@@ -127,6 +179,60 @@ function printPath(label, rows) {
   }
 }
 
+function readJson(text, what) {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    console.error(`${RED}Could not parse ${what} as JSON: ${err.message}${RESET}`);
+    process.exit(1);
+  }
+}
+
+function readJsonFile(path, what) {
+  const fs = require('fs');
+  let text;
+  try {
+    text = fs.readFileSync(path, 'utf8');
+  } catch (err) {
+    console.error(`${RED}Could not read ${what} ${path}: ${err.message}${RESET}`);
+    process.exit(1);
+  }
+  return readJson(text, `${what} ${path}`);
+}
+
+/** The tuning object from --tuning or --tuning-file (never both). */
+function loadTuning(flags) {
+  if (flags.tuning !== undefined && flags.tuningFile !== undefined) {
+    console.error('Error: pass --tuning or --tuning-file, not both');
+    process.exit(1);
+  }
+  if (flags.tuning !== undefined) return readJson(flags.tuning, '--tuning');
+  if (flags.tuningFile !== undefined) return readJsonFile(flags.tuningFile, '--tuning-file');
+  return undefined;
+}
+
+/**
+ * The signals saved in a previous --json replay. Refuses a file from another
+ * chat or turn — reusing its signals would replay a different question.
+ */
+function loadSignals(path, chatId, turn) {
+  const saved = readJsonFile(path, '--signals-from');
+  const result = saved.data ?? saved;
+  if (!result.signals) {
+    console.error(`${RED}${path} has no saved signals (its distillation failed); replay without --signals-from${RESET}`);
+    process.exit(1);
+  }
+  if (result.chatId && result.chatId !== chatId) {
+    console.error(`${RED}${path} is a replay of chat ${result.chatId}, not ${chatId}${RESET}`);
+    process.exit(1);
+  }
+  if (turn !== undefined && result.turnIndex !== undefined && result.turnIndex !== turn) {
+    console.error(`${RED}${path} is a replay of turn ${result.turnIndex}, not ${turn}${RESET}`);
+    process.exit(1);
+  }
+  return result.signals;
+}
+
 async function recallReplayCommand(args) {
   const { flags, positional } = parseFlags(args);
 
@@ -145,6 +251,11 @@ async function recallReplayCommand(args) {
   if (flags.turn !== undefined) body.turnIndex = flags.turn;
   if (flags.char) body.characterId = flags.char;
   if (flags.limit !== undefined) body.limit = flags.limit;
+  if (flags.memoryBudget !== undefined) body.memoryBudget = flags.memoryBudget;
+  const tuning = loadTuning(flags);
+  if (tuning !== undefined) body.tuning = tuning;
+  if (flags.signalsFrom !== undefined) body.signals = loadSignals(flags.signalsFrom, chatId, flags.turn);
+  if (flags.asOf) body.asOf = true;
 
   process.stderr.write(`${BOLD}Replaying recall${RESET} for chat ${DIM}${chatId}${RESET} via ${DIM}${url}${RESET}\n`);
 
@@ -170,6 +281,11 @@ async function recallReplayCommand(args) {
   }
   if (!res.ok || payload?.success === false) {
     console.error(`${RED}Replay failed (status ${res.status}): ${payload?.error || payload?.message || 'unknown error'}${RESET}`);
+    if (Array.isArray(payload?.details)) {
+      for (const issue of payload.details) {
+        console.error(`  ${(issue.path || []).join('.') || '(body)'}: ${issue.message}`);
+      }
+    }
     process.exit(1);
   }
 
@@ -193,8 +309,15 @@ async function recallReplayCommand(args) {
     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 || []);
+  const pinned = result.signalsPinned ? `${CYAN}pinned${RESET}` : `${DIM}fresh distillation${RESET}`;
+  const asOf = result.asOf
+    ? `${CYAN}as of ${result.asOf}${RESET} ${DIM}(${result.excludedAfterAsOf} later memories left out)${RESET}`
+    : `${DIM}whole corpus${RESET}`;
+  console.log(`${BOLD}Harness${RESET}   signals ${pinned} · ${asOf}`);
+  console.log(`${BOLD}Tuning${RESET}    ${result.tuning === 'defaults' || !result.tuning ? `${DIM}defaults${RESET}` : `${YELLOW}${result.tuning}${RESET}`} ${DIM}(new path only)${RESET}`);
+
+  printPath('OLD PATH (episodic signals inert)', result.oldPath || [], result.oldHeadSize);
+  printPath('NEW PATH (retrospective/window/entities live)', result.newPath || [], result.newHeadSize);
   console.log('');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.10.0-dev.117",
+  "version": "4.10.0-dev.139",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",