@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/bin/install-templates.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Idempotent setup for the three template files.
+ *
+ * Dry-run by default. `--apply` is explicit: it copies rules.md / habits.md only
+ * when missing, and appends the AGENTS pointer only when absent. AGENTS is
+ * backed up before any write.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const templates = path.join(root, 'templates');
+const args = process.argv.slice(2);
+const apply = args.includes('--apply');
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const contHome = process.env.DSH_CONTINUITY_HOME
+  ? process.env.DSH_CONTINUITY_HOME
+  : path.join(os.homedir(), '.dsh', 'continuity');
+const agentsFile = argOf('--agents') ?? path.join(os.homedir(), '.dsh', 'AGENTS.md');
+const markers = ['## Continuity 的 rules.md', '## Continuity 的规则层'];
+
+function read(file) {
+  try { return fs.readFileSync(file, 'utf8'); } catch { return null; }
+}
+function backup(file) {
+  if (!fs.existsSync(file)) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dst = `${file}.bak-${stamp}`;
+  fs.copyFileSync(file, dst);
+  return dst;
+}
+function copyIfMissing(name) {
+  const src = path.join(templates, name);
+  const dst = path.join(contHome, name);
+  if (!fs.existsSync(src)) throw new Error(`missing template: ${src}`);
+  if (fs.existsSync(dst)) return `keep ${dst}`;
+  if (apply) {
+    fs.mkdirSync(contHome, { recursive: true });
+    fs.copyFileSync(src, dst);
+    return `create ${dst}`;
+  }
+  return `would create ${dst}`;
+}
+function mergeAgents() {
+  const snippetSrc = path.join(templates, 'AGENTS-continuity.md');
+  if (!fs.existsSync(snippetSrc)) throw new Error(`missing template: ${snippetSrc}`);
+  const existing = read(agentsFile);
+  if (existing === null) {
+    if (apply) fs.mkdirSync(path.dirname(agentsFile), { recursive: true });
+    const text = fs.readFileSync(snippetSrc, 'utf8');
+    if (apply) fs.writeFileSync(agentsFile, text, 'utf8');
+    return `create ${agentsFile}`;
+  }
+  if (markers.some((m) => existing.includes(m))) return `keep ${agentsFile} (pointer present)`;
+  const text = existing.replace(/\s*$/, '') + '\n\n' + fs.readFileSync(snippetSrc, 'utf8');
+  if (!apply) return `would append pointer to ${agentsFile}`;
+  const bak = backup(agentsFile);
+  fs.writeFileSync(agentsFile, text, 'utf8');
+  return `append pointer to ${agentsFile}${bak ? ` (backup ${bak})` : ''}`;
+}
+
+console.log(`mode: ${apply ? 'APPLY' : 'DRY-RUN (use --apply)'}`);
+console.log(`continuity: ${contHome}`);
+console.log(`agents: ${agentsFile}`);
+for (const name of ['rules.md', 'habits.md']) console.log(copyIfMissing(name));
+console.log(mergeAgents());

package/bin/memory-bench.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEventLog } from '../src/memory/event-log.mjs';
+import { BM25Index } from '../src/memory/bm25.mjs';
+import { VectorIndex } from '../src/memory/vector-index.mjs';
+import { buildPlanner, summaryIndex } from '../src/memory/planner.mjs';
+import { embedTexts } from '../src/facets/embedding.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const dir = argOf('--dir');
+if (!dir) {
+  console.error('usage: node bin/memory-bench.mjs --dir .durable-memory');
+  process.exit(2);
+}
+const records = readEventLog(path.join(dir, 'events.jsonl'));
+const bm25 = BM25Index.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'bm25.json'), 'utf8')));
+const vectors = VectorIndex.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'vectors.json'), 'utf8')));
+const tree = JSON.parse(fs.readFileSync(path.join(dir, 'summary-tree.json'), 'utf8'));
+const planner = buildPlanner({ records, bm25, vectorIndex: vectors, summaryBm25: summaryIndex(tree) });
+const set = JSON.parse(fs.readFileSync(path.join(dir, 'QUERY-SET.json'), 'utf8'));
+const rows = [];
+for (const testCase of set.cases) {
+  const expected = new Set(testCase.expected);
+  const [queryVector] = await embedTexts([testCase.query]);
+  const plan = planner.query(testCase.query, { queryVector, topK: 10 });
+  const got = plan.fused.map((hit) => hit.turn);
+  const top = got.slice(0, 10);
+  const tp = top.filter((turn) => expected.has(turn)).length;
+  rows.push({
+    query: testCase.query,
+    route: plan.route,
+    expected: expected.size,
+    returned: top.length,
+    hits: tp,
+    precision: top.length === 0 ? 0 : tp / top.length,
+    recall: expected.size === 0 ? (top.length === 0 ? 1 : 0) : tp / expected.size,
+    top: top.slice(0, 5),
+  });
+}
+const aggregate = {
+  precision: rows.reduce((sum, row) => sum + row.precision, 0) / rows.length,
+  recall: rows.reduce((sum, row) => sum + row.recall, 0) / rows.length,
+  emptyCorrect: rows.filter((row) => row.expected === 0 && row.returned === 0).length,
+  emptyQueries: rows.filter((row) => row.expected === 0).length,
+};
+const output = { dir, set: set.provenance, aggregate, rows };
+fs.writeFileSync(path.join(dir, 'QUERY-BENCH.json'), JSON.stringify(output, null, 2));
+console.log(JSON.stringify(output, null, 2));

package/bin/memory-build-summary.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildSummaryTree, verifySummaryTree } from '../src/memory/summary-tree.mjs';
+import { readEventLog } from '../src/memory/event-log.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const eventsFile = argOf('--events');
+const outDir = argOf('--out') ?? '.durable-memory';
+if (!eventsFile) {
+  console.error('usage: node bin/memory-build-summary.mjs --events events.jsonl --out .durable-memory');
+  process.exit(2);
+}
+const records = readEventLog(eventsFile);
+const tree = buildSummaryTree(records, {
+  segmentSize: Number(argOf('--segment')) || 8,
+  chapterSize: Number(argOf('--chapter')) || 8,
+});
+fs.mkdirSync(outDir, { recursive: true });
+const treeFile = path.join(outDir, 'summary-tree.json');
+fs.writeFileSync(treeFile, `${JSON.stringify(tree, null, 2)}\n`, 'utf8');
+const manifestFile = path.join(outDir, 'manifest.json');
+if (fs.existsSync(manifestFile)) {
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  manifest.layers.summary = {
+    file: 'summary-tree.json',
+    version: tree.version,
+    nodeCount: tree.nodeCount,
+    treeRootHash: tree.treeRootHash,
+  };
+  fs.writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+const verification = verifySummaryTree(tree);
+console.log(JSON.stringify({
+  out: treeFile,
+  ...verification,
+  levels: tree.levels,
+  treeRootHash: tree.treeRootHash,
+}, null, 2));

package/bin/memory-build-vector.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEventLog } from '../src/memory/event-log.mjs';
+import { VectorIndex, loadEmbeddings } from '../src/memory/vector-index.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const eventsFile = argOf('--events');
+const embeddingsFile = argOf('--embeddings');
+const outDir = argOf('--out') ?? '.durable-memory';
+if (!eventsFile || !embeddingsFile) {
+  console.error('usage: node bin/memory-build-vector.mjs --events events.jsonl --embeddings embeddings.json --out .durable-memory');
+  process.exit(2);
+}
+const records = readEventLog(eventsFile);
+const vectors = loadEmbeddings(embeddingsFile);
+const index = new VectorIndex().build(records, vectors);
+fs.mkdirSync(outDir, { recursive: true });
+const file = path.join(outDir, 'vectors.json');
+fs.writeFileSync(file, `${JSON.stringify(index.toJSON())}\n`, 'utf8');
+const manifestFile = path.join(outDir, 'manifest.json');
+if (fs.existsSync(manifestFile)) {
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  manifest.layers.vector = { file: 'vectors.json', docs: index.docs.length };
+  fs.writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+}
+console.log(JSON.stringify({ out: file, docs: index.docs.length }, null, 2));

package/bin/memory-build.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { buildEventLog, writeEventLog, verifyEventLog, readEventLog } from '../src/memory/event-log.mjs';
+import { BM25Index } from '../src/memory/bm25.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const input = argOf('--input');
+const outDir = argOf('--out') ?? '.durable-memory';
+if (!input) {
+  console.error('usage: node bin/memory-build.mjs --input rows.jsonl --out .durable-memory');
+  process.exit(2);
+}
+const source = fs.readFileSync(input);
+const sourceSha = createHash('sha256').update(source).digest('hex');
+const rows = source.toString('utf8').split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+const records = buildEventLog(rows);
+fs.mkdirSync(outDir, { recursive: true });
+const eventFile = path.join(outDir, 'events.jsonl');
+const eventResult = writeEventLog(eventFile, records);
+const bm25 = new BM25Index().build(records);
+fs.writeFileSync(path.join(outDir, 'bm25.json'), `${JSON.stringify(bm25.toJSON())}\n`, 'utf8');
+const manifest = {
+  schema: 1,
+  sourceFile: path.basename(input),
+  sourceSha,
+  eventCount: records.length,
+  rootHash: eventResult.rootHash,
+  layers: {
+    event: { file: 'events.jsonl', count: records.length, rootHash: eventResult.rootHash },
+    bm25: { file: 'bm25.json', docs: bm25.docs.length },
+  },
+};
+fs.writeFileSync(path.join(outDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+const verification = verifyEventLog(readEventLog(eventFile));
+console.log(JSON.stringify({ outDir, sourceSha, eventFile, ...verification, bm25Docs: bm25.docs.length }, null, 2));

package/bin/memory-calibration.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Local facet-head calibration on the copied history.
+ * Labels are weak T-derived labels, not human gold.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEventLog } from '../src/memory/event-log.mjs';
+import { deserializeMlp, predictMlp } from '../src/facets/mlp-probe.mjs';
+import { reliabilityBins, thresholdCurve, chooseThreshold } from '../src/memory/calibration.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const dir = argOf('--dir');
+const modelPath = argOf('--model');
+const embeddingsPath = argOf('--embeddings');
+if (!dir || !modelPath || !embeddingsPath) {
+  console.error('usage: node bin/memory-calibration.mjs --dir .durable-memory --model MLP-MODEL.json --embeddings embeddings-1500.json');
+  process.exit(2);
+}
+const records = readEventLog(path.join(dir, 'events.jsonl'));
+const vectors = new Map(JSON.parse(fs.readFileSync(embeddingsPath, 'utf8')).map((row) => [row.turn, row.vector]));
+const model = deserializeMlp(JSON.parse(fs.readFileSync(modelPath, 'utf8')));
+const classes = new Set(model.slots.activity.classes);
+const points = [];
+let skipped = 0;
+for (const record of records) {
+  const vector = vectors.get(record.turn);
+  if (vector === undefined) {
+    skipped += 1;
+    continue;
+  }
+  const actual = record.facets.activity;
+  if (!classes.has(actual)) {
+    skipped += 1;
+    continue;
+  }
+  const prediction = predictMlp(model, vector);
+  points.push({
+    turn: record.turn,
+    confidence: prediction.confidence.activity,
+    correct: prediction.facets.activity === actual,
+    predicted: prediction.facets.activity,
+    actual,
+  });
+}
+const summary = {
+  model: path.basename(modelPath),
+  total: records.length,
+  evaluated: points.length,
+  skipped,
+  accuracy: points.filter((point) => point.correct).length / points.length,
+  averageConfidence: points.reduce((sum, point) => sum + point.confidence, 0) / points.length,
+  bins: reliabilityBins(points),
+  curve: thresholdCurve(points),
+  target90: chooseThreshold(points, { targetPrecision: 0.9 }),
+  target80: chooseThreshold(points, { targetPrecision: 0.8 }),
+};
+fs.writeFileSync(path.join(dir, 'CALIBRATION.json'), JSON.stringify(summary, null, 2));
+console.log(JSON.stringify({
+  evaluated: summary.evaluated,
+  skipped: summary.skipped,
+  accuracy: +summary.accuracy.toFixed(3),
+  averageConfidence: +summary.averageConfidence.toFixed(3),
+  target90: summary.target90,
+  target80: summary.target80,
+}, null, 2));

package/bin/memory-closed-loop.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * Closed-loop probe: local MLP facet prediction -> gate -> scene candidate.
+ * Compares raw MLP vs retrieval-stabilized facets.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEventLog } from '../src/memory/event-log.mjs';
+import { BM25Index } from '../src/memory/bm25.mjs';
+import { VectorIndex } from '../src/memory/vector-index.mjs';
+import { embedTexts } from '../src/facets/embedding.mjs';
+import { deserializeMlp, predictMlp } from '../src/facets/mlp-probe.mjs';
+import { MemoryLoadState, latestCandidate, candidateSegment } from '../src/memory/load-gate.mjs';
+import { stabilizeFacets } from '../src/memory/facet-stabilizer.mjs';
+import { summaryIndex } from '../src/memory/planner.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const dir = argOf('--dir');
+const modelPath = argOf('--model');
+if (!dir || !modelPath) {
+  console.error('usage: node bin/memory-closed-loop.mjs --dir .durable-memory --model MLP-MODEL.json');
+  process.exit(2);
+}
+const records = readEventLog(path.join(dir, 'events.jsonl'));
+const bm25 = BM25Index.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'bm25.json'), 'utf8')));
+const vectors = VectorIndex.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'vectors.json'), 'utf8')));
+const model = deserializeMlp(JSON.parse(fs.readFileSync(modelPath, 'utf8')));
+const tree = JSON.parse(fs.readFileSync(path.join(dir, 'summary-tree.json'), 'utf8'));
+const summaries = summaryIndex(tree);
+const dev = { activity: '开发', topic: '技术' };
+const messages = [
+  ['我们现在开始跑团吧', 'load'],
+  ['开团', 'load'],
+  ['TRPG 开一把', 'load'],
+  ['来一局', 'load'],
+  ['规则怎么写', 'none'],
+  ['规则文档在哪', 'none'],
+  ['上次跑团怎么样了', 'load'],
+  ['钥匙最后交给谁了', 'load'],
+  ['沈砚后来呢', 'load'],
+  ['跑团这个设计挺有意思', 'none'],
+  ['我推门进灯室', 'hint'],
+  ['Coo：灯室见', 'load'],
+  ['开始写文档', 'none'],
+  ['更新 README', 'none'],
+  ['开始调试插件', 'none'],
+  ['修一下这个 bug', 'none'],
+  ['今天天气不错', 'none'],
+  ['量子计算怎么样', 'none'],
+];
+const vectorsByText = new Map();
+for (const [text] of messages) {
+  const [vector] = await embedTexts([text]);
+  vectorsByText.set(text, vector);
+}
+
+const rows = [];
+for (const [text, expected] of messages) {
+  const vector = vectorsByText.get(text);
+  const raw = predictMlp(model, vector);
+  const keyword = bm25.search(text, { topK: 5, minCoverage: 0.4 });
+  const semantic = vectors.search(vector, { topK: 5 });
+  const summary = summaries.search(text, { topK: 3, minCoverage: 0.3 });
+  const stabilized = stabilizeFacets({ raw, text, records, keyword, semantic, summary });
+  const candidate = latestCandidate(records, 'activity', stabilized.facets.activity);
+  const segment = candidateSegment(records, candidate);
+  const gateState = new MemoryLoadState({ loadedFacets: dev, loadedAtTurn: 1490 });
+  const rawCandidate = latestCandidate(records, 'activity', raw.facets.activity);
+  const rawGate = gateState.decide({
+    text,
+    currentFacets: raw.facets,
+    confidence: raw.confidence.activity ?? 0,
+    nowTurn: 1500,
+    hasCandidate: rawCandidate !== null,
+    candidate: rawCandidate,
+    role: text.startsWith('Coo') ? 'coo' : 'user',
+  });
+  const stableGate = gateState.decide({
+    text,
+    currentFacets: stabilized.facets,
+    confidence: stabilized.confidence.activity ?? 0,
+    nowTurn: 1500,
+    hasCandidate: candidate !== null,
+    candidate,
+    role: text.startsWith('Coo') ? 'coo' : 'user',
+  });
+  rows.push({
+    text,
+    expected,
+    rawPass: rawGate.action === expected,
+    stablePass: stableGate.action === expected,
+    rawFacets: raw.facets,
+    rawConfidence: Object.fromEntries(Object.entries(raw.confidence).map(([key, value]) => [key, +value.toFixed(2)])),
+    evidence: { activity: stabilized.evidence.activity, topic: stabilized.evidence.topic },
+    stabilized: stabilized.facets,
+    stabilizeReason: stabilized.reason,
+    rawGate: rawGate.action,
+    rawReason: rawGate.reason,
+    stableGate: stableGate.action,
+    stableReason: stableGate.reason,
+    candidateTurn: candidate?.turn ?? null,
+    segmentTurns: segment?.turns ?? 0,
+  });
+}
+const summary = {
+  cases: rows.length,
+  rawPass: rows.filter((row) => row.rawPass).length,
+  stablePass: rows.filter((row) => row.stablePass).length,
+  rawFailures: rows.filter((row) => !row.rawPass).map((row) => row.text),
+  stableFailures: rows.filter((row) => !row.stablePass).map((row) => row.text),
+  lowActivityConfidence: rows.filter((row) => row.rawConfidence.activity < 0.7).length,
+  changedByStabilizer: rows.filter((row) => row.rawFacets.activity !== row.stabilized.activity).length,
+};
+console.log(JSON.stringify({ model: path.basename(modelPath), summary, rows }, null, 2));
+fs.writeFileSync(path.join(dir, 'CLOSED-LOOP.json'), JSON.stringify({ model: path.basename(modelPath), summary, rows }, null, 2));

package/bin/memory-dry-run.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Offline dry run: query -> planner -> seq ranges -> simulated load.
+ * No live session and no writes.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEventLog } from '../src/memory/event-log.mjs';
+import { BM25Index } from '../src/memory/bm25.mjs';
+import { VectorIndex } from '../src/memory/vector-index.mjs';
+import { buildPlanner, summaryIndex } from '../src/memory/planner.mjs';
+import { embedTexts } from '../src/facets/embedding.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const dir = argOf('--dir');
+if (!dir) {
+  console.error('usage: node bin/memory-dry-run.mjs --dir .durable-memory');
+  process.exit(2);
+}
+const records = readEventLog(path.join(dir, 'events.jsonl'));
+const byTurn = new Map(records.map((record) => [record.turn, record]));
+const bm25 = BM25Index.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'bm25.json'), 'utf8')));
+const vectors = VectorIndex.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'vectors.json'), 'utf8')));
+const tree = JSON.parse(fs.readFileSync(path.join(dir, 'summary-tree.json'), 'utf8'));
+const planner = buildPlanner({ records, bm25, vectorIndex: vectors, summaryBm25: summaryIndex(tree) });
+const set = JSON.parse(fs.readFileSync(path.join(dir, 'QUERY-SET.json'), 'utf8'));
+
+const rows = [];
+for (const testCase of set.cases) {
+  const expected = new Set(testCase.expected);
+  const [queryVector] = await embedTexts([testCase.query]);
+  const plan = planner.query(testCase.query, { queryVector, topK: 10 });
+  const ranges = [];
+  const loaded = [];
+  for (const hit of plan.fused.slice(0, 10)) {
+    const record = byTurn.get(hit.turn);
+    if (record === undefined) {
+      ranges.push({ turn: hit.turn, valid: false });
+      continue;
+    }
+    ranges.push({ turn: hit.turn, seqStart: record.seqStart, seqEnd: record.seqEnd, valid: true });
+    loaded.push(record);
+  }
+  const text = loaded.map((record) => record.text).join('\n');
+  const hitTurns = loaded.map((record) => record.turn).filter((turn) => expected.has(turn));
+  rows.push({
+    query: testCase.query,
+    route: plan.route,
+    expected: expected.size,
+    loadedTurns: loaded.length,
+    expectedHits: hitTurns.length,
+    allRangesValid: ranges.every((range) => range.valid),
+    chars: text.length,
+    ranges,
+  });
+}
+const summary = {
+  queries: rows.length,
+  allRangesValid: rows.every((row) => row.allRangesValid),
+  expectedHitQueries: rows.filter((row) => row.expected === 0 || row.expectedHits > 0).length,
+  emptyCorrect: rows.filter((row) => row.expected === 0 && row.loadedTurns === 0).length,
+  emptyQueries: rows.filter((row) => row.expected === 0).length,
+};
+const output = { dir, summary, rows };
+fs.writeFileSync(path.join(dir, 'DRY-RUN.json'), JSON.stringify(output, null, 2));
+console.log(JSON.stringify(output, null, 2));

package/bin/memory-eval.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Retrieval ablation: facet / BM25 / vector / summary / routed planner.
+ * Ground truth is the weak facet label or an explicit text predicate.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readEventLog } from '../src/memory/event-log.mjs';
+import { BM25Index } from '../src/memory/bm25.mjs';
+import { VectorIndex } from '../src/memory/vector-index.mjs';
+import { buildPlanner, summaryIndex } from '../src/memory/planner.mjs';
+import { buildFacetIndex, queryFacets } from '../src/facets/index.mjs';
+import { aliasFacets } from '../src/facets/schema.mjs';
+import { embedTexts } from '../src/facets/embedding.mjs';
+
+const args = process.argv.slice(2);
+const argOf = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const dir = argOf('--dir');
+if (!dir) {
+  console.error('usage: node bin/memory-eval.mjs --dir .durable-memory');
+  process.exit(2);
+}
+const records = readEventLog(path.join(dir, 'events.jsonl'));
+const bm25 = BM25Index.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'bm25.json'), 'utf8')));
+const vectors = VectorIndex.fromJSON(JSON.parse(fs.readFileSync(path.join(dir, 'vectors.json'), 'utf8')));
+const tree = JSON.parse(fs.readFileSync(path.join(dir, 'summary-tree.json'), 'utf8'));
+const facetIndex = buildFacetIndex(records);
+const summaries = summaryIndex(tree);
+const planner = buildPlanner({ records, bm25, vectorIndex: vectors, summaryBm25: summaries });
+
+const cases = [];
+for (const [query, core] of [
+  ['跑团', { activity: '跑团' }],
+  ['开发', { activity: '开发' }],
+  ['调试', { activity: '调试' }],
+  ['记忆', { topic: '记忆' }],
+  ['规则', { topic: '规则' }],
+  ['图像', { topic: '设备', medium: '图像' }],
+  ['技术', { topic: '技术' }],
+]) {
+  cases.push({
+    query,
+    expected: new Set(records.filter((record) => Object.entries(core).every(([key, value]) => record.facets[key] === value)).map((record) => record.turn)),
+  });
+}
+cases.push({
+  query: 'd100 钥匙',
+  expected: new Set(records.filter((record) => record.facets.activity === '跑团' && /d100|钥匙/.test(record.text)).map((record) => record.turn)),
+});
+cases.push({
+  query: 'TAG 闸',
+  expected: new Set(records.filter((record) => /TAG|打标/.test(record.text) && /闸/.test(record.text)).map((record) => record.turn)),
+});
+cases.push({ query: '量子计算', expected: new Set() });
+
+function rankMetrics(got, expected) {
+  const top = got.slice(0, 10);
+  const tp = top.filter((turn) => expected.has(turn)).length;
+  return {
+    precision: top.length === 0 ? 0 : tp / top.length,
+    recall: expected.size === 0 ? (top.length === 0 ? 1 : 0) : tp / expected.size,
+    hits: tp,
+    returned: top.length,
+    expected: expected.size,
+  };
+}
+
+const rows = [];
+for (const testCase of cases) {
+  const [queryVector] = await embedTexts([testCase.query]);
+  const alias = aliasFacets(testCase.query);
+  const facet = Object.keys(alias).length > 0
+    ? queryFacets(facetIndex, testCase.query, { topK: 10 }).matches.map((hit) => hit.turn)
+    : [];
+  const keyword = bm25.search(testCase.query, { topK: 10, minCoverage: 0.6 }).map((hit) => hit.turn);
+  const semantic = vectors.search(queryVector, { topK: 10 }).map((hit) => hit.turn);
+  const summary = summaries.search(testCase.query, { topK: 5, minCoverage: 0.5 }).map((hit) => hit.turn);
+  const plan = planner.query(testCase.query, { queryVector, topK: 10 });
+  const hybrid = plan.fused.map((hit) => hit.turn);
+  rows.push({
+    query: testCase.query,
+    route: plan.route,
+    expected: testCase.expected.size,
+    facet: rankMetrics(facet, testCase.expected),
+    bm25: rankMetrics(keyword, testCase.expected),
+    vector: rankMetrics(semantic, testCase.expected),
+    summary: rankMetrics(summary, testCase.expected),
+    hybrid: rankMetrics(hybrid, testCase.expected),
+  });
+}
+
+const aggregate = {};
+for (const layer of ['facet', 'bm25', 'vector', 'summary', 'hybrid']) {
+  aggregate[layer] = {
+    precision: rows.reduce((sum, row) => sum + row[layer].precision, 0) / rows.length,
+    recall: rows.reduce((sum, row) => sum + row[layer].recall, 0) / rows.length,
+  };
+}
+const output = { dir, cases: rows, aggregate };
+fs.writeFileSync(path.join(dir, 'RETRIEVAL-ABLATION.json'), JSON.stringify(output, null, 2));
+console.log(JSON.stringify(output, null, 2));