@jossuealcala/madre 0.3.3 → 0.4.1

package/src/maturity.mjs

@@ -0,0 +1,94 @@
+// How grown a room is, and how far from being worth training on.
+//
+// Pure functions. The room hands in what it has; nothing here reads a file or calls a model.
+//
+// This replaces a bar that filled toward three hundred. That number was a rule of thumb from
+// somebody else's paper, not a measurement of this room, and a corpus of three hundred pairs all
+// about the same afternoon teaches less than eighty that are not. What is measured here is what
+// can actually be counted about this archive, and each reading says plainly what would raise it.
+
+// How much of the whole each reading is worth. Volume counts, but it is one voice of six: a room
+// can be large and still be narrow, unjudged and lopsided.
+import { t } from './i18n.mjs';
+
+export const WEIGHTS = { volume: 0.2, coverage: 0.2, weave: 0.15, judgement: 0.2, balance: 0.15, upkeep: 0.1 };
+export const VOLUME_TARGET = 300;   // the usual floor for a small adapter, and nothing more than that
+
+const share = (part, whole) => (whole > 0 ? Math.min(1, Math.max(0, part / whole)) : 0);
+const round = (value) => Number(value.toFixed(3));
+
+// Six readings, each 0 to 1, each with the one thing that would raise it.
+export function maturity({ readiness = null, notes = [], links = [], stats = null } = {}) {
+  const standing = notes.filter((note) => note.kind !== 'aberration' && !note.refutedBy);
+  const pairs = Number(readiness?.pairs ?? 0);
+  const rated = Number(readiness?.good ?? 0) + Number(readiness?.bad ?? 0);
+  const turns = Number(readiness?.turns ?? 0) + Number(readiness?.delegated ?? 0);
+  const noteShare = pairs > 0 ? Number(readiness?.notes ?? 0) / pairs : 0;
+
+  const recalled = standing.filter((note) => Number(note.recalled ?? 0) > 0).length;
+  const linked = new Set(links.flatMap((link) => [link.a, link.b]));
+  const connected = standing.filter((note) => linked.has(note.id)).length;
+  const pending = Number(stats?.pending ?? 0);
+  const entries = Number(stats?.entries ?? 0);
+
+  const signals = [
+    {
+      id: 'volume', label: t('HOW MUCH THERE IS'),
+      value: round(share(pairs, VOLUME_TARGET)),
+      detail: t('{pairs} of about {target} exchanges worth training on', { pairs, target: VOLUME_TARGET }),
+      next: t('Use the room. Nothing else fills this.'),
+    },
+    {
+      id: 'coverage', label: t('HOW MUCH OF IT GETS USED'),
+      value: round(share(recalled, standing.length)),
+      detail: t('{recalled} of {total} memories have been reached for at least once', { recalled, total: standing.length }),
+      next: t('Memories nobody has needed may be noise, or may simply not have come up yet. Ask the room about older decisions and see which ones answer.'),
+    },
+    {
+      id: 'weave', label: t('HOW WOVEN IT IS'),
+      value: round(share(connected, standing.length)),
+      detail: t('{connected} of {total} memories share a subject with another', { connected, total: standing.length }),
+      next: t('An archive of unrelated notes is a list. Depth comes from returning to the same subjects.'),
+    },
+    {
+      id: 'judgement', label: t('HOW MUCH OF IT YOU JUDGED'),
+      // A tenth rated is enough to steer a small adapter; asking for all of it would never be met.
+      value: round(share(rated, Math.max(1, pairs * 0.1))),
+      detail: t('{rated} of {pairs} replies rated', { rated, pairs }),
+      next: t('Rate replies with the thumbs on a bubble. A corpus nobody judged teaches what the agents said, not what you approved.'),
+    },
+    {
+      id: 'balance', label: t('HOW MUCH OF IT IS REAL WORK'),
+      // Half recall pairs is healthy; a corpus that is mostly recall teaches recitation. A room
+      // with no corpus at all is not balanced, it is empty, and saying otherwise would show
+      // progress where there is none.
+      value: pairs > 0 ? round(1 - Math.min(1, Math.max(0, (noteShare - 0.5) / 0.5))) : 0,
+      detail: t('{share}% of the corpus is recall questions, {turns} exchanges are real work', { share: Math.round(noteShare * 100), turns }),
+      next: t('Recall pairs are made from notes and cost nothing, so they pile up. Work in the room to balance them.'),
+    },
+    {
+      id: 'upkeep', label: t('HOW CURRENT IT IS'),
+      value: round(entries > 0 ? 1 - share(pending, Math.max(1, entries * 0.15)) : 0),
+      detail: t('{pending} exchanges nobody has distilled yet, of {entries}', { pending, entries }),
+      next: t('The archivist catches up on its own. A backlog that never clears means it cannot run: check who is allowed to distil.'),
+    },
+  ];
+
+  const score = round(signals.reduce((sum, signal) => sum + signal.value * (WEIGHTS[signal.id] ?? 0), 0));
+  return { score, stage: stageOf(score), signals, weakest: [...signals].sort((a, b) => a.value - b.value)[0]?.id ?? null };
+}
+
+// What to call it. A name is not a measurement, but a number alone tells nobody whether to act.
+export const STAGES = [
+  { at: 0.85, id: 'mature', label: 'MATURE', says: 'Worth training on. Export and run the recipe.' },
+  { at: 0.6, id: 'working', label: 'WORKING', says: 'Usable, and it will be better for waiting.' },
+  { at: 0.35, id: 'forming', label: 'FORMING', says: 'It has a shape. Too thin to train on.' },
+  { at: 0.12, id: 'sparse', label: 'SPARSE', says: 'A few things remembered, little connecting them.' },
+  { at: 0, id: 'empty', label: 'EMPTY', says: 'Nothing has been distilled yet.' },
+];
+// The table holds the English, and the stage is said in the room's language when it is asked
+// for: this list is built when the file is imported, and the room learns its language after.
+export function stageOf(score) {
+  const stage = STAGES.find((one) => score >= one.at) ?? STAGES.at(-1);
+  return { ...stage, label: t(stage.label), says: t(stage.says) };
+}

package/src/mcp/image-server.mjs

@@ -9,14 +9,16 @@
 // Environment:
 //   PULSE_IMAGE_OUT_DIR   required, absolute lease directory
 //   PULSE_IMAGE_MODEL     default gemini-2.5-flash-image
-//   GEMINI_API_KEY        optional; otherwise the macOS keychain entry the
+//   GEMINI_API_KEY        optional; otherwise ~/.gemini/.env, then the macOS keychain entry the
 //                         Gemini CLI stores (service gemini-cli-api-key)
 //   PULSE_IMAGE_FAKE=1    write a 1×1 PNG without calling Google (tests)
 
 import { execFile } from 'node:child_process';
-import { mkdir, writeFile, realpath } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { basename, extname, join, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
+import { OutboundLog } from '../outbound.mjs';
 
 const execFileAsync = promisify(execFile);
 const SERVER_NAME = 'pulse-image';
@@ -24,9 +26,30 @@ const SERVER_VERSION = '0.1.0';
 const DEFAULT_MODEL = 'gemini-2.5-flash-image';
 const FAKE_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64');
 
+// Where a Gemini key can be, in the order the room should trust them: what this process was
+// given, then the file the CLI reads on every run — which is also the file MADRE itself writes
+// when a key is pasted into CONNECTIONS — and last the macOS keychain, which only exists when
+// the CLI's own sign-in put it there. Leaving the file out meant MADRE saved a key in a place it
+// then refused to look, and on Linux, where there is no keychain, that was the only place it
+// could have been: Image Studio could never find a key there at all.
+async function keyFromGeminiEnvFile(env) {
+  const home = env.GEMINI_CLI_HOME ?? homedir();
+  let text;
+  try { text = await readFile(join(home, '.gemini', '.env'), 'utf8'); } catch { return null; }
+  for (const line of text.split('\n')) {
+    const match = line.match(/^\s*(?:export\s+)?(GEMINI_API_KEY|GOOGLE_API_KEY)\s*=\s*(.*)$/);
+    if (!match) continue;
+    const value = match[2].trim().replace(/^(['"])(.*)\1$/, '$2').trim();
+    if (value) return value;
+  }
+  return null;
+}
+
 export async function resolveGeminiKey(env = process.env) {
   if (env.GEMINI_API_KEY) return env.GEMINI_API_KEY;
   if (env.GOOGLE_API_KEY) return env.GOOGLE_API_KEY;
+  const fromFile = await keyFromGeminiEnvFile(env);
+  if (fromFile) return fromFile;
   if (process.platform !== 'darwin') return null;
   // The keychain occasionally answers empty under concurrent reads; one retry.
   for (let attempt = 0; attempt < 2; attempt += 1) {
@@ -62,6 +85,16 @@ export function explainGoogleError(status, body) {
   return { code: 'ERROR', message: message || `Google returned HTTP ${status}.` };
 }
 
+// The image studio runs in a process of its own, so it writes its own line into the room's
+// outbound log. Without this, the one request MADRE makes that carries somebody's words to
+// Google would be the one request the log could not see.
+let outboundLog = null;
+function outboundFetch(fetchImpl, file) {
+  if (!file) return fetchImpl;
+  outboundLog ??= new OutboundLog({ file });
+  return outboundLog.watch(fetchImpl);
+}
+
 export async function generateImage({ prompt, fileName, outDir, model = process.env.PULSE_IMAGE_MODEL || DEFAULT_MODEL, env = process.env, fetchImpl = fetch }) {
   if (!prompt || typeof prompt !== 'string') throw Object.assign(new Error('A text prompt is required.'), { code: 'INVALID' });
   const root = await realpath(outDir).catch(() => null);
@@ -76,7 +109,7 @@ export async function generateImage({ prompt, fileName, outDir, model = process.
   }
   const key = await resolveGeminiKey(env);
   if (!key) throw Object.assign(new Error('No Gemini API key: set GEMINI_API_KEY or sign in with the Gemini CLI (/auth → API key).'), { code: 'NO_KEY' });
-  const response = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`, {
+  const response = await outboundFetch(fetchImpl, env.PULSE_OUTBOUND_LOG)(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`, {
     method: 'POST',
     headers: { 'content-type': 'application/json', 'x-goog-api-key': key },
     body: JSON.stringify({ contents: [{ parts: [{ text: prompt }] }], generationConfig: { responseModalities: ['IMAGE'] } }),

package/src/mcp/memory-server.mjs

@@ -57,7 +57,7 @@ export const TOOLS = [
     name: 'memory_note',
     description: 'Save one durable memory of this room, ONLY when the human explicitly asks you to remember, note or save something (memories are otherwise distilled automatically; never save on your own initiative). One self-contained sentence, at most 240 characters, in the language the room uses, with the ledger sequences it comes from when you know them. Refused in a GHOST turn.',
     inputSchema: { type: 'object', properties: {
-      kind: { type: 'string', enum: MEMORY_KINDS, description: 'decision, fact, preference or question.' },
+      kind: { type: 'string', enum: MEMORY_KINDS, description: 'decision, fact, preference, question, or aberration for a claim this room established is false.' },
       text: { type: 'string', description: 'The memory, one sentence, names and numbers exact.' },
       sources: { type: 'array', items: { type: 'integer' }, description: 'Ledger sequences it comes from, if known.' },
     }, required: ['kind', 'text'] },

package/src/memory.mjs

@@ -15,8 +15,37 @@ import { dirname } from 'node:path';
 import { messageEntry } from './conversation-context.mjs';
 import { cosine, toBlob, fromBlob } from './embeddings.mjs';
 
+// How many recall rows a room keeps. Six or so per turn, so this is months of work.
+export const RECALL_HISTORY = 20000;
+
+// Spreading activation. Two memories that keep arriving in the same turn are associated, however
+// differently they read: the room's own work says so. The strength is Jaccard over the turns
+// where each was found by the search on its own merits — so a memory the room reaches for
+// constantly does not end up attached to everything, and one that only ever arrived by cascade
+// never votes on what comes next. Without that second rule the network would feed itself into a
+// clique within a few days.
+export const CASCADE_FLOOR = 0.34;      // of the turns where either appeared, they appeared together
+export const CASCADE_MIN_TIMES = 2;     // once is a coincidence
+export const CASCADE_RESERVE = 2;       // slots the search does not get to fill on its own
+
 export const MEMORY_SCHEMA_VERSION = 3;
-export const MEMORY_KINDS = ['decision', 'fact', 'preference', 'question'];
+// An aberration is the one kind that is not knowledge. It is a claim the room decided is false:
+// a hallucination, an unfounded assertion, a distortion, or a memory that drifted away from what
+// the project actually settled. It is kept because it is worth training against, and it is kept
+// out of every turn because a room that recalls its own hallucinations repeats them.
+export const ABERRATION = 'aberration';
+export const MEMORY_KINDS = ['decision', 'fact', 'preference', 'question', ABERRATION];
+// What the room will hand an agent: knowledge that still stands. Everything else is archive.
+export const STANDING_KINDS = MEMORY_KINDS.filter((kind) => kind !== ABERRATION);
+
+// The dedup key. An aberration almost always quotes the claim it refutes word for word, so on a
+// shared key the archive would silently drop the refutation as a duplicate of the thing it is
+// refuting. Aberrations are keyed in their own space: one of each still dedupes, and a false
+// claim can sit beside the note it takes down.
+export function memoryKey(kind, text) {
+  const norm = normalizeMemory(text);
+  return kind === ABERRATION ? `${ABERRATION}:${norm}` : norm;
+}
 
 // Words that carry no meaning for recall, in the two languages the rooms speak.
 const STOPWORDS = new Set(('the and for with that this from what which where when have has are was were will would could should about into your you our their there here they them then than also just like only over under some any all not but can does did done been being make made use used using please into onto ' +
@@ -112,6 +141,10 @@ export class RoomMemory {
     this.#setMeta = this.#db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');
     this.#insert = this.#db.prepare('INSERT OR IGNORE INTO entries (sequence, event_id, timestamp, type, role, sender, target, message_id, text) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
     if (this.#metaValue('schema') === null) this.#setMeta.run('schema', String(MEMORY_SCHEMA_VERSION));
+    // When this room started keeping the trail of which memories travel together. Counters from
+    // before that day are real; the company they kept was never written down, and a card must be
+    // able to say so instead of showing an empty list as if a memory had always been alone.
+    if (this.#metaValue('recalls_since') === null) this.#setMeta.run('recalls_since', new Date().toISOString());
   }
 
   #createSchema() {
@@ -145,7 +178,9 @@ export class RoomMemory {
         from_sequence INTEGER NOT NULL,
         through_sequence INTEGER NOT NULL,
         sources TEXT NOT NULL,
-        agent TEXT NOT NULL
+        agent TEXT NOT NULL,
+        recalled INTEGER NOT NULL DEFAULT 0,
+        last_recalled TEXT
       );
       CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(text, kind, content='memories', content_rowid='id', tokenize='trigram');
       CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
@@ -154,9 +189,30 @@ export class RoomMemory {
       CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
         INSERT INTO memories_fts(memories_fts, rowid, text, kind) VALUES ('delete', old.id, old.text, old.kind);
       END;
+      -- Every time the room reaches for a memory, one row. A turn recalls several at once and
+      -- they share a batch, so the archive knows not only how often a note was used but which
+      -- other notes travelled with it: two memories that keep arriving together are talking.
+      CREATE TABLE IF NOT EXISTS recalls (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        memory_id INTEGER NOT NULL,
+        batch TEXT NOT NULL,
+        at TEXT NOT NULL,
+        agent TEXT,
+        turn TEXT,
+        via TEXT NOT NULL DEFAULT 'search'
+      );
+      CREATE INDEX IF NOT EXISTS recalls_memory ON recalls(memory_id, id DESC);
+      CREATE INDEX IF NOT EXISTS recalls_batch ON recalls(batch);
       CREATE TABLE IF NOT EXISTS entry_vectors (sequence INTEGER PRIMARY KEY, model TEXT NOT NULL, vec BLOB NOT NULL);
       CREATE TABLE IF NOT EXISTS memory_vectors (id INTEGER PRIMARY KEY, model TEXT NOT NULL, vec BLOB NOT NULL);
     `);
+    // Older files have recalls without a reason; everything written before the cascade existed
+    // was found by the search, which is what the default says.
+    try { this.#db.exec("ALTER TABLE recalls ADD COLUMN via TEXT NOT NULL DEFAULT 'search'"); } catch { /* already there */ }
+    // Older files predate the recall counters; adding them is harmless and keeps the notes.
+    for (const column of ['recalled INTEGER NOT NULL DEFAULT 0', 'last_recalled TEXT']) {
+      try { this.#db.exec(`ALTER TABLE memories ADD COLUMN ${column}`); } catch { /* already there */ }
+    }
     // Older files: each entry remembers whether it was distilled (the old watermark seeds it).
     const entryColumns = this.#db.prepare('PRAGMA table_info(entries)').all().map((column) => column.name);
     if (entryColumns.length && !entryColumns.includes('distilled')) {
@@ -168,6 +224,16 @@ export class RoomMemory {
     const columns = this.#db.prepare('PRAGMA table_info(memories)').all().map((column) => column.name);
     if (!columns.includes('origin')) this.#db.exec("ALTER TABLE memories ADD COLUMN origin TEXT NOT NULL DEFAULT 'distilled'");
     if (!columns.includes('message_id')) this.#db.exec('ALTER TABLE memories ADD COLUMN message_id TEXT');
+    // Aberrations, and what they do to the notes they refute. A memory's text is never rewritten
+    // here: what a refutation changes is its standing, not what it said.
+    //   contradicts  on an aberration, the note it refutes
+    //   correction   on an aberration, what is true instead, when the room knows
+    //   detector     who caught it: a person, the archivist, or a watcher
+    //   confidence   0..1 from whoever caught it
+    //   refuted_by   on a note, the aberration that took it out of circulation
+    for (const column of ['contradicts INTEGER', 'correction TEXT', 'detector TEXT', 'confidence REAL', 'refuted_by INTEGER']) {
+      if (!columns.includes(column.split(' ')[0])) this.#db.exec(`ALTER TABLE memories ADD COLUMN ${column}`);
+    }
   }
 
   /* ---------- embeddings ---------- */
@@ -324,6 +390,15 @@ export class RoomMemory {
     }
   }
   undistilledCount() { return this.#db.prepare('SELECT COUNT(*) AS n FROM entries WHERE distilled = 0').get().n; }
+
+  // The exchanges a note says it came from, for anyone checking whether they say what it says.
+  entriesAt(sequences = []) {
+    if (!this.#db) return [];
+    const wanted = [...new Set(sequences.filter((n) => Number.isInteger(n)))].slice(0, 60);
+    if (!wanted.length) return [];
+    const fetch = this.#db.prepare('SELECT sequence, sender, text FROM entries WHERE sequence = ?');
+    return wanted.map((sequence) => fetch.get(sequence)).filter(Boolean);
+  }
   memoryCount() { return this.#db.prepare('SELECT COUNT(*) AS n FROM memories').get().n; }
 
   // The next batch to distil: the NEWEST entries nobody has distilled, cut at a
@@ -347,7 +422,7 @@ export class RoomMemory {
   // Stores distilled memories; a note already held (same text, ignoring case
   // and punctuation) is not stored twice. Returns how many were new.
   addMemories(list, { agent, fromSequence, throughSequence, origin = 'distilled', messageId = null }) {
-    const insert = this.#db.prepare('INSERT OR IGNORE INTO memories (created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, message_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    const insert = this.#db.prepare('INSERT OR IGNORE INTO memories (created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, message_id, correction, detector, confidence) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
     const now = new Date().toISOString();
     let added = 0;
     this.#db.exec('BEGIN');
@@ -355,10 +430,25 @@ export class RoomMemory {
       for (const memory of list) {
         const text = this.#guard(String(memory.text ?? '').trim());
         if (!text) continue;
-        const kind = MEMORY_KINDS.includes(memory.kind) ? memory.kind : 'fact';
+        // An unknown kind is dropped, never filed as a fact: with one kind in the list that is
+        // not knowledge, a typo either way would put a hallucination where the room trusts it.
+        if (!MEMORY_KINDS.includes(memory.kind)) continue;
+        const kind = memory.kind;
         const sources = (Array.isArray(memory.sources) ? memory.sources : []).filter((n) => Number.isInteger(n));
-        const result = insert.run(now, kind, text, normalizeMemory(text), fromSequence ?? sources[0] ?? 0, throughSequence ?? sources.at(-1) ?? 0, JSON.stringify(sources), agent, origin, messageId);
+        // Only an aberration carries a correction, and only ever as the archivist heard it: the
+        // note that refutes it is wired up later, by whoever can name the id.
+        const aberrant = kind === ABERRATION;
+        const correction = aberrant ? this.#guard(String(memory.correction ?? '').trim()) || null : null;
+        const result = insert.run(now, kind, text, memoryKey(kind, text), fromSequence ?? sources[0] ?? 0, throughSequence ?? sources.at(-1) ?? 0, JSON.stringify(sources), agent, origin, messageId, correction, aberrant ? (memory.detector ?? agent) : null, aberrant ? (Number.isFinite(memory.confidence) ? memory.confidence : null) : null);
         added += Number(result.changes ?? 0);
+        if (aberrant && Number(result.changes ?? 0)) {
+          const id = Number(result.lastInsertRowid);
+          const target = this.#refutedBy(text);
+          if (target) {
+            this.#db.prepare('UPDATE memories SET contradicts = ? WHERE id = ?').run(target, id);
+            this.#db.prepare('UPDATE memories SET refuted_by = ? WHERE id = ? AND refuted_by IS NULL').run(id, target);
+          }
+        }
       }
       this.#db.exec('COMMIT');
     } catch (error) {
@@ -368,6 +458,83 @@ export class RoomMemory {
     return added;
   }
 
+  // An aberration filed by the archivist cannot name an id: the archivist reads exchanges, not
+  // the archive. So when the room records that a claim is false, the store looks for the note
+  // already standing that says the same thing, and wires the two together. Without this the
+  // room quarantines the refutation and goes on handing agents the very claim it just recorded
+  // as false, which is the one outcome all of this exists to prevent.
+  //
+  // The bar is high on purpose: almost every distinctive word of one has to be in the other.
+  // A merely related note is not the same claim, and taking down the wrong one is worse than
+  // taking down none.
+  #refutedBy(text) {
+    const terms = new Set(normalizeMemory(text).split(' ').filter((word) => word.length > 2));
+    if (terms.size < 3) return null;
+    let best = null;
+    const standing = this.#db.prepare(`SELECT id, text FROM memories WHERE kind != '${ABERRATION}' AND refuted_by IS NULL ORDER BY id DESC LIMIT 200`).all();
+    for (const row of standing) {
+      const other = new Set(normalizeMemory(row.text).split(' ').filter((word) => word.length > 2));
+      if (other.size < 3) continue;
+      let shared = 0;
+      for (const term of other) if (terms.has(term)) shared += 1;
+      const overlap = shared / Math.min(terms.size, other.size);
+      if (overlap >= 0.8 && (!best || overlap > best.overlap)) best = { id: row.id, overlap };
+    }
+    return best?.id ?? null;
+  }
+
+  // Flagging an aberration is two writes that have to happen together: the claim is filed, and
+  // whatever it refutes stops being handed to agents. A refutation does not rewrite what a note
+  // said; it takes it out of circulation, which is reversible, where an edit would not be.
+  flagAberration({ text, correction = null, contradicts = null, sources = [], agent = 'eyecat', detector = 'eyecat', confidence = null, fromSequence = null, throughSequence = null }) {
+    if (!this.#db) return null;
+    const claim = this.#guard(String(text ?? '').trim());
+    if (!claim) return null;
+    const cites = (Array.isArray(sources) ? sources : []).filter((n) => Number.isInteger(n));
+    const refuted = Number.isInteger(contradicts) ? this.#db.prepare(`SELECT id, kind FROM memories WHERE id = ? AND kind != '${ABERRATION}'`).get(contradicts) : null;
+    this.#db.exec('BEGIN');
+    try {
+      const result = this.#db.prepare('INSERT OR IGNORE INTO memories (created, kind, text, norm, from_sequence, through_sequence, sources, agent, origin, contradicts, correction, detector, confidence) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+        .run(new Date().toISOString(), ABERRATION, claim, memoryKey(ABERRATION, claim), fromSequence ?? cites[0] ?? 0, throughSequence ?? cites.at(-1) ?? 0, JSON.stringify(cites), agent, 'flagged', refuted?.id ?? null, this.#guard(String(correction ?? '').trim()) || null, detector, Number.isFinite(confidence) ? confidence : null);
+      if (!Number(result.changes ?? 0)) { this.#db.exec('ROLLBACK'); return null; }   // already known
+      const id = Number(result.lastInsertRowid);
+      if (refuted) this.#db.prepare('UPDATE memories SET refuted_by = ? WHERE id = ? AND refuted_by IS NULL').run(id, refuted.id);
+      this.#db.exec('COMMIT');
+      return { id, refuted: refuted?.id ?? null };
+    } catch (error) {
+      this.#db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  // The other direction, for when the room was wrong about being wrong: the aberration goes and
+  // whatever it took out of circulation stands again.
+  clearAberration(id) {
+    if (!this.#db) return null;
+    const row = this.#db.prepare(`SELECT id, text, contradicts FROM memories WHERE id = ? AND kind = '${ABERRATION}'`).get(Number(id));
+    if (!row) return null;
+    this.#db.exec('BEGIN');
+    try {
+      this.#db.prepare('UPDATE memories SET refuted_by = NULL WHERE refuted_by = ?').run(row.id);
+      this.#db.prepare('DELETE FROM memories WHERE id = ?').run(row.id);
+      this.#db.prepare('DELETE FROM memory_vectors WHERE id = ?').run(row.id);
+      this.#db.exec('COMMIT');
+      return { id: row.id, text: row.text, restored: row.contradicts ?? null };
+    } catch (error) {
+      this.#db.exec('ROLLBACK');
+      throw error;
+    }
+  }
+
+  // Everything the room has decided is false, newest first, with what it took down.
+  aberrations({ limit = 50 } = {}) {
+    if (!this.#db) return [];
+    return this.#db.prepare(`SELECT a.id, a.created, a.text, a.correction, a.detector, a.confidence, a.contradicts, a.sources, a.agent, m.text AS contradictsText
+      FROM memories a LEFT JOIN memories m ON m.id = a.contradicts
+      WHERE a.kind = '${ABERRATION}' ORDER BY a.id DESC LIMIT ?`).all(limit)
+      .map((row) => ({ ...row, sources: JSON.parse(row.sources) }));
+  }
+
   // Exact text of a stretch of the ledger, capped so a tool answer stays readable.
   range({ from = 1, through = Number.MAX_SAFE_INTEGER, limit = 40, maxChars = 12000 } = {}) {
     const rows = this.#db.prepare('SELECT sequence, timestamp, type, role, sender, target, message_id AS messageId, text FROM entries WHERE sequence >= ? AND sequence <= ? ORDER BY sequence LIMIT ?').all(from, through, limit + 1);
@@ -394,6 +561,10 @@ export class RoomMemory {
     this.#db.exec('BEGIN');
     try {
       this.#db.prepare('DELETE FROM memory_vectors WHERE id = ?').run(id);
+      this.#db.prepare('DELETE FROM recalls WHERE memory_id = ?').run(id);
+      // A note quarantined by this one comes back: with the aberration gone there is nothing
+      // holding it out of circulation, and a memory must never be lost to a pointer at nothing.
+      this.#db.prepare('UPDATE memories SET refuted_by = NULL WHERE refuted_by = ?').run(id);
       this.#db.prepare('DELETE FROM memories WHERE id = ?').run(id);
       this.#db.exec('COMMIT');
     } catch (error) { this.#db.exec('ROLLBACK'); throw error; }
@@ -436,10 +607,10 @@ export class RoomMemory {
 
   memories({ limit = 50, kind = null } = {}) {
     if (kind) {
-      return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId FROM memories WHERE kind = ? ORDER BY id DESC LIMIT ?').all(kind, limit)
+      return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, recalled, last_recalled AS lastRecalled, contradicts, correction, detector, confidence, refuted_by AS refutedBy FROM memories WHERE kind = ? ORDER BY id DESC LIMIT ?').all(kind, limit)
         .map((row) => ({ ...row, sources: JSON.parse(row.sources) }));
     }
-    return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId FROM memories ORDER BY id DESC LIMIT ?').all(limit)
+    return this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, recalled, last_recalled AS lastRecalled, contradicts, correction, detector, confidence, refuted_by AS refutedBy FROM memories ORDER BY id DESC LIMIT ?').all(limit)
       .map((row) => ({ ...row, sources: JSON.parse(row.sources) }));
   }
 
@@ -448,14 +619,16 @@ export class RoomMemory {
   // preferences, all from before `beforeSequence` so they add to the window
   // rather than repeat it, within a character budget.
   // `fallback` fills a thin match with the latest decisions and preferences; @madre turns it off to stay honest.
-  recallMemories(text, { beforeSequence = Number.MAX_SAFE_INTEGER, limit = 6, maxChars = 1200, queryVector = null, semanticFloor = 0.45, fallback = true } = {}) {
+  recallMemories(text, { beforeSequence = Number.MAX_SAFE_INTEGER, limit = 6, maxChars = 1200, queryVector = null, semanticFloor = 0.45, fallback = true, track = true, by = null, cascade = true } = {}) {
     if (!this.#db) return [];
     const total = this.memoryCount();
     if (!total) return [];
     const terms = queryTerms(text);
     const semantic = this.#semanticScores('memory_vectors', 'id', queryVector, { beforeSequence, floor: semanticFloor });
     const scores = new Map();
-    const lookup = this.#db.prepare('SELECT m.id FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid WHERE memories_fts MATCH ? AND m.through_sequence < ? LIMIT 500');
+    // Nothing that is false and nothing that has been refuted travels into a turn. This is the
+    // gate: an archive that hands its own hallucinations back to the room repeats them.
+    const lookup = this.#db.prepare(`SELECT m.id FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid WHERE memories_fts MATCH ? AND m.through_sequence < ? AND m.kind != '${ABERRATION}' AND m.refuted_by IS NULL LIMIT 500`);
     for (const term of terms) {
       let rows;
       try { rows = lookup.all(`"${term.replaceAll('"', '""')}"`, beforeSequence); } catch { continue; }
@@ -465,24 +638,159 @@ export class RoomMemory {
     }
     const ids = RoomMemory.fuse(scores, semantic).map(([id]) => id);
     if (fallback && ids.length < 2) {
-      const recent = this.#db.prepare("SELECT id FROM memories WHERE through_sequence < ? AND kind IN ('decision', 'preference') ORDER BY id DESC LIMIT ?").all(beforeSequence, limit);
+      const recent = this.#db.prepare("SELECT id FROM memories WHERE through_sequence < ? AND kind IN ('decision', 'preference') AND refuted_by IS NULL ORDER BY id DESC LIMIT ?").all(beforeSequence, limit);
       for (const { id } of recent) if (!ids.includes(id)) ids.push(id);
     }
-    const fetch = this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId FROM memories WHERE id = ?');
+    const fetch = this.#db.prepare('SELECT id, created, kind, text, from_sequence AS fromSequence, through_sequence AS throughSequence, sources, agent, origin, message_id AS messageId, contradicts, correction, detector, confidence, refuted_by AS refutedBy FROM memories WHERE id = ?');
     const chosen = [];
     let remaining = Math.max(0, maxChars);
-    for (const id of ids) {
-      if (chosen.length >= limit) break;
-      const row = fetch.get(id);
-      if (!row) continue;
+    let cursor = 0;
+    const take = (row, via) => {
       const cost = row.text.length + 24;
-      if (cost > remaining) continue;
+      if (cost > remaining) return false;
       remaining -= cost;
-      chosen.push({ ...row, sources: JSON.parse(row.sources) });
+      chosen.push({ ...row, sources: JSON.parse(row.sources), via });
+      return true;
+    };
+    // What the search itself found, up to a ceiling. The cascade is given the last slots to fill,
+    // and hands back whatever it does not use: association adds to a turn, it never displaces.
+    const fill = (ceiling) => {
+      while (cursor < ids.length && chosen.length < ceiling) {
+        const row = fetch.get(ids[cursor]);
+        cursor += 1;
+        // The semantic side of the search does not go through the gate above, so it is checked
+        // here as well: one path in means one path to keep clean, and there are two.
+        if (!row || row.kind === ABERRATION || row.refutedBy !== null) continue;
+        take(row, 'search');
+      }
+    };
+    const reserve = cascade ? Math.min(CASCADE_RESERVE, Math.max(0, limit - 1)) : 0;
+    fill(limit - reserve);
+    // Spreading activation: what the room has kept carrying alongside what it just found. This is
+    // the one part of recall that owes nothing to how a memory reads — only to what the room has
+    // actually done with it.
+    if (reserve && chosen.length) {
+      const seeds = chosen.map((note) => note.id);
+      for (const mate of this.associates(seeds, { limit: reserve })) {
+        if (chosen.length >= limit) break;
+        const row = fetch.get(mate.id);
+        if (!row || row.kind === ABERRATION || row.refutedBy !== null) continue;
+        if (row.throughSequence >= beforeSequence) continue;   // it is already in the window
+        take(row, 'cascade');
+      }
     }
+    fill(limit);
+    // A note that just travelled into a turn has been used: the archive counts it, so the room
+    // can tell which memories it actually leans on, and why each one came.
+    if (track && chosen.length) this.#markRecalled(chosen.map((note) => ({ id: note.id, via: note.via })), by);
     return chosen.sort((a, b) => a.fromSequence - b.fromSequence || a.id - b.id);
   }
 
+  // What one recall leaves behind: the counters the map reads, and one row per note with the
+  // batch they shared, so the traffic between two memories can be read back later.
+  #markRecalled(entries, by = null) {
+    try {
+      const now = new Date().toISOString();
+      const batch = `${now}/${Math.random().toString(36).slice(2, 10)}`;
+      const agent = by?.agent ? String(by.agent).slice(0, 40) : null;
+      const turn = by?.turn ? String(by.turn).slice(0, 80) : null;
+      const mark = this.#db.prepare('UPDATE memories SET recalled = recalled + 1, last_recalled = ? WHERE id = ?');
+      const log = this.#db.prepare('INSERT INTO recalls (memory_id, batch, at, agent, turn, via) VALUES (?, ?, ?, ?, ?, ?)');
+      this.#db.exec('BEGIN');
+      try {
+        for (const entry of entries) {
+          const id = typeof entry === 'object' ? entry.id : entry;
+          mark.run(now, id);
+          log.run(id, batch, now, agent, turn, (typeof entry === 'object' && entry.via) || 'search');
+        }
+        // The traffic is a record of the recent past, not an archive of its own.
+        this.#db.prepare(`DELETE FROM recalls WHERE id <= (SELECT MAX(id) FROM recalls) - ${RECALL_HISTORY}`).run();
+        this.#db.exec('COMMIT');
+      } catch (error) { this.#db.exec('ROLLBACK'); throw error; }
+    } catch (error) { console.error(`MADRE could not count a recall: ${error.message}`); }
+  }
+
+  // Every turn that reached into the archive, oldest first. These are the chances a memory had
+  // to be the answer; a note nothing carried across many of them is adrift, not new.
+  recallBatches() {
+    if (!this.#db) return [];
+    return this.#db.prepare('SELECT MIN(at) AS at FROM recalls GROUP BY batch ORDER BY at').all().map((row) => row.at);
+  }
+
+  // The day this room started keeping that trail. Counters from before it are real; the turns
+  // behind them were never written down.
+  recallsSince() { return this.#metaValue('recalls_since'); }
+
+  // Which memories keep travelling with these, and how strongly. Only the turns where each was
+  // found by the search itself are counted: a memory that arrived by cascade must never become
+  // the evidence for the next cascade, or the network closes into a clique that carries itself.
+  associates(ids, { floor = CASCADE_FLOOR, minTimes = CASCADE_MIN_TIMES, limit = CASCADE_RESERVE, exclude = [] } = {}) {
+    if (!this.#db) return [];
+    const seeds = [...new Set((ids ?? []).filter((id) => Number.isInteger(id)))];
+    if (!seeds.length || limit <= 0) return [];
+    const blocked = new Set([...seeds, ...(exclude ?? [])]);
+    const holes = seeds.map(() => '?').join(',');
+    const together = this.#db.prepare(`
+      SELECT mine.memory_id AS seed, other.memory_id AS id, COUNT(DISTINCT other.batch) AS times
+      FROM recalls mine JOIN recalls other ON other.batch = mine.batch AND other.memory_id != mine.memory_id
+      WHERE mine.memory_id IN (${holes}) AND mine.via = 'search' AND other.via = 'search'
+      GROUP BY mine.memory_id, other.memory_id
+    `).all(...seeds).filter((row) => !blocked.has(row.id) && Number(row.times) >= minTimes);
+    if (!together.length) return [];
+    // How often each of them was found on its own, for the union underneath the ratio.
+    const involved = [...new Set([...seeds, ...together.map((row) => row.id)])];
+    const alone = new Map(this.#db.prepare(`
+      SELECT memory_id AS id, COUNT(DISTINCT batch) AS times FROM recalls
+      WHERE via = 'search' AND memory_id IN (${involved.map(() => '?').join(',')}) GROUP BY memory_id
+    `).all(...involved).map((row) => [row.id, Number(row.times)]));
+    const best = new Map();
+    for (const row of together) {
+      const times = Number(row.times);
+      const union = (alone.get(row.seed) ?? 0) + (alone.get(row.id) ?? 0) - times;
+      const strength = union > 0 ? times / union : 0;
+      if (strength < floor) continue;
+      const known = best.get(row.id);
+      if (!known || strength > known.strength) best.set(row.id, { id: row.id, strength: Number(strength.toFixed(3)), times, with: row.seed });
+    }
+    return [...best.values()].sort((a, b) => b.strength - a.strength || b.times - a.times).slice(0, limit);
+  }
+
+  // Everything one memory has to say about its own life: how often the room reached for it, who
+  // asked, and which other memories keep arriving in the same turn. A memory that has never been
+  // recalled answers with zeros, which is itself the reading.
+  recallTraffic(id, { limit = 8, together = 8 } = {}) {
+    if (!this.#db) return null;
+    const note = this.#db.prepare('SELECT id, kind, recalled, last_recalled AS lastRecalled, refuted_by AS refutedBy, contradicts FROM memories WHERE id = ?').get(Number(id));
+    if (!note) return null;
+    const recent = this.#db.prepare('SELECT batch, at, agent, turn FROM recalls WHERE memory_id = ? ORDER BY id DESC LIMIT ?').all(note.id, limit);
+    const fired = this.#db.prepare(`
+      SELECT other.memory_id AS id, COUNT(*) AS times, MAX(other.at) AS last
+      FROM recalls mine JOIN recalls other ON mine.batch = other.batch AND other.memory_id != mine.memory_id
+      WHERE mine.memory_id = ? GROUP BY other.memory_id ORDER BY times DESC, last DESC LIMIT ?
+    `).all(note.id, together);
+    // Which of that company is association rather than coincidence: the ones this memory would
+    // now bring along with it into a turn.
+    const pulls = new Map(this.associates([note.id], { limit: 24 }).map((mate) => [mate.id, mate.strength]));
+    const askers = this.#db.prepare('SELECT agent, COUNT(*) AS times FROM recalls WHERE memory_id = ? AND agent IS NOT NULL GROUP BY agent ORDER BY times DESC').all(note.id);
+    // What a refutation did, from either end: the aberration knows what it took down, and a note
+    // taken down knows what took it.
+    const refutes = this.#db.prepare('SELECT id, kind, text FROM memories WHERE refuted_by = ?').all(note.id)
+      .map((row) => ({ ...row, text: row.text.slice(0, 200) }));
+    const refutedBy = note.refutedBy ? this.#db.prepare('SELECT id, kind, text FROM memories WHERE id = ?').get(note.refutedBy) : null;
+    return {
+      id: note.id,
+      kind: note.kind,
+      recalled: Number(note.recalled ?? 0),
+      lastRecalled: note.lastRecalled ?? null,
+      since: this.#metaValue('recalls_since'),
+      recent: recent.map((row) => ({ at: row.at, agent: row.agent, turn: row.turn, batch: row.batch })),
+      fired: fired.map((row) => ({ id: row.id, times: Number(row.times), last: row.last, strength: pulls.get(row.id) ?? null, cascades: pulls.has(row.id) })),
+      askers: askers.map((row) => ({ agent: row.agent, times: Number(row.times) })),
+      refutes,
+      refutedBy: refutedBy ? { ...refutedBy, text: refutedBy.text.slice(0, 200) } : null,
+    };
+  }
+
   #metaValue(key) { return this.#meta.get(key)?.value ?? null; }
 
   // The last ledger sequence this index has seen, indexed or not.