quilltap 4.10.0-dev.146 → 4.10.0-dev.173

package/lib/anchor-probe-command.js

@@ -1,8 +1,10 @@
 'use strict';
 
+const { resolveServerPort } = require('./lock-helpers');
+
 /**
  * `quilltap anchor-probe <characterId>` — measure whether the episodic anchor
- * line embedded with each memory suppresses Memory Gate reinforcement.
+ * 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.
@@ -23,16 +25,21 @@ 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.
+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: 3000)
+      --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
 
@@ -44,7 +51,7 @@ Examples:
 }
 
 function parseFlags(args) {
-  const flags = { limit: undefined, port: 3000, json: false, help: false };
+  const flags = { limit: undefined, port: undefined, dataDir: '', instance: '', json: false, help: false };
   const positional = [];
   let i = 0;
   while (i < args.length) {
@@ -59,6 +66,19 @@ function parseFlags(args) {
         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) {
@@ -107,19 +127,19 @@ function printRows(rows, thresholds) {
   console.log(
     `  ${DIM}${'anchored'.padEnd(10)}${'free'.padEnd(10)}${'delta'.padEnd(9)}${'anchor'.padEnd(8)}summary${RESET}`
   );
-  const reinforce = thresholds?.reinforce ?? 0.85;
+  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 = typeof f === 'number' && f >= reinforce && !(typeof a === 'number' && a >= reinforce);
+    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}= crosses ${reinforce} only without the anchor line${RESET}`);
+  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) {
@@ -135,7 +155,17 @@ async function anchorProbeCommand(args) {
   }
   const characterId = positional[0];
 
-  const url = `http://localhost:${flags.port}/api/v1/memories?action=anchor-gate-probe`;
+  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;
 
@@ -149,8 +179,8 @@ async function anchorProbeCommand(args) {
       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.');
+    console.error(`${RED}Could not reach Quilltap server at http://localhost:${port}: ${err.message}${RESET}`);
+    console.error(target.hint);
     process.exit(1);
   }
 
@@ -178,14 +208,15 @@ async function anchorProbeCommand(args) {
   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}${('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}`);
+  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}Crossed only without anchors${RESET}  ${only > 0 ? YELLOW : GREEN}${only}${RESET}`);
+  console.log(`${BOLD}Fold only without anchors${RESET}  ${only > 0 ? YELLOW : GREEN}${only}${RESET}`);
 
   printRows(result.rows || [], t);
   console.log('');
 }
 
-module.exports = { anchorProbeCommand, printAnchorProbeHelp };
+module.exports = { anchorProbeCommand, printAnchorProbeHelp, parseFlags };

package/lib/completion/bash.template

@@ -69,11 +69,11 @@ _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 --tier --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 --memory-budget --tuning --tuning-file --signals-from --port "
@@ -185,6 +185,10 @@ _quilltap_complete() {
       COMPREPLY=($(compgen -W "hot cold" -- "$cur"))
       return
       ;;
+    --phases)
+      COMPREPLY=($(compgen -W "fold-near-duplicates consolidate demote retire mirror" -- "$cur"))
+      return
+      ;;
     --sort)
       COMPREPLY=($(compgen -W "name time size links reinforced importance created accessed reinforcement-count" -- "$cur"))
       return
@@ -220,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"
@@ -317,13 +321,13 @@ _quilltap_complete() {
       fi
       ;;
     memories)
-      local mem_verbs="ls find grep show tree status validate consolidate"
+      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 --dry-run \
-        --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"))
@@ -339,11 +343,11 @@ _quilltap_complete() {
       COMPREPLY=($(compgen -W "$md_flags" -- "$cur"))
       ;;
     recall-replay)
-      local rr_flags="--turn --char --limit --memory-budget --tuning --tuning-file --signals-from --as-of --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="--limit --port --json --help"
+      local ap_flags="--instance --data-dir --passphrase --limit --port --json --help"
       COMPREPLY=($(compgen -W "$ap_flags" -- "$cur"))
       ;;
     logs)

package/lib/completion/fish.template

@@ -114,6 +114,7 @@ complete -c quilltap -n '__quilltap_using_subcommand db' -l 'character' -d 'Char
 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 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'
@@ -272,14 +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 'consolidate' -d 'Fold memory clusters into digests'
+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 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 '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

package/lib/completion/zsh.template

@@ -152,6 +152,7 @@ _quilltap_db() {
     '--project[Project name or id]:project:'
     '--about[Subject character]:character:'
     '--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]'
@@ -538,20 +539,24 @@ _quilltap_memories() {
     'tree:ASCII walk of graph'
     'status:Per-character rollup'
     'validate:Health check'
-    'consolidate:Fold memory clusters into digests'
+    '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 CONSOLIDATED)'
     '--tier[Memory tier]:tier:(hot cold)'
-    '--dry-run[Consolidate: rehearse and print the report, write nothing]'
+    '--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:'

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 || ''),

package/lib/graph-integrity.js

@@ -3,6 +3,11 @@
 // Shared graph-integrity scanner used by `memories status` (per-holder
 // rollup) and `memories validate` (read-only dangling-edge check).
 //
+// `scanDanglingEdges` covers `relatedMemoryIds`; `scanDigestIntegrity`
+// covers the consolidation links (`consolidatedFrom`, `supersededById`) and
+// rows with no embedding — the same four things the server's graph repair
+// (`POST /api/v1/memories?action=repair`) finds and fixes.
+//
 // "Dangling edges" are UUIDs in `memories.relatedMemoryIds` that no longer
 // resolve to a row in the `memories` table. Cross-character links are
 // legitimate — a memory's links may point at memories owned by other holders
@@ -34,10 +39,7 @@ function scanDanglingEdges(db, opts = {}) {
   // The valid set is *every* memory ID in the table. Computed once even
   // when restricted to a single holder, because cross-character links are
   // legitimate and we don't want them counted as dangling.
-  const allIds = new Set();
-  for (const row of db.prepare('SELECT id FROM memories').all()) {
-    allIds.add(row.id);
-  }
+  const allIds = opts.allIds || loadMemoryIds(db);
 
   const scanRows = characterId
     ? db.prepare('SELECT id, characterId, relatedMemoryIds FROM memories WHERE characterId = ?').all(characterId)
@@ -102,4 +104,105 @@ function scanDanglingEdges(db, opts = {}) {
   return result;
 }
 
-module.exports = { scanDanglingEdges };
+/** Every memory id in the table — the universe a link may legitimately name. */
+function loadMemoryIds(db) {
+  const allIds = new Set();
+  for (const row of db.prepare('SELECT id FROM memories').all()) {
+    allIds.add(row.id);
+  }
+  return allIds;
+}
+
+/** The memories table's column names (old instances lack the tier-era columns). */
+function memoryColumns(db) {
+  try {
+    return new Set(db.prepare("PRAGMA table_info('memories')").all().map((c) => c.name));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Scan the consolidation links and embeddings for one holder (or every row).
+ *
+ * - dangling `consolidatedFrom`: member ids a digest names that no longer exist
+ * - dangling `supersededById`: members pointing at a digest that is gone
+ * - missing embeddings: rows with `embedding IS NULL` (not recallable by
+ *   meaning until re-embedded; a warning, not graph damage)
+ *
+ * Columns absent on very old instances read as nothing to scan.
+ *
+ * @param {import('better-sqlite3').Database} db  Open readonly DB handle.
+ * @param {object} [opts]
+ * @param {string} [opts.characterId]  Restrict the scan to one holder.
+ * @param {boolean} [opts.includePairs] Return the offending rows (for --list).
+ * @param {Set<string>} [opts.allIds]  Reuse a precomputed id universe.
+ * @returns {{
+ *   consolidatedFrom: { links: number, digests: number },
+ *   supersededBy: number,
+ *   missingEmbeddings: number,
+ *   consolidatedFromPairs?: Array<{ digestId: string, characterId: string, memberIds: string[] }>,
+ *   supersededByPairs?: Array<{ memberId: string, characterId: string, digestId: string }>
+ * }}
+ */
+function scanDigestIntegrity(db, opts = {}) {
+  const { characterId, includePairs = false } = opts;
+  const cols = opts.columns || memoryColumns(db);
+  const allIds = opts.allIds || loadMemoryIds(db);
+  const where = characterId ? ' AND characterId = ?' : '';
+  const params = characterId ? [characterId] : [];
+
+  const result = {
+    consolidatedFrom: { links: 0, digests: 0 },
+    supersededBy: 0,
+    missingEmbeddings: 0,
+  };
+  if (includePairs) {
+    result.consolidatedFromPairs = [];
+    result.supersededByPairs = [];
+  }
+
+  if (cols.has('consolidatedFrom')) {
+    const rows = db.prepare(
+      `SELECT id, characterId, consolidatedFrom FROM memories
+       WHERE consolidatedFrom IS NOT NULL AND consolidatedFrom != '[]'${where}`
+    ).all(...params);
+    for (const row of rows) {
+      let arr;
+      try { arr = JSON.parse(row.consolidatedFrom || '[]'); } catch { arr = []; }
+      if (!Array.isArray(arr)) continue;
+      const missing = arr.filter((id) => !allIds.has(id));
+      if (missing.length === 0) continue;
+      result.consolidatedFrom.links += missing.length;
+      result.consolidatedFrom.digests++;
+      if (includePairs) {
+        result.consolidatedFromPairs.push({ digestId: row.id, characterId: row.characterId, memberIds: missing });
+      }
+    }
+  }
+
+  if (cols.has('supersededById')) {
+    const rows = db.prepare(
+      `SELECT id, characterId, supersededById FROM memories
+       WHERE supersededById IS NOT NULL${where}`
+    ).all(...params);
+    for (const row of rows) {
+      if (allIds.has(row.supersededById)) continue;
+      result.supersededBy++;
+      if (includePairs) {
+        result.supersededByPairs.push({ memberId: row.id, characterId: row.characterId, digestId: row.supersededById });
+      }
+    }
+  }
+
+  if (cols.has('embedding')) {
+    const row = db.prepare(
+      `SELECT COUNT(*) AS n FROM memories WHERE embedding IS NULL${where}`
+    ).get(...params);
+    result.missingEmbeddings = row ? row.n || 0 : 0;
+  }
+
+  return result;
+}
+
+module.exports = { scanDanglingEdges, scanDigestIntegrity, loadMemoryIds, memoryColumns };

package/lib/lock-helpers.js

@@ -110,6 +110,70 @@ function getLockStatus(dataDir) {
   };
 }
 
+// ============================================================================
+// Server port resolution
+//
+// CLI tools that talk to a RUNNING server over HTTP (memory-diff, recall-replay,
+// anchor-probe, memories consolidate) need its port. The server records the
+// port it listens on in the instance lock, so naming an instance (or a data
+// dir) is enough to find it. An explicit --port always wins.
+// ============================================================================
+
+const DEFAULT_SERVER_PORT = 3000;
+
+/**
+ * Decide which port to call.
+ *
+ * @param {{ port?: number, instance?: string, dataDir?: string }} opts
+ *   `port` is the explicit --port (undefined when not given).
+ * @returns {{ port: number, source: 'flag'|'lock'|'default', note: string|null,
+ *            hint: string }}
+ *   `note` is a one-line message to print when the lock supplied the port;
+ *   `hint` is the connection-failure advice.
+ * @throws if both instance and dataDir are given, or the instance is unknown.
+ */
+function resolveServerPort({ port, instance, dataDir } = {}) {
+  const baseHint = 'Start the server (npm run dev) or pass --port to match a non-default port.';
+  if (port !== undefined && port !== null) {
+    return { port, source: 'flag', note: null, hint: baseHint };
+  }
+  if (!instance && !dataDir) {
+    return { port: DEFAULT_SERVER_PORT, source: 'default', note: null, hint: baseHint };
+  }
+
+  // Lazy require: db-helpers is heavier and nothing else here needs it.
+  const { resolveDataDirAndPassphrase } = require('./db-helpers');
+  const resolved = resolveDataDirAndPassphrase({ instance, dataDir });
+  const label = resolved.instanceName || resolved.dataDir;
+  const status = getLockStatus(resolved.dataDir);
+  const lockPort = status.lock && Number.isInteger(status.lock.port) &&
+    status.lock.port >= 1 && status.lock.port <= 65535
+    ? status.lock.port
+    : null;
+
+  if (status.state === 'active' && lockPort !== null) {
+    return {
+      port: lockPort,
+      source: 'lock',
+      note: `Using port ${lockPort} from the ${label} instance lock`,
+      hint: baseHint,
+    };
+  }
+
+  let why;
+  if (status.state === 'active') why = 'its lock records no port (server predates port recording)';
+  else if (status.state === 'absent') why = 'it has no instance lock, so no server appears to be running';
+  else if (status.state === 'stale') why = `its lock is stale (${status.reason})`;
+  else if (status.state === 'suspect') why = `its lock looks suspect (${status.reason})`;
+  else why = 'its lock file is unreadable';
+  return {
+    port: DEFAULT_SERVER_PORT,
+    source: 'default',
+    note: null,
+    hint: `${baseHint}\nNo port found for the ${label} instance: ${why}; fell back to ${DEFAULT_SERVER_PORT}.`,
+  };
+}
+
 // ============================================================================
 // Write-lock acquire / release
 //
@@ -354,4 +418,6 @@ module.exports = {
   acquireWriteLock,
   releaseWriteLock,
   detectEnvironmentType,
+  resolveServerPort,
+  DEFAULT_SERVER_PORT,
 };