pi-mega-compact 0.4.20 → 0.4.23

package/extensions/conflict-scan.ts

@@ -0,0 +1,209 @@
+/**
+ * conflict-scan.ts — detect other installed pi extensions that overlap with
+ * pi-mega-compact's two owned responsibilities:
+ *
+ *   1. Conversation auto-compaction (we hook session_before_compact).
+ *   2. Durable "save to memory" (we now keep a `memories` table in our SQLite).
+ *
+ * This is a DETECT-AND-WARN scanner only. pi has no pre-load / veto hook — one
+ * extension cannot block another from loading — so we inspect the installed
+ * package set at startup and on demand, then report overlaps. No config is
+ * mutated. (See memory `pi-memory-mcp-review` for the original conflict pattern.)
+ *
+ * Pi-agnostic: reads package.json + greps source. No pi runtime types, so it is
+ * unit-testable against a fixture node_modules tree.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type ConflictKind = "compaction" | "memory" | "tool-output";
+export type ConflictSeverity = "high" | "info";
+
+export interface ConflictHit {
+  package: string;
+  severity: ConflictSeverity;
+  kind: ConflictKind;
+  evidence: string[];
+  /** One-line recommended action for the user. */
+  recommendation: string;
+}
+
+export interface ConflictReport {
+  scanned: string[];
+  conflicts: ConflictHit[];
+}
+
+// Marker sets. A package is flagged when its source matches a marker in a
+// category. File-grep (not AST) keeps this dependency-free and fast.
+const MARKERS = {
+  // Directly competes with our conversation compaction.
+  compaction: [
+    "session_before_compact",
+    "session_compact",
+    "compactSession",
+    "autoCompact",
+    "auto_compact",
+  ],
+  // Saves durable memory to its own store — the takeover target.
+  memory: [
+    "MEMORY_TOOL",
+    "learn-memory",
+    "saveMemory",
+    "memoryPolicy",
+    "wal_checkpoint",
+    "store/db.ts",
+    "memoryTool",
+  ],
+  // Tool-output shaping (compact/summarize tool results) — overlap, not a rival.
+  toolOutput: [
+    "tool_result",
+    "ToolResult",
+  ],
+} as const;
+
+/** Resolve the node_modules dir that contains this package (or env override). */
+export function resolveExtensionRoot(selfDir: string = dirname(fileURLToPath(import.meta.url))): string | null {
+  const override = process.env.MEGACOMPACT_EXT_SCAN_DIR;
+  if (override && override.trim() !== "") return override;
+  // selfDir is <root>/extensions or <root>/dist/extensions. Walk up to the
+  // node_modules that holds pi-mega-compact.
+  let dir = selfDir;
+  for (let i = 0; i < 6; i++) {
+    const candidate = join(dir, "node_modules");
+    if (existsSync(candidate) && existsSync(join(candidate, "pi-mega-compact"))) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Recursively collect source-ish files under a package, capped to avoid scans. */
+function collectFiles(root: string, max = 400): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    if (out.length >= max) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= max) return;
+      const full = join(dir, e);
+      let st;
+      try {
+        st = statSync(full);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (e === "node_modules" || e === ".git") continue;
+        walk(full);
+      } else if (/\.(ts|js|mjs|cjs|json|md)$/.test(e)) {
+        out.push(full);
+      }
+    }
+  };
+  walk(root);
+  return out;
+}
+
+/** Grep a package's source for any marker in `keys`; return matched markers. */
+function matchMarkers(pkgDir: string, keys: readonly string[]): string[] {
+  const found = new Set<string>();
+  let files: string[];
+  try {
+    files = collectFiles(pkgDir);
+  } catch {
+    return [];
+  }
+  for (const f of files) {
+    let text: string;
+    try {
+      text = readFileSync(f, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const m of keys) {
+      if (text.includes(m)) found.add(m);
+    }
+    if (found.size === keys.length) break;
+  }
+  return [...found];
+}
+
+/**
+ * Scan installed extensions for overlaps with pi-mega-compact.
+ * @param selfName package name to skip (defaults to this package's name).
+ */
+export function detectConflicts(selfName = "pi-mega-compact"): ConflictReport {
+  const root = resolveExtensionRoot();
+  const scanned: string[] = [];
+  const conflicts: ConflictHit[] = [];
+  if (!root || !existsSync(root)) return { scanned, conflicts };
+
+  let entries: string[];
+  try {
+    entries = readdirSync(root);
+  } catch {
+    return { scanned, conflicts };
+  }
+
+  for (const name of entries) {
+    const pkgDir = join(root, name);
+    if (!statSync(pkgDir).isDirectory()) continue;
+    const pkgJson = join(pkgDir, "package.json");
+    if (!existsSync(pkgJson)) continue;
+    let pkg: { name?: string; pi?: { extensions?: string[] } };
+    try {
+      pkg = JSON.parse(readFileSync(pkgJson, "utf-8"));
+    } catch {
+      continue;
+    }
+    const pkgName = pkg.name ?? name;
+    if (pkgName === selfName) continue;
+    // Only consider packages that declare pi extensions.
+    if (!pkg.pi || !Array.isArray(pkg.pi.extensions) || pkg.pi.extensions.length === 0) continue;
+    scanned.push(pkgName);
+
+    const memHits = matchMarkers(pkgDir, MARKERS.memory);
+    const compHits = matchMarkers(pkgDir, MARKERS.compaction);
+    const toolHits = matchMarkers(pkgDir, MARKERS.toolOutput);
+
+    if (compHits.length > 0) {
+      conflicts.push({
+        package: pkgName,
+        severity: "high",
+        kind: "compaction",
+        evidence: compHits,
+        recommendation: "Disabling recommended — competes with pi-mega-compact's conversation compaction.",
+      });
+      continue; // compaction is the dominant conflict; don't double-flag.
+    }
+    if (memHits.length > 0) {
+      conflicts.push({
+        package: pkgName,
+        severity: "high",
+        kind: "memory",
+        evidence: memHits,
+        recommendation: "pi-mega-compact now owns save-to-memory (/mega-memory, its own SQLite). Disable this to avoid duplicate memory stores.",
+      });
+      continue;
+    }
+    if (toolHits.length > 0) {
+      conflicts.push({
+        package: pkgName,
+        severity: "info",
+        kind: "tool-output",
+        evidence: toolHits,
+        recommendation: "Shapes tool output (summarize/compact tool results). Generally compatible; no action needed.",
+      });
+    }
+  }
+
+  return { scanned, conflicts };
+}

package/extensions/dashboard-server.ts

@@ -16,7 +16,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, watch, writeFileSync }
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import Database from "better-sqlite3";
+import { DatabaseSync } from "node:sqlite";
 
 // --- Multi-repo index (Phase 5b) ------------------------------------------------
 // The extension writes a machine-wide repo registry into a single SQLite DB
@@ -54,11 +54,11 @@ interface IndexRepo {
 function readIndex(): { updatedAt: string; summary: unknown; repos: unknown[] } | null {
   const indexPath = join(getIndexDir(), "index.sqlite");
   if (!existsSync(indexPath)) return null;
-  let db: Database.Database | undefined;
+  let db: DatabaseSync | undefined;
   try {
     // Read-only + immutable WAL so a concurrent writer's WAL never blocks us.
-    db = new Database(indexPath, { readonly: true, fileMustExist: true });
-    db.pragma("journal_mode = WAL");
+    db = new DatabaseSync(indexPath, { readOnly: true });
+    db.exec("PRAGMA journal_mode = WAL");
     const rows = db
       .prepare("SELECT * FROM repo_registry ORDER BY last_seen DESC")
       .all() as Record<string, unknown>[];

package/extensions/mega-compact-driver.ts

@@ -0,0 +1,105 @@
+/**
+ * mega-compact-driver.ts — the durable-trim driver (Fix B).
+ *
+ * The read-path token-growth bug: the old design cancelled pi's native
+ * compaction (`{ cancel: true }`) and did its own ephemeral `context`-hook
+ * drop. That drop only affected the outgoing request — the on-disk transcript
+ * was never trimmed (the session manager is read-only for extensions). So on
+ * resume pi reloaded the FULL transcript and we ADDED a recall block on top →
+ * more tokens than before compaction.
+ *
+ * The fix: on `session_before_compact` we RUN the Trident pipeline to produce a
+ * genuinely compressed summary, then RETURN it as a `CompactionResult`. pi
+ * durably writes our summary into a `compactionSummary` entry AND truncates the
+ * transcript from `firstKeptEntryId`. After that, resume reloads the already-
+ * trimmed transcript (summary baked in) — no additive re-injection, no token
+ * growth.
+ *
+ * We reuse pi's `preparation.firstKeptEntryId` (pi already computed the cut
+ * honoring the anchor-floor + tool-pair guards — PREVENT-PI-002) rather than
+ * recomputing it, so we cannot hand pi a boundary that splits a tool pair.
+ */
+
+import type { SessionBeforeCompactEvent } from "@earendil-works/pi-coding-agent";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { compactSession } from "../src/engine.js";
+import { toEngineMessages } from "../src/adapt.js";
+import { estimateBlockTokens, estimateSessionTokens } from "../src/tokens.js";
+import type { MegaRuntime } from "./mega-runtime.js";
+import type { MegaConfig } from "./mega-config.js";
+import { recallRaptorRootSummary } from "../src/dedup/raptor/index.js";
+
+export interface NativeCompactionResult {
+  /** Our trimmed summary + the pi entry to keep from (durable trim). */
+  compaction: {
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    estimatedTokensAfter: number;
+  };
+}
+
+/**
+ * Build our durable compaction result from pi's pre-computed preparation.
+ *
+ * Returns undefined when there is nothing to summarize (pi will then run its
+ * own native compaction, or skip). Never throws for "empty" — best-effort.
+ */
+export function driveNativeCompaction(
+  event: SessionBeforeCompactEvent,
+  runtime: MegaRuntime,
+  config: MegaConfig,
+): NativeCompactionResult | undefined {
+  const prep = event.preparation;
+  if (!prep) return undefined;
+
+  const sid = runtime.rt.sessionId;
+  const messagesToSummarize: AgentMessage[] = prep.messagesToSummarize ?? [];
+  if (messagesToSummarize.length === 0) return undefined;
+
+  const engineView = toEngineMessages(messagesToSummarize);
+  // We don't drop anything here — pi keeps from prep.firstKeptEntryId. We only
+  // summarize the region pi is about to discard.
+  const keepFrom = engineView.length;
+
+  const result = compactSession(
+    {
+      sessionId: sid,
+      messages: engineView,
+      keepFrom,
+      timestamp: Date.now(),
+      useExtractiveSummary: true,
+    },
+    runtime.store,
+  );
+  if (result.skipped) return undefined;
+
+  // Prefer the RAPTOR root summary when the tree is built + enabled (Fix D):
+  // it is a session-level compressed summary, broader than one slice's. Fall
+  // back to the extractive topicSummary of this slice.
+  let summary = result.summary;
+  if (config.raptorEnabled) {
+    const root = recallRaptorRootSummary(sid, runtime.currentStateDir);
+    if (root) summary = root;
+  }
+
+  const tokensBefore = prep.tokensBefore ?? estimateSessionTokens(engineView);
+  const summaryTokens = estimateBlockTokens(summary);
+  // pi keeps the tail from firstKeptEntryId; our summary replaces the discarded
+  // region. Honest saved = discarded-region tokens − our summary tokens.
+  const savedTokens = Math.max(0, tokensBefore - summaryTokens);
+
+  runtime.rt.lastCompactedFrom = keepFrom;
+  runtime.rt.lastCompactedTokens = tokensBefore;
+  runtime.rt.tokensSaved += savedTokens;
+  runtime.rt.persistedThisSession = true;
+
+  return {
+    compaction: {
+      summary,
+      firstKeptEntryId: prep.firstKeptEntryId,
+      tokensBefore,
+      estimatedTokensAfter: summaryTokens,
+    },
+  };
+}

package/extensions/mega-compact.test.ts

@@ -45,6 +45,7 @@ function harness(opts: { keepTier?: boolean; keepThreshold?: boolean } = {}) {
   let statusKey: string | undefined;
   let statusText: string | undefined;
   const notifies: string[] = [];
+  const compactCalls: any[] = [];
 
   // Minimal AgentMessage factory for the session we project into the extension.
   function msg(role: string, text: string, toolName?: string): AgentMessage {
@@ -107,7 +108,30 @@ function harness(opts: { keepTier?: boolean; keepThreshold?: boolean } = {}) {
       hasPendingMessages: () => false,
       shutdown: () => {},
       getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }),
-      compact: () => {},
+      // Faithful mock: ctx.compact() starts pi's flow, which fires the
+      // session_before_compact handler (where WE supply the durable trim).
+      compact: (opts?: any) => {
+        compactCalls.push(opts);
+        if (handlers["session_before_compact"]) {
+          return handlers["session_before_compact"](
+            {
+              type: "session_before_compact",
+              reason: "threshold",
+              willRetry: false,
+              signal: undefined,
+              // pi computed the cut honoring anchor floor + tool-pair (PREVENT-PI-002);
+              // our handler reuses it as firstKeptEntryId.
+              preparation: {
+                firstKeptEntryId: "e2",
+                messagesToSummarize: session.slice(0, 2),
+                tokensBefore: 500,
+              },
+            } as any,
+            makeCtx(),
+          );
+        }
+        return undefined;
+      },
       getSystemPrompt: () => "system base",
       ...over,
     } as any;
@@ -143,14 +167,14 @@ function harness(opts: { keepTier?: boolean; keepThreshold?: boolean } = {}) {
   mod.default(pi);
 
   return {
-    stateDir, handlers, commands, appended, get status() { return { statusKey, statusText }; }, notifies,
+    stateDir, handlers, commands, appended, get status() { return { statusKey, statusText }; }, notifies, compactCalls,
     fire: (ev: string, event: any, ctx: any) => handlers[ev](event, ctx),
     ctx: makeCtx,
     session,
   };
 }
 
-test("auto-trigger: past threshold persists a chkpt and drops context", async () => {
+test("auto-trigger: past threshold persists a chkpt and starts a durable trim", async () => {
   const h = harness();
   const messages = h.session;
   const ctx = h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
@@ -159,27 +183,50 @@ test("auto-trigger: past threshold persists a chkpt and drops context", async ()
   const { listCheckpoints } = await import("../src/store/sqlite.js");
   assert.ok(listCheckpoints("sess_ext_001", h.stateDir).length > 0, "checkpoint persisted to local vector db");
   assert.equal(h.appended.some((a) => a.t === "mega-compact-marker"), true, "marker sentinel appended");
-  // Context dropped (the compacted range was trimmed).
-  assert.ok(res && Array.isArray(res.messages), "context handler returns filtered messages");
-  assert.ok((res.messages as any[]).length < messages.length, "outgoing context shrank");
+  // The context handler no longer drops messages itself (that was ephemeral —
+  // the read-path token-growth bug). It triggers pi's compaction flow, which
+  // calls our session_before_compact handler to supply the DURABLE trim.
+  assert.equal(res, undefined, "context handler returns nothing (no local drop)");
+  assert.equal(h.compactCalls.length, 1, "ctx.compact() called to start durable trim");
+  // The durable trim was supplied (summary + firstKeptEntryId from pi's prep).
+  assert.ok(h.compactCalls[0] !== undefined, "compaction flow executed");
 });
 
-test("session_before_compact cancels once we've persisted", async () => {
+test("session_before_compact supplies our durable trim (not pi's summary)", async () => {
   const h = harness();
-  const ctx = h.ctx();
-  // First fire the auto-trigger so a checkpoint is persisted this session.
-  await h.fire("context", { type: "context", messages: h.session }, h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) }));
-  // Now pi tries to compact natively — we must cancel (no double-compact).
-  const res = await h.fire("session_before_compact", { type: "session_before_compact", reason: "overflow", willRetry: true, preparation: {}, signal: undefined } as any, ctx);
-  assert.deepEqual(res, { cancel: true });
+  // pi fires session_before_compact with its own computed preparation.
+  const res = await h.fire(
+    "session_before_compact",
+    {
+      type: "session_before_compact",
+      reason: "overflow",
+      willRetry: true,
+      preparation: { firstKeptEntryId: "e2", messagesToSummarize: h.session.slice(0, 2), tokensBefore: 500 },
+      signal: undefined,
+    } as any,
+    h.ctx(),
+  );
+  assert.ok(res && res.compaction, "returns a compaction result");
+  assert.equal(res.compaction.firstKeptEntryId, "e2", "reuses pi's cut boundary (PREVENT-PI-002 safe)");
+  assert.ok(typeof res.compaction.summary === "string" && res.compaction.summary.length > 0, "our summary supplied");
+  assert.ok(res.compaction.tokensBefore >= 0, "tokensBefore reported");
 });
 
-test("session_before_compact does NOT cancel when nothing persisted", async () => {
+test("session_before_compact falls back to pi when nothing to summarize", async () => {
   const h = harness();
-  const ctx = h.ctx();
-  // Do NOT fire context first; this session has no checkpoint.
-  const res = await h.fire("session_before_compact", { type: "session_before_compact", reason: "threshold", willRetry: false, preparation: {}, signal: undefined } as any, ctx);
-  assert.deepEqual(res, {});
+  // Empty preparation → no messages to summarize → return {} so pi compacts natively.
+  const res = await h.fire(
+    "session_before_compact",
+    {
+      type: "session_before_compact",
+      reason: "threshold",
+      willRetry: false,
+      preparation: { firstKeptEntryId: "e0", messagesToSummarize: [], tokensBefore: 0 },
+      signal: undefined,
+    } as any,
+    h.ctx(),
+  );
+  assert.deepEqual(res, {}, "no compaction supplied → pi runs its own");
 });
 
 test("resume auto-inline stages recall into the system prompt", async () => {

package/extensions/mega-compact.ts

@@ -31,6 +31,7 @@ import { MegaRuntime } from "./mega-runtime.js";
 import { registerEventHandlers } from "./mega-events.js";
 import { registerCommands } from "./mega-commands.js";
 import { registerDashboardCommands } from "./mega-dashboard-cmds.js";
+import { registerConflictCommands } from "./mega-conflict-cmds.js";
 
 export default function (pi: ExtensionAPI) {
   const config = loadConfig();
@@ -38,4 +39,5 @@ export default function (pi: ExtensionAPI) {
   registerEventHandlers(pi, runtime, config);
   registerCommands(pi, runtime, config);
   registerDashboardCommands(pi, runtime);
+  registerConflictCommands(pi, runtime);
 }

package/extensions/mega-config.ts

@@ -34,10 +34,24 @@ export interface MegaConfig {
   fastGatePct: number;
   anchorUserMessages: number;
   preserveRecent: number;
+  /** High-pressure floor for preserveRecent — when context is near the limit
+   *  we compact deeper, but never below this (keeps recent turns for coherence). */
+  preserveRecentMin: number;
   auto: boolean;
   autoInline: boolean;
   autoInlineK: number;
   dedupSim: number;
+  /** RAPTOR hierarchical recall enabled (Fix D). Drives both live recall and
+   *  the durable-trim summary source (root summary). */
+  raptorEnabled: boolean;
+  /** Token ceiling for the re-injected recall block (Fix C). Recall stops
+   *  adding checkpoints once the block would exceed this — bounds read-path
+   *  token cost so it can never net-inflate the window. */
+  recallMaxTokens: number;
+  /** Inline-dedupe recalled checkpoints against the live window (Fix C): drop
+   *  a hit whose summary is ≥ dedupSim similar to a live message — "dedupe on
+   *  inline/read" so we never re-inject context already resident. */
+  windowDedupe: boolean;
   debug: boolean;
 }
 
@@ -65,6 +79,13 @@ function resolveThreshold(): { tier: CompactTier | "custom"; thresholdTokens: nu
   return { tier, thresholdTokens: COMPACT_TIERS[tier] };
 }
 
+/**
+ * Pressure helpers for adaptive compression (Fix E) live in src/config.ts
+ * (pi-agnostic) so unit tests can import them without the pi runtime. Re-export
+ * here so the extension has one import surface.
+ */
+export { pressureFromPct, preserveRecentForPressure } from "../src/config.js";
+
 /** Build the resolved config from env + defaults. */
 export function loadConfig(): MegaConfig {
   const { tier, thresholdTokens } = resolveThreshold();
@@ -77,10 +98,14 @@ export function loadConfig(): MegaConfig {
     thresholdTokens,
     anchorUserMessages: envFlag("MEGACOMPACT_ANCHOR_USER_MESSAGES", 3),
     preserveRecent: envFlag("MEGACOMPACT_PRESERVE_RECENT", 4),
+    preserveRecentMin: envFlag("MEGACOMPACT_PRESERVE_RECENT_MIN", 2),
     auto: envBool("MEGACOMPACT_AUTO", true),
     autoInline: envBool("MEGACOMPACT_AUTO_INLINE", true),
     autoInlineK: envFlag("MEGACOMPACT_AUTO_INLINE_K", 3),
     dedupSim: Number(process.env.MEGACOMPACT_DEDUP_SIM ?? "0.9"),
+    raptorEnabled: envBool("MEGACOMPACT_RAPTOR_ENABLED", true),
+    recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
+    windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
     debug: envBool("MEGACOMPACT_DEBUG", false),
   };
 }

package/extensions/mega-conflict-cmds.ts

@@ -0,0 +1,129 @@
+/**
+ * mega-conflict-cmds.ts — extension conflict validator + save-to-memory command.
+ *
+ * Detects other installed extensions that overlap with pi-mega-compact
+ * (conversation compaction, or save-to-memory) and WARNs — pi has no pre-load
+ * veto hook, so this is detect-and-warn only. Also registers /mega-memory, our
+ * own durable memory store in SQLite (the takeover of memory extensions).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { detectConflicts, type ConflictReport } from "./conflict-scan.js";
+import { addMemory, listMemories, searchMemories, recallMemory, type MemoryRecord } from "../src/store/sqlite.js";
+import { resolveRepoRoot } from "./mega-config.js";
+import { MegaRuntime } from "./mega-runtime.js";
+
+/** Run the conflict scan and format a human-readable report. */
+export function validateExtensions(): { report: ConflictReport; lines: string[] } {
+  const report = detectConflicts();
+  const lines: string[] = [];
+  if (report.conflicts.length === 0) {
+    lines.push(`[mega-compact] conflict check: ${report.scanned.length} extensions scanned, no overlaps.`);
+    return { report, lines };
+  }
+  const high = report.conflicts.filter((c) => c.severity === "high");
+  lines.push(`[mega-compact] conflict check: ${report.scanned.length} scanned, ${report.conflicts.length} overlap(s), ${high.length} high-severity.`);
+  for (const c of report.conflicts) {
+    const tag = c.severity === "high" ? "⚠ HIGH" : "ℹ info";
+    lines.push(`  ${tag} ${c.package} — ${c.kind} — ${c.recommendation}`);
+  }
+  return { report, lines };
+}
+
+/** Run the scan at activation and surface a one-line warning if needed. */
+export function runLoadTimeConflictCheck(): void {
+  try {
+    const { lines } = validateExtensions();
+    const high = lines.filter((l) => l.includes("⚠ HIGH"));
+    if (high.length > 0) {
+      // Non-fatal: just inform on stderr; the dashboard/commands carry details.
+      console.warn(lines.join("\n"));
+    }
+  } catch {
+    /* best-effort; never block session load */
+  }
+}
+
+function memoryLine(m: MemoryRecord): string {
+  const tags = m.tags.length ? ` [${m.tags.join(", ")}]` : "";
+  const snap = m.content.length > 80 ? m.content.slice(0, 77) + "…" : m.content;
+  return `#${m.id} (${m.kind})${tags}: ${snap}`;
+}
+
+/** Register conflict-check + memory commands. */
+export function registerConflictCommands(pi: ExtensionAPI, runtime: MegaRuntime): void {
+  runLoadTimeConflictCheck();
+
+  pi.registerCommand("mega-compat-check", {
+    description: "Scan installed extensions for overlaps with pi-mega-compact (compaction / save-to-memory) and warn.",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      const { lines } = validateExtensions();
+      for (const l of lines) ctx.ui.notify(l);
+      if (lines.length === 1) {
+        ctx.ui.notify("[mega-compact] You own compaction + memory; no conflicting extensions detected.");
+      }
+    },
+  });
+
+  pi.registerCommand("mega-memory", {
+    description: "Save and recall durable memory in pi-mega-compact's SQLite store. Usage: /mega-memory save <text> | list | search <q> | recall <id>",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const repo = resolveRepoRoot(ctx.cwd) ?? runtime.currentStateDir;
+      const parts = args.trim().split(/\s+/);
+      const sub = parts[0]?.toLowerCase() ?? "list";
+
+      if (sub === "save") {
+        const text = args.trim().slice(4).trim();
+        if (!text) {
+          ctx.ui.notify("[mega-memory] usage: /mega-memory save <text>");
+          return;
+        }
+        // Optional "#tag #tag" parsing from the tail.
+        const tagMatches = [...text.matchAll(/#([\w-]+)/g)].map((m) => m[1]);
+        const content = text.replace(/#[\w-]+/g, "").trim();
+        const id = addMemory({ content, tags: tagMatches }, repo, runtime.currentStateDir);
+        ctx.ui.notify(`[mega-memory] saved #${id} to ${repo.split(/[\\/]/).pop()}`);
+        return;
+      }
+
+      if (sub === "search") {
+        const q = parts.slice(1).join(" ").trim();
+        if (!q) {
+          ctx.ui.notify("[mega-memory] usage: /mega-memory search <query>");
+          return;
+        }
+        const hits = searchMemories(q, repo, 50, runtime.currentStateDir);
+        if (!hits.length) {
+          ctx.ui.notify("[mega-memory] no memories match.");
+          return;
+        }
+        for (const m of hits) ctx.ui.notify(memoryLine(m));
+        return;
+      }
+
+      if (sub === "recall") {
+        const id = Number(parts[1]);
+        if (!Number.isFinite(id) || parts[1] === undefined) {
+          ctx.ui.notify("[mega-memory] usage: /mega-memory recall <id>");
+          return;
+        }
+        if (recallMemory(id, runtime.currentStateDir)) {
+          const found = listMemories(repo, 1000, runtime.currentStateDir).find((m) => m.id === id);
+          ctx.ui.notify(found ? `[mega-memory] ${memoryLine(found)}` : `[mega-memory] recalled #${id}`);
+        } else {
+          ctx.ui.notify(`[mega-memory] #${id} not found.`);
+        }
+        return;
+      }
+
+      // default: list
+      const all = listMemories(repo, 50, runtime.currentStateDir);
+      if (!all.length) {
+        ctx.ui.notify("[mega-memory] no saved memories yet. Use /mega-memory save <text>.");
+        return;
+      }
+      ctx.ui.notify(`[mega-memory] ${all.length} saved to ${repo.split(/[\\/]/).pop()}:`);
+      for (const m of all) ctx.ui.notify(memoryLine(m));
+    },
+  });
+}