@h-rig/memory-plugin 0.0.6-alpha.156

package/dist/src/cli.js

@@ -0,0 +1,1500 @@
+// @bun
+// packages/memory-plugin/src/cli.ts
+import { existsSync } from "fs";
+import { randomUUID } from "crypto";
+
+// packages/memory-plugin/src/db.ts
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+import {
+  NO_MATCH_RETRIEVAL_CANONICAL_KEY
+} from "@rig/contracts";
+var SCHEMA_STATEMENTS = [
+  `CREATE TABLE IF NOT EXISTS memory_events (
+    event_id TEXT PRIMARY KEY,
+    event_type TEXT NOT NULL,
+    canonical_key TEXT NOT NULL,
+    summary TEXT,
+    kind TEXT,
+    category TEXT,
+    confidence REAL,
+    source_run_id TEXT,
+    source_task_id TEXT,
+    branch TEXT,
+    source_canonical_key TEXT,
+    replacement_canonical_key TEXT,
+    retrieval_query TEXT,
+    retrieval_rank INTEGER,
+    feedback_outcome TEXT,
+    details_json TEXT,
+    created_at TEXT NOT NULL
+  )`,
+  `CREATE TABLE IF NOT EXISTS memory_items (
+    canonical_key TEXT PRIMARY KEY,
+    summary TEXT NOT NULL,
+    kind TEXT,
+    category TEXT,
+    status TEXT NOT NULL,
+    confidence REAL NOT NULL,
+    source_run_id TEXT,
+    source_task_id TEXT,
+    branch TEXT,
+    details_json TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    last_event_id TEXT NOT NULL,
+    superseded_by TEXT,
+    embedding TEXT
+  )`,
+  `CREATE TABLE IF NOT EXISTS memory_links (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_key TEXT NOT NULL,
+    to_key TEXT NOT NULL,
+    relation TEXT NOT NULL,
+    source_event_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`,
+  `CREATE TABLE IF NOT EXISTS task_runs (
+    run_id TEXT PRIMARY KEY,
+    task_id TEXT,
+    branch TEXT,
+    first_event_id TEXT,
+    last_event_id TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  )`,
+  `CREATE TABLE IF NOT EXISTS retrieval_feedback (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    canonical_key TEXT NOT NULL,
+    outcome TEXT NOT NULL,
+    retrieval_rank INTEGER,
+    source_run_id TEXT,
+    source_task_id TEXT,
+    query_text TEXT,
+    source_event_id TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`
+];
+var MEMORY_EVENT_COLUMNS = [
+  ["summary", "TEXT"],
+  ["kind", "TEXT"],
+  ["category", "TEXT"],
+  ["confidence", "REAL"],
+  ["source_run_id", "TEXT"],
+  ["source_task_id", "TEXT"],
+  ["branch", "TEXT"],
+  ["source_canonical_key", "TEXT"],
+  ["replacement_canonical_key", "TEXT"],
+  ["retrieval_query", "TEXT"],
+  ["retrieval_rank", "INTEGER"],
+  ["feedback_outcome", "TEXT"],
+  ["details_json", "TEXT"]
+];
+var MEMORY_ITEM_COLUMNS = [
+  ["kind", "TEXT"],
+  ["category", "TEXT"],
+  ["branch", "TEXT"],
+  ["details_json", "TEXT"],
+  ["superseded_by", "TEXT"],
+  ["embedding", "TEXT"]
+];
+function jsonText(value) {
+  if (value == null) {
+    return null;
+  }
+  return JSON.stringify(value);
+}
+function parseJsonRecord(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return null;
+  }
+  return JSON.parse(value);
+}
+function parseEmbedding(value) {
+  if (typeof value !== "string" || value.length === 0) {
+    return null;
+  }
+  return JSON.parse(value);
+}
+function rowString(row, key) {
+  const value = row[key];
+  return value == null ? null : String(value);
+}
+function eventSummary(event) {
+  return "summary" in event ? event.summary : null;
+}
+function eventKind(event) {
+  return "kind" in event ? event.kind : null;
+}
+function eventCategory(event) {
+  return "category" in event ? event.category ?? null : null;
+}
+function eventConfidence(event) {
+  return "confidence" in event ? event.confidence : null;
+}
+function eventDetails(event) {
+  return "details" in event ? event.details ?? null : null;
+}
+function eventSourceCanonicalKey(event) {
+  return "sourceCanonicalKey" in event ? event.sourceCanonicalKey : null;
+}
+function eventReplacementCanonicalKey(event) {
+  return "replacementCanonicalKey" in event ? event.replacementCanonicalKey : null;
+}
+function eventRetrievalQuery(event) {
+  return "retrievalQuery" in event ? event.retrievalQuery ?? null : null;
+}
+function eventRetrievalRank(event) {
+  return "retrievalRank" in event ? event.retrievalRank : null;
+}
+function eventFeedbackOutcome(event) {
+  return "feedbackOutcome" in event ? event.feedbackOutcome : null;
+}
+function normalizeStatement(statement, args) {
+  if (typeof statement === "string") {
+    return { sql: statement, args };
+  }
+  return {
+    sql: statement.sql,
+    args: statement.args ?? args
+  };
+}
+function normalizeBindings(bindings) {
+  return (bindings ?? []).map((binding) => binding === undefined ? null : binding);
+}
+function statementVerb(sql) {
+  const match = sql.trim().match(/^[A-Za-z]+/);
+  return match ? match[0].toUpperCase() : "";
+}
+function isMutationStatement(sql) {
+  return new Set([
+    "ALTER",
+    "ATTACH",
+    "BEGIN",
+    "COMMIT",
+    "CREATE",
+    "DELETE",
+    "DETACH",
+    "DROP",
+    "END",
+    "INSERT",
+    "REINDEX",
+    "RELEASE",
+    "REPLACE",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "UPDATE",
+    "VACUUM"
+  ]).has(statementVerb(sql));
+}
+function executeSqlite(sqlite, statement, args) {
+  const normalized = normalizeStatement(statement, args);
+  const bindings = normalizeBindings(normalized.args);
+  if (isMutationStatement(normalized.sql)) {
+    const result = bindings.length > 0 ? sqlite.run(normalized.sql, ...bindings) : sqlite.run(normalized.sql);
+    return {
+      rows: [],
+      rowsAffected: Number(result.changes)
+    };
+  }
+  const query = sqlite.query(normalized.sql);
+  const rows = bindings.length > 0 ? query.all(...bindings) : query.all();
+  return {
+    rows,
+    rowsAffected: 0
+  };
+}
+function createTransaction(sqlite, mode) {
+  sqlite.run(mode === "write" ? "BEGIN IMMEDIATE" : "BEGIN");
+  let active = true;
+  return {
+    async execute(statement, args) {
+      if (!active) {
+        throw new Error("memory transaction is closed");
+      }
+      return executeSqlite(sqlite, statement, args);
+    },
+    async commit() {
+      if (!active) {
+        return;
+      }
+      sqlite.run("COMMIT");
+      active = false;
+    },
+    async rollback() {
+      if (!active) {
+        return;
+      }
+      sqlite.run("ROLLBACK");
+      active = false;
+    },
+    close() {
+      if (!active) {
+        return;
+      }
+      try {
+        sqlite.run("ROLLBACK");
+      } catch {} finally {
+        active = false;
+      }
+    }
+  };
+}
+function createMemoryDbClient(sqlite) {
+  return {
+    async execute(statement, args) {
+      return executeSqlite(sqlite, statement, args);
+    },
+    async transaction(mode) {
+      return createTransaction(sqlite, mode);
+    },
+    close() {
+      sqlite.close();
+    }
+  };
+}
+async function listColumns(executor, tableName) {
+  const result = await executor.execute(`PRAGMA table_info(${tableName})`);
+  return new Set(result.rows.map((row) => String(row.name)));
+}
+async function ensureColumns(executor, tableName, columns) {
+  const existing = await listColumns(executor, tableName);
+  for (const [columnName, definition] of columns) {
+    if (!existing.has(columnName)) {
+      await executor.execute(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${definition}`);
+    }
+  }
+}
+async function ensureSchema(db) {
+  for (const statement of SCHEMA_STATEMENTS) {
+    await db.client.execute(statement);
+  }
+  await ensureColumns(db.client, "memory_events", MEMORY_EVENT_COLUMNS);
+  await ensureColumns(db.client, "memory_items", MEMORY_ITEM_COLUMNS);
+}
+function toMemoryItemRow(row) {
+  return {
+    canonicalKey: String(row.canonical_key),
+    summary: String(row.summary),
+    kind: rowString(row, "kind"),
+    category: rowString(row, "category"),
+    status: String(row.status),
+    confidence: Number(row.confidence),
+    sourceRunId: rowString(row, "source_run_id"),
+    sourceTaskId: rowString(row, "source_task_id"),
+    branch: rowString(row, "branch"),
+    details: parseJsonRecord(row.details_json),
+    createdAt: String(row.created_at),
+    updatedAt: String(row.updated_at),
+    lastEventId: String(row.last_event_id),
+    supersededBy: rowString(row, "superseded_by"),
+    embedding: parseEmbedding(row.embedding)
+  };
+}
+async function hasMemoryItem(executor, canonicalKey) {
+  const result = await executor.execute({
+    sql: "SELECT 1 AS present FROM memory_items WHERE canonical_key = ? LIMIT 1",
+    args: [canonicalKey]
+  });
+  return result.rows.length > 0;
+}
+async function assertMemoryItemExists(executor, canonicalKey, errorPrefix) {
+  if (!await hasMemoryItem(executor, canonicalKey)) {
+    throw new Error(`${errorPrefix}: unknown memory ${canonicalKey}`);
+  }
+}
+async function upsertTaskRun(executor, event) {
+  if (!event.sourceRunId) {
+    return;
+  }
+  await executor.execute({
+    sql: `
+      INSERT INTO task_runs (
+        run_id,
+        task_id,
+        branch,
+        first_event_id,
+        last_event_id,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(run_id) DO UPDATE SET
+        task_id = COALESCE(excluded.task_id, task_runs.task_id),
+        branch = COALESCE(excluded.branch, task_runs.branch),
+        last_event_id = excluded.last_event_id,
+        updated_at = excluded.updated_at
+    `,
+    args: [
+      event.sourceRunId,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      event.eventId,
+      event.eventId,
+      event.createdAt,
+      event.createdAt
+    ]
+  });
+}
+async function insertEventRow(executor, event) {
+  await executor.execute({
+    sql: `
+      INSERT INTO memory_events (
+        event_id,
+        event_type,
+        canonical_key,
+        summary,
+        kind,
+        category,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        source_canonical_key,
+        replacement_canonical_key,
+        retrieval_query,
+        retrieval_rank,
+        feedback_outcome,
+        details_json,
+        created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `,
+    args: [
+      event.eventId,
+      event.eventType,
+      event.canonicalKey,
+      eventSummary(event),
+      eventKind(event),
+      eventCategory(event),
+      eventConfidence(event),
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      eventSourceCanonicalKey(event),
+      eventReplacementCanonicalKey(event),
+      eventRetrievalQuery(event),
+      eventRetrievalRank(event),
+      eventFeedbackOutcome(event),
+      jsonText(eventDetails(event)),
+      event.createdAt
+    ]
+  });
+}
+async function upsertProjectedMemory(executor, event, status = "active") {
+  await executor.execute({
+    sql: `
+      INSERT INTO memory_items (
+        canonical_key,
+        summary,
+        kind,
+        category,
+        status,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        details_json,
+        created_at,
+        updated_at,
+        last_event_id,
+        superseded_by,
+        embedding
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+      ON CONFLICT(canonical_key) DO UPDATE SET
+        summary = excluded.summary,
+        kind = excluded.kind,
+        category = excluded.category,
+        status = excluded.status,
+        confidence = COALESCE(excluded.confidence, memory_items.confidence),
+        source_run_id = COALESCE(excluded.source_run_id, memory_items.source_run_id),
+        source_task_id = COALESCE(excluded.source_task_id, memory_items.source_task_id),
+        branch = COALESCE(excluded.branch, memory_items.branch),
+        details_json = COALESCE(excluded.details_json, memory_items.details_json),
+        updated_at = excluded.updated_at,
+        last_event_id = excluded.last_event_id,
+        superseded_by = excluded.superseded_by,
+        embedding = excluded.embedding
+    `,
+    args: [
+      event.canonicalKey,
+      eventSummary(event),
+      eventKind(event),
+      eventCategory(event),
+      status,
+      eventConfidence(event) ?? 0,
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      jsonText(eventDetails(event)),
+      event.createdAt,
+      event.createdAt,
+      event.eventId,
+      eventReplacementCanonicalKey(event)
+    ]
+  });
+}
+async function insertMemoryLink(executor, fromKey, toKey, relation, event) {
+  await executor.execute({
+    sql: `
+      INSERT INTO memory_links (from_key, to_key, relation, source_event_id, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `,
+    args: [fromKey, toKey, relation, event.eventId, event.createdAt]
+  });
+}
+async function markSuperseded(executor, event) {
+  const result = await executor.execute({
+    sql: `
+      UPDATE memory_items
+      SET
+        status = 'superseded',
+        superseded_by = ?,
+        updated_at = ?,
+        last_event_id = ?
+      WHERE canonical_key = ?
+    `,
+    args: [eventReplacementCanonicalKey(event), event.createdAt, event.eventId, event.canonicalKey]
+  });
+  if ((result.rowsAffected ?? 0) === 0) {
+    throw new Error(`cannot supersede unknown memory ${event.canonicalKey}`);
+  }
+  if (eventReplacementCanonicalKey(event)) {
+    await insertMemoryLink(executor, event.canonicalKey, eventReplacementCanonicalKey(event), "superseded_by", event);
+  }
+}
+async function activeMemoryItem(executor, canonicalKey) {
+  const result = await executor.execute({
+    sql: `
+      SELECT
+        canonical_key,
+        summary,
+        kind,
+        category,
+        status,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        details_json,
+        created_at,
+        updated_at,
+        last_event_id,
+        superseded_by,
+        embedding
+      FROM memory_items
+      WHERE canonical_key = ?
+      LIMIT 1
+    `,
+    args: [canonicalKey]
+  });
+  const row = result.rows[0];
+  return row ? toMemoryItemRow(row) : null;
+}
+async function markRetracted(executor, event) {
+  const result = await executor.execute({
+    sql: `
+      UPDATE memory_items
+      SET
+        status = 'retracted',
+        updated_at = ?,
+        last_event_id = ?
+      WHERE canonical_key = ?
+    `,
+    args: [event.createdAt, event.eventId, event.canonicalKey]
+  });
+  if ((result.rowsAffected ?? 0) === 0) {
+    throw new Error(`cannot retract unknown memory ${event.canonicalKey}`);
+  }
+}
+async function recordRetrievalFeedback(executor, event) {
+  await executor.execute({
+    sql: `
+      INSERT INTO retrieval_feedback (
+        canonical_key,
+        outcome,
+        retrieval_rank,
+        source_run_id,
+        source_task_id,
+        query_text,
+        source_event_id,
+        created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `,
+    args: [
+      event.canonicalKey,
+      eventFeedbackOutcome(event) ?? "ignored",
+      eventRetrievalRank(event),
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      eventRetrievalQuery(event),
+      event.eventId,
+      event.createdAt
+    ]
+  });
+}
+async function applyReinforcement(executor, event) {
+  const existing = await activeMemoryItem(executor, event.canonicalKey);
+  if (!existing) {
+    throw new Error(`cannot reinforce unknown memory ${event.canonicalKey}`);
+  }
+  if (existing.status !== "active") {
+    throw new Error(`cannot reinforce non-active memory ${event.canonicalKey}`);
+  }
+  const result = await executor.execute({
+    sql: `
+      UPDATE memory_items
+      SET
+        status = 'active',
+        confidence = ?,
+        source_run_id = COALESCE(?, source_run_id),
+        source_task_id = COALESCE(?, source_task_id),
+        branch = COALESCE(?, branch),
+        updated_at = ?,
+        last_event_id = ?,
+        superseded_by = NULL
+      WHERE canonical_key = ?
+    `,
+    args: [
+      eventConfidence(event),
+      event.sourceRunId ?? null,
+      event.sourceTaskId ?? null,
+      event.branch ?? null,
+      event.createdAt,
+      event.eventId,
+      event.canonicalKey
+    ]
+  });
+  if ((result.rowsAffected ?? 0) === 0) {
+    throw new Error(`cannot reinforce unknown memory ${event.canonicalKey}`);
+  }
+}
+async function validateEventTargets(executor, event) {
+  switch (event.eventType) {
+    case "observed":
+      return;
+    case "promoted":
+    case "corrected":
+      await assertMemoryItemExists(executor, event.sourceCanonicalKey, `cannot ${event.eventType}`);
+      return;
+    case "superseded":
+      await assertMemoryItemExists(executor, event.replacementCanonicalKey, "cannot supersede");
+      await assertMemoryItemExists(executor, event.canonicalKey, "cannot supersede");
+      return;
+    case "retracted":
+    case "feedback_recorded":
+      await assertMemoryItemExists(executor, event.canonicalKey, `cannot ${event.eventType}`);
+      return;
+    case "reinforced":
+      await assertMemoryItemExists(executor, event.canonicalKey, "cannot reinforce");
+      return;
+    case "retrieved":
+      if (event.retrievalRank === 0 && event.canonicalKey === NO_MATCH_RETRIEVAL_CANONICAL_KEY) {
+        return;
+      }
+      await assertMemoryItemExists(executor, event.canonicalKey, `cannot ${event.eventType}`);
+      return;
+    default: {
+      const _exhaustive = event;
+      return _exhaustive;
+    }
+  }
+}
+async function openMemoryDb(dbPath) {
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const sqlite = new Database(dbPath, { create: true, strict: true });
+  const client = createMemoryDbClient(sqlite);
+  const db = {
+    path: dbPath,
+    client,
+    async close() {
+      client.close();
+    }
+  };
+  await ensureSchema(db);
+  return db;
+}
+async function applyMemoryEvent(db, event) {
+  const transaction = await db.client.transaction("write");
+  try {
+    await validateEventTargets(transaction, event);
+    await insertEventRow(transaction, event);
+    await upsertTaskRun(transaction, event);
+    switch (event.eventType) {
+      case "observed":
+        await upsertProjectedMemory(transaction, event, "active");
+        break;
+      case "promoted":
+        await upsertProjectedMemory(transaction, event, "active");
+        if (event.sourceCanonicalKey) {
+          await insertMemoryLink(transaction, event.canonicalKey, event.sourceCanonicalKey, "promoted_from", event);
+        }
+        break;
+      case "corrected":
+        await upsertProjectedMemory(transaction, event, "active");
+        if (event.sourceCanonicalKey) {
+          await insertMemoryLink(transaction, event.canonicalKey, event.sourceCanonicalKey, "corrected_from", event);
+        }
+        break;
+      case "superseded":
+        await markSuperseded(transaction, event);
+        break;
+      case "retracted":
+        await markRetracted(transaction, event);
+        break;
+      case "reinforced":
+        await applyReinforcement(transaction, event);
+        break;
+      case "retrieved":
+        break;
+      case "feedback_recorded":
+        await recordRetrievalFeedback(transaction, event);
+        break;
+    }
+    await transaction.commit();
+  } catch (error) {
+    await transaction.rollback();
+    throw error;
+  } finally {
+    transaction.close();
+  }
+}
+async function setMemoryItemEmbedding(db, canonicalKey, embedding) {
+  await db.client.execute({
+    sql: `
+      UPDATE memory_items
+      SET embedding = ?
+      WHERE canonical_key = ?
+    `,
+    args: [JSON.stringify(embedding), canonicalKey]
+  });
+}
+async function getMemoryItemByKey(db, canonicalKey) {
+  const result = await db.client.execute({
+    sql: `
+      SELECT
+        canonical_key,
+        summary,
+        kind,
+        category,
+        status,
+        confidence,
+        source_run_id,
+        source_task_id,
+        branch,
+        details_json,
+        created_at,
+        updated_at,
+        last_event_id,
+        superseded_by,
+        embedding
+      FROM memory_items
+      WHERE canonical_key = ?
+      LIMIT 1
+    `,
+    args: [canonicalKey]
+  });
+  const row = result.rows[0];
+  return row ? toMemoryItemRow(row) : null;
+}
+async function listActiveMemoryItems(db) {
+  const result = await db.client.execute(`
+    SELECT
+      canonical_key,
+      summary,
+      kind,
+      category,
+      status,
+      confidence,
+      source_run_id,
+      source_task_id,
+      branch,
+      details_json,
+      created_at,
+      updated_at,
+      last_event_id,
+      superseded_by,
+      embedding
+    FROM memory_items
+    WHERE status = 'active'
+    ORDER BY canonical_key
+  `);
+  return result.rows.map((row) => toMemoryItemRow(row));
+}
+async function hasMemoryEvent(db, eventId) {
+  const result = await db.client.execute({
+    sql: "SELECT 1 AS present FROM memory_events WHERE event_id = ? LIMIT 1",
+    args: [eventId]
+  });
+  return result.rows.length > 0;
+}
+
+// packages/memory-plugin/src/embed.ts
+import { createHash } from "crypto";
+var DEFAULT_EMBEDDING_API_BASE_URL = "https://api.openai.com/v1";
+var DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+var DETERMINISTIC_EMBEDDER_MODE = "deterministic";
+var DETERMINISTIC_VECTOR_DIMS = 32;
+var MISSING_MEMORY_EMBEDDER_WARNING = "Shared memory embeddings disabled: OPENAI_API_KEY is not set. Continuing with lexical-only memory.";
+var missingMemoryEmbedderWarningShown = false;
+function embeddingTextForItem(item) {
+  const parts = [item.summary, item.kind ?? "", item.category ?? "", item.details ? JSON.stringify(item.details) : ""];
+  return parts.filter(Boolean).join(`
+`);
+}
+function tokenizeForDeterministicEmbedding(text) {
+  const tokens = text.toLowerCase().match(/[a-z0-9_./:-]+/g) ?? [];
+  return tokens.length > 0 ? tokens : [text.toLowerCase()];
+}
+function deterministicTokenVector(token) {
+  const hash = createHash("sha256").update(token).digest();
+  const vector = new Array(DETERMINISTIC_VECTOR_DIMS).fill(0);
+  for (let index = 0;index < 8; index += 1) {
+    const slot = (hash[index] ?? 0) % DETERMINISTIC_VECTOR_DIMS;
+    const sign = ((hash[index + 8] ?? 0) & 1) === 0 ? 1 : -1;
+    const magnitude = ((hash[index + 16] ?? 0) + 1) / 256;
+    vector[slot] = (vector[slot] ?? 0) + sign * magnitude;
+  }
+  return vector;
+}
+function normalizeVector(vector) {
+  const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
+  if (norm === 0) {
+    return vector.map(() => 0);
+  }
+  return vector.map((value) => Number((value / norm).toFixed(6)));
+}
+function createDeterministicMemoryEmbedder() {
+  return {
+    async embed(texts) {
+      return texts.map((text) => {
+        const vector = new Array(DETERMINISTIC_VECTOR_DIMS).fill(0);
+        for (const token of tokenizeForDeterministicEmbedding(text)) {
+          const tokenVector = deterministicTokenVector(token);
+          for (let index = 0;index < tokenVector.length; index += 1) {
+            vector[index] = (vector[index] ?? 0) + (tokenVector[index] ?? 0);
+          }
+        }
+        return normalizeVector(vector);
+      });
+    }
+  };
+}
+function embeddingResponseMessage(payload, status) {
+  if (typeof payload === "object" && payload !== null) {
+    const maybeMessage = payload.error?.message;
+    if (maybeMessage) {
+      return maybeMessage;
+    }
+  }
+  return `memory embedding request failed with status ${status}`;
+}
+function createOpenAiMemoryEmbedder(options) {
+  const apiKey = options.apiKey.trim();
+  const model = options.model?.trim() || DEFAULT_EMBEDDING_MODEL;
+  const apiBaseUrl = (options.apiBaseUrl?.trim() || DEFAULT_EMBEDDING_API_BASE_URL).replace(/\/+$/, "");
+  const fetchImpl = options.fetchImpl ?? fetch;
+  if (!apiKey) {
+    throw new Error("memory embedding api key must be non-empty");
+  }
+  return {
+    async embed(texts) {
+      if (texts.length === 0) {
+        return [];
+      }
+      const response = await fetchImpl(`${apiBaseUrl}/embeddings`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          input: texts,
+          model
+        })
+      });
+      const payload = await response.json();
+      if (!response.ok) {
+        throw new Error(embeddingResponseMessage(payload, response.status));
+      }
+      if (!Array.isArray(payload.data) || payload.data.length !== texts.length) {
+        throw new Error(`memory embedding provider returned ${payload.data?.length ?? 0} embeddings for ${texts.length} inputs`);
+      }
+      const byIndex = new Map;
+      for (const row of payload.data) {
+        if (typeof row.index !== "number" || !Array.isArray(row.embedding)) {
+          throw new Error("memory embedding provider returned an invalid response payload");
+        }
+        byIndex.set(row.index, row.embedding);
+      }
+      return texts.map((_text, index) => {
+        const embedding = byIndex.get(index);
+        if (!embedding) {
+          throw new Error(`memory embedding provider omitted embedding ${index}`);
+        }
+        return embedding;
+      });
+    }
+  };
+}
+function createConfiguredMemoryEmbedder(options = {}) {
+  const env = options.env ?? process.env;
+  const mode = env.RIG_MEMORY_EMBEDDER?.trim();
+  if (mode === DETERMINISTIC_EMBEDDER_MODE) {
+    return createDeterministicMemoryEmbedder();
+  }
+  const apiKey = env.OPENAI_API_KEY?.trim();
+  if (!apiKey) {
+    throw new Error("memory embeddings require OPENAI_API_KEY or RIG_MEMORY_EMBEDDER=deterministic");
+  }
+  return createOpenAiMemoryEmbedder({
+    apiKey,
+    model: env.RIG_MEMORY_EMBEDDING_MODEL?.trim() || DEFAULT_EMBEDDING_MODEL,
+    apiBaseUrl: options.apiBaseUrl ?? env.RIG_MEMORY_EMBEDDING_API_BASE_URL?.trim() ?? DEFAULT_EMBEDDING_API_BASE_URL,
+    fetchImpl: options.fetchImpl
+  });
+}
+function warnMissingMemoryEmbedderOnce(warn) {
+  if (missingMemoryEmbedderWarningShown) {
+    return;
+  }
+  missingMemoryEmbedderWarningShown = true;
+  warn(MISSING_MEMORY_EMBEDDER_WARNING);
+}
+function embeddingTargetsForEvent(event) {
+  switch (event.eventType) {
+    case "observed":
+    case "promoted":
+    case "corrected":
+    case "reinforced":
+      return [event.canonicalKey];
+    case "superseded":
+    case "retracted":
+    case "retrieved":
+    case "feedback_recorded":
+      return [];
+  }
+}
+function memoryEventRequiresEmbedding(event) {
+  return embeddingTargetsForEvent(event).length > 0;
+}
+function maybeCreateConfiguredMemoryEmbedder(options = {}, warn = (message) => {
+  console.warn(message);
+}) {
+  const env = options.env ?? process.env;
+  const mode = env.RIG_MEMORY_EMBEDDER?.trim();
+  if (mode === DETERMINISTIC_EMBEDDER_MODE) {
+    return createConfiguredMemoryEmbedder(options);
+  }
+  const apiKey = env.OPENAI_API_KEY?.trim();
+  if (!apiKey) {
+    warnMissingMemoryEmbedderOnce(warn);
+    return null;
+  }
+  return createConfiguredMemoryEmbedder(options);
+}
+async function embedChangedMemoryItems(db, event, embedder) {
+  const targets = [...new Set(embeddingTargetsForEvent(event))];
+  if (targets.length === 0) {
+    return [];
+  }
+  const items = [];
+  for (const canonicalKey of targets) {
+    const item = await getMemoryItemByKey(db, canonicalKey);
+    if (item && item.status === "active") {
+      items.push(item);
+    }
+  }
+  if (items.length === 0) {
+    return [];
+  }
+  const texts = items.map(embeddingTextForItem);
+  const embeddings = await embedder.embed(texts);
+  for (const [index, item] of items.entries()) {
+    const embedding = embeddings[index];
+    if (!embedding) {
+      throw new Error(`missing embedding for ${item.canonicalKey}`);
+    }
+    await setMemoryItemEmbedding(db, item.canonicalKey, embedding);
+  }
+  return texts;
+}
+
+// packages/memory-plugin/src/query.ts
+import {
+  DEFAULT_RUNTIME_MEMORY_RETRIEVAL
+} from "@rig/runtime/control-plane/runtime/context";
+var DEFAULT_RESULT_LIMIT = DEFAULT_RUNTIME_MEMORY_RETRIEVAL.topK;
+var DAY_MS = 24 * 60 * 60 * 1000;
+var MIN_VECTOR_MATCH_SCORE = 0.2;
+function tokenize(text) {
+  return (text.toLowerCase().match(/[a-z0-9_./:-]+/g) ?? []).flatMap((token) => {
+    const split = token.split(/[./:_-]+/).filter(Boolean);
+    return split.length > 0 ? [token, ...split] : [token];
+  });
+}
+function lexicalScore(query, item) {
+  const queryTokens = [...new Set(tokenize(query))];
+  if (queryTokens.length === 0) {
+    return 0;
+  }
+  const haystackTokens = new Set(tokenize(item.summary));
+  let matched = 0;
+  for (const token of queryTokens) {
+    if (haystackTokens.has(token)) {
+      matched += 1;
+    }
+  }
+  return matched / queryTokens.length;
+}
+function cosineSimilarity(left, right) {
+  if (left.length === 0 || left.length !== right.length) {
+    return 0;
+  }
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+  for (let index = 0;index < left.length; index += 1) {
+    const l = left[index] ?? 0;
+    const r = right[index] ?? 0;
+    dot += l * r;
+    leftNorm += l * l;
+    rightNorm += r * r;
+  }
+  if (leftNorm === 0 || rightNorm === 0) {
+    return 0;
+  }
+  return dot / Math.sqrt(leftNorm * rightNorm);
+}
+function recencyScore(item, now) {
+  const updatedAt = Date.parse(item.updatedAt);
+  if (Number.isNaN(updatedAt)) {
+    return 0;
+  }
+  const ageMs = Math.max(0, now.getTime() - updatedAt);
+  return 1 / (1 + ageMs / DAY_MS);
+}
+async function maybeEmbedQuery(items, query, embedder) {
+  if (!items.some((item) => Array.isArray(item.embedding) && item.embedding.length > 0)) {
+    return null;
+  }
+  try {
+    const resolvedEmbedder = embedder ?? createConfiguredMemoryEmbedder();
+    const [queryEmbedding] = await resolvedEmbedder.embed([query]);
+    return queryEmbedding ?? null;
+  } catch {
+    return null;
+  }
+}
+async function queryRelevantMemory(db, input) {
+  const retrieval = input.retrieval ?? DEFAULT_RUNTIME_MEMORY_RETRIEVAL;
+  const now = input.now instanceof Date ? input.now : new Date(input.now ?? Date.now());
+  const items = await listActiveMemoryItems(db);
+  if (items.length === 0) {
+    return [];
+  }
+  const queryEmbedding = await maybeEmbedQuery(items, input.query, input.embedder);
+  const scored = items.map((item) => {
+    const lexical = lexicalScore(input.query, item);
+    const vector = queryEmbedding && item.embedding ? cosineSimilarity(queryEmbedding, item.embedding) : 0;
+    const recency = recencyScore(item, now);
+    const score = retrieval.lexicalWeight * lexical + retrieval.vectorWeight * vector + retrieval.recencyWeight * recency + retrieval.confidenceWeight * item.confidence;
+    return {
+      canonicalKey: item.canonicalKey,
+      summary: item.summary,
+      kind: item.kind,
+      category: item.category,
+      confidence: item.confidence,
+      updatedAt: item.updatedAt,
+      score,
+      lexicalScore: lexical,
+      vectorScore: vector,
+      recencyScore: recency
+    };
+  }).filter((item) => item.lexicalScore > 0 || item.vectorScore >= MIN_VECTOR_MATCH_SCORE).sort((left, right) => right.score - left.score || Date.parse(right.updatedAt) - Date.parse(left.updatedAt) || right.confidence - left.confidence || left.canonicalKey.localeCompare(right.canonicalKey));
+  return scored.slice(0, input.limit ?? retrieval.topK ?? DEFAULT_RESULT_LIMIT);
+}
+function formatMemoryQueryResults(results) {
+  if (results.length === 0) {
+    return "No shared memories matched.";
+  }
+  return results.map((result, index) => `${index + 1}. [${result.canonicalKey}] ${result.summary} (confidence ${result.confidence.toFixed(2)})`).join(`
+`);
+}
+
+// packages/memory-plugin/src/write.ts
+import { nativePushRefWithLease, nativeWriteTreeCommit } from "@rig/runtime/control-plane/native/git-native";
+
+// packages/memory-plugin/src/read.ts
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { nativeFetchRef, nativeReadBlobBytesAtRef } from "@rig/runtime/control-plane/native/git-native";
+import { resolveMonorepoRoot } from "@rig/runtime/control-plane/native/utils";
+var CANONICAL_MEMORY_DB_PATH = "rig/memory/project-memory.db";
+var DEFAULT_READ_DEPS = {
+  fetchRef: nativeFetchRef,
+  readBlobBytesAtRef: nativeReadBlobBytesAtRef,
+  openMemoryDb,
+  makeTempDir: () => mkdtempSync(join(tmpdir(), "memory-sync-read-")),
+  removeDir: (path) => rmSync(path, { recursive: true, force: true })
+};
+function isMissingCanonicalMemoryBlobError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes(`path '${CANONICAL_MEMORY_DB_PATH}' does not exist in`) || message.includes(`path '${CANONICAL_MEMORY_DB_PATH}' exists on disk, but not in`) || message.includes(`pathspec '${CANONICAL_MEMORY_DB_PATH}' did not match any file(s) known to git`);
+}
+async function validateReadableDatabase(dbPath, open) {
+  const db = await open(dbPath);
+  await db.close();
+}
+async function readCanonicalMemoryDb(projectRoot, deps = {}) {
+  const readDeps = { ...DEFAULT_READ_DEPS, ...deps };
+  const repoPath = resolveMonorepoRoot(projectRoot);
+  let baseOid;
+  let remoteUnavailable = false;
+  try {
+    baseOid = readDeps.fetchRef(repoPath, "origin", "main");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const originAbsent = /no such remote|remote (?:'|")?origin(?:'|")? not found/i.test(message);
+    if (!originAbsent) {
+      console.warn(`[rig-memory] canonical project memory unavailable (origin/main): ${message.split(`
+`)[0]} \u2014 starting this run with empty project memory.`);
+    }
+    baseOid = "";
+    remoteUnavailable = true;
+  }
+  const tempDir = readDeps.makeTempDir();
+  const dbPath = join(tempDir, "project-memory.db");
+  let createdFresh = false;
+  try {
+    if (remoteUnavailable) {
+      const db = await readDeps.openMemoryDb(dbPath);
+      await db.close();
+      createdFresh = true;
+    } else {
+      try {
+        const bytes = readDeps.readBlobBytesAtRef(repoPath, baseOid, CANONICAL_MEMORY_DB_PATH);
+        writeFileSync(dbPath, bytes);
+      } catch (error) {
+        if (!isMissingCanonicalMemoryBlobError(error)) {
+          throw error;
+        }
+        const db = await readDeps.openMemoryDb(dbPath);
+        await db.close();
+        createdFresh = true;
+      }
+    }
+    await validateReadableDatabase(dbPath, readDeps.openMemoryDb);
+    return {
+      repoPath,
+      baseOid,
+      dbPath,
+      createdFresh,
+      async cleanup() {
+        readDeps.removeDir(tempDir);
+      }
+    };
+  } catch (error) {
+    readDeps.removeDir(tempDir);
+    throw error;
+  }
+}
+
+// packages/memory-plugin/src/write.ts
+var CANONICAL_MEMORY_DB_PATH2 = "rig/memory/project-memory.db";
+var MAX_PROMOTION_ATTEMPTS = 2;
+var DEFAULT_WRITE_DEPS = {
+  readCanonicalMemoryDb,
+  openMemoryDb,
+  applyMemoryEvent,
+  hasMemoryEvent,
+  embedChangedMemoryItems,
+  writeTreeCommit: nativeWriteTreeCommit,
+  pushRefWithLease: nativePushRefWithLease
+};
+async function promoteCanonicalMemoryEvent(projectRoot, input, deps = {}) {
+  const writeDeps = { ...DEFAULT_WRITE_DEPS, ...deps };
+  let lastError;
+  for (let attempt = 0;attempt < MAX_PROMOTION_ATTEMPTS; attempt += 1) {
+    const snapshot = await writeDeps.readCanonicalMemoryDb(projectRoot);
+    try {
+      const db = await writeDeps.openMemoryDb(snapshot.dbPath);
+      try {
+        if (await writeDeps.hasMemoryEvent(db, input.event.eventId)) {
+          return {
+            outcome: "applied",
+            baseOid: snapshot.baseOid,
+            commitOid: snapshot.baseOid
+          };
+        }
+        await writeDeps.applyMemoryEvent(db, input.event);
+        const embedder = input.embedder ?? (memoryEventRequiresEmbedding(input.event) ? maybeCreateConfiguredMemoryEmbedder() : null);
+        if (embedder) {
+          await writeDeps.embedChangedMemoryItems(db, input.event, embedder);
+        }
+      } finally {
+        await db.close();
+      }
+      const updates = [
+        {
+          path: CANONICAL_MEMORY_DB_PATH2,
+          sourceFilePath: snapshot.dbPath
+        }
+      ];
+      const commitOid = writeDeps.writeTreeCommit(snapshot.repoPath, snapshot.baseOid, updates, input.message ?? `chore(memory): ${input.event.eventType} ${input.event.canonicalKey}`);
+      try {
+        await Promise.resolve(writeDeps.pushRefWithLease(snapshot.repoPath, commitOid, "refs/heads/main", snapshot.baseOid));
+        return {
+          outcome: "applied",
+          baseOid: snapshot.baseOid,
+          commitOid
+        };
+      } catch (error) {
+        lastError = error;
+      }
+    } finally {
+      await snapshot.cleanup();
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "memory promotion failed"));
+}
+
+// packages/memory-plugin/src/cli.ts
+import { NO_MATCH_RETRIEVAL_CANONICAL_KEY as NO_MATCH_RETRIEVAL_CANONICAL_KEY2 } from "@rig/contracts";
+function takeOption(args, option) {
+  const rest = [];
+  let value;
+  for (let index = 0;index < args.length; index += 1) {
+    const current = args[index];
+    if (current === option) {
+      if (value !== undefined) {
+        throw new Error(`Duplicate option ${option}`);
+      }
+      const next = args[index + 1];
+      if (!next || next.startsWith("-")) {
+        throw new Error(`Missing value for ${option}`);
+      }
+      value = next;
+      index += 1;
+      continue;
+    }
+    if (current !== undefined) {
+      rest.push(current);
+    }
+  }
+  return { value, rest };
+}
+function usage(verb) {
+  switch (verb) {
+    case "observe":
+      return "Usage: rig-agent memory observe <canonical-key> <summary> [--kind <kind>] [--category <category>] [--confidence <number>]";
+    case "supersede":
+      return "Usage: rig-agent memory supersede <canonical-key> --replacement <replacement-key>";
+    case "retract":
+      return "Usage: rig-agent memory retract <canonical-key>";
+    case "reinforce":
+      return "Usage: rig-agent memory reinforce <canonical-key> --confidence <number>";
+    case "recall":
+      return "Usage: rig-agent memory recall [query]";
+    default:
+      return [
+        "Usage:",
+        "  rig-agent memory observe <canonical-key> <summary> [--kind <kind>] [--category <category>] [--confidence <number>]",
+        "  rig-agent memory supersede <canonical-key> --replacement <replacement-key>",
+        "  rig-agent memory retract <canonical-key>",
+        "  rig-agent memory reinforce <canonical-key> --confidence <number>",
+        "  rig-agent memory recall [query]"
+      ].join(`
+`);
+  }
+}
+function parseConfidence(raw, fallback) {
+  if (!raw) {
+    return fallback;
+  }
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0 || value > 1) {
+    throw new Error("Confidence must be a number between 0 and 1.");
+  }
+  return value;
+}
+function currentBranch(projectRoot) {
+  const proc = Bun.spawnSync(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd: projectRoot,
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  return proc.exitCode === 0 ? proc.stdout.toString().trim() || "main" : "main";
+}
+function requireRuntimeMemoryContext(runtimeContext) {
+  if (!runtimeContext?.memory) {
+    throw new Error("Shared memory is unavailable without a hydrated runtime-context.json.");
+  }
+  return runtimeContext.memory;
+}
+async function ensureRuntimeMemoryUsable(runtimeContext) {
+  const memory = requireRuntimeMemoryContext(runtimeContext);
+  if (!existsSync(memory.hydratedPath)) {
+    throw new Error(`Shared memory database is missing: ${memory.hydratedPath}`);
+  }
+  const db = await openMemoryDb(memory.hydratedPath);
+  await db.close();
+}
+async function syncRuntimeMemory(runtimeContext, event) {
+  const memory = requireRuntimeMemoryContext(runtimeContext);
+  const db = await openMemoryDb(memory.hydratedPath);
+  try {
+    if (await hasMemoryEvent(db, event.eventId)) {
+      return;
+    }
+    await applyMemoryEvent(db, event);
+    if (memoryEventRequiresEmbedding(event)) {
+      const embedder = maybeCreateConfiguredMemoryEmbedder();
+      if (!embedder) {
+        return;
+      }
+      await embedChangedMemoryItems(db, event, embedder);
+    }
+  } finally {
+    await db.close();
+  }
+}
+async function lookupRelevantMemory(runtimeContext, query) {
+  const memory = requireRuntimeMemoryContext(runtimeContext);
+  const db = await openMemoryDb(memory.hydratedPath);
+  try {
+    return await queryRelevantMemory(db, {
+      query,
+      limit: memory.retrieval.topK,
+      retrieval: memory.retrieval
+    });
+  } finally {
+    await db.close();
+  }
+}
+async function memorySummaryForKey(runtimeContext, canonicalKey) {
+  const memory = requireRuntimeMemoryContext(runtimeContext);
+  const db = await openMemoryDb(memory.hydratedPath);
+  try {
+    const item = await getMemoryItemByKey(db, canonicalKey);
+    return item?.summary ?? null;
+  } finally {
+    await db.close();
+  }
+}
+function formatRelatedMemorySection(results) {
+  return formatMemoryQueryResults(results);
+}
+function defaultRecallQuery(options) {
+  const role = options.runtimeContext?.role?.trim();
+  const scopeTerms = (options.runtimeContext?.scopes ?? []).flatMap((scope) => scope.split("/").slice(-3)).map((term) => term.trim()).filter(Boolean);
+  const validationTerms = (options.runtimeContext?.validation ?? []).map((command) => command.split(/\s+/)[0]?.trim() ?? "").filter(Boolean);
+  const parts = [...new Set([role, ...scopeTerms, ...validationTerms].filter(Boolean))];
+  return parts.join(" ").trim() || options.taskId;
+}
+function assertNoFlagTokens(args, usageText) {
+  if (args.some((arg) => arg.startsWith("-"))) {
+    throw new Error(usageText);
+  }
+}
+function baseEventFields(options, branch) {
+  return {
+    eventId: `memory-${randomUUID()}`,
+    sourceRunId: options.runtimeContext?.runtimeId || options.taskId,
+    sourceTaskId: options.taskId,
+    branch,
+    createdAt: new Date().toISOString()
+  };
+}
+function requestedPayload(verb, mutationKind, canonicalKey, extra) {
+  return {
+    command: verb,
+    mutationKind,
+    canonicalKey,
+    ...extra
+  };
+}
+function mutationKindForVerb(verb) {
+  switch (verb) {
+    case "observe":
+      return "observed";
+    case "supersede":
+      return "superseded";
+    case "retract":
+      return "retracted";
+    case "reinforce":
+      return "reinforced";
+    case "recall":
+      return "retrieved";
+  }
+}
+var DEFAULT_EXECUTE_MEMORY_COMMAND_DEPS = {
+  currentBranch,
+  ensureRuntimeMemoryUsable,
+  syncRuntimeMemory,
+  lookupRelevantMemory,
+  memorySummaryForKey,
+  promoteCanonicalMemoryEvent
+};
+async function executeMemoryCommand(options, deps = {}) {
+  const [verbRaw, ...rest] = options.args;
+  const verb = verbRaw;
+  if (!verb || !["observe", "supersede", "retract", "reinforce", "recall"].includes(verb)) {
+    throw new Error(usage());
+  }
+  const commandDeps = { ...DEFAULT_EXECUTE_MEMORY_COMMAND_DEPS, ...deps };
+  let requested;
+  try {
+    switch (verb) {
+      case "observe": {
+        const kind = takeOption(rest, "--kind");
+        const category = takeOption(kind.rest, "--category");
+        const confidence = takeOption(category.rest, "--confidence");
+        assertNoFlagTokens(confidence.rest, usage("observe"));
+        const [canonicalKey, summary] = confidence.rest;
+        if (!canonicalKey || !summary || confidence.rest.length !== 2) {
+          throw new Error(usage("observe"));
+        }
+        await commandDeps.ensureRuntimeMemoryUsable(options.runtimeContext);
+        const event = {
+          ...baseEventFields(options, commandDeps.currentBranch(options.projectRoot)),
+          eventType: "observed",
+          canonicalKey,
+          summary,
+          kind: kind.value || "fact",
+          category: category.value ?? null,
+          confidence: parseConfidence(confidence.value, 0.7)
+        };
+        requested = requestedPayload("observe", "observed", canonicalKey);
+        await options.eventBus?.emit("memory.command.requested", requested);
+        await commandDeps.promoteCanonicalMemoryEvent(options.projectRoot, { event });
+        await commandDeps.syncRuntimeMemory(options.runtimeContext, event);
+        const relatedResults = await commandDeps.lookupRelevantMemory(options.runtimeContext, summary);
+        const output = [`Observed memory ${canonicalKey}.`, "", "Related shared memories:", formatRelatedMemorySection(relatedResults)].join(`
+`);
+        await options.eventBus?.emit("memory.command.applied", {
+          ...requested,
+          relatedCanonicalKeys: relatedResults.map((result) => result.canonicalKey)
+        });
+        return output;
+      }
+      case "supersede": {
+        const replacement = takeOption(rest, "--replacement");
+        assertNoFlagTokens(replacement.rest, usage("supersede"));
+        const canonicalKey = replacement.rest[0];
+        if (!canonicalKey || !replacement.value || replacement.rest.length !== 1) {
+          throw new Error(usage("supersede"));
+        }
+        await commandDeps.ensureRuntimeMemoryUsable(options.runtimeContext);
+        const event = {
+          ...baseEventFields(options, commandDeps.currentBranch(options.projectRoot)),
+          eventType: "superseded",
+          canonicalKey,
+          replacementCanonicalKey: replacement.value
+        };
+        requested = requestedPayload("supersede", "superseded", canonicalKey, { replacementCanonicalKey: replacement.value });
+        await options.eventBus?.emit("memory.command.requested", requested);
+        const relatedQuery = await commandDeps.memorySummaryForKey(options.runtimeContext, replacement.value) ?? replacement.value;
+        await commandDeps.promoteCanonicalMemoryEvent(options.projectRoot, { event });
+        await commandDeps.syncRuntimeMemory(options.runtimeContext, event);
+        const relatedResults = await commandDeps.lookupRelevantMemory(options.runtimeContext, relatedQuery);
+        const output = [`Superseded memory ${canonicalKey}.`, "", "Related shared memories:", formatRelatedMemorySection(relatedResults)].join(`
+`);
+        await options.eventBus?.emit("memory.command.applied", {
+          ...requested,
+          relatedCanonicalKeys: relatedResults.map((result) => result.canonicalKey)
+        });
+        return output;
+      }
+      case "retract": {
+        const canonicalKey = rest[0];
+        assertNoFlagTokens(rest, usage("retract"));
+        if (!canonicalKey || rest.length !== 1) {
+          throw new Error(usage("retract"));
+        }
+        await commandDeps.ensureRuntimeMemoryUsable(options.runtimeContext);
+        const event = {
+          ...baseEventFields(options, commandDeps.currentBranch(options.projectRoot)),
+          eventType: "retracted",
+          canonicalKey
+        };
+        requested = requestedPayload("retract", "retracted", canonicalKey);
+        await options.eventBus?.emit("memory.command.requested", requested);
+        const relatedQuery = await commandDeps.memorySummaryForKey(options.runtimeContext, canonicalKey) ?? canonicalKey;
+        await commandDeps.promoteCanonicalMemoryEvent(options.projectRoot, { event });
+        await commandDeps.syncRuntimeMemory(options.runtimeContext, event);
+        const relatedResults = await commandDeps.lookupRelevantMemory(options.runtimeContext, relatedQuery);
+        const output = [`Retracted memory ${canonicalKey}.`, "", "Related shared memories:", formatRelatedMemorySection(relatedResults)].join(`
+`);
+        await options.eventBus?.emit("memory.command.applied", {
+          ...requested,
+          relatedCanonicalKeys: relatedResults.map((result) => result.canonicalKey)
+        });
+        return output;
+      }
+      case "reinforce": {
+        const confidence = takeOption(rest, "--confidence");
+        assertNoFlagTokens(confidence.rest, usage("reinforce"));
+        const canonicalKey = confidence.rest[0];
+        if (!canonicalKey || !confidence.value || confidence.rest.length !== 1) {
+          throw new Error(usage("reinforce"));
+        }
+        await commandDeps.ensureRuntimeMemoryUsable(options.runtimeContext);
+        const event = {
+          ...baseEventFields(options, commandDeps.currentBranch(options.projectRoot)),
+          eventType: "reinforced",
+          canonicalKey,
+          confidence: parseConfidence(confidence.value, 0.7)
+        };
+        requested = requestedPayload("reinforce", "reinforced", canonicalKey);
+        await options.eventBus?.emit("memory.command.requested", requested);
+        const relatedQuery = await commandDeps.memorySummaryForKey(options.runtimeContext, canonicalKey) ?? canonicalKey;
+        await commandDeps.promoteCanonicalMemoryEvent(options.projectRoot, { event });
+        await commandDeps.syncRuntimeMemory(options.runtimeContext, event);
+        const relatedResults = await commandDeps.lookupRelevantMemory(options.runtimeContext, relatedQuery);
+        const output = [`Reinforced memory ${canonicalKey}.`, "", "Related shared memories:", formatRelatedMemorySection(relatedResults)].join(`
+`);
+        await options.eventBus?.emit("memory.command.applied", {
+          ...requested,
+          relatedCanonicalKeys: relatedResults.map((result) => result.canonicalKey)
+        });
+        return output;
+      }
+      case "recall": {
+        if (rest.some((arg) => arg.startsWith("--"))) {
+          throw new Error(usage("recall"));
+        }
+        const query = rest.join(" ").trim() || defaultRecallQuery(options);
+        await commandDeps.ensureRuntimeMemoryUsable(options.runtimeContext);
+        requested = requestedPayload("recall", "retrieved", undefined, { query });
+        await options.eventBus?.emit("memory.command.requested", requested);
+        const relatedResults = await commandDeps.lookupRelevantMemory(options.runtimeContext, query);
+        const topResult = relatedResults[0];
+        const retrievedEvent = {
+          ...baseEventFields(options, commandDeps.currentBranch(options.projectRoot)),
+          eventType: "retrieved",
+          canonicalKey: topResult?.canonicalKey ?? NO_MATCH_RETRIEVAL_CANONICAL_KEY2,
+          retrievalQuery: query,
+          retrievalRank: topResult ? 1 : 0
+        };
+        await commandDeps.promoteCanonicalMemoryEvent(options.projectRoot, { event: retrievedEvent });
+        await commandDeps.syncRuntimeMemory(options.runtimeContext, retrievedEvent);
+        await options.eventBus?.emit("memory.command.applied", {
+          ...requested,
+          retrievedCanonicalKeys: relatedResults.map((result) => result.canonicalKey)
+        });
+        return formatRelatedMemorySection(relatedResults);
+      }
+    }
+  } catch (error) {
+    const fallbackRequested = requested ?? requestedPayload(verb, mutationKindForVerb(verb), ["observe", "supersede", "retract", "reinforce"].includes(verb) ? rest[0] : undefined);
+    await options.eventBus?.emit("memory.command.failed", {
+      ...fallbackRequested,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+export {
+  executeMemoryCommand
+};