@cleocode/cleo 2026.10.3 → 2026.10.5-rc.ci.672

package/dist/cli/memory-IAEYKXG6.js

@@ -0,0 +1,1895 @@
+(() => {
+  const _installed = Symbol.for('cleocode.cli.sqliteWarningFilter');
+  if (globalThis[_installed]) return;
+  globalThis[_installed] = true;
+  const _origEmitWarning = process.emitWarning;
+  process.emitWarning = function(warning, type, code, ctor) {
+    if (typeof warning === 'object' && warning.name === 'ExperimentalWarning' && typeof warning.message === 'string' && /SQLite is an experimental feature/i.test(warning.message)) {
+      return;
+    }
+    if (typeof warning === 'string' && /SQLite is an experimental feature/i.test(warning)) {
+      return;
+    }
+    return _origEmitWarning.call(process, warning, type, code, ctor);
+  };
+})();
+import {
+  lazyOperation
+} from "./chunk-TYC7G5LF.js";
+import {
+  errorResult,
+  handleErrorResult,
+  paramBool,
+  paramNumber,
+  paramString,
+  paramStringArray,
+  paramStringRequired,
+  unsupportedOp,
+  wrapResult
+} from "./chunk-XHRZ7OYZ.js";
+
+// packages/cleo/src/dispatch/domains/memory.ts
+import {
+  OAUTH_STATUS_PROVIDERS,
+  resolveCredentials,
+  resolveProviderStatus
+} from "@cleocode/core/llm/credentials";
+import { getLogger } from "@cleocode/core/logger";
+import {
+  approveBackfillRun,
+  listBackfillRuns,
+  rollbackBackfillRun,
+  stagedBackfillRun
+} from "@cleocode/core/memory/brain-backfill.js";
+import { precompactFlush } from "@cleocode/core/memory/precompact-flush.js";
+import { getProjectRoot } from "@cleocode/core/project-scope";
+import { createAttachmentStore } from "@cleocode/core/store/attachment-store";
+import { getBrainNativeDb } from "@cleocode/core/store/memory-sqlite";
+import { typedAll } from "@cleocode/core/store/typed-query";
+var generateMemoryBridgeContent = lazyOperation(
+  async () => (await import("@cleocode/core/memory/memory-bridge")).generateMemoryBridgeContent
+);
+var getBrainDb = lazyOperation(
+  async () => (await import("@cleocode/core/store/memory-sqlite")).getBrainDb
+);
+var memoryDecisionFind = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryDecisionFind
+);
+var memoryDecisionStore = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryDecisionStore
+);
+var memoryFetch = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryFetch
+);
+var memoryFind = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryFind
+);
+var memoryGraphAdd = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphAdd
+);
+var memoryGraphContext = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphContext
+);
+var memoryGraphNeighbors = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphNeighbors
+);
+var memoryGraphRelated = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphRelated
+);
+var memoryGraphRemove = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphRemove
+);
+var memoryGraphShow = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphShow
+);
+var memoryGraphStatsFull = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphStatsFull
+);
+var memoryGraphTrace = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryGraphTrace
+);
+var memoryLearningFind = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryLearningFind
+);
+var memoryLearningStore = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryLearningStore
+);
+var memoryLink = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryLink
+);
+var memoryObserve = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryObserve
+);
+var memoryPatternFind = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryPatternFind
+);
+var memoryPatternStore = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryPatternStore
+);
+var memoryQualityReport = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryQualityReport
+);
+var memoryReasonSimilar = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryReasonSimilar
+);
+var memoryReasonWhy = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryReasonWhy
+);
+var memorySearchHybrid = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memorySearchHybrid
+);
+var memoryTimeline = lazyOperation(
+  async () => (await import("@cleocode/core/memory/engine-compat")).memoryTimeline
+);
+var MemoryHandler = class {
+  // -----------------------------------------------------------------------
+  // Query
+  // -----------------------------------------------------------------------
+  async query(operation, params) {
+    const projectRoot = getProjectRoot();
+    const startTime = Date.now();
+    try {
+      switch (operation) {
+        case "find": {
+          const query = paramStringRequired(params, "query");
+          if (!query)
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "query is required",
+              startTime
+            );
+          return wrapResult(
+            await memoryFind(
+              {
+                query,
+                limit: paramNumber(params, "limit"),
+                tables: paramStringArray(params, "tables"),
+                includeHistory: paramBool(params, "includeHistory"),
+                dateStart: paramString(params, "dateStart"),
+                dateEnd: paramString(params, "dateEnd"),
+                agent: paramString(params, "agent")
+              },
+              projectRoot
+            ),
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        case "timeline": {
+          const anchor = paramStringRequired(params, "anchor");
+          if (!anchor)
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "anchor is required",
+              startTime
+            );
+          return wrapResult(
+            await memoryTimeline(
+              {
+                anchor,
+                depthBefore: paramNumber(params, "depthBefore"),
+                depthAfter: paramNumber(params, "depthAfter")
+              },
+              projectRoot
+            ),
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        case "fetch": {
+          const ids = paramStringArray(params, "ids");
+          if (!ids || ids.length === 0)
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "ids is required (non-empty array)",
+              startTime
+            );
+          return wrapResult(
+            await memoryFetch({ ids }, projectRoot),
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        case "decision.find": {
+          const result = await memoryDecisionFind(
+            {
+              query: paramString(params, "query"),
+              taskId: paramString(params, "taskId"),
+              limit: paramNumber(params, "limit"),
+              // T1830: opt-in to AGT-* dispatch rows; excluded by default
+              includeAgentDispatch: paramBool(params, "includeAgentDispatch") ?? false
+            },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "pattern.find": {
+          const patternType = paramString(params, "type");
+          const patternImpact = paramString(params, "impact");
+          const result = await memoryPatternFind(
+            {
+              type: patternType,
+              impact: patternImpact,
+              query: paramString(params, "query"),
+              minFrequency: paramNumber(params, "minFrequency"),
+              limit: paramNumber(params, "limit")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "learning.find": {
+          const result = await memoryLearningFind(
+            {
+              query: paramString(params, "query"),
+              minConfidence: paramNumber(params, "minConfidence"),
+              actionableOnly: paramBool(params, "actionableOnly"),
+              applicableType: paramString(params, "applicableType"),
+              limit: paramNumber(params, "limit")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "graph.show": {
+          const nodeId = paramStringRequired(params, "nodeId");
+          if (!nodeId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "nodeId is required",
+              startTime
+            );
+          }
+          const result = await memoryGraphShow({ nodeId }, projectRoot);
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "graph.neighbors": {
+          const nodeId = paramStringRequired(params, "nodeId");
+          if (!nodeId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "nodeId is required",
+              startTime
+            );
+          }
+          const result = await memoryGraphNeighbors(
+            { nodeId, edgeType: paramString(params, "edgeType") },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "graph.trace": {
+          const nodeId = paramStringRequired(params, "nodeId");
+          if (!nodeId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "nodeId is required",
+              startTime
+            );
+          }
+          const result = await memoryGraphTrace(
+            { nodeId, maxDepth: paramNumber(params, "maxDepth") },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "graph.related": {
+          const nodeId = paramStringRequired(params, "nodeId");
+          if (!nodeId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "nodeId is required",
+              startTime
+            );
+          }
+          const result = await memoryGraphRelated(
+            { nodeId, edgeType: paramString(params, "edgeType") },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "graph.context": {
+          const nodeId = paramStringRequired(params, "nodeId");
+          if (!nodeId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "nodeId is required",
+              startTime
+            );
+          }
+          const result = await memoryGraphContext({ nodeId }, projectRoot);
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "graph.stats": {
+          const result = await memoryGraphStatsFull(projectRoot);
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "reason.why": {
+          const taskId = paramStringRequired(params, "taskId");
+          if (!taskId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "taskId is required",
+              startTime
+            );
+          }
+          const result = await memoryReasonWhy({ taskId }, projectRoot);
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "reason.similar": {
+          const entryId = paramStringRequired(params, "entryId");
+          if (!entryId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "entryId is required",
+              startTime
+            );
+          }
+          const result = await memoryReasonSimilar(
+            { entryId, limit: paramNumber(params, "limit") },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "search.hybrid": {
+          const query = paramStringRequired(params, "query");
+          if (!query) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "query is required",
+              startTime
+            );
+          }
+          const result = await memorySearchHybrid(
+            {
+              query,
+              ftsWeight: paramNumber(params, "ftsWeight"),
+              vecWeight: paramNumber(params, "vecWeight"),
+              graphWeight: paramNumber(params, "graphWeight"),
+              limit: paramNumber(params, "limit")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "quality": {
+          const result = await memoryQualityReport(projectRoot);
+          return wrapResult(result, "query", "memory", operation, startTime);
+        }
+        case "code.links": {
+          const { listCodeLinks } = await import("@cleocode/core/memory/graph-memory-bridge");
+          const links = await listCodeLinks(projectRoot);
+          return wrapResult(
+            { success: true, data: links },
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        case "code.memories-for-code": {
+          const symbol = paramStringRequired(params, "symbol");
+          if (!symbol) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "symbol is required",
+              startTime
+            );
+          }
+          const { queryMemoriesForCode } = await import("@cleocode/core/memory/graph-memory-bridge");
+          const result = await queryMemoriesForCode(projectRoot, symbol);
+          return wrapResult(
+            { success: true, data: result },
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        case "code.for-memory": {
+          const memoryId = paramStringRequired(params, "memoryId");
+          if (!memoryId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "memoryId is required",
+              startTime
+            );
+          }
+          const { queryCodeForMemory } = await import("@cleocode/core/memory/graph-memory-bridge");
+          const result = await queryCodeForMemory(projectRoot, memoryId);
+          return wrapResult(
+            { success: true, data: result },
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        // T1262 — brain noise detector (read-only, E1-parallel per council verdict)
+        case "doctor": {
+          const { scanBrainNoise } = await import("@cleocode/core/memory/brain-doctor.js");
+          const result = await scanBrainNoise(projectRoot);
+          const assertClean = paramBool(params, "assert-clean");
+          if (assertClean) {
+            let pendingCandidates = 0;
+            try {
+              const { getBrainNativeDb: _getDoctorNativeDb } = await import("@cleocode/core/store/memory-sqlite.js");
+              const doctorNativeDb = _getDoctorNativeDb();
+              if (doctorNativeDb) {
+                const stagingTableRow = doctorNativeDb.prepare(
+                  `SELECT name FROM sqlite_master WHERE type='table' AND name IN ('brain_observations_staging', 'brain_v2_candidate') ORDER BY CASE name WHEN 'brain_observations_staging' THEN 0 ELSE 1 END LIMIT 1`
+                ).get();
+                if (stagingTableRow?.name) {
+                  const countRow = doctorNativeDb.prepare(
+                    `SELECT COUNT(*) AS cnt FROM ${stagingTableRow.name} WHERE validation_status = 'pending'`
+                  ).get();
+                  pendingCandidates = countRow?.cnt ?? 0;
+                }
+              }
+            } catch {
+            }
+            if (!result.isClean) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_BRAIN_NOISE_DETECTED",
+                `Brain noise detected: ${result.findings.length} pattern(s) across ${result.totalScanned} entries. ` + result.findings.map((f) => `${f.pattern}(${f.count})`).join(", ") + ". Run `cleo memory doctor` for details. Fix noise before enabling Sentient v1 (M7 gate).",
+                startTime
+              );
+            }
+            if (pendingCandidates > 0) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_SWEEP_PENDING",
+                `Staged sweep has ${pendingCandidates} pending brain_observations_staging rows. Run \`cleo memory sweep --status\` to review, then \`cleo memory sweep --approve <runId>\` to apply.`,
+                startTime
+              );
+            }
+          } else if (!result.isClean) {
+          }
+          return wrapResult(
+            { success: true, data: { ...result, pendingCandidates: 0 } },
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        // T1147 W7 — BRAIN noise sweep (shadow-write envelope, self-healing gate)
+        case "sweep": {
+          const dryRun = params?.["dry-run"] === true || params?.dryRun === true;
+          const approveRunId = paramString(params, "approve");
+          const statusQuery = params?.status === true;
+          const rollbackRunId = paramString(params, "rollback");
+          if (statusQuery) {
+            const { getBrainDb: _getBrainDb2, getBrainNativeDb: _getNativeDb2 } = await import("@cleocode/core/store/memory-sqlite.js");
+            const sweepDb = await _getBrainDb2(projectRoot);
+            const nativeDb2 = _getNativeDb2();
+            if (!nativeDb2) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db not available",
+                startTime
+              );
+            }
+            const rows = nativeDb2.prepare(
+              `SELECT id, status, rows_affected, created_at, approved_at, approved_by
+                 FROM brain_backfill_runs
+                 WHERE kind = 'noise-sweep-2440'
+                 ORDER BY created_at DESC
+                 LIMIT 20`
+            ).all();
+            void sweepDb;
+            return wrapResult(
+              { success: true, data: { runs: rows } },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          }
+          if (approveRunId) {
+            const { executeSweep } = await import("@cleocode/core/memory/brain-sweep-executor.js");
+            const result = await executeSweep({
+              projectRoot,
+              runId: approveRunId,
+              approvedBy: "cleo-cli"
+            });
+            if (!result.success) {
+              return errorResult(
+                "mutate",
+                "memory",
+                operation,
+                "E_SWEEP_FAILED",
+                result.errorMessage ?? "Sweep failed",
+                startTime
+              );
+            }
+            return wrapResult(
+              { success: true, data: result },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          }
+          if (rollbackRunId) {
+            const { rollbackSweep } = await import("@cleocode/core/memory/brain-sweep-executor.js");
+            const rolled = await rollbackSweep(projectRoot, rollbackRunId);
+            if (!rolled) {
+              return errorResult(
+                "mutate",
+                "memory",
+                operation,
+                "E_SWEEP_ROLLBACK_FAILED",
+                `Run '${rollbackRunId}' not found or not in staged status`,
+                startTime
+              );
+            }
+            return wrapResult(
+              { success: true, data: { rolledBack: rollbackRunId } },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          }
+          const { detectNoiseCandidates } = await import("@cleocode/core/memory/brain-noise-detector.js");
+          const detectResult = await detectNoiseCandidates(projectRoot, { dryRun });
+          return wrapResult(
+            { success: true, data: detectResult },
+            dryRun ? "query" : "mutate",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        // T791 — LLM extraction backend status
+        case "llm-status": {
+          const _anthropicCred = resolveCredentials("anthropic");
+          const extractionEnabled = _anthropicCred.apiKey !== null;
+          const resolvedSource = (() => {
+            switch (_anthropicCred.source) {
+              case "env":
+                return "env";
+              case "claude-creds":
+                return "oauth";
+              case "global-config":
+              case "project-config":
+                return "config";
+              default:
+                return "none";
+            }
+          })();
+          const providers = OAUTH_STATUS_PROVIDERS.map(resolveProviderStatus);
+          let lastExtractionRun = null;
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (nativeDb) {
+              const row = nativeDb.prepare(
+                `SELECT created_at FROM brain_observations
+                   WHERE source_type IN ('observer', 'reflector', 'transcript')
+                   ORDER BY created_at DESC LIMIT 1`
+              ).get();
+              if (row?.created_at) {
+                lastExtractionRun = row.created_at.replace(" ", "T");
+                if (!lastExtractionRun.includes("Z")) lastExtractionRun += "Z";
+              }
+            }
+          } catch {
+          }
+          return wrapResult(
+            {
+              success: true,
+              data: {
+                resolvedSource,
+                extractionEnabled,
+                lastExtractionRun,
+                testCommand: "cleo memory reflect --json",
+                providers
+              }
+            },
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        // T792 — surface unverified-but-highly-cited entries as verification queue
+        case "pending-verify": {
+          const minCitations = paramNumber(params, "minCitations") ?? 5;
+          const limitVal = paramNumber(params, "limit") ?? 50;
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (!nativeDb) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db is unavailable",
+                startTime
+              );
+            }
+            const tables = [
+              { name: "brain_observations", labelCol: "title" },
+              { name: "brain_decisions", labelCol: "decision" },
+              { name: "brain_patterns", labelCol: "pattern" },
+              { name: "brain_learnings", labelCol: "insight" }
+            ];
+            const allPending = [];
+            for (const t of tables) {
+              try {
+                const rawRows = nativeDb.prepare(
+                  `SELECT id,
+                            COALESCE(${t.labelCol}, id) AS title,
+                            source_confidence,
+                            citation_count,
+                            memory_tier,
+                            created_at
+                     FROM ${t.name}
+                     WHERE verified = 0
+                       AND citation_count >= ?
+                       AND invalid_at IS NULL
+                     ORDER BY citation_count DESC
+                     LIMIT ?`
+                ).all(minCitations, limitVal);
+                const rows = rawRows.map((raw) => {
+                  const r = raw;
+                  return {
+                    id: String(r["id"] ?? ""),
+                    title: r["title"] != null ? String(r["title"]) : null,
+                    source_confidence: r["source_confidence"] != null ? String(r["source_confidence"]) : null,
+                    citation_count: Number(r["citation_count"] ?? 0),
+                    memory_tier: r["memory_tier"] != null ? String(r["memory_tier"]) : null,
+                    created_at: String(r["created_at"] ?? "")
+                  };
+                });
+                for (const row of rows) {
+                  allPending.push({ ...row, table: t.name.replace("brain_", "") });
+                }
+              } catch {
+              }
+            }
+            allPending.sort((a, b) => b.citation_count - a.citation_count);
+            const items = allPending.slice(0, limitVal);
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  count: items.length,
+                  minCitations,
+                  items,
+                  hint: `Run 'cleo memory verify <id>' to promote an entry to verified=true`
+                }
+              },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (dbErr) {
+            return handleErrorResult("query", "memory", operation, dbErr, startTime);
+          }
+        }
+        // T1006 — summarized top-N observations as session briefing digest
+        case "digest": {
+          const limitVal = paramNumber(params, "limit") ?? 10;
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (!nativeDb) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db is unavailable",
+                startTime
+              );
+            }
+            let rows = [];
+            try {
+              const rawRows = nativeDb.prepare(
+                `SELECT id,
+                          title,
+                          text,
+                          citation_count,
+                          quality_score,
+                          memory_tier,
+                          created_at
+                   FROM brain_observations
+                   WHERE invalid_at IS NULL
+                   ORDER BY citation_count DESC, quality_score DESC
+                   LIMIT ?`
+              ).all(limitVal);
+              rows = rawRows.map((raw) => {
+                const r = raw;
+                return {
+                  id: String(r["id"] ?? ""),
+                  title: r["title"] != null ? String(r["title"]) : null,
+                  text: String(r["text"] ?? ""),
+                  citation_count: Number(r["citation_count"] ?? 0),
+                  quality_score: r["quality_score"] != null ? Number(r["quality_score"]) : null,
+                  memory_tier: r["memory_tier"] != null ? String(r["memory_tier"]) : null,
+                  created_at: String(r["created_at"] ?? "")
+                };
+              });
+            } catch {
+            }
+            const summaryLines = rows.map((r, i) => {
+              const label = r.title ?? r.id;
+              const snippet = r.text.slice(0, 80).replace(/\n/g, " ");
+              return `${i + 1}. [${r.id}] ${label} \u2014 ${snippet}${r.text.length > 80 ? "\u2026" : ""}`;
+            });
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  count: rows.length,
+                  limit: limitVal,
+                  summary: summaryLines.join("\n"),
+                  observations: rows
+                }
+              },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (dbErr) {
+            return handleErrorResult("query", "memory", operation, dbErr, startTime);
+          }
+        }
+        // T1006 — tail recent observations with optional filters
+        case "recent": {
+          const limitVal = paramNumber(params, "limit") ?? 20;
+          const sinceParam = paramString(params, "since");
+          const typeFilter = paramString(params, "type");
+          const sessionFilter = paramString(params, "session");
+          const tierFilter = paramString(params, "tier");
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (!nativeDb) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db is unavailable",
+                startTime
+              );
+            }
+            let sinceIso;
+            if (sinceParam) {
+              const durationMatch = /^(\d+)(m|h|d|w)$/i.exec(sinceParam);
+              if (durationMatch) {
+                const amount = Number(durationMatch[1]);
+                const unit = durationMatch[2].toLowerCase();
+                const ms = unit === "m" ? amount * 6e4 : unit === "h" ? amount * 36e5 : unit === "d" ? amount * 864e5 : amount * 7 * 864e5;
+                sinceIso = new Date(Date.now() - ms).toISOString().replace("T", " ").slice(0, 19);
+              } else {
+                sinceIso = sinceParam;
+              }
+            }
+            const clauses = ["invalid_at IS NULL"];
+            const bindArgs = [];
+            if (sinceIso) {
+              clauses.push("created_at >= ?");
+              bindArgs.push(sinceIso);
+            }
+            if (typeFilter) {
+              clauses.push("type = ?");
+              bindArgs.push(typeFilter);
+            }
+            if (sessionFilter) {
+              clauses.push("source_session_id = ?");
+              bindArgs.push(sessionFilter);
+            }
+            if (tierFilter) {
+              clauses.push("memory_tier = ?");
+              bindArgs.push(tierFilter);
+            }
+            bindArgs.push(limitVal);
+            const whereClause = clauses.join(" AND ");
+            const rawRows = nativeDb.prepare(
+              `SELECT id, title, narrative AS text, type, source_session_id, memory_tier, created_at
+                 FROM brain_observations
+                 WHERE ${whereClause}
+                 ORDER BY created_at DESC
+                 LIMIT ?`
+            ).all(...bindArgs);
+            const rows = rawRows.map((raw) => {
+              const r = raw;
+              return {
+                id: String(r["id"] ?? ""),
+                title: r["title"] != null ? String(r["title"]) : null,
+                text: String(r["text"] ?? ""),
+                type: r["type"] != null ? String(r["type"]) : null,
+                source_session_id: r["source_session_id"] != null ? String(r["source_session_id"]) : null,
+                memory_tier: r["memory_tier"] != null ? String(r["memory_tier"]) : null,
+                created_at: String(r["created_at"] ?? "")
+              };
+            });
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  count: rows.length,
+                  limit: limitVal,
+                  since: sinceIso ?? null,
+                  observations: rows
+                }
+              },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (dbErr) {
+            return handleErrorResult("query", "memory", operation, dbErr, startTime);
+          }
+        }
+        // T1006 — read diary-typed observations
+        case "diary": {
+          const limitVal = paramNumber(params, "limit") ?? 20;
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (!nativeDb) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db is unavailable",
+                startTime
+              );
+            }
+            const rawRows = nativeDb.prepare(
+              `SELECT id, title, narrative AS text, source_session_id, memory_tier, created_at
+                 FROM brain_observations
+                 WHERE type = 'diary'
+                   AND invalid_at IS NULL
+                 ORDER BY created_at DESC
+                 LIMIT ?`
+            ).all(limitVal);
+            const rows = rawRows.map((raw) => {
+              const r = raw;
+              return {
+                id: String(r["id"] ?? ""),
+                title: r["title"] != null ? String(r["title"]) : null,
+                text: String(r["text"] ?? ""),
+                source_session_id: r["source_session_id"] != null ? String(r["source_session_id"]) : null,
+                memory_tier: r["memory_tier"] != null ? String(r["memory_tier"]) : null,
+                created_at: String(r["created_at"] ?? "")
+              };
+            });
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  count: rows.length,
+                  limit: limitVal,
+                  type: "diary",
+                  entries: rows
+                }
+              },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (dbErr) {
+            return handleErrorResult("query", "memory", operation, dbErr, startTime);
+          }
+        }
+        // T1006 — long-poll stream of recent brain writes (SSE-style polling stub)
+        // Returns the latest N observations created after an optional cursor.
+        // Clients call this in a loop, advancing the cursor with the returned `nextCursor`.
+        case "watch": {
+          const cursorParam = paramString(params, "cursor");
+          const limitVal = paramNumber(params, "limit") ?? 10;
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (!nativeDb) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db is unavailable",
+                startTime
+              );
+            }
+            const clauses = ["invalid_at IS NULL"];
+            const bindArgs = [];
+            if (cursorParam) {
+              clauses.push("created_at > ?");
+              bindArgs.push(cursorParam);
+            }
+            bindArgs.push(limitVal);
+            const rawRows = nativeDb.prepare(
+              `SELECT id, title, narrative AS text, type, memory_tier, created_at
+                 FROM brain_observations
+                 WHERE ${clauses.join(" AND ")}
+                 ORDER BY created_at ASC
+                 LIMIT ?`
+            ).all(...bindArgs);
+            const rows = rawRows.map((raw) => {
+              const r = raw;
+              return {
+                id: String(r["id"] ?? ""),
+                title: r["title"] != null ? String(r["title"]) : null,
+                text: String(r["text"] ?? ""),
+                type: r["type"] != null ? String(r["type"]) : null,
+                memory_tier: r["memory_tier"] != null ? String(r["memory_tier"]) : null,
+                created_at: String(r["created_at"] ?? "")
+              };
+            });
+            const nextCursor = rows.length > 0 ? rows[rows.length - 1].created_at : cursorParam ?? null;
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  count: rows.length,
+                  cursor: cursorParam ?? null,
+                  nextCursor,
+                  events: rows,
+                  hint: "Poll again with cursor=nextCursor to stream new writes"
+                }
+              },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (dbErr) {
+            return handleErrorResult("query", "memory", operation, dbErr, startTime);
+          }
+        }
+        // T1003 — list staged backfill runs (pending/approved/rolled-back)
+        case "backfill.list": {
+          try {
+            const status = paramString(params, "status");
+            const limit = paramNumber(params, "limit");
+            const runs = await listBackfillRuns(projectRoot, { status, limit });
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  count: runs.length,
+                  runs,
+                  hint: `Use 'cleo memory backfill.approve <runId>' or 'cleo memory backfill.rollback <runId>'`
+                }
+              },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (listErr) {
+            return handleErrorResult("query", "memory", operation, listErr, startTime);
+          }
+        }
+        // T999 — stream brain.db memory-bridge content directly (cli mode default)
+        case "bridge": {
+          const content = await generateMemoryBridgeContent(projectRoot);
+          return wrapResult(
+            { success: true, data: { content } },
+            "query",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        // T997 — read-only view over STDP weights + retrieval log + citation data
+        case "promote-explain": {
+          const entryId = paramStringRequired(params, "id");
+          if (!entryId) {
+            return errorResult(
+              "query",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "id is required",
+              startTime
+            );
+          }
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (!nativeDb) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db is unavailable",
+                startTime
+              );
+            }
+            const typedTables = [
+              { name: "brain_observations", labelCol: "title" },
+              { name: "brain_decisions", labelCol: "decision" },
+              { name: "brain_patterns", labelCol: "pattern" },
+              { name: "brain_learnings", labelCol: "insight" }
+            ];
+            let foundTable = "";
+            let typedRow;
+            for (const t of typedTables) {
+              try {
+                const row = nativeDb.prepare(
+                  `SELECT id, citation_count, quality_score, memory_tier, tier_promoted_at, verified
+                     FROM ${t.name}
+                     WHERE id = ? AND invalid_at IS NULL
+                     LIMIT 1`
+                ).get(entryId);
+                if (row) {
+                  typedRow = row;
+                  foundTable = t.name.replace("brain_", "");
+                  break;
+                }
+              } catch {
+              }
+            }
+            if (!typedRow) {
+              return errorResult(
+                "query",
+                "memory",
+                operation,
+                "E_NOT_FOUND",
+                `Entry '${entryId}' not found in any brain table (or is invalidated)`,
+                startTime
+              );
+            }
+            let pruneCandidate = false;
+            try {
+              const pruneRow = nativeDb.prepare(`SELECT prune_candidate FROM brain_${foundTable} WHERE id = ? LIMIT 1`).get(entryId);
+              pruneCandidate = (pruneRow?.prune_candidate ?? 0) === 1;
+            } catch {
+            }
+            let stdpWeights = [];
+            try {
+              const stmt = nativeDb.prepare(
+                `SELECT from_id, to_id, edge_type, weight,
+                        COALESCE(reinforcement_count, 0) AS reinforcement_count,
+                        last_reinforced_at
+                 FROM brain_page_edges
+                 WHERE (from_id = ? OR to_id = ?)
+                   AND plasticity_class IN ('hebbian', 'stdp')
+                 ORDER BY weight DESC
+                 LIMIT 20`
+              );
+              stdpWeights = typedAll(stmt, entryId, entryId);
+            } catch {
+              try {
+                const stmt = nativeDb.prepare(
+                  `SELECT from_id, to_id, edge_type, weight,
+                          COALESCE(reinforcement_count, 0) AS reinforcement_count,
+                          last_reinforced_at
+                   FROM brain_page_edges
+                   WHERE from_id = ? OR to_id = ?
+                   ORDER BY weight DESC
+                   LIMIT 20`
+                );
+                stdpWeights = typedAll(stmt, entryId, entryId);
+              } catch {
+              }
+            }
+            let retrievalCount = 0;
+            let lastAccessedAt = null;
+            try {
+              const logRow = nativeDb.prepare(
+                `SELECT COUNT(*) AS retrieval_count,
+                          MAX(created_at) AS last_accessed_at
+                   FROM brain_retrieval_log
+                   WHERE entry_ids LIKE ?`
+              ).get(`%${entryId}%`);
+              retrievalCount = logRow?.retrieval_count ?? 0;
+              lastAccessedAt = logRow?.last_accessed_at ?? null;
+              if (lastAccessedAt && !lastAccessedAt.includes("T")) {
+                lastAccessedAt = lastAccessedAt.replace(" ", "T");
+                if (!lastAccessedAt.endsWith("Z")) lastAccessedAt += "Z";
+              }
+            } catch {
+            }
+            const citationCount = typedRow.citation_count ?? 0;
+            const qualityScore = typedRow.quality_score ?? null;
+            const memoryTier = typedRow.memory_tier ?? null;
+            const promotedAt = typedRow.tier_promoted_at ?? null;
+            const verified = typedRow.verified === 1;
+            const stdpWeightMax = stdpWeights.length > 0 ? Math.max(...stdpWeights.map((e) => e.weight)) : 0;
+            let tier;
+            let explanation;
+            if (pruneCandidate) {
+              tier = "rejected";
+              explanation = `Entry flagged as prune candidate. quality_score=${qualityScore ?? "null"}, citation_count=${citationCount}, retrieval_count=${retrievalCount}. Meets pruning criteria: low quality and/or zero citations over time.`;
+            } else if (memoryTier === "long" || memoryTier === "medium" || verified || promotedAt !== null) {
+              tier = "promoted";
+              explanation = `Entry promoted to memory tier '${memoryTier ?? "promoted"}'. citation_count=${citationCount}, retrieval_count=${retrievalCount}, stdp_weight_max=${stdpWeightMax.toFixed(3)}, verified=${verified}. ` + (promotedAt ? `Tier promotion recorded at ${promotedAt}.` : "Verified by owner.");
+            } else {
+              tier = "pending";
+              explanation = `Entry has not yet been promoted or flagged for pruning. memory_tier='${memoryTier ?? "short"}', citation_count=${citationCount}, retrieval_count=${retrievalCount}, stdp_weight_max=${stdpWeightMax.toFixed(3)}. Increase retrieval frequency or citation count to qualify for promotion.`;
+            }
+            const scoreBreakdown = {
+              stdpWeightMax,
+              retrievalCount,
+              lastAccessedAt,
+              citationCount,
+              qualityScore,
+              pruneCandidate,
+              verified
+            };
+            const weights = stdpWeights.map((e) => ({
+              fromId: e.from_id,
+              toId: e.to_id,
+              edgeType: e.edge_type,
+              weight: e.weight,
+              reinforcementCount: e.reinforcement_count,
+              lastReinforcedAt: e.last_reinforced_at
+            }));
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  id: entryId,
+                  table: foundTable,
+                  tier,
+                  explanation,
+                  promotedAt: promotedAt ?? null,
+                  stdpWeights: weights,
+                  scoreBreakdown
+                }
+              },
+              "query",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (dbErr) {
+            return handleErrorResult("query", "memory", operation, dbErr, startTime);
+          }
+        }
+        default:
+          return unsupportedOp("query", "memory", operation, startTime);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      getLogger("domain:memory").error(
+        { gateway: "query", domain: "memory", operation, err: error },
+        message
+      );
+      return handleErrorResult("query", "memory", operation, error, startTime);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Mutate
+  // -----------------------------------------------------------------------
+  async mutate(operation, params) {
+    const projectRoot = getProjectRoot();
+    const startTime = Date.now();
+    try {
+      switch (operation) {
+        case "observe": {
+          const text = paramStringRequired(params, "text");
+          if (!text) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "text is required",
+              startTime
+            );
+          }
+          let attachmentRefs;
+          const attachArr = paramStringArray(params, "attach");
+          const attachStr = paramString(params, "attach");
+          if (attachArr !== void 0) {
+            attachmentRefs = attachArr.filter((r) => r.length > 0);
+          } else if (attachStr?.trim()) {
+            attachmentRefs = attachStr.split(",").map((r) => r.trim()).filter(Boolean);
+          }
+          const result = await memoryObserve(
+            {
+              text,
+              title: paramString(params, "title"),
+              type: paramString(params, "type"),
+              project: paramString(params, "project"),
+              sourceSessionId: paramString(params, "sourceSessionId"),
+              sourceType: paramString(params, "sourceType"),
+              // T417: optional agent provenance for mental model observations
+              agent: paramString(params, "agent"),
+              // T799: optional attachment refs
+              attachmentRefs,
+              // T12494: interactive observe opts in to the System One type choice.
+              askTypeDecision: true
+            },
+            projectRoot
+          );
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        case "decision.store": {
+          const decision = paramStringRequired(params, "decision");
+          const rationale = paramStringRequired(params, "rationale");
+          if (!decision || !rationale) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "decision and rationale are required",
+              startTime
+            );
+          }
+          const confirmationStateRaw = paramString(params, "confirmationState");
+          const decidedByRaw = paramString(params, "decidedBy");
+          const result = await memoryDecisionStore(
+            {
+              decision,
+              rationale,
+              alternatives: paramStringArray(params, "alternatives"),
+              taskId: paramString(params, "taskId"),
+              sessionId: paramString(params, "sessionId"),
+              adrPath: paramString(params, "adrPath"),
+              supersedes: paramString(params, "supersedes"),
+              confirmationState: confirmationStateRaw === "proposed" || confirmationStateRaw === "accepted" || confirmationStateRaw === "superseded" ? confirmationStateRaw : void 0,
+              decidedBy: decidedByRaw === "owner" || decidedByRaw === "council" || decidedByRaw === "agent" ? decidedByRaw : void 0
+            },
+            projectRoot
+          );
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        case "pattern.store": {
+          const patternText = paramStringRequired(params, "pattern");
+          const context = paramStringRequired(params, "context");
+          if (!patternText || !context) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "pattern and context are required",
+              startTime
+            );
+          }
+          const storePatternType = paramString(params, "type");
+          const storePatternImpact = paramString(params, "impact");
+          const result = await memoryPatternStore(
+            {
+              type: storePatternType || "workflow",
+              pattern: patternText,
+              context,
+              impact: storePatternImpact,
+              antiPattern: paramString(params, "antiPattern"),
+              mitigation: paramString(params, "mitigation"),
+              examples: paramStringArray(params, "examples"),
+              successRate: paramNumber(params, "successRate")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        case "learning.store": {
+          const insight = paramStringRequired(params, "insight");
+          const source = paramStringRequired(params, "source");
+          if (!insight || !source) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "insight and source are required",
+              startTime
+            );
+          }
+          const result = await memoryLearningStore(
+            {
+              insight,
+              source,
+              confidence: paramNumber(params, "confidence") ?? 0.5,
+              actionable: paramBool(params, "actionable"),
+              application: paramString(params, "application"),
+              applicableTypes: paramStringArray(params, "applicableTypes")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        case "link": {
+          const taskId = paramStringRequired(params, "taskId");
+          const entryId = paramStringRequired(params, "entryId");
+          if (!taskId || !entryId) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "taskId and entryId are required",
+              startTime
+            );
+          }
+          const result = await memoryLink({ taskId, entryId }, projectRoot);
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        case "graph.add": {
+          const result = await memoryGraphAdd(
+            {
+              nodeId: paramString(params, "nodeId"),
+              nodeType: paramString(params, "nodeType"),
+              label: paramString(params, "label"),
+              metadataJson: paramString(params, "metadataJson"),
+              fromId: paramString(params, "fromId"),
+              toId: paramString(params, "toId"),
+              edgeType: paramString(params, "edgeType"),
+              weight: paramNumber(params, "weight")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        case "graph.remove": {
+          const result = await memoryGraphRemove(
+            {
+              nodeId: paramString(params, "nodeId"),
+              fromId: paramString(params, "fromId"),
+              toId: paramString(params, "toId"),
+              edgeType: paramString(params, "edgeType")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        case "code.link": {
+          const memoryId = paramStringRequired(params, "memoryId");
+          const codeSymbol = paramStringRequired(params, "codeSymbol");
+          if (!memoryId || !codeSymbol) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "memoryId and codeSymbol are required",
+              startTime
+            );
+          }
+          const { linkMemoryToCode } = await import("@cleocode/core/memory/graph-memory-bridge");
+          const linked = await linkMemoryToCode(projectRoot, memoryId, codeSymbol);
+          return wrapResult(
+            { success: true, data: { linked } },
+            "mutate",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        case "code.auto-link": {
+          const { autoLinkMemories } = await import("@cleocode/core/memory/graph-memory-bridge");
+          const result = await autoLinkMemories(projectRoot);
+          return wrapResult(
+            { success: true, data: result },
+            "mutate",
+            "memory",
+            operation,
+            startTime
+          );
+        }
+        // T792 — promote an agent observation to verified=true (owner/cleo-prime only)
+        case "verify": {
+          const entryId = paramStringRequired(params, "id");
+          if (!entryId) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "id is required (the observation/decision/pattern/learning ID to verify)",
+              startTime
+            );
+          }
+          const VERIFY_PERMITTED_IDENTITIES = /* @__PURE__ */ new Set([
+            "owner",
+            "project-orchestrator",
+            "cleo-prime"
+            // legacy alias — see migration shim note above
+          ]);
+          const callerAgent = paramString(params, "agent");
+          if (callerAgent && !VERIFY_PERMITTED_IDENTITIES.has(callerAgent)) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_FORBIDDEN",
+              `verify requires agent identity 'project-orchestrator' or 'owner'; got '${callerAgent}'`,
+              startTime
+            );
+          }
+          try {
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            if (!nativeDb) {
+              return errorResult(
+                "mutate",
+                "memory",
+                operation,
+                "E_DB_UNAVAILABLE",
+                "brain.db is unavailable",
+                startTime
+              );
+            }
+            const tables = [
+              "brain_observations",
+              "brain_decisions",
+              "brain_patterns",
+              "brain_learnings"
+            ];
+            const now = (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 19);
+            let found = false;
+            let foundTable = "";
+            let alreadyVerified = false;
+            let foundNarrative = null;
+            for (const tbl of tables) {
+              try {
+                const selectSql = tbl === "brain_observations" ? `SELECT id, verified, narrative FROM ${tbl} WHERE id = ? AND invalid_at IS NULL LIMIT 1` : `SELECT id, verified FROM ${tbl} WHERE id = ? AND invalid_at IS NULL LIMIT 1`;
+                const row = nativeDb.prepare(selectSql).get(entryId);
+                if (row) {
+                  found = true;
+                  foundTable = tbl;
+                  alreadyVerified = row.verified === 1;
+                  foundNarrative = row.narrative ?? null;
+                  if (!alreadyVerified) {
+                    if (tbl === "brain_observations") {
+                      try {
+                        nativeDb.prepare(
+                          `UPDATE ${tbl} SET verified = 1, updated_at = ?, validated_at = ? WHERE id = ?`
+                        ).run(now, now, entryId);
+                      } catch {
+                        nativeDb.prepare(`UPDATE ${tbl} SET verified = 1, updated_at = ? WHERE id = ?`).run(now, entryId);
+                      }
+                    } else {
+                      nativeDb.prepare(`UPDATE ${tbl} SET verified = 1, updated_at = ? WHERE id = ?`).run(now, entryId);
+                    }
+                  }
+                  break;
+                }
+              } catch {
+              }
+            }
+            if (!found) {
+              return errorResult(
+                "mutate",
+                "memory",
+                operation,
+                "E_NOT_FOUND",
+                `Entry '${entryId}' not found in any brain table (or is invalidated)`,
+                startTime
+              );
+            }
+            let attachmentMissing;
+            let attachmentId;
+            if (foundTable === "brain_observations" && foundNarrative) {
+              try {
+                const payload = JSON.parse(
+                  foundNarrative
+                );
+                if (payload.kind === "doc-attachment" && typeof payload.attachmentId === "string") {
+                  attachmentId = payload.attachmentId;
+                  const store = createAttachmentStore();
+                  const meta = await store.getMetadata(payload.attachmentId);
+                  attachmentMissing = meta === null;
+                }
+              } catch {
+              }
+            }
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  id: entryId,
+                  table: foundTable.replace("brain_", ""),
+                  verified: true,
+                  alreadyVerified,
+                  verifiedAt: alreadyVerified ? null : now,
+                  // T9976 — doc-attachment round-trip fields (only present when applicable).
+                  ...attachmentId !== void 0 ? { attachmentId } : {},
+                  ...attachmentMissing !== void 0 ? { attachmentMissing } : {},
+                  ...attachmentMissing === true ? {
+                    warning: `Attachment '${attachmentId}' referenced by this observation no longer exists in the docs store. The doc may have been removed.`
+                  } : {}
+                }
+              },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (dbErr) {
+            return handleErrorResult("mutate", "memory", operation, dbErr, startTime);
+          }
+        }
+        // T1006 — write a diary-typed observation (thin wrapper over observe)
+        case "diary.write": {
+          const text = paramStringRequired(params, "text");
+          if (!text) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "text is required",
+              startTime
+            );
+          }
+          const result = await memoryObserve(
+            {
+              text,
+              title: paramString(params, "title"),
+              type: "diary",
+              sourceSessionId: paramString(params, "sourceSessionId"),
+              agent: paramString(params, "agent")
+            },
+            projectRoot
+          );
+          return wrapResult(result, "mutate", "memory", operation, startTime);
+        }
+        // T1004 — flush in-flight observations + WAL checkpoint before context compaction
+        case "precompact-flush": {
+          try {
+            const flushResult = await precompactFlush(projectRoot);
+            return wrapResult(
+              {
+                success: true,
+                data: flushResult
+              },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (flushErr) {
+            return handleErrorResult("mutate", "memory", operation, flushErr, startTime);
+          }
+        }
+        // T1003 — stage a new graph backfill run (rows held pending approval)
+        case "backfill.run": {
+          try {
+            const source = paramString(params, "source");
+            const kind = paramString(params, "kind");
+            const targetTable = paramString(params, "targetTable");
+            const nodeIds = paramStringArray(params, "nodeIds");
+            if (params?.["nodeIds"] !== void 0 && !nodeIds)
+              throw new Error("nodeIds must be an array of qualified graph IDs.");
+            const result = await stagedBackfillRun(projectRoot, {
+              source,
+              kind,
+              targetTable,
+              nodeIds
+            });
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  runId: result.run.id,
+                  run: result.run,
+                  empty: result.empty,
+                  hint: result.empty ? "All candidate nodes already present \u2014 nothing to backfill" : `Run staged with ${result.run.rowsAffected} rows. Approve with 'cleo memory backfill.approve ${result.run.id}'`
+                }
+              },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (runErr) {
+            return handleErrorResult("mutate", "memory", operation, runErr, startTime);
+          }
+        }
+        // T1003 — approve a staged backfill run (commits rows to live tables)
+        case "backfill.approve": {
+          const runId = paramString(params, "runId");
+          if (!runId) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "runId is required",
+              startTime
+            );
+          }
+          try {
+            const approvedBy = paramString(params, "approvedBy");
+            const result = await approveBackfillRun(projectRoot, runId, approvedBy);
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  runId: result.run.id,
+                  run: result.run,
+                  alreadySettled: result.alreadySettled,
+                  backfillResult: result.backfillResult ?? null,
+                  hint: result.alreadySettled ? `Run '${runId}' was already settled (status: ${result.run.status})` : `Backfill committed: ${result.backfillResult?.nodesInserted ?? 0} nodes inserted`
+                }
+              },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (approveErr) {
+            return handleErrorResult("mutate", "memory", operation, approveErr, startTime);
+          }
+        }
+        // T1003 — rollback a backfill run (removes staged/committed rows)
+        case "backfill.rollback": {
+          const runId = paramString(params, "runId");
+          if (!runId) {
+            return errorResult(
+              "mutate",
+              "memory",
+              operation,
+              "E_INVALID_INPUT",
+              "runId is required",
+              startTime
+            );
+          }
+          try {
+            const result = await rollbackBackfillRun(projectRoot, runId);
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  runId: result.run.id,
+                  run: result.run,
+                  alreadySettled: result.alreadySettled,
+                  deletedRows: result.deletedRows,
+                  hint: result.alreadySettled ? `Run '${runId}' was already rolled back` : result.deletedRows > 0 ? `Rolled back: deleted ${result.deletedRows} committed rows` : "Run was still staged \u2014 no committed rows to delete"
+                }
+              },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (rollbackErr) {
+            return handleErrorResult("mutate", "memory", operation, rollbackErr, startTime);
+          }
+        }
+        // T1147 W7 — sweep mutate operations (approve, rollback) delegate to query handler
+        // which already handles all sweep sub-commands via a unified case block.
+        case "sweep":
+          return this.query(operation, params);
+        // T9976 — backfill: emit memory observations for existing doc attachments
+        // that do not yet have a corresponding brain observation.
+        case "backfill-docs": {
+          try {
+            const store = createAttachmentStore();
+            const allAttachments = await store.listAllInProject();
+            await getBrainDb(projectRoot);
+            const nativeDb = getBrainNativeDb(projectRoot);
+            const existingAttachmentIds = /* @__PURE__ */ new Set();
+            if (nativeDb) {
+              try {
+                const existing = nativeDb.prepare(
+                  `SELECT narrative FROM brain_observations
+                     WHERE narrative LIKE '%"kind":"doc-attachment"%'
+                       AND invalid_at IS NULL`
+                ).all();
+                for (const row of existing) {
+                  if (!row.narrative) continue;
+                  try {
+                    const p = JSON.parse(row.narrative);
+                    if (p.kind === "doc-attachment" && typeof p.attachmentId === "string") {
+                      existingAttachmentIds.add(p.attachmentId);
+                    }
+                  } catch {
+                  }
+                }
+              } catch {
+              }
+            }
+            let emitted = 0;
+            let skipped = 0;
+            const emittedIds = [];
+            for (const item of allAttachments) {
+              const attId = item.metadata.id;
+              if (existingAttachmentIds.has(attId)) {
+                skipped++;
+                continue;
+              }
+              const extras = await store.getExtras(attId);
+              const slug = extras?.slug ?? void 0;
+              const type = extras?.type ?? void 0;
+              const payload = {
+                kind: "doc-attachment",
+                attachmentId: attId,
+                ownerId: item.ownerId,
+                addedAt: item.metadata.createdAt,
+                ...slug !== void 0 ? { slug } : {},
+                ...type !== void 0 ? { type } : {}
+              };
+              const { memoryObserve: brainObserve } = await import("@cleocode/core/memory/engine-compat");
+              await brainObserve(
+                {
+                  text: JSON.stringify(payload),
+                  title: `Doc attached: ${slug ?? attId}`,
+                  type: "feature",
+                  // sourceType: 'manual' avoids the mental-model queue (5s flush interval).
+                  // The mental-model queue is only entered when `agent` is set + type is in
+                  // MENTAL_MODEL_TYPES. Using 'manual' bypasses this path entirely.
+                  sourceType: "manual"
+                },
+                projectRoot
+              ).catch(() => {
+              });
+              emittedIds.push(attId);
+              emitted++;
+            }
+            return wrapResult(
+              {
+                success: true,
+                data: {
+                  total: allAttachments.length,
+                  emitted,
+                  skipped,
+                  emittedAttachmentIds: emittedIds,
+                  hint: emitted === 0 ? "All existing attachments already have memory observations \u2014 nothing to backfill." : `Emitted ${emitted} new doc-attachment observations. Use 'cleo memory find <slug>' to verify.`
+                }
+              },
+              "mutate",
+              "memory",
+              operation,
+              startTime
+            );
+          } catch (backfillErr) {
+            return handleErrorResult("mutate", "memory", operation, backfillErr, startTime);
+          }
+        }
+        default:
+          return unsupportedOp("mutate", "memory", operation, startTime);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      getLogger("domain:memory").error(
+        { gateway: "mutate", domain: "memory", operation, err: error },
+        message
+      );
+      return handleErrorResult("mutate", "memory", operation, error, startTime);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Supported operations
+  // -----------------------------------------------------------------------
+  getSupportedOperations() {
+    return {
+      query: [
+        "find",
+        "timeline",
+        "fetch",
+        "decision.find",
+        "pattern.find",
+        "learning.find",
+        "graph.show",
+        "graph.neighbors",
+        "graph.trace",
+        "graph.related",
+        "graph.context",
+        "graph.stats",
+        "reason.why",
+        "reason.similar",
+        "search.hybrid",
+        "quality",
+        "code.links",
+        "code.memories-for-code",
+        "code.for-memory",
+        // T1262 — brain noise detector (E1-parallel, read-only) + assert-clean gate
+        "doctor",
+        // T1147 W7 — sweep status query (dry-run mode)
+        "sweep",
+        // T791 — LLM extraction backend status
+        "llm-status",
+        // T792 — pending verification queue
+        "pending-verify",
+        // T999 — live memory-bridge content from brain.db (cli mode)
+        "bridge",
+        // T997 — read-only explainability view for promotion decisions
+        "promote-explain",
+        // T1006 — summarized top-N observations as session briefing digest
+        "digest",
+        // T1006 — tail recent observations with optional filters
+        "recent",
+        // T1006 — diary-typed observations (requires diary enum from T1005)
+        "diary",
+        // T1006 — long-poll stream of recent brain writes (SSE-style polling stub)
+        "watch",
+        // T1003 — list staged backfill runs
+        "backfill.list"
+      ],
+      mutate: [
+        "observe",
+        "decision.store",
+        "pattern.store",
+        "learning.store",
+        "link",
+        "graph.add",
+        "graph.remove",
+        "code.link",
+        "code.auto-link",
+        // T792 — promote entry to verified=true
+        "verify",
+        // T1004 — flush in-flight observations + WAL checkpoint before context compaction
+        "precompact-flush",
+        // T1006 — write a diary-typed observation
+        "diary.write",
+        // T1147 W7 — sweep mutate operations (approve, rollback)
+        "sweep",
+        // T1003 — staged backfill operations
+        "backfill.run",
+        "backfill.approve",
+        "backfill.rollback",
+        // T9976 — emit memory observations for existing doc attachments
+        "backfill-docs"
+      ]
+    };
+  }
+};
+export {
+  MemoryHandler
+};
+//# sourceMappingURL=memory-IAEYKXG6.js.map