@causyne/agent 0.0.0-stage → 1.10.0

package/src/cortex/autoCondenser.js

@@ -0,0 +1,192 @@
+import { cortexDb } from './vectorDb.js';
+
+// Diagnostics, off by default: console output during a turn overwrites the
+// prompt's live region. See src/cortex/provisioner.js for the full reason.
+function debugLog(message) {
+  if (process.env.CAUSYNE_DEBUG !== '1') return;
+  process.stderr.write(`[causyne] ${message}\n`);
+}
+
+
+// V5 Cortex — Tiered Auto-Condensation
+//
+// When the sliding window amputates older messages, that knowledge must not
+// simply evaporate: continuity across sessions is what turns a stateless text
+// predictor into something with a useful retained history.
+//
+// The original implementation fired an untracked LLM call on the user's own
+// BYOK key at every single amputation, feeding it the entire dropped chunk —
+// which on a saturated 400,000-character window could cost more than the
+
+// displayed. The answer is not to switch memory formation off; it is to make it
+// tiered:
+//
+//   Tier 1 (always, free)  — a deterministic structural summary is written to
+//                            the Cortex with no LLM involved. The brain always
+//                            learns something, on every provider, at zero cost.
+//   Tier 2 (gated, billed) — semantic LLM condensation, but only when the
+//                            dropped chunk is materially large, capped per task,
+//                            with bounded input and fully tracked usage.
+
+const MAX_CONDENSE_CHARS = 24000;
+const MIN_CHARS_FOR_LLM_PASS = 6000;
+const DEFAULT_MAX_LLM_PASSES_PER_TASK = 3;
+
+function serialiseContent(content) {
+  // An assistant message that only carries tool_calls has no content at all,
+  // and JSON.stringify(undefined) returns undefined rather than a string.
+  if (content == null) return '';
+  return typeof content === 'string' ? content : (JSON.stringify(content) || '');
+}
+
+/**
+ * Tier 1: structural facts extracted without any model call.
+ * Records what was attempted, which files were touched and what failed —
+ * exactly the things the agent asks itself again ten steps later.
+ */
+function buildStructuralSummary(droppedMessages) {
+  const toolCounts = new Map();
+  const touchedPaths = new Set();
+  const failures = [];
+  const userTurns = [];
+
+  for (const msg of droppedMessages) {
+    const content = serialiseContent(msg.content);
+
+    if (msg.role === 'user' && typeof msg.content === 'string' && msg.content.length < 600) {
+      userTurns.push(msg.content.trim());
+    }
+
+    if (msg.role === 'tool') {
+      if (msg.name) toolCounts.set(msg.name, (toolCounts.get(msg.name) || 0) + 1);
+
+      // Absolute paths are the highest-value breadcrumb in a dropped chunk.
+      const paths = content.match(/\/[\w.\-/]+\.[a-zA-Z0-9]{1,6}/g);
+      if (paths) for (const p of paths.slice(0, 6)) touchedPaths.add(p);
+
+      try {
+        const parsed = JSON.parse(content);
+        if (parsed && parsed.success === false && parsed.error) {
+          failures.push(`${msg.name || 'tool'}: ${String(parsed.error).slice(0, 140)}`);
+        }
+      } catch (e) {
+        // Non-JSON tool output carries no structured verdict; skip it.
+      }
+    }
+  }
+
+  const parts = [];
+  if (userTurns.length > 0) {
+    parts.push(`Requests in this segment: ${userTurns.slice(0, 3).join(' | ')}`);
+  }
+  if (toolCounts.size > 0) {
+    const tools = [...toolCounts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([name, count]) => `${name}x${count}`)
+      .join(', ');
+    parts.push(`Tools used: ${tools}`);
+  }
+  if (touchedPaths.size > 0) {
+    parts.push(`Files touched: ${[...touchedPaths].slice(0, 12).join(', ')}`);
+  }
+  if (failures.length > 0) {
+    parts.push(`Failures encountered: ${failures.slice(0, 4).join(' | ')}`);
+  }
+
+  return parts.length > 0 ? parts.join('. ') : '';
+}
+
+/**
+ * @param {Array}  droppedMessages  Messages leaving the active window.
+ * @param {object} llm              Provider used for the optional Tier 2 pass.
+ * @param {object} tokenTracker     Required for Tier 2 so usage is never hidden.
+ * @param {object} options          { maxLlmPasses, passesUsed, enableLlmPass }
+ * @returns {Promise<{ structural: boolean, semantic: boolean }>}
+ */
+export async function condenseAndSave(droppedMessages, llm, tokenTracker = null, options = {}) {
+  const result = { structural: false, semantic: false };
+  if (!droppedMessages || droppedMessages.length === 0) return result;
+
+  // ---- Tier 1: always-on, zero cost -------------------------------------
+  try {
+    const structural = buildStructuralSummary(droppedMessages);
+    if (structural) {
+      await cortexDb.saveCondensedMemory(structural);
+      result.structural = true;
+    }
+  } catch (e) {
+    debugLog(`[Auto-Condenser] Structural condensation failed: ${e.message}`);
+  }
+
+  // ---- Tier 2: gated semantic pass --------------------------------------
+  if (!llm || options.enableLlmPass === false) return result;
+
+  const maxPasses = Number.isInteger(options.maxLlmPasses)
+    ? options.maxLlmPasses
+    : DEFAULT_MAX_LLM_PASSES_PER_TASK;
+  if ((options.passesUsed || 0) >= maxPasses) return result;
+
+  let conversationText = droppedMessages.map(m => {
+    let content = serialiseContent(m.content);
+    // Tool payloads dominate the volume and are the least useful thing to
+    // summarise verbatim.
+    if (content.length > 2000) content = content.slice(0, 2000) + ' …[truncated]';
+    return `${m.role.toUpperCase()}: ${content}`;
+  }).join('\n\n');
+
+  // A trivial chunk is not worth a model call; Tier 1 already captured it.
+  if (conversationText.length < MIN_CHARS_FOR_LLM_PASS) return result;
+
+  if (conversationText.length > MAX_CONDENSE_CHARS) {
+    conversationText = conversationText.slice(-MAX_CONDENSE_CHARS);
+  }
+
+  try {
+    const prompt = `You are an AI Memory Condenser for an autonomous agent.
+Below is a chunk of an older conversation between the User and the Assistant that is being pushed out of the short-term memory window due to length constraints.
+Your task is to summarize the KEY FACTS, DECISIONS, or OUTCOMES from this conversation snippet into 1-3 concise bullet points.
+- Do NOT include pleasantries, filler, or transient errors that were immediately fixed.
+- Only include structural knowledge, architectural decisions, and final outcomes that the agent might need later.
+- If there is nothing permanently useful in this chunk, reply with exactly: SKIP
+
+Conversation Snippet:
+${conversationText}
+
+Provide only the bullet points.`;
+
+    // maxTokens capped deliberately. The prompt asks for one to three bullet
+    // points; without a ceiling a model that misreads the instruction can
+    // return a full re-summary of the transcript it was given, at completion
+    // rates. Module 4 stage 1 of the scaling plan: cap the output of anything
+    // whose shape you already know.
+    const response = await llm.chat([{ role: 'user', content: prompt }], {
+      temperature: 0.1,
+      maxTokens: 400
+    });
+
+    // This call spends the user's own BYOK credits. It used to bypass the
+    
+    // real bill.
+    if (tokenTracker && response && response.usage) {
+      await tokenTracker.trackUsage(
+        response.usage.promptTokens || 0,
+        response.usage.completionTokens || 0,
+        null,
+        response.usage
+      );
+    }
+
+    if (response && response.content) {
+      const summary = response.content.trim();
+      if (summary && summary !== 'SKIP' && summary.length > 10) {
+        await cortexDb.saveCondensedMemory(summary);
+        result.semantic = true;
+      }
+    }
+  } catch (e) {
+    debugLog(`[Auto-Condenser] Semantic condensation failed: ${e.message}`);
+  }
+
+  return result;
+}

package/src/cortex/provisioner.js

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { causyneHome } from '../utils/paths.js';
+
+const CORTEX_DIR = path.join(causyneHome(), 'cortex');
+
+// Read-only check. The legacy implementation silently ran npm during memory
+// initialization. Optional native packages now require explicit manual setup.
+export async function provisionCortexDependencies() {
+  for (const name of ['better-sqlite3', '@xenova/transformers']) {
+    if (!fs.existsSync(path.join(CORTEX_DIR, 'node_modules', name))) {
+      throw new Error('Optional Cortex dependencies are not installed. Automatic installation is disabled; see docs/OPTIONAL_CAPABILITIES.md. Standard local session memory remains available.');
+    }
+  }
+}
+
+export async function requireCortexModule(moduleName) {
+  if (!['better-sqlite3', '@xenova/transformers'].includes(moduleName)) {
+    throw new Error(`Unsupported Cortex module: ${moduleName}`);
+  }
+  const require = createRequire(path.join(CORTEX_DIR, 'package.json'));
+  const resolved = require.resolve(moduleName);
+  const mod = await import(pathToFileURL(resolved).href);
+  return mod.default || mod;
+}

package/src/cortex/vectorDb.js

@@ -0,0 +1,447 @@
+import fs from 'fs';
+import crypto from 'crypto';
+import path from 'path';
+import os from 'os';
+import { requireCortexModule, provisionCortexDependencies } from './provisioner.js';
+import { causyneHome } from '../utils/paths.js';
+
+// Diagnostics, off by default: console output during a turn overwrites the
+// prompt's live region. See src/cortex/provisioner.js for the full reason.
+function debugLog(message) {
+  if (process.env.CAUSYNE_DEBUG !== '1') return;
+  process.stderr.write(`[causyne] ${message}\n`);
+}
+
+
+// We will load these dynamically after provisioning
+let Database;
+let pipeline;
+let env;
+
+// Environment configuration is now done dynamically in init()
+
+const CORTEX_DIR = causyneHome();
+const CORTEX_DB_FILE = path.join(CORTEX_DIR, 'cortex.db');
+
+/**
+ * How long a memory keeps half its weight. Thirty days.
+ *
+ * A lesson from last week is usually about the code as it is now; one from
+ * March is usually about code that no longer exists. Decay does not delete it —
+ * it just stops an ancient memory outranking a recent one on a tie.
+ */
+const RECENCY_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * OBLIVION adaptive memory stability constants:
+ * S = BASE_HALF_LIFE * (1 + hits * REINFORCEMENT_ALPHA) * tierMultiplier
+ * R = e^(-t/S) — adaptive retention that rewards retrieved memories with slower decay
+ */
+const REINFORCEMENT_ALPHA = 0.2;
+
+const TIER_MULTIPLIERS = {
+  condensed: 2.0,  // L1: Topic summaries persist longer
+  creative: 1.5,   // L2: Creative successes are valuable
+  mistake: 1.0     // L3: Mistakes decay normally unless reinforced
+};
+
+/** Similarity below this is noise, whatever the recency. */
+const MIN_SIMILARITY = 0.5;
+
+/** Rows scored per search. Beyond this the newest win, so search stays O(1)-ish. */
+const MAX_CANDIDATES = 500;
+
+/** Ceiling on stored memories per workspace before the oldest are retired. */
+const MAX_MEMORIES_PER_WORKSPACE = 2000;
+
+/** The dedup key: same lesson, same row, however many times it is learned. */
+function fingerprintOf(text) {
+  const normalised = String(text || '').toLowerCase().replace(/\s+/g, ' ').trim();
+  return crypto.createHash('sha256').update(normalised).digest('hex').slice(0, 32);
+}
+
+/** Type as a COLUMN, not as a prefix a LIKE has to scan for. */
+function kindOf(text) {
+  const value = String(text || '');
+  if (value.startsWith('CREATIVE SUCCESS:')) return 'creative';
+  if (value.startsWith('[PAST MISTAKE')) return 'mistake';
+  return 'condensed';
+}
+
+export class VectorDB {
+  constructor() {
+    this.extractor = null;
+    this.isInitialized = false;
+    this.db = null;
+  }
+
+  async ensureDb() {
+    if (this.db) return;
+
+    if (!fs.existsSync(CORTEX_DIR)) {
+      fs.mkdirSync(CORTEX_DIR, { recursive: true, mode: 0o700 });
+    }
+    
+    // Ensure dependencies are provisioned first
+    await provisionCortexDependencies();
+    
+    if (!Database) {
+      Database = await requireCortexModule('better-sqlite3');
+    }
+
+    // Initialize SQLite Database
+    this.db = new Database(CORTEX_DB_FILE);
+    
+    // Create the task_memories table if it doesn't exist
+    // embedding_vector is stored as a JSON string array of floats
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS task_memories (
+        id TEXT PRIMARY KEY,
+        text TEXT NOT NULL,
+        embedding_vector TEXT NOT NULL,
+        timestamp INTEGER NOT NULL
+      )
+    `);
+
+    this.migrateSchema();
+  }
+
+  /**
+   * Bring an existing store up to the current schema, additively.
+   *
+   * WHAT THE ORIGINAL SCHEMA COULD NOT DO, measured on a real store of 11 rows:
+   *
+   *   - NO WORKSPACE. search() scanned every memory ever recorded, so a lesson
+   *     learned in one client's repository was injected into another client's
+   *     task. That is a relevance problem and a CONFIDENTIALITY problem, and it
+   *     is the same class of bug that made one global chat_history.json resume
+   *     the wrong project's conversation.
+   *   - NO DEDUPLICATION. 11 rows held 3 distinct lessons — 73% duplicates. A
+   *     top-3 search could return the same lesson three times, so the agent paid
+   *     for three slots and received one.
+   *   - TIMESTAMP STORED, NEVER USED. A memory from months ago ranked exactly
+   *     as high as one from yesterday.
+   *   - TYPE BY STRING PREFIX. Creative patterns were told apart from mistakes
+   *     with `LIKE 'CREATIVE SUCCESS:%'` — a full table scan against a
+   *     convention nothing enforced.
+   *   - NO INDEX beyond the primary key.
+   *
+   * ALTER TABLE ADD COLUMN is the only migration used: it cannot lose a row,
+   * and an interrupted upgrade leaves a store that still reads.
+   */
+  migrateSchema() {
+    const columns = new Set(this.db.prepare('PRAGMA table_info(task_memories)').all().map(c => c.name));
+
+    if (!columns.has('workspace')) this.db.exec("ALTER TABLE task_memories ADD COLUMN workspace TEXT DEFAULT ''");
+    if (!columns.has('kind')) this.db.exec("ALTER TABLE task_memories ADD COLUMN kind TEXT DEFAULT 'mistake'");
+    if (!columns.has('fingerprint')) this.db.exec('ALTER TABLE task_memories ADD COLUMN fingerprint TEXT');
+    if (!columns.has('hits')) this.db.exec('ALTER TABLE task_memories ADD COLUMN hits INTEGER DEFAULT 0');
+
+    // Backfill the two derived columns for rows written before they existed.
+    // Existing memories keep workspace '' — global — because we genuinely do
+    // not know where they came from, and guessing would attach one project's
+    // lesson to another. '' matches every workspace, which is the old
+    // behaviour, so nothing a user already relies on disappears.
+    const stale = this.db.prepare('SELECT id, text FROM task_memories WHERE fingerprint IS NULL').all();
+    if (stale.length > 0) {
+      const setRow = this.db.prepare('UPDATE task_memories SET fingerprint = ?, kind = ? WHERE id = ?');
+      const run = this.db.transaction((rows) => {
+        for (const row of rows) setRow.run(fingerprintOf(row.text), kindOf(row.text), row.id);
+      });
+      run(stale);
+    }
+
+    // ONE-TIME COLLAPSE of duplicates written before fingerprints existed.
+    //
+    // The real store held 11 rows carrying 3 distinct lessons — five copies
+    // each of two of them. That is not merely wasted disk: a top-3 retrieval
+    // returned the same lesson three times, so the agent paid for three slots
+    // and learned one thing. The newest row of each group survives and inherits
+    // the group's total hit count, because reinforcement is real evidence that
+    // the lesson matters.
+    const groups = this.db.prepare(
+      `SELECT fingerprint, workspace, COUNT(*) c FROM task_memories
+        WHERE fingerprint IS NOT NULL
+        GROUP BY fingerprint, workspace HAVING c > 1`
+    ).all();
+
+    if (groups.length > 0) {
+      const collapse = this.db.transaction((rows) => {
+        for (const group of rows) {
+          const copies = this.db.prepare(
+            `SELECT id, hits FROM task_memories
+              WHERE fingerprint = ? AND workspace = ? ORDER BY timestamp DESC`
+          ).all(group.fingerprint, group.workspace);
+
+          const keep = copies[0];
+          const totalHits = copies.reduce((sum, row) => sum + (row.hits || 0), 0);
+          this.db.prepare('UPDATE task_memories SET hits = ? WHERE id = ?').run(totalHits, keep.id);
+          for (const row of copies.slice(1)) {
+            this.db.prepare('DELETE FROM task_memories WHERE id = ?').run(row.id);
+          }
+        }
+      });
+      collapse(groups);
+      debugLog(`[CORTEX] collapsed ${groups.length} duplicate group(s)`);
+    }
+
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_memories_ws_time ON task_memories(workspace, timestamp DESC)');
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_memories_kind ON task_memories(kind, timestamp DESC)');
+    this.db.exec('CREATE INDEX IF NOT EXISTS idx_memories_fingerprint ON task_memories(fingerprint, workspace)');
+  }
+
+  async init() {
+    if (this.isInitialized) return;
+    
+    await this.ensureDb();
+
+    if (!pipeline || !env) {
+      const transformers = await requireCortexModule('@xenova/transformers');
+      pipeline = transformers.pipeline;
+      env = transformers.env;
+
+      // Optimization: Allow local model caching
+      env.localModelPath = path.join(causyneHome(), 'models');
+      env.allowRemoteModels = false; // Model provisioning is an explicit setup step.
+    }
+
+    // Load the lightweight feature extraction pipeline
+    try {
+      this.extractor = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+      this.isInitialized = true;
+    } catch (error) {
+      debugLog(`[CORTEX] Failed to initialize neural engine: ${error.message}`);
+      throw error;
+    }
+  }
+
+  async embed(text) {
+    if (!this.isInitialized) await this.init();
+    
+    // Generate embeddings
+    const output = await this.extractor(text, { pooling: 'mean', normalize: true });
+    return Array.from(output.data);
+  }
+
+  cosineSimilarity(vecA, vecB) {
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < vecA.length; i++) {
+      dotProduct += vecA[i] * vecB[i];
+      normA += vecA[i] * vecA[i];
+      normB += vecB[i] * vecB[i];
+    }
+    if (normA === 0 || normB === 0) return 0;
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+  }
+
+  /**
+   * A mistake and how it was recovered from. Scoped to the project it happened in.
+   *
+   * `workspace` defaults to the current directory rather than to '' — a lesson
+   * about THIS repository's build is not a lesson about every repository, and
+   * cross-project leakage is the whole reason retrieval had to be scoped.
+   */
+  async saveMemory(taskGoal, errorEncountered, resolution, workspace = process.cwd()) {
+    const searchableText = `Goal: ${taskGoal}\nError: ${errorEncountered}`;
+    const fullText = `[PAST MISTAKE RECOVERED]\nGoal: ${taskGoal}\nError: ${errorEncountered}\nResolution: ${resolution}`;
+    const result = await this.upsertMemory(fullText, { workspace, kind: 'mistake', searchableText });
+    debugLog(`[CORTEX] mistake ${result.created ? 'recorded' : 'reinforced'}`);
+    return result;
+  }
+
+  /** A condensed run of chat history, kept against the project it summarises. */
+  async saveCondensedMemory(summaryText, workspace = process.cwd()) {
+    const fullText = `[CONDENSED CHAT HISTORY]\n${summaryText}`;
+    return this.upsertMemory(fullText, { workspace, kind: 'condensed' });
+  }
+
+  async search(queryText, topK = 3, options = {}) {
+    await this.ensureDb();
+
+    const workspace = String(options.workspace ?? process.cwd() ?? '');
+    const rows = this.db.prepare(
+      `SELECT id, text, embedding_vector, timestamp, kind, hits
+         FROM task_memories
+        WHERE workspace = ? OR workspace = ''
+        ORDER BY timestamp DESC
+        LIMIT ?`
+    ).all(workspace, MAX_CANDIDATES);
+
+    if (rows.length === 0) return [];
+
+    const queryEmbedding = await this.embed(queryText);
+    const now = Date.now();
+
+    const scored = [];
+    for (const memory of rows) {
+      let similarity;
+      try {
+        similarity = this.cosineSimilarity(queryEmbedding, JSON.parse(memory.embedding_vector));
+      } catch (e) {
+        continue; // a corrupt vector is skipped, never fatal
+      }
+      if (similarity <= MIN_SIMILARITY) continue;
+
+      const ageMs = Math.max(0, now - (memory.timestamp || 0));
+      // OBLIVION: S = BASE_HALF_LIFE * (1 + hits * REINFORCEMENT_ALPHA) * tierMultiplier
+      // R = e^(-t/S) — adaptive retention that rewards reinforced memories with slower decay
+      const tierMult = TIER_MULTIPLIERS[memory.kind] || 1.0;
+      const stability = Math.max(1, RECENCY_HALF_LIFE_MS * (1 + (memory.hits || 0) * REINFORCEMENT_ALPHA) * tierMult);
+      const retention = Math.exp(-ageMs / stability);
+      scored.push({
+        id: memory.id,
+        text: memory.text,
+        kind: memory.kind,
+        timestamp: memory.timestamp,
+        hits: memory.hits || 0,
+        similarity,
+        retention,
+        score: similarity * retention
+      });
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    const matches = scored.slice(0, topK);
+
+    // Reinforce retrieved memories: incrementing hits increases memory stability S
+    // in OBLIVION formula, preserving high-utility memories against decay.
+    if (matches.length > 0) {
+      try {
+        const bump = this.db.prepare('UPDATE task_memories SET hits = hits + 1 WHERE id = ?');
+        const run = this.db.transaction((ids) => { for (const id of ids) bump.run(id); });
+        run(matches.map(m => m.id));
+      } catch (e) { /* telemetry must never fail a retrieval */ }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Write a memory, or refresh the one that already says this.
+   *
+   * A store of 11 rows held 3 distinct lessons. Recording the same lesson again
+   * is not new knowledge — it is evidence that the lesson matters, so the
+   * existing row's timestamp and hit count move instead of a duplicate landing
+   * next to it. Duplicates do not merely waste space: they crowd each other out
+   * of a top-3, so the agent pays for three slots and receives one lesson.
+   */
+  async upsertMemory(text, { workspace = '', kind = null, searchableText = null } = {}) {
+    await this.ensureDb();
+
+    const fingerprint = fingerprintOf(text);
+    const scope = String(workspace || '');
+
+    const existing = this.db.prepare(
+      'SELECT id FROM task_memories WHERE fingerprint = ? AND workspace = ?'
+    ).get(fingerprint, scope);
+
+    if (existing) {
+      this.db.prepare('UPDATE task_memories SET timestamp = ?, hits = hits + 1 WHERE id = ?')
+        .run(Date.now(), existing.id);
+      debugLog(`[CORTEX] memory reinforced rather than duplicated: ${fingerprint.slice(0, 8)}`);
+      return { id: existing.id, created: false };
+    }
+
+    const embedding = await this.embed(searchableText || text);
+    const id = `mem_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+
+    this.db.prepare(
+      `INSERT INTO task_memories (id, text, embedding_vector, timestamp, workspace, kind, fingerprint, hits)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 0)`
+    ).run(id, text, JSON.stringify(embedding), Date.now(), scope, kind || kindOf(text), fingerprint);
+
+    this.pruneWorkspace(scope);
+    return { id, created: true };
+  }
+
+  /**
+   * Retire the least useful memories once a workspace passes its ceiling.
+   *
+   * Oldest first, and never-retrieved before ever-retrieved: a memory the agent
+   * has actually used is worth more than one that has sat there since August.
+   * Called on write rather than on a timer — nothing may run in the background
+   * (ZM-01), and a write is exactly when the store can have grown.
+   */
+  pruneWorkspace(workspace, max = MAX_MEMORIES_PER_WORKSPACE) {
+    try {
+      const { c } = this.db.prepare('SELECT COUNT(*) c FROM task_memories WHERE workspace = ?').get(workspace);
+      if (c <= max) return 0;
+      const result = this.db.prepare(
+        `DELETE FROM task_memories WHERE id IN (
+           SELECT id FROM task_memories WHERE workspace = ?
+            ORDER BY hits ASC, timestamp ASC LIMIT ?
+         )`
+      ).run(workspace, c - max);
+      return result.changes;
+    } catch (e) {
+      return 0;
+    }
+  }
+
+  /** Everything stored, for `/cortex`. Vectors excluded — they are unreadable. */
+  async inventory(options = {}) {
+    await this.ensureDb();
+    const workspace = options.workspace;
+    const rows = workspace
+      ? this.db.prepare(
+          `SELECT id, text, kind, timestamp, hits, workspace FROM task_memories
+            WHERE workspace = ? OR workspace = '' ORDER BY timestamp DESC LIMIT 200`
+        ).all(String(workspace))
+      : this.db.prepare(
+          'SELECT id, text, kind, timestamp, hits, workspace FROM task_memories ORDER BY timestamp DESC LIMIT 200'
+        ).all();
+    return rows;
+  }
+
+  /** Counts, for a one-line answer to "is my digital brain actually on?". */
+  async stats() {
+    await this.ensureDb();
+    const total = this.db.prepare('SELECT COUNT(*) c FROM task_memories').get().c;
+    const byKind = this.db.prepare('SELECT kind, COUNT(*) c FROM task_memories GROUP BY kind').all();
+    const workspaces = this.db.prepare("SELECT COUNT(DISTINCT workspace) c FROM task_memories WHERE workspace != ''").get().c;
+    const newest = this.db.prepare('SELECT MAX(timestamp) t FROM task_memories').get().t || 0;
+    const distinct = this.db.prepare('SELECT COUNT(DISTINCT fingerprint) c FROM task_memories').get().c;
+    return { total, distinct, byKind, workspaces, newest };
+  }
+
+  /** Forget one memory, or every memory in a workspace. */
+  async forget({ id = null, workspace = null } = {}) {
+    await this.ensureDb();
+    if (id) return this.db.prepare('DELETE FROM task_memories WHERE id = ?').run(id).changes;
+    if (workspace !== null) {
+      return this.db.prepare('DELETE FROM task_memories WHERE workspace = ?').run(String(workspace)).changes;
+    }
+    return 0;
+  }
+
+  /**
+   * A design approach that worked, so the next one deliberately differs.
+   *
+   * Global on purpose (workspace ''): the anti-slop directive is about not
+   * repeating YOURSELF, and repeating the same palette in a different repo is
+   * still repeating yourself.
+   */
+  async saveCreativePattern(pattern) {
+    const text = `CREATIVE SUCCESS: Built "${pattern.project}" using ${pattern.designApproach} style. Colors: ${pattern.colorPalette}. Fonts: ${pattern.fonts}.`;
+    const result = await this.upsertMemory(text, { workspace: '', kind: 'creative' });
+    debugLog(`[CORTEX] creative pattern ${result.created ? 'saved' : 'reinforced'}: ${pattern.designApproach}`);
+    return result;
+  }
+
+  // Anti-Slop: Retrieve recent creative patterns for the "DO NOT REPEAT" directive
+  async getRecentCreativePatterns(limit = 5) {
+    await this.ensureDb();
+    try {
+      const results = this.db.prepare(
+        'SELECT text FROM task_memories WHERE kind = ? ORDER BY timestamp DESC LIMIT ?'
+      ).all('creative', limit);
+      return results.map(r => r.text);
+    } catch (e) {
+      return [];
+    }
+  }
+}
+
+export const cortexDb = new VectorDB();