@yemi33/minions 0.1.2369 → 0.1.2371

package/engine/comment-format.js

@@ -1,48 +1,10 @@
 /**
  * engine/comment-format.js — platform-neutral PR-comment body fragments.
  *
- * Harness Transparency, Stage 3 readout #1 (P-e4b7a6d5). The other readouts —
- * the work-item modal (P-d5a6f7c4) and the notes/inbox digest — live in the
- * dashboard renderer and the consolidation path respectively. This module owns
- * the *PR-comment* surface.
- *
- * `buildHarnessUsedSection(harnessUsed)` renders the grounded harness-usage
- * record (the canonical `{ skills, mcpServers, commands, docs }` shape produced
- * by `shared.groundHarnessUsed` / `shared.normalizeHarnessUsed`; each entry may
- * carry `grounded: true | false`) as a collapsible Markdown `<details>` block.
- *
- * It is deliberately platform-NEUTRAL: the output is plain Markdown with no
- * GitHub- or ADO-specific syntax, so the GitHub comment path
- * (`engine/gh-comment.js buildMinionsCommentBody`) and the ADO comment path
- * (agent-authored via `az repos pr comment` per `playbooks/shared-rules.md`)
- * fold in a **byte-identical** section. Both consume this one helper — there is
- * no second renderer to drift.
- *
- * Returns '' when the record is absent, malformed, or has no renderable entries
- * so callers can append it unconditionally without emitting an empty section.
+ * Owns the platform-neutral Minions marker and brand-link formatting shared by
+ * GitHub and Azure DevOps comment transports.
  */
 
-// Kind metadata mirrors the dashboard work-item modal (P-d5a6f7c4,
-// dashboard/js/render-work-items.js): same four kinds, same icons, same
-// primary/secondary field mapping, so the PR-comment and modal readouts stay
-// visually consistent.
-const HARNESS_KINDS = [
-  { key: 'skills', icon: '\u{1F9E9}', primary: 'name', secondary: 'source' }, // 🧩
-  { key: 'mcpServers', icon: '\u{1F50C}', primary: 'name', secondary: 'scope' }, // 🔌
-  { key: 'commands', icon: '\u{2318}', primary: 'name', secondary: 'scope' }, // ⌘
-  { key: 'docs', icon: '\u{1F4C4}', primary: 'path', secondary: 'why' }, // 📄
-];
-
-const HARNESS_SUMMARY_ICON = '\u{1F9F0}'; // 🧰
-const HARNESS_WARN_ICON = '⚠️'; // ⚠️
-
-// W-mr287sc0000uc214 — the visible "skipped project skill" callout. The label is
-// a stable literal so buildMinionsCommentBody can dedupe (never stack two
-// callouts) and tests can assert on it. Clamps mirror the harness field caps.
-const SKILL_SKIPPED_LABEL = '**Skipped project skill:**';
-const SKILL_SKIPPED_MAX_NAME_LEN = 200;
-const SKILL_SKIPPED_MAX_REASON_LEN = 1000;
-
 // Canonical Minions site URL. shared-rules.md ("Brand link (MANDATORY)") requires
 // the human-readable "Minions" mention in a PR/ADO comment to render as a markdown
 // hyperlink to this destination. Keep this in sync with the literal in
@@ -76,118 +38,10 @@ function linkifyBrandTrailer(text) {
   return text.replace(BRAND_TRAILER_RE, `by [Minions](${MINIONS_BRAND_URL})`);
 }
 
-// Collapse internal whitespace/newlines to single spaces and neutralize
-// backticks so each entry renders on one line and can't break the inline-code
-// span. Values arrive already trimmed + length-clamped by normalizeHarnessUsed,
-// but may still contain internal newlines.
-function _clean(value) {
-  return String(value).replace(/`/g, "'").replace(/\s+/g, ' ').trim();
-}
-
-/**
- * Render the grounded harnessUsed record as a collapsible Markdown section.
- * @param {object|null} harnessUsed canonical { skills, mcpServers, commands, docs }
- * @returns {string} '' when empty, else a `<details>` block (no trailing newline)
- */
-function buildHarnessUsedSection(harnessUsed) {
-  if (!harnessUsed || typeof harnessUsed !== 'object' || Array.isArray(harnessUsed)) return '';
-
-  const lines = [];
-  let anyUngrounded = false;
-
-  for (const kind of HARNESS_KINDS) {
-    const entries = Array.isArray(harnessUsed[kind.key]) ? harnessUsed[kind.key] : [];
-    for (const entry of entries) {
-      if (!entry || typeof entry !== 'object') continue;
-      const primaryRaw = entry[kind.primary];
-      if (typeof primaryRaw !== 'string' || !primaryRaw.trim()) continue;
-      const primary = _clean(primaryRaw);
-
-      const grounded = entry.grounded === true;
-      if (!grounded) anyUngrounded = true;
-
-      const secondaryRaw = entry[kind.secondary];
-      const secondary = (typeof secondaryRaw === 'string' && secondaryRaw.trim())
-        ? _clean(secondaryRaw) : '';
-
-      const tail = secondary ? ` — ${secondary}` : ''; // em dash
-      const warn = grounded ? '' : ` ${HARNESS_WARN_ICON}`;
-      lines.push(`- ${kind.icon} \`${primary}\`${tail}${warn}`);
-    }
-  }
-
-  if (lines.length === 0) return '';
-
-  const legend = anyUngrounded
-    ? `\n\n> ${HARNESS_WARN_ICON} agent-reported, not verified by the engine`
-    : '';
-
-  return `<details>\n<summary>${HARNESS_SUMMARY_ICON} Harnesses used (${lines.length})</summary>\n\n`
-    + `${lines.join('\n')}${legend}\n\n</details>`;
-}
-
-/**
- * Extract a canonical `{ name, reason }` skip record from a self-reported skip
- * value. Accepts the raw `{ name, reason }` shape directly, or a `meta` wrapper
- * that carries it — `meta.skill` (`{ skipped: { name, reason } }`) or
- * `meta.review` (`{ skillSkipped: { name, reason } }`) — so callers can pass the
- * completion-report block verbatim. Returns null when no non-empty `name` is
- * present so callers treat "no skip" as a single falsy case.
- * @param {*} input
- * @returns {{name:string, reason:string}|null}
- */
-function _extractSkillSkipped(input) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
-  let node = input;
-  if (input.skipped && typeof input.skipped === 'object' && !Array.isArray(input.skipped)) {
-    node = input.skipped; // meta.skill shape
-  } else if (input.skillSkipped && typeof input.skillSkipped === 'object' && !Array.isArray(input.skillSkipped)) {
-    node = input.skillSkipped; // meta.review shape
-  }
-  const name = typeof node.name === 'string' ? node.name.trim() : '';
-  if (!name) return null;
-  const reason = typeof node.reason === 'string' ? node.reason.trim() : '';
-  return { name, reason };
-}
-
-/**
- * Render the "skipped project skill" self-report as a VISIBLE Markdown
- * blockquote callout (W-mr287sc0000uc214), e.g.:
- *   > ⚠️ **Skipped project skill:** `FMF-review-context` — small 2-file diff…
- *
- * A review/fix agent may self-report that it intentionally skipped an available,
- * in-scope project (review) skill via `meta.review.skillSkipped` /
- * `meta.skill.skipped` (shape `{name, reason}`). That skip used to live ONLY in
- * the completion-report JSON — invisible to a human reading the PR before merge.
- * This is a sibling of buildHarnessUsedSection (same neutral chokepoint, same
- * `_clean` hygiene) but a VISIBLE blockquote rather than a collapsed <details>:
- * the whole point is that a human reviewing the PR sees the skip rationale in the
- * same comment as the APPROVE / REQUEST_CHANGES verdict, before merge.
- *
- * Deliberately platform-NEUTRAL Markdown so the GitHub and ADO posters fold in a
- * byte-identical callout — there is no second renderer to drift. Accepts either
- * the raw `{name, reason}` record or a `meta.skill` / `meta.review` wrapper.
- *
- * Returns '' when the record is absent/malformed (no skip name), so callers can
- * append it unconditionally without emitting a stray callout — reports without
- * meta.review.skillSkipped / meta.skill.skipped render identically to today.
- *
- * @param {object|null} skillSkipped `{name, reason}` or a meta.skill/meta.review wrapper
- * @returns {string} '' when empty, else a one-line `> ⚠️ …` blockquote
- */
-function buildSkippedSkillSection(skillSkipped) {
-  const parsed = _extractSkillSkipped(skillSkipped);
-  if (!parsed) return '';
-  const name = _clean(parsed.name).slice(0, SKILL_SKIPPED_MAX_NAME_LEN);
-  const reasonClean = parsed.reason ? _clean(parsed.reason).slice(0, SKILL_SKIPPED_MAX_REASON_LEN) : '';
-  const tail = reasonClean ? ` — ${reasonClean}` : ''; // em dash
-  return `> ${HARNESS_WARN_ICON} ${SKILL_SKIPPED_LABEL} \`${name}\`${tail}`;
-}
-
 // ── Minions marker + neutral comment-body builder ───────────────────────────
 //
 // The hidden HTML-comment marker and the body composition (marker + harness
-// section + brand link) are platform-NEUTRAL: GitHub (engine/gh-comment.js) and
+// brand link) are platform-NEUTRAL: GitHub (engine/gh-comment.js) and
 // Azure DevOps (engine/ado-comment.js) both post the byte-identical body built
 // here, so there is one builder and no drift. The host modules own only the
 // transport (gh CLI vs ADO REST) and host-specific validation (repo slug vs
@@ -246,42 +100,21 @@ function _buildMarker({ agentId, kind, workItemId }) {
 }
 
 /**
- * Compose a minions PR-comment body: prepend the hidden marker, fold in the
- * collapsible "Harnesses used" section, and hyperlink the first bare brand
- * trailer. Platform-neutral — GitHub and ADO posters both call this.
+ * Compose a minions PR-comment body: prepend the hidden marker and hyperlink the
+ * first bare brand trailer. Platform-neutral — GitHub and ADO posters both call this.
  *
  * Idempotency: if `body` already starts with a minions marker it is returned
- * with the harness/brand transforms applied but no second marker prepended.
+ * with the brand transform applied but no second marker prepended.
  *
- * @param {{agentId:string, kind:string, workItemId?:string, body?:string, harnessUsed?:object, skillSkipped?:object}} args
+ * @param {{agentId:string, kind:string, workItemId?:string, body?:string}} args
  * @returns {string} the final comment body
  */
-function buildMinionsCommentBody({ agentId, kind, workItemId, body, harnessUsed, skillSkipped }) {
+function buildMinionsCommentBody({ agentId, kind, workItemId, body }) {
   // Validate the inputs even when the body is pre-marked, so callers can't
   // silently bypass validation by pre-marking their body.
   _validateMarkerInputs({ agentId, kind, workItemId });
   let safeBody = body == null ? '' : String(body);
 
-  // Fold in the VISIBLE "skipped project skill" callout (W-mr287sc0000uc214)
-  // BEFORE the collapsed harness section so a human sees the skip rationale in
-  // the same comment as the verdict — not buried in a <details> or reachable
-  // only via a separate API call. Dedup on the stable label so a re-marked body
-  // already carrying the callout doesn't stack a second one. Absent/malformed
-  // skip → '' → no-op (byte-identical to today).
-  const skipSection = buildSkippedSkillSection(skillSkipped);
-  if (skipSection && !safeBody.includes(SKILL_SKIPPED_LABEL)) {
-    safeBody = safeBody ? `${safeBody}\n\n${skipSection}` : skipSection;
-  }
-
-  // Fold the grounded harness-usage digest in as a collapsible <details>
-  // section. Append at the END so it survives the marker-idempotency path;
-  // dedup on the summary line so a re-marked body that already carries the
-  // section doesn't stack a second one.
-  const harnessSection = buildHarnessUsedSection(harnessUsed);
-  if (harnessSection && !safeBody.includes('<summary>\u{1F9F0} Harnesses used')) {
-    safeBody = safeBody ? `${safeBody}\n\n${harnessSection}` : harnessSection;
-  }
-
   // Brand-link safety net: deterministically hyperlink the first bare
   // "… by Minions" signature trailer (no-op when the agent already linked it).
   safeBody = linkifyBrandTrailer(safeBody);
@@ -307,8 +140,6 @@ function parseMinionsMarker(body) {
 }
 
 module.exports = {
-  buildHarnessUsedSection,
-  buildSkippedSkillSection,
   linkifyBrandTrailer,
   MINIONS_BRAND_URL,
   // Neutral marker + body builder (consumed by gh-comment.js and ado-comment.js).
@@ -322,9 +153,4 @@ module.exports = {
   // Internal helpers exported for tests / host posters.
   _buildMarker,
   _validateMarkerInputs,
-  // Exported for tests / advanced callers that want to mirror the kind mapping.
-  HARNESS_KINDS,
-  // W-mr287sc0000uc214 — skipped-project-skill callout helpers.
-  _extractSkillSkipped,
-  SKILL_SKIPPED_LABEL,
 };

package/engine/consolidation.js

@@ -149,6 +149,44 @@ function extractInboxAgent(item) {
   return null;
 }
 
+function extractInboxProject(item) {
+  const content = String(item?.content || '');
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return '';
+  const projectLine = fmMatch[1].split('\n').find(l => /^project:\s*/i.test(l));
+  return projectLine ? projectLine.replace(/^project:\s*/i, '').trim() : '';
+}
+
+function _indexMemoryRecord(record) {
+  try {
+    return require('./memory-store').upsertMemoryRecord(record);
+  } catch (err) {
+    log('warn', `Structured memory index write failed (${record?.sourceRef || 'unknown'}): ${err.message}`);
+    return null;
+  }
+}
+
+function _indexAgentMemoryItem(item, agent) {
+  const content = String(item?.content || '').trim();
+  if (!content) return null;
+  const titleMatch = content.match(/^#\s+(.+)/m);
+  return _indexMemoryRecord({
+    memoryType: 'semantic',
+    scopeType: 'agent',
+    scopeKey: agent,
+    title: titleMatch ? titleMatch[1].trim() : String(item.name || 'Agent learning').replace(/\.md$/, ''),
+    body: content,
+    tags: ['agent-memory', agent],
+    sourceType: 'inbox',
+    sourcePath: `notes/inbox/${item.name}`,
+    sourceRef: String(item.name),
+    trust: 'agent',
+    importance: 0.6,
+    confidence: 0.6,
+    metadata: { agent, project: extractInboxProject(item) || null },
+  });
+}
+
 /**
  * Append an inbox item to its author's personal memory file when the agent
  * is a known team member (must be present in `knownAgents`) and not a
@@ -207,6 +245,7 @@ function appendToAgentMemory(item, knownAgents, config) {
       const next = pruneAgentMemoryToBudget(existing + entry, agent, _pruneOptsFromConfig(config));
       safeWrite(memPath, next);
     });
+    _indexAgentMemoryItem(item, agent);
     return true;
   } catch (err) {
     log('warn', `Failed to append to knowledge/agents/${agent}.md: ${err.message}`);
@@ -571,7 +610,22 @@ function reconcileAndAppendToAgentMemory(item, knownAgents, config) {
       lockErr = err;
     }
 
-    if (reconciled) return true;
+    if (reconciled) {
+      const indexed = _indexAgentMemoryItem(item, agent);
+      if (indexed) {
+        try {
+          require('./memory-store').supersedeMatchingRecords({
+            scopeType: 'agent',
+            scopeKey: agent,
+            oldTexts: edits.map(edit => edit.old_text),
+            supersededBy: indexed.id,
+          });
+        } catch (err) {
+          log('warn', `Structured memory reconcile transition failed for ${agent}: ${err.message}`);
+        }
+      }
+      return true;
+    }
     if (lockErr) log('warn', `agent-memory reconcile: lock/write error for ${agent}: ${lockErr.message} — plain append`);
     return appendToAgentMemory(item, knownAgents, config);
   }).catch((err) => {
@@ -1291,6 +1345,22 @@ async function classifyToKnowledgeBase(items, config) {
       const frontmatter = `---\nsource: ${item.name}\nagent: ${agent}\ncategory: ${category}\ndate: ${dateStamp()}\nreusable: ${reusable}${isSystemAlert ? `\nalertHash: ${alertHash}` : ''}\n---\n\n`;
       try {
         safeWrite(kbPath, frontmatter + kbBody);
+        const project = extractInboxProject(item);
+        _indexMemoryRecord({
+          memoryType: 'semantic',
+          scopeType: project ? 'project' : 'global',
+          scopeKey: project || '',
+          title: titleMatch ? titleMatch[1].trim() : titleSlug,
+          body: frontmatter + kbBody,
+          tags: [category, agent, reusable ? 'reusable' : 'reference'],
+          sourceType: 'knowledge-base',
+          sourcePath: path.relative(shared.MINIONS_DIR, kbPath).replace(/\\/g, '/'),
+          sourceRef: item.name,
+          trust: 'agent',
+          importance: reusable ? 0.8 : 0.4,
+          confidence: 0.6,
+          metadata: { category, agent, reusable, inbox: item.name },
+        });
         classified++;
       } catch (err) {
         log('warn', `Failed to classify ${item.name} to knowledge base: ${err.message}`);
@@ -1430,6 +1500,7 @@ module.exports = {
   checkDuplicateHash,
   // per-agent memory routing
   extractInboxAgent,
+  extractInboxProject,
   appendToAgentMemory,
   reconcileAndAppendToAgentMemory,
   pruneAgentMemoryToBudget,

package/engine/db/index.js

@@ -21,6 +21,45 @@ let _db = null;
 let _dbPath = null;
 let _dbInitError = null;
 let _exitCheckpointRegistered = false;
+let _cleanedDbPath = null;
+
+function _cleanupRetiredJsonFiles(db, dbPath) {
+  if (_cleanedDbPath === dbPath) return;
+  const marker = db.prepare("SELECT value FROM state_markers WHERE key='sql_only_cutover'").get();
+  if (!marker) return;
+  const minionsDir = path.dirname(path.dirname(dbPath));
+  const engineDir = path.join(minionsDir, 'engine');
+  const engineFiles = [
+    'dispatch.json', 'log.json', 'metrics.json', 'watches.json',
+    'schedule-runs.json', 'pipeline-runs.json', 'managed-processes.json',
+    'worktree-pool.json', 'qa-runs.json', 'qa-sessions.json', 'pr-links.json',
+    'cooldowns.json', 'pending-rebases.json', 'cc-sessions.json', 'doc-sessions.json',
+  ];
+  const targets = engineFiles.map(name => path.join(engineDir, name));
+  targets.push(path.join(minionsDir, 'work-items.json'), path.join(minionsDir, 'pull-requests.json'));
+  try {
+    for (const project of fs.readdirSync(path.join(minionsDir, 'projects'), { withFileTypes: true })) {
+      if (!project.isDirectory() || project.name === '.archived') continue;
+      targets.push(
+        path.join(minionsDir, 'projects', project.name, 'work-items.json'),
+        path.join(minionsDir, 'projects', project.name, 'pull-requests.json'),
+      );
+    }
+  } catch { /* projects directory is optional */ }
+  for (const dir of [path.join(minionsDir, 'prd'), path.join(minionsDir, 'prd', 'archive')]) {
+    try {
+      for (const name of fs.readdirSync(dir)) {
+        if (name.endsWith('.json')) targets.push(path.join(dir, name));
+      }
+    } catch { /* PRD directory is optional */ }
+  }
+  for (const target of targets) {
+    for (const suffix of ['', '.backup', '.lock']) {
+      try { fs.unlinkSync(target + suffix); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    }
+  }
+  _cleanedDbPath = dbPath;
+}
 
 // DATA-LOSS GUARD: register a one-time process-exit hook that checkpoints +
 // closes the DB. Registered by getDb() on first successful open so EVERY DB
@@ -68,14 +107,6 @@ function _installExperimentalWarningFilter() {
 }
 
 function getDb() {
-  // Hard opt-out (issue #3035, option #3): MINIONS_FORCE_JSON=1 makes
-  // every getDb() call throw, forcing the entire stack onto the JSON
-  // fallback path. Useful for users who can't enable
-  // --experimental-sqlite on Node 22.x and for regression tests that
-  // need to exercise the JSON-fallback branches deterministically.
-  if (process.env.MINIONS_FORCE_JSON === '1') {
-    throw new Error('engine/db: SQL disabled via MINIONS_FORCE_JSON=1');
-  }
   // Re-resolve the DB path on every call so tests that swap MINIONS_TEST_DIR
   // (or production-side configuration that changes MINIONS_HOME between
   // operations) get a fresh connection to the new location instead of
@@ -143,12 +174,13 @@ function getDb() {
     if (lastErr) throw lastErr;
     const { runMigrations } = require('./migrate');
     runMigrations(_db);
+    _cleanupRetiredJsonFiles(_db, dbPath);
     _registerExitCheckpoint();
     return _db;
   } catch (e) {
     const nodeMajor = parseInt(String(process.versions.node).split('.')[0], 10);
     const flagHint = nodeMajor === 22
-      ? ` On Node 22.x, node:sqlite is gated behind --experimental-sqlite. Restart with NODE_OPTIONS=--experimental-sqlite, upgrade to Node 24+, or set MINIONS_FORCE_JSON=1 to bypass SQL.`
+      ? ` On Node 22.x, node:sqlite is gated behind --experimental-sqlite. Restart with NODE_OPTIONS=--experimental-sqlite or upgrade to Node 24+.`
       : ` Node 22.5+ (with --experimental-sqlite on 22.x) or 24+ required for built-in 'node:sqlite' support.`;
     _dbInitError = new Error(`engine/db: failed to open SQLite — ${e.message}.${flagHint}`);
     throw _dbInitError;
@@ -200,4 +232,22 @@ function withTransaction(db, fn) {
   }
 }
 
-module.exports = { getDb, closeDb, withTransaction };
+// Cache compiled statements on the db connection itself so hot, fixed-shape
+// read paths (e.g. FTS5 memory search run repeatedly per dispatch) don't pay
+// SQLite's parse/plan cost on every call — `db.prepare()` recompiles from
+// scratch each time it's invoked, node:sqlite does not dedupe by text. Keyed
+// per-connection (not module-level) so closeDb()/getDb() reopening against a
+// new path (test isolation) naturally starts with an empty cache instead of
+// holding stale statements bound to a closed handle.
+function prepareCached(db, sql) {
+  if (!db) throw new Error('engine/db.prepareCached: db is required');
+  if (!db._minionsStmtCache) db._minionsStmtCache = new Map();
+  let stmt = db._minionsStmtCache.get(sql);
+  if (!stmt) {
+    stmt = db.prepare(sql);
+    db._minionsStmtCache.set(sql, stmt);
+  }
+  return stmt;
+}
+
+module.exports = { getDb, closeDb, withTransaction, prepareCached };

package/engine/db/migrations/017-agent-memory.js

@@ -0,0 +1,208 @@
+// engine/db/migrations/017-agent-memory.js
+//
+// Structured long-term memory for task-aware retrieval. Markdown remains the
+// operator-facing source/mirror during rollout; these rows are the searchable,
+// provenance-preserving representation used by dispatch.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const KB_CATEGORIES = [
+  'architecture', 'conventions', 'project-notes', 'build-reports', 'reviews',
+  'learnings', 'decisions', 'incidents', 'api-notes',
+];
+
+function _resolveMinionsDir() {
+  return process.env.MINIONS_TEST_DIR
+    || process.env.MINIONS_HOME
+    || path.resolve(__dirname, '..', '..', '..');
+}
+
+function _read(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch { return ''; }
+}
+
+function _title(content, fallback) {
+  const match = String(content || '').match(/^#\s+(.+)/m);
+  return match ? match[1].trim() : fallback;
+}
+
+function _recordId(sourceType, sourceRef, content) {
+  const hash = crypto.createHash('sha256').update(`${sourceType}\0${sourceRef}\0${content}`).digest('hex');
+  return `M-${hash.slice(0, 24)}`;
+}
+
+function _contentHash(content) {
+  return crypto.createHash('sha256').update(String(content || '')).digest('hex');
+}
+
+function _splitAgentMemory(content) {
+  const boundary = /(?=\n---\n\n### \d{4}-\d{2}-\d{2}:)/g;
+  const parts = String(content || '').split(boundary).map(s => s.trim()).filter(Boolean);
+  return parts.length ? parts : [String(content || '')];
+}
+
+function _splitTeamNotes(content) {
+  const parts = String(content || '').split(/(?=^### \d{4}-\d{2}-\d{2})/m).map(s => s.trim()).filter(Boolean);
+  return parts.length ? parts : [String(content || '')];
+}
+
+module.exports = {
+  version: 17,
+  description: 'structured agent memory records, FTS5 retrieval, and retrieval telemetry',
+  up(db) {
+    db.exec(`
+      CREATE TABLE memory_records (
+        id              TEXT PRIMARY KEY,
+        memory_type     TEXT NOT NULL,
+        scope_type      TEXT NOT NULL,
+        scope_key       TEXT NOT NULL DEFAULT '',
+        title           TEXT NOT NULL,
+        body            TEXT NOT NULL,
+        tags            TEXT NOT NULL DEFAULT '[]',
+        source_type     TEXT NOT NULL,
+        source_path     TEXT,
+        source_ref      TEXT NOT NULL,
+        trust           TEXT NOT NULL DEFAULT 'agent',
+        importance      REAL NOT NULL DEFAULT 0.5,
+        confidence      REAL NOT NULL DEFAULT 0.5,
+        status          TEXT NOT NULL DEFAULT 'active',
+        valid_from      INTEGER,
+        valid_to        INTEGER,
+        supersedes_id   TEXT,
+        superseded_by   TEXT,
+        content_hash    TEXT NOT NULL,
+        metadata        TEXT NOT NULL DEFAULT '{}',
+        created_at      INTEGER NOT NULL,
+        updated_at      INTEGER NOT NULL
+      );
+      CREATE UNIQUE INDEX idx_memory_source_content
+        ON memory_records(source_type, source_ref, content_hash);
+      CREATE INDEX idx_memory_scope_status
+        ON memory_records(scope_type, scope_key, status);
+      CREATE INDEX idx_memory_type_status
+        ON memory_records(memory_type, status);
+      CREATE INDEX idx_memory_updated
+        ON memory_records(updated_at DESC);
+      CREATE INDEX idx_memory_supersedes
+        ON memory_records(supersedes_id);
+
+      CREATE VIRTUAL TABLE memory_records_fts USING fts5(
+        title,
+        body,
+        tags,
+        source_path,
+        content='memory_records',
+        content_rowid='rowid'
+      );
+
+      CREATE TRIGGER memory_records_ai AFTER INSERT ON memory_records BEGIN
+        INSERT INTO memory_records_fts(rowid, title, body, tags, source_path)
+        VALUES (new.rowid, new.title, new.body, new.tags, COALESCE(new.source_path, ''));
+      END;
+      CREATE TRIGGER memory_records_ad AFTER DELETE ON memory_records BEGIN
+        INSERT INTO memory_records_fts(memory_records_fts, rowid, title, body, tags, source_path)
+        VALUES ('delete', old.rowid, old.title, old.body, old.tags, COALESCE(old.source_path, ''));
+      END;
+      CREATE TRIGGER memory_records_au AFTER UPDATE OF title, body, tags, source_path ON memory_records BEGIN
+        INSERT INTO memory_records_fts(memory_records_fts, rowid, title, body, tags, source_path)
+        VALUES ('delete', old.rowid, old.title, old.body, old.tags, COALESCE(old.source_path, ''));
+        INSERT INTO memory_records_fts(rowid, title, body, tags, source_path)
+        VALUES (new.rowid, new.title, new.body, new.tags, COALESCE(new.source_path, ''));
+      END;
+
+      CREATE TABLE memory_retrieval_runs (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        work_item_id     TEXT,
+        project          TEXT,
+        agent            TEXT,
+        query            TEXT NOT NULL,
+        candidate_count  INTEGER NOT NULL,
+        selected_count   INTEGER NOT NULL,
+        selected_bytes   INTEGER NOT NULL,
+        duration_ms      REAL NOT NULL,
+        shadow           INTEGER NOT NULL DEFAULT 1,
+        created_at       INTEGER NOT NULL
+      );
+      CREATE INDEX idx_memory_retrieval_created
+        ON memory_retrieval_runs(created_at DESC);
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+
+    const insert = db.prepare(`
+      INSERT OR IGNORE INTO memory_records (
+        id, memory_type, scope_type, scope_key, title, body, tags,
+        source_type, source_path, source_ref, trust, importance, confidence,
+        status, valid_from, content_hash, metadata, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)
+    `);
+    const now = Date.now();
+    const add = ({ type = 'semantic', scopeType = 'global', scopeKey = '', title, body,
+      tags = [], sourceType = 'legacy-markdown', sourcePath, sourceRef,
+      trust = 'agent', importance = 0.5, metadata = {} }) => {
+      if (!body || !String(body).trim()) return;
+      let mtime = now;
+      try { mtime = Math.round(fs.statSync(path.join(minionsDir, sourcePath)).mtimeMs); } catch {}
+      insert.run(
+        _recordId(sourceType, sourceRef, body),
+        type, scopeType, scopeKey, title || sourceRef, body, JSON.stringify(tags),
+        sourceType, sourcePath, sourceRef, trust, importance, 0.5,
+        mtime, _contentHash(body), JSON.stringify(metadata), mtime, now,
+      );
+    };
+
+    for (const category of KB_CATEGORIES) {
+      const dir = path.join(minionsDir, 'knowledge', category);
+      let files = [];
+      try { files = fs.readdirSync(dir).filter(f => f.endsWith('.md')); } catch {}
+      for (const file of files) {
+        const sourcePath = path.join('knowledge', category, file).replace(/\\/g, '/');
+        const body = _read(path.join(minionsDir, sourcePath));
+        add({
+          title: _title(body, file.replace(/\.md$/, '')),
+          body,
+          tags: [category],
+          sourceType: 'knowledge-base',
+          sourcePath,
+          sourceRef: sourcePath,
+          metadata: { category },
+        });
+      }
+    }
+
+    const agentDir = path.join(minionsDir, 'knowledge', 'agents');
+    let agentFiles = [];
+    try { agentFiles = fs.readdirSync(agentDir).filter(f => f.endsWith('.md') && f !== 'README.md'); } catch {}
+    for (const file of agentFiles) {
+      const agent = file.replace(/\.md$/, '').toLowerCase();
+      const sourcePath = path.join('knowledge', 'agents', file).replace(/\\/g, '/');
+      const body = _read(path.join(minionsDir, sourcePath));
+      _splitAgentMemory(body).forEach((section, index) => add({
+        scopeType: 'agent',
+        scopeKey: agent,
+        title: _title(section, `${agent} memory ${index + 1}`),
+        body: section,
+        tags: ['agent-memory', agent],
+        sourceType: 'agent-memory',
+        sourcePath,
+        sourceRef: `${sourcePath}#${index + 1}`,
+        metadata: { agent, section: index + 1 },
+      }));
+    }
+
+    const notesPath = 'notes.md';
+    const notes = _read(path.join(minionsDir, notesPath));
+    _splitTeamNotes(notes).forEach((section, index) => add({
+      title: _title(section, `Team notes ${index + 1}`),
+      body: section,
+      tags: ['team-notes'],
+      sourceType: 'team-notes',
+      sourcePath: notesPath,
+      sourceRef: `${notesPath}#${index + 1}`,
+      metadata: { section: index + 1 },
+    }));
+  },
+};