@jossuealcala/madre 0.3.2 → 0.4.0

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.

package/src/modules/ahp.mjs

@@ -2,9 +2,10 @@
 // command. Verified project state, checkpoints and handoffs in .ahp/.
 
 import { join, resolve } from 'node:path';
+import { t } from '../i18n.mjs';
 import { realpath } from 'node:fs/promises';
 import { defineModule } from './sdk.mjs';
-import { readJson, gitToplevel, findOnPath } from './helpers.mjs';
+import { readJson, gitToplevel, findOnPath, packageVersion } from './helpers.mjs';
 
 // AHP+ platform names for the agents MADRE knows about. Gemini has no AHP+
 // adapter yet, so it is simply not requested.
@@ -14,14 +15,14 @@ const VERSION = '1.4.1';
 
 async function detect(projectRoot) {
   const manifest = await readJson(join(projectRoot, '.ahp', 'manifest.json'));
-  if (!manifest) return { installed: false };
-  const pinned = await readJson(join(projectRoot, 'node_modules', '@jossuealcala', 'ahp-plus', 'package.json'));
+  if (!manifest) return { installed: false, detail: t('not in this project') };
+  const pinned = await packageVersion(PACKAGE, { projectRoot });
   return {
     installed: true,
-    version: pinned?.version ?? null,
+    version: pinned ?? null,
     protocolVersion: manifest.protocol_version ?? null,
     projectId: manifest.project_id ?? null,
-    detail: [pinned?.version ? `cli ${pinned.version}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
+    detail: [pinned ? `cli ${pinned}` : null, manifest.protocol_version ? `protocol ${manifest.protocol_version}` : null].filter(Boolean).join(' · '),
   };
 }
 
@@ -52,13 +53,14 @@ export default defineModule({
   name: 'AHP+',
   vendor: 'Agent Handoff Protocol Plus',
   package: PACKAGE,
-  version: VERSION,
+  tracks: { name: PACKAGE, npm: PACKAGE },
   summary: 'Verified project state, checkpoints and handoffs between AI sessions, stored in .ahp/ next to your code.',
+  requires: ['the project is a git repository', 'npx on the PATH of the terminal MADRE was started from'],
   creates: ['.ahp/ with manifest, sessions, handoffs and evidence', 'a project-local pin of @jossuealcala/ahp-plus', 'IDE adapter files for the detected agents'],
   detect, preflight, installCommand,
   async status(ctx) {
     const status = await detect(ctx.projectRoot);
     const plan = installCommand({ agents: ctx.agents });
-    return { status, preflight: await preflight(ctx.projectRoot), install: { display: plan.display, platforms: plan.platforms } };
+    return { status, runs: [{ name: PACKAGE, version: await packageVersion(PACKAGE, { projectRoot: ctx.projectRoot }), target: VERSION }], preflight: await preflight(ctx.projectRoot), install: { display: plan.display, platforms: plan.platforms } };
   },
 });

package/src/modules/ash.mjs

@@ -0,0 +1,36 @@
+// Ash: MADRE's token economy.
+//
+// It used to be a text compressor that rewrote the human's message before sending it. That was
+// retired: it altered the one thing nobody asked it to touch, it was lossy, and measured against
+// a real turn it saved a fifth of one per cent. Everything it claimed to do is now done without
+// touching a word anyone wrote.
+//
+// Most of the economy needs no switch and is always on, because none of it loses anything: the
+// briefing carries only the blocks a turn can use, what never changes is read first so a CLI can
+// take it from its own cache, the transcript window holds still instead of sliding, and every
+// turn is weighed against what it was actually charged.
+//
+// What is left to decide is the one thing that changes how an agent answers rather than what it
+// is asked: whether to ask for compact prose. Output is the dearer half of a bill, so this is
+// the switch worth having, and it is the human's to make.
+
+import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
+
+export default defineModule({
+  id: 'ash',
+  configKey: 'ash',
+  name: 'Ash',
+  vendor: 'MADRE',
+  version: '1.0.0',
+  summary: 'Asks every agent for compact prose. The rest of the economy is always on: the briefing carries only what a turn can use, what never changes is read first so a cache can match it, and the transcript holds still instead of sliding.',
+  creates: ['nothing in the project', 'a switch in ~/.pulse/config.json'],
+  card: 'ash',
+  async status(ctx) {
+    return {
+      status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? t('on · agents answer in compact prose') : t('off · agents answer at their own length') },
+      install: { display: ctx.settings.enabled ? 'stop asking for compact replies' : 'ask every agent for compact replies', platforms: [] },
+    };
+  },
+  async onToggle(ctx, enabled) { ctx.room.setAsh(enabled); return null; },
+});

package/src/modules/git-pulse.mjs

@@ -2,21 +2,23 @@
 // Nothing to switch: it is on wherever the project is a git repository.
 
 import { defineModule } from './sdk.mjs';
+import { t } from '../i18n.mjs';
 import { gitToplevel } from './helpers.mjs';
 
 export default defineModule({
   id: 'git-pulse',
   name: 'Git Pulse',
   vendor: 'MADRE',
-  summary: 'Type /git in the composer to bring the repository\'s branch, uncommitted changes, recent commits or diff stats into the room as a shared fact card, read-only, without spending an agent turn.',
-  creates: ['nothing: read-only git commands run inside the project'],
+  version: '1.0.0',
+  summary: 'Brings the repository into the room: /git posts the branch, the uncommitted changes, the recent commits or the diff stats as a shared fact card, without spending an agent turn.',
+  creates: ['nothing by itself \u00b7 the read commands only read', 'a local commit only when you type /git commit', 'a push only when you type /git push confirm, after it shows what would leave'],
   requires: ['the project is a git repository'],
-  commands: ['/git status', '/git log [n]', '/git diff', '/git branches'],
+  commands: ['/git status', '/git log [n]', '/git diff', '/git branches', '/git commit "message"', '/git push [confirm]'],
   card: 'fixed',
   async status(ctx) {
     const isRepo = await gitToplevel(ctx.projectRoot);
     return {
-      status: { installed: Boolean(isRepo), detail: isRepo ? 'on · project is a git repository' : 'not a git repository' },
+      status: { installed: Boolean(isRepo), detail: isRepo ? t('on · project is a git repository') : t('not a git repository') },
       preflight: isRepo ? { ok: true, problems: [] } : { ok: false, problems: ['Run `git init` in the project to use /git.'] },
       install: { display: '/git in the composer', platforms: [] },
       fixed: true,

package/src/modules/helpers.mjs

@@ -28,3 +28,34 @@ export async function findOnPath(name, envPath = process.env.PATH ?? '') {
   }
   return null;
 }
+
+// The version of an npm package that is actually on this machine, found by reading its
+// package.json: up the node_modules chain from the project first, then npm's global root.
+// Nothing is executed. Asking a package for its own --version through npx is not a test of
+// anything: when the package is not installed at all, npx answers with npm's version and exits
+// cleanly, which is how PLAYWRIGHT came to report a browser server that was never there.
+let globalRoot;
+async function npmGlobalRoot(env = process.env) {
+  if (globalRoot !== undefined) return globalRoot;
+  try { const { stdout } = await execFileAsync('npm', ['root', '-g'], { env, timeout: 10000 }); globalRoot = stdout.trim() || null; }
+  catch { globalRoot = null; }
+  return globalRoot;
+}
+
+export async function packageVersion(name, { projectRoot = process.cwd(), env = process.env } = {}) {
+  const parts = name.split('/');
+  let directory = projectRoot;
+  for (let depth = 0; depth < 24; depth += 1) {
+    const found = await readJson(join(directory, 'node_modules', ...parts, 'package.json'));
+    if (found?.version) return found.version;
+    const parent = join(directory, '..');
+    if (parent === directory) break;
+    directory = parent;
+  }
+  const root = await npmGlobalRoot(env);
+  if (root) {
+    const found = await readJson(join(root, ...parts, 'package.json'));
+    if (found?.version) return found.version;
+  }
+  return null;
+}