chainlesschain 0.166.9 → 0.166.13

package/src/commands/compact.js

@@ -27,10 +27,20 @@ import {
   readVerifiedProjection,
   sessionExists,
 } from "../harness/jsonl-session-store.js";
-import { PromptCompressor } from "../harness/prompt-compressor.js";
+import {
+  estimateMessagesTokens,
+  getContextWindow,
+  PromptCompressor,
+} from "../harness/prompt-compressor.js";
 import { compactConversationWithProvider } from "../harness/provider-backed-compaction.js";
 import { runMeteredDirectModelCall } from "../lib/direct-model-usage.js";
 import { chatWithTools } from "../runtime/agent-core.js";
+import { canonicalDigest } from "@chainlesschain/context-memory-kernel";
+import {
+  contextItemsToMessages,
+  createCliContextMemoryRuntime,
+  createSummaryContextItem,
+} from "../lib/context-memory-kernel/index.js";
 
 /** Build a compressor sized to the session (or explicit overrides). */
 function buildCompressor(options, recorded, llmQuery) {
@@ -75,7 +85,7 @@ function attachMeteringMetadata(value, { callId, settled }) {
   }
 }
 
-function buildSemanticQuery(options, recorded, sessionId, ledger) {
+function buildSemanticQuery(options, recorded, sessionId, operationId, ledger) {
   const provider = options.provider || recorded.provider || undefined;
   const model = options.model || recorded.model || undefined;
   // A preview must be both write-free and spend-free. It uses the same
@@ -92,6 +102,7 @@ function buildSemanticQuery(options, recorded, sessionId, ledger) {
         provider,
         model,
         source: "semantic-compaction",
+        operationId,
         persist: async (type, data) => {
           const appended = appendEventIfHead(
             sessionId,
@@ -138,6 +149,201 @@ function buildSemanticQuery(options, recorded, sessionId, ledger) {
   };
 }
 
+function kernelBudget(options, recorded, compressor) {
+  const model = options.model || recorded.model || undefined;
+  const provider = options.provider || recorded.provider || undefined;
+  const modelWindowTokens = getContextWindow(model, provider);
+  const reservedOutputTokens = Math.max(
+    1,
+    Math.min(2048, Math.floor(modelWindowTokens / 10)),
+  );
+  const maximumInput = Math.max(1, modelWindowTokens - reservedOutputTokens);
+  const targetInput = Math.max(
+    1,
+    Math.min(
+      maximumInput,
+      Math.trunc(Number(compressor.maxTokens)) || maximumInput,
+    ),
+  );
+  const safetyMarginTokens = Math.max(
+    0,
+    modelWindowTokens - reservedOutputTokens - targetInput,
+  );
+  const recoveryReserveTokens =
+    targetInput <= 1
+      ? 0
+      : Math.min(256, Math.max(1, Math.floor(targetInput * 0.05)));
+  return {
+    modelWindowTokens,
+    reservedOutputTokens,
+    safetyMarginTokens,
+    recoveryReserveTokens,
+  };
+}
+
+function buildKernelSummarizer({
+  llmQuery,
+  provider,
+  model,
+  compressor,
+  ledger,
+  sessionPort,
+}) {
+  if (typeof llmQuery !== "function") return undefined;
+  return async (droppedItems, context) => {
+    if (ledger.headHash !== context.inputHead) {
+      const error = new Error("session changed before semantic compaction");
+      error.code = "SESSION_REVISION_STALE";
+      throw error;
+    }
+    const droppedMessages = contextItemsToMessages(droppedItems);
+    if (droppedMessages.length < 3) {
+      return { items: [], usageReceipt: { outcome: "not_metered" } };
+    }
+    const summaryCompressor = new PromptCompressor({
+      maxMessages: 4,
+      maxTokens: Math.max(256, Math.floor(compressor.maxTokens / 4)),
+      llmQuery,
+    });
+    let compacted;
+    try {
+      compacted = await compactConversationWithProvider(droppedMessages, {
+        compressor: summaryCompressor,
+        provider,
+        model,
+      });
+    } finally {
+      if (ledger.headHash !== context.inputHead) {
+        sessionPort.registerOwnedHeadAdvance({
+          operationId: context.operationId,
+          fromHead: context.inputHead,
+          toHead: ledger.headHash,
+        });
+      }
+    }
+    const { messages, stats } = compacted;
+    if (stats.summaryUsageUnknown === true) {
+      const error = new Error(
+        stats.summaryUsageUnknownReason || "provider usage outcome is unknown",
+      );
+      error.code = "reconciliation_required";
+      error.outcomeUnknown = true;
+      throw error;
+    }
+    const providerWasCalled = Boolean(stats.summaryCallId);
+    if (providerWasCalled && stats.summaryUsageLedgerSettled !== true) {
+      const error = new Error("semantic compaction usage ledger is unsettled");
+      error.code = "provider_usage_unsettled";
+      error.outcomeUnknown = true;
+      throw error;
+    }
+    const reduced =
+      Number(stats.saved || 0) > 0 || messages.length < droppedMessages.length;
+    const item = reduced
+      ? createSummaryContextItem({
+          messages,
+          parents: droppedItems,
+          operationId: context.operationId,
+          now: new Date().toISOString(),
+        })
+      : null;
+    const usageReceipt = providerWasCalled
+      ? {
+          outcome: "settled",
+          callId: stats.summaryCallId,
+          ...(stats.summaryProvider || provider
+            ? { provider: stats.summaryProvider || provider }
+            : {}),
+          ...(stats.summaryModel || model
+            ? { model: stats.summaryModel || model }
+            : {}),
+          inputTokens: stats.summaryUsage?.inputTokens || 0,
+          outputTokens: stats.summaryUsage?.outputTokens || 0,
+          ledgerDigest: canonicalDigest(
+            { callId: stats.summaryCallId, headHash: ledger.headHash },
+            "chainlesschain.cli-compaction-usage/v1",
+          ),
+        }
+      : { outcome: "not_metered" };
+    return { items: item ? [item] : [], usageReceipt };
+  };
+}
+
+function compactionRequest({
+  sessionId,
+  operationId,
+  options,
+  source,
+  compressor,
+  memoryRevision,
+  summarizer,
+}) {
+  const provider =
+    options.provider || source.recorded.provider || "provider.local";
+  const model = options.model || source.recorded.model || "default";
+  return {
+    operationId,
+    sessionId,
+    ...kernelBudget(options, source.recorded, compressor),
+    sink: provider,
+    scopeAdmissions: [{ scope: "session", scopeId: sessionId }],
+    policyVersion: "cli-context-policy-v1",
+    modelProfile: model,
+    memoryRevision,
+    allowFallback: false,
+    ...(summarizer ? { summarizer } : {}),
+    metadata: {
+      inputMessageCount: source.messages.length,
+      originalTokens: estimateMessagesTokens(source.messages),
+      provider,
+      model,
+    },
+  };
+}
+
+async function dryRunKernelPlan(runtime, request) {
+  const snapshot = await runtime.sessionPort.readSnapshot(request.sessionId);
+  const plan = await runtime.kernel.planContext({
+    modelWindowTokens: request.modelWindowTokens,
+    reservedOutputTokens: request.reservedOutputTokens,
+    safetyMarginTokens: request.safetyMarginTokens,
+    recoveryReserveTokens: request.recoveryReserveTokens,
+    items: snapshot.items,
+    sink: request.sink,
+    scopeAdmissions: request.scopeAdmissions,
+    ...(request.partitionCeilings
+      ? { partitionCeilings: request.partitionCeilings }
+      : {}),
+    ...(request.partitionMinimums
+      ? { partitionMinimums: request.partitionMinimums }
+      : {}),
+    policyVersion: request.policyVersion,
+    modelProfile: request.modelProfile,
+    sessionHead: snapshot.head,
+    memoryRevision: request.memoryRevision ?? snapshot.memoryRevision,
+    ...(request.now ? { now: request.now } : {}),
+  });
+  return {
+    plan,
+    messages: contextItemsToMessages(plan.selected),
+    stats: {
+      strategy: "canonical-deterministic-selection",
+      originalMessages: snapshot.items.length,
+      compressedMessages: plan.selected.length,
+      originalTokens: snapshot.items.reduce(
+        (total, item) => total + item.tokenEstimate,
+        0,
+      ),
+      compressedTokens: plan.selectedTokens,
+      saved:
+        snapshot.items.reduce((total, item) => total + item.tokenEstimate, 0) -
+        plan.selectedTokens,
+      dropped: plan.dropped,
+      digest: plan.digest,
+    },
+  };
+}
+
 function readCompactSource(sessionId) {
   return readVerifiedProjection(sessionId, () => {
     let recorded = Object.freeze({ model: "", provider: "" });
@@ -192,6 +398,10 @@ export function registerCompactCommand(program) {
       "Disable provider summarization and stay deterministic",
     )
     .option("--base-url <url>", "Provider base URL for semantic compaction")
+    .option(
+      "--operation-id <id>",
+      "Stable idempotency key (default: derived from session head)",
+    )
     .option("--json", "Output as JSON")
     .action(async (sessionId, options) => {
       try {
@@ -204,6 +414,10 @@ export function registerCompactCommand(program) {
 
         const source = readCompactSource(sessionId);
         const messages = source.messages;
+        const operationId =
+          options.operationId ||
+          `compact-${sessionId}-${String(source.headHash).slice(-24)}`;
+        const runtime = createCliContextMemoryRuntime({ sessionId });
         const ledger = {
           headHash: source.headHash,
           callId: null,
@@ -214,9 +428,133 @@ export function registerCompactCommand(program) {
           options,
           source.recorded,
           sessionId,
+          operationId,
           ledger,
         );
         const compressor = buildCompressor(options, source.recorded, llmQuery);
+        const memoryRevision =
+          runtime.decision.canonical && !options.dryRun
+            ? await runtime.memoryPort.getRevision()
+            : 0;
+        const summarizer = buildKernelSummarizer({
+          llmQuery,
+          provider: options.provider || source.recorded.provider || undefined,
+          model: options.model || source.recorded.model || undefined,
+          compressor,
+          ledger,
+          sessionPort: runtime.sessionPort,
+        });
+        const request = compactionRequest({
+          sessionId,
+          operationId,
+          options,
+          source,
+          compressor,
+          memoryRevision,
+          summarizer,
+        });
+        const canonicalPreview = await dryRunKernelPlan(runtime, request);
+
+        if (runtime.decision.canonical) {
+          const reduced = canonicalPreview.plan.dropped.length > 0;
+          if (!reduced || options.dryRun) {
+            if (options.json) {
+              console.log(
+                JSON.stringify(
+                  {
+                    sessionId,
+                    operationId,
+                    compacted: false,
+                    dryRun: Boolean(options.dryRun),
+                    cutover: runtime.decision,
+                    stats: canonicalPreview.stats,
+                  },
+                  null,
+                  2,
+                ),
+              );
+              return;
+            }
+            logger.log(
+              chalk.gray(
+                reduced
+                  ? `Would compact ${canonicalPreview.plan.dropped.length} canonical item(s).`
+                  : `Nothing to compact - ${messages.length} message(s) are within the canonical budget.`,
+              ),
+            );
+            return;
+          }
+
+          const receipt = await runtime.kernel.compactContext(request);
+          if (["stale", "reconciliation_required"].includes(receipt.status)) {
+            if (options.json) {
+              console.log(
+                JSON.stringify(
+                  {
+                    sessionId,
+                    operationId,
+                    cutover: runtime.decision,
+                    receipt,
+                  },
+                  null,
+                  2,
+                ),
+              );
+            } else {
+              logger.error(
+                chalk.yellow(
+                  `Compaction requires ${receipt.status === "stale" ? "a retry" : "reconciliation"}: ${operationId}`,
+                ),
+              );
+            }
+            process.exitCode = receipt.status === "stale" ? 1 : 2;
+            return;
+          }
+          const committed = await runtime.sessionPort.readSnapshot(sessionId);
+          const compressedTokens = committed.items.reduce(
+            (total, item) => total + item.tokenEstimate,
+            0,
+          );
+          const stats = {
+            strategy: "canonical-context-memory-kernel",
+            originalMessages: messages.length,
+            compressedMessages: committed.items.length,
+            originalTokens: canonicalPreview.stats.originalTokens,
+            compressedTokens,
+            saved: canonicalPreview.stats.originalTokens - compressedTokens,
+            dropped: canonicalPreview.plan.dropped,
+          };
+          if (options.json) {
+            console.log(
+              JSON.stringify(
+                {
+                  sessionId,
+                  operationId,
+                  compacted: true,
+                  cutover: runtime.decision,
+                  stats,
+                  receipt,
+                },
+                null,
+                2,
+              ),
+            );
+            return;
+          }
+          logger.log(chalk.green(`Compacted ${sessionId}`));
+          logger.log(
+            chalk.gray(
+              `  ${stats.originalMessages} -> ${stats.compressedMessages} messages` +
+                `, ${stats.originalTokens} -> ${stats.compressedTokens} tokens` +
+                ` (saved ${stats.saved}, canonical kernel)`,
+            ),
+          );
+          logger.log(
+            chalk.gray(`  resume with: cc agent --resume ${sessionId}`),
+          );
+          return;
+        }
+
         // llmQuery already persisted a complete call ledger. The provider
         // helper only carries its metadata through stats; its projected usage
         // event is intentionally not appended a second time here.
@@ -260,7 +598,15 @@ export function registerCompactCommand(program) {
         if (options.json) {
           console.log(
             JSON.stringify(
-              { sessionId, dryRun: !!options.dryRun, stats },
+              {
+                sessionId,
+                dryRun: !!options.dryRun,
+                cutover: runtime.decision,
+                stats,
+                ...(runtime.decision.shadow
+                  ? { canonicalShadow: canonicalPreview.stats }
+                  : {}),
+              },
               null,
               2,
             ),

package/src/commands/context.js

@@ -74,7 +74,7 @@ export function registerContextCommand(program) {
     .action(async (id, options) => {
       const { rebuildMessages, getLastSessionId, sessionExists, readEvents } =
         await import("../harness/jsonl-session-store.js");
-      const { estimateTokens, getContextWindow } =
+      const { adaptiveThresholds, estimateTokens, getContextWindow } =
         await import("../harness/prompt-compressor.js");
 
       const sessionId = id || getLastSessionId();
@@ -118,6 +118,61 @@ export function registerContextCommand(program) {
       const provider = options.provider || recordedProvider || "ollama";
       const window = getContextWindow(model, provider);
 
+      let canonicalReport = null;
+      try {
+        const { createCliContextMemoryRuntime } =
+          await import("../lib/context-memory-kernel/index.js");
+        const runtime = createCliContextMemoryRuntime({ sessionId });
+        const snapshot = await runtime.sessionPort.readSnapshot(sessionId);
+        const threshold = adaptiveThresholds(window).maxTokens;
+        const reservedOutputTokens = Math.max(
+          1,
+          Math.min(2048, Math.floor(window / 10)),
+        );
+        const safetyMarginTokens = Math.max(
+          0,
+          window - reservedOutputTokens - threshold,
+        );
+        const recoveryReserveTokens = Math.min(
+          256,
+          Math.max(1, Math.floor(threshold * 0.05)),
+        );
+        const plan = await runtime.kernel.planContext({
+          modelWindowTokens: window,
+          reservedOutputTokens,
+          safetyMarginTokens,
+          recoveryReserveTokens,
+          items: snapshot.items,
+          sink: provider,
+          scopeAdmissions: [{ scope: "session", scopeId: sessionId }],
+          policyVersion: "cli-context-policy-v1",
+          modelProfile: model || "default",
+          sessionHead: snapshot.head,
+          memoryRevision: snapshot.memoryRevision,
+        });
+        canonicalReport = {
+          stage: runtime.decision.stage,
+          mode: runtime.decision.mode,
+          shadow: runtime.decision.shadow,
+          planDigest: plan.digest,
+          policyVersion: plan.policyVersion,
+          selectedItems: plan.selected.length,
+          droppedItems: plan.dropped.length,
+          selectedTokens: plan.selectedTokens,
+          inputBudget: plan.inputBudget,
+          selectableBudget: plan.selectableBudget,
+          partitions: plan.partitions,
+          minimumShortfalls: plan.minimumShortfalls,
+          dropped: plan.dropped,
+        };
+      } catch (error) {
+        canonicalReport = {
+          status: "rejected",
+          code: error?.code || "context_plan_failed",
+          message: error?.message || String(error),
+        };
+      }
+
       const { buckets, counts, total } = categorizeContext(
         messages,
         estimateTokens,
@@ -227,6 +282,7 @@ export function registerContextCommand(program) {
               breakdown: buckets,
               counts,
               overflows: total > window,
+              contextMemoryKernel: canonicalReport,
               ...(sourceReport
                 ? {
                     sources: sourceReport.ranked,
@@ -291,6 +347,21 @@ export function registerContextCommand(program) {
           `  headroom      ${String(remaining).padStart(7)} tokens remaining`,
         ),
       );
+      if (canonicalReport?.status === "rejected") {
+        logger.log(
+          chalk.red(
+            `  canonical plan rejected: ${canonicalReport.code} - ${canonicalReport.message}`,
+          ),
+        );
+      } else if (canonicalReport) {
+        logger.log(
+          chalk.gray(
+            `  kernel ${canonicalReport.stage}/${canonicalReport.mode}: ` +
+              `${canonicalReport.selectedItems} selected, ${canonicalReport.droppedItems} dropped, ` +
+              `${canonicalReport.selectedTokens}/${canonicalReport.inputBudget} tokens`,
+          ),
+        );
+      }
       if (total > window) {
         logger.log(
           chalk.red(

package/src/commands/graph.js

@@ -1,9 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import {
-  defaultRolloutStoreDirectory,
-  JsonlRolloutStore,
-} from "../lib/app-server/rollout-store.js";
+import { defaultRolloutStoreDirectory } from "../lib/app-server/rollout-store.js";
+import { createRolloutStore } from "../lib/app-server/rollout-store-factory.js";
 import { GraphCutoverAuthorityResolver } from "../lib/graph-kernel/cutover-authority-resolver.js";
 import { GraphCutoverLedger } from "../lib/graph-kernel/cutover-ledger.js";
 import {
@@ -22,16 +20,18 @@ import {
   evaluateGraphProjection,
 } from "../lib/graph-kernel/eval.js";
 
-function graphEventStore(directory) {
+function graphEventStore(directory, backend) {
   return new GraphEventStore({
-    rolloutStore: new JsonlRolloutStore({
+    rolloutStore: createRolloutStore({
+      backend,
       directory: path.resolve(directory || defaultGraphEventStoreDirectory()),
     }),
   });
 }
 
-function cutoverStore(directory) {
-  return new JsonlRolloutStore({
+function cutoverStore(directory, backend) {
+  return createRolloutStore({
+    backend,
     directory: path.resolve(directory || defaultRolloutStoreDirectory()),
   });
 }
@@ -99,11 +99,14 @@ export function registerGraphCommand(program) {
       "Project a durable GraphRun into Agent/Task/Artifact/Trace views",
     )
     .option("--state-dir <path>", "Graph rollout directory")
+    .option("--store <backend>", "Physical rollout adapter: jsonl or sqlite")
     .option("--at-seq <n>", "Time-travel through a durable event sequence")
     .option("--blocked-root <nodeId>", "Locate a deterministic blocked root")
     .option("--include-content", "Include message and HumanTask content")
     .action((runId, options) => {
-      const events = graphEventStore(options.stateDir).read(runId);
+      const events = graphEventStore(options.stateDir, options.store).read(
+        runId,
+      );
       const projection = options.atSeq
         ? timeTravelGraphTrace(events, Number(options.atSeq), {
             includeContent: options.includeContent === true,
@@ -127,8 +130,11 @@ export function registerGraphCommand(program) {
     .requiredOption("--from-seq <n>", "First durable event sequence")
     .requiredOption("--to-seq <n>", "Second durable event sequence")
     .option("--state-dir <path>", "Graph rollout directory")
+    .option("--store <backend>", "Physical rollout adapter: jsonl or sqlite")
     .action((runId, options) => {
-      const events = graphEventStore(options.stateDir).read(runId);
+      const events = graphEventStore(options.stateDir, options.store).read(
+        runId,
+      );
       print(
         diffGraphTrace(
           timeTravelGraphTrace(events, Number(options.fromSeq)),
@@ -143,13 +149,14 @@ export function registerGraphCommand(program) {
       "Evaluate a durable GraphRun and optionally enforce thresholds",
     )
     .option("--state-dir <path>", "Graph rollout directory")
+    .option("--store <backend>", "Physical rollout adapter: jsonl or sqlite")
     .option(
       "--thresholds <json>",
       'Metric threshold object, e.g. \'{"deadlocked":{"max":0}}\'',
     )
     .action((runId, options) => {
       const projection = reduceGraphTrace(
-        graphEventStore(options.stateDir).read(runId),
+        graphEventStore(options.stateDir, options.store).read(runId),
       );
       const report = evaluateGraphProjection(projection);
       const gate = options.thresholds
@@ -167,6 +174,7 @@ export function registerGraphCommand(program) {
     .command("init")
     .description("Bind declared runtime entries to the durable cutover ledger")
     .option("--state-dir <path>", "Cutover ledger directory")
+    .option("--store <backend>", "Physical rollout adapter: jsonl or sqlite")
     .option("--surface <name>", "Initialize one origin surface")
     .option("--entry <id>", "Initialize one entry id")
     .option(
@@ -176,7 +184,7 @@ export function registerGraphCommand(program) {
     .action((options) => {
       const manifest = loadGraphRuntimeSurfaceManifest();
       const ledger = new GraphCutoverLedger({
-        store: cutoverStore(options.stateDir),
+        store: cutoverStore(options.stateDir, options.store),
       });
       const selected = selectedCutoverEntries(manifest, options).filter(
         ({ surface }) =>
@@ -205,12 +213,13 @@ export function registerGraphCommand(program) {
     .command("status")
     .description("List manifest bindings and durable cutover stages")
     .option("--state-dir <path>", "Cutover ledger directory")
+    .option("--store <backend>", "Physical rollout adapter: jsonl or sqlite")
     .option("--surface <name>", "Inspect one origin surface")
     .option("--entry <id>", "Inspect one entry id")
     .action((options) => {
       const manifest = loadGraphRuntimeSurfaceManifest();
       const ledger = new GraphCutoverLedger({
-        store: cutoverStore(options.stateDir),
+        store: cutoverStore(options.stateDir, options.store),
       });
       const entries = selectedCutoverEntries(manifest, options).map(
         ({ surface, entry }) => {
@@ -251,6 +260,7 @@ export function registerGraphCommand(program) {
     .command("authority <surface> <entryId>")
     .description("Resolve one new run through the durable entry ledger")
     .option("--state-dir <path>", "Cutover ledger directory")
+    .option("--store <backend>", "Physical rollout adapter: jsonl or sqlite")
     .option("--run-key <key>", "Stable logical run identity")
     .option("--opt-in", "Explicitly enroll an opt-in-only canary run")
     .option("--fallback <mode>", "Pre-ledger feature-flag fallback")
@@ -259,7 +269,7 @@ export function registerGraphCommand(program) {
       const resolver = cutoverResolver({
         manifest,
         ledger: new GraphCutoverLedger({
-          store: cutoverStore(options.stateDir),
+          store: cutoverStore(options.stateDir, options.store),
         }),
         surface,
         entryId,
@@ -278,11 +288,12 @@ export function registerGraphCommand(program) {
     .description("Advance or roll back one entry using durable JSON evidence")
     .requiredOption("--evidence <path>", "Evidence JSON file")
     .option("--state-dir <path>", "Cutover ledger directory")
+    .option("--store <backend>", "Physical rollout adapter: jsonl or sqlite")
     .option("--expected-head <digest>", "Expected ledger event head CAS")
     .action((surface, entryId, stage, options) => {
       const manifest = loadGraphRuntimeSurfaceManifest();
       const ledger = new GraphCutoverLedger({
-        store: cutoverStore(options.stateDir),
+        store: cutoverStore(options.stateDir, options.store),
       });
       const resolver = cutoverResolver({
         manifest,

package/src/commands/hmemory.js

@@ -8,6 +8,10 @@ import { numericOption } from "../lib/cli-numeric.js";
 import ora from "ora";
 import { logger } from "../lib/logger.js";
 import { bootstrap, shutdown } from "../runtime/bootstrap.js";
+import {
+  assertLegacyMutationAllowed,
+  resolveCliContextMemoryCutover,
+} from "../lib/context-memory-kernel/authority.js";
 import {
   storeMemory,
   recallMemory,
@@ -41,6 +45,23 @@ export function registerHmemoryCommand(program) {
     .command("hmemory")
     .description("Hierarchical Memory 2.0 — four-layer memory system");
 
+  // This namespace is the pre-Kernel store. Even recall mutates access counts
+  // and forgetting state, so the entire surface is fenced once canonical owns
+  // the scope. Historical data remains available through the canonical
+  // one-time importer and `cc memory recall`.
+  hmemory.hook("preAction", (_thisCommand, actionCommand) => {
+    const decision = resolveCliContextMemoryCutover({
+      scopeKey: `cli:hmemory:${actionCommand.name()}`,
+    });
+    try {
+      assertLegacyMutationAllowed(decision);
+    } catch (error) {
+      error.message += "; use `cc memory store|recall|consolidate`";
+      error.replacement = "cc memory";
+      throw error;
+    }
+  });
+
   // hmemory store <content>
   hmemory
     .command("store")