mulmoclaude 2.4.0 → 2.4.1

package/server/index.ts

@@ -84,7 +84,6 @@ import { announceShadowedEnv, SHADOWED_ENV_KEYS_VAR } from "./system/shadowedEnv
 import { announceOptionalDeps } from "./system/announceOptionalDeps.js";
 import { announceGeminiKey } from "./system/announceGeminiKey.js";
 import { currentLaunchRouteFacts } from "./system/geminiKeyGuidance.js";
-import { migrateLegacyBillingPresets } from "./workspace/billing-migration.js";
 import { APP_VERSION } from "./system/appVersion.js";
 import { createChatService } from "@mulmobridge/chat-service";
 import { readSessionJsonl, readSessionMeta } from "./utils/files/session-io.js";
@@ -109,8 +108,7 @@ import { preflightUserServers, logPreflightResult } from "./agent/mcpPreflight.j
 import { loadMcpConfig, loadSettings } from "./system/config.js";
 import { getVoiceInputStatus, stopWhisperSidecar, warmupVoiceInput } from "./system/whisper/index.js";
 import { initWorkspace, workspacePath } from "./workspace/workspace.js";
-import { runMemoryMigrationOnce } from "./workspace/memory/run.js";
-import { runTopicMigrationOnce } from "./workspace/memory/topic-run.js";
+import { startMemoryMigrations } from "./workspace/memory/startup.js";
 import { migrateCookingRecipesFromPlugin } from "./workspace/cooking-recipes/migrate.js";
 import { env, isAblated, isGeminiAvailable } from "./system/env.js";
 import { buildSandboxStatus } from "./api/sandboxStatus.js";
@@ -242,27 +240,21 @@ warnIfCspExtended();
 //
 // Both runners are idempotent: legacy no-ops when the source file
 // is gone, topic no-ops when the workspace already uses the topic
-// format or staging is already pending review. The agent can serve
-// traffic while the chain runs.
-//
-// `.then(noop, noop)` keeps the floating-promises rule happy
-// without smuggling in a `void` (banned by sonarjs/void-use). Each
-// runner logs its own failures; the chain's outer rejection
-// handler is therefore a hard backstop only.
+// format, and retries the swap when staging is left from a crash. The agent can serve
+// traffic while the chain runs, but the journal waits for it
+// (`memoryMigrationsSettled`) so its extractor can't append to a
+// `memory.md` that is mid-migration.
 //
 // CLEANUP 2026-07-01: this whole chain is one-shot migration code
 // for #1029 + #1070. After every active workspace has flipped to
 // the topic format, delete the chain plus the runners under
-// `server/workspace/memory/` (run.ts / migrate.ts /
+// `server/workspace/memory/` (startup.ts + the journal's wait on it / run.ts / migrate.ts /
 // llm-classifier.ts / topic-run.ts / topic-migrate.ts /
 // topic-cluster.ts / topic-swap.ts) and the
 // `scripts/memory-swap-topic-staging.ts` helper. Topic-format
 // reading / writing (`topic-types.ts`, `topic-io.ts`,
 // `topic-detect.ts`) plus the topic branch in `prompt.ts` stays.
-const noop = (): void => {};
-runMemoryMigrationOnce(workspacePath)
-  .then(() => runTopicMigrationOnce(workspacePath))
-  .then(noop, noop);
+startMemoryMigrations(workspacePath);
 
 // Recipe-book plugin → `mc-cooking-coach` skill migration (#1286).
 // Boot-time idempotent copy from the plugin's `files.data` scope
@@ -1081,13 +1073,6 @@ async function initBootDiagnostics(): Promise<void> {
   // inside the request. No-op when voice input is off / not ready.
   warmupVoiceInput(bootSettings);
 
-  // --- Billing-suite migration ---
-  // The invoicing collections moved from bundled `mc-*` presets to
-  // help-file recipes. Remove any lingering starred `mc-*` billing
-  // skill from `.claude/skills/` (records preserved) and fire a
-  // one-time bell. No-op once the dirs are gone. Never throws.
-  migrateLegacyBillingPresets();
-
   // --- Collection completion watchers ---
   // Mount `fs.watch` over every discovered collection's dataDir so
   // schemas with `completionField` fire / clear bell notifications

package/server/prompts/system/system.md

@@ -19,9 +19,8 @@ All data lives in the workspace directory as plain files:
 - `conversations/chat/` — chat session history (one .jsonl per session)
 - `conversations/memory/` — distilled user facts as topic files (`<type>/<topic>.md`); see the Memory section below for the index and read rules.
 - `conversations/summaries/` — journal output (daily / topics / archive)
-- `data/contacts/` — address book entries
 - `data/wiki/` — personal knowledge wiki (index.md, pages/, sources/, log.md)
-- `data/scheduler/` — scheduled tasks
+- `config/scheduler/tasks.json` — scheduled tasks (Automations)
 - `artifacts/documents/`, `artifacts/images/`, `artifacts/html/`, `artifacts/charts/`, `artifacts/spreadsheets/`, `artifacts/stories/` — LLM-generated output
 - `config/` — settings.json, mcp.json, roles/, helps/
 - `github/` — git-cloned repositories. Clone here, not /tmp/. If the dir already exists with the same remote, `git pull` to update. If a different remote, ask the user for a new dir name.

package/server/workspace/journal/index.ts

@@ -18,6 +18,7 @@ import { buildIndexMarkdown, type IndexTopicEntry, type IndexDailyEntry } from "
 import { runClaudeCli, ClaudeCliNotFoundError, type Summarize, type JournalSummaryModel } from "./archivist-cli.js";
 import { extractFirstH1 } from "@mulmoclaude/markdown-utils/markdown/extractFirstH1";
 import { log } from "../../system/logger/index.js";
+import { memoryMigrationsSettled } from "../memory/startup.js";
 import { journalMode as resolveJournalMode, loadSettings, type JournalMode } from "../../system/config.js";
 
 export { extractFirstH1 };
@@ -57,6 +58,8 @@ export async function maybeRunJournal(opts: MaybeRunJournalOptions = {}): Promis
   if (mode === "off") return;
   running = true;
   try {
+    // Waiting under the lock makes triggers that arrive meanwhile return instead of queueing a second pass.
+    await memoryMigrationsSettled();
     await runJournalPass(opts, mode);
   } catch (err) {
     if (err instanceof ClaudeCliNotFoundError) {

package/server/workspace/journal/memoryExtractor.ts

@@ -7,6 +7,7 @@ import { WORKSPACE_FILES } from "../paths.js";
 import { writeFileAtomic } from "../../utils/files/atomic.js";
 import { log } from "../../system/logger/index.js";
 import { ClaudeCliNotFoundError } from "./archivist-cli.js";
+import { hasTopicFormat } from "../memory/topic-detect.js";
 
 const EXTRACTION_SYSTEM_PROMPT = `You are a personal-fact extractor. Given a batch of chat excerpts between a user and an AI assistant, extract ONLY durable facts about the USER — things that would still be true next week.
 
@@ -39,6 +40,11 @@ export interface MemoryExtractionDeps {
 }
 
 export async function extractAndAppendMemory(deps: MemoryExtractionDeps): Promise<number> {
+  // Same predicate the prompt reader uses: in topic format memory.md is never read, so writing it only grows a dead file.
+  if (hasTopicFormat(deps.workspaceRoot)) {
+    log.debug("memory-extractor", "topic-format workspace, skipping legacy memory.md extraction");
+    return 0;
+  }
   const memoryPath = path.join(deps.workspaceRoot, WORKSPACE_FILES.memory);
   const existingMemory = existsSync(memoryPath) ? readFileSync(memoryPath, "utf-8") : "";
 

package/server/workspace/memory/legacy-fold.ts

@@ -0,0 +1,34 @@
+// Bullets from a leftover `conversations/memory.md` that the atomic → topic cluster must include, or they drop out of
+// the prompt at the swap (#3460). By the time topic migration clusters, a present `memory.md` is never going to be
+// handled by the #1029 migration: it sits beside `.backup`, or is under its placeholder threshold.
+
+import type { MemoryCandidate } from "./migrate.js";
+import type { MemoryEntry, MemoryType } from "./types.js";
+
+// Nothing classifies these bullets; the clusterer files them by the type it is given.
+export const FOLDED_LEGACY_TYPE: MemoryType = "fact";
+
+const FOLDED_NAME_MAX_CHARS = 80;
+
+function dedupeKey(text: string): string {
+  return text.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+/** Turn legacy bullets into cluster input, skipping any already present as an atomic entry body or earlier bullet. */
+export function legacyFoldEntries(candidates: readonly MemoryCandidate[], atomicEntries: readonly MemoryEntry[]): MemoryEntry[] {
+  const seen = new Set(atomicEntries.map((entry) => dedupeKey(entry.body)));
+  const folded: MemoryEntry[] = [];
+  candidates.forEach((candidate, index) => {
+    const key = dedupeKey(candidate.body);
+    if (key.length === 0 || seen.has(key)) return;
+    seen.add(key);
+    folded.push({
+      type: FOLDED_LEGACY_TYPE,
+      name: candidate.body.slice(0, FOLDED_NAME_MAX_CHARS),
+      description: candidate.section || "from conversations/memory.md",
+      body: candidate.body,
+      slug: `${FOLDED_LEGACY_TYPE}_legacy-${index}`,
+    });
+  });
+  return folded;
+}

package/server/workspace/memory/legacy-migration-gate.ts

@@ -0,0 +1,27 @@
+// Decides whether the one-shot `memory.md` → atomic migration (#1029) may run, from facts the
+// caller has already read off disk. Pure so every skip reason can be tested without a workspace.
+
+// The init placeholder we used to write was smaller than this; a file this small has no facts.
+export const LEGACY_MEMORY_PLACEHOLDER_MAX_BYTES = 64;
+
+export interface LegacyMemoryState {
+  /** Size of `conversations/memory.md`, or null when the file is absent. */
+  legacySizeBytes: number | null;
+  /** `memory.md.backup` exists — the marker a previous migration completed. */
+  backupExists: boolean;
+  /** The workspace already uses the topic layout (#1070). */
+  topicFormat: boolean;
+}
+
+export type LegacyMigrationSkipReason = "no-legacy-file" | "topic-format" | "placeholder" | "already-migrated";
+
+export type LegacyMigrationGate = { run: true } | { run: false; reason: LegacyMigrationSkipReason };
+
+export function decideLegacyMigration(state: LegacyMemoryState): LegacyMigrationGate {
+  if (state.legacySizeBytes === null) return { run: false, reason: "no-legacy-file" };
+  // Atomic files written into a topic `memory/` are never read and never re-clustered.
+  if (state.topicFormat) return { run: false, reason: "topic-format" };
+  if (state.legacySizeBytes < LEGACY_MEMORY_PLACEHOLDER_MAX_BYTES) return { run: false, reason: "placeholder" };
+  if (state.backupExists) return { run: false, reason: "already-migrated" };
+  return { run: true };
+}

package/server/workspace/memory/llm-classifier.ts

@@ -18,10 +18,8 @@ import type { MemoryClassification, MemoryCandidate, MemoryClassifier } from "./
 import { isMemoryType } from "./types.js";
 import { extractFirstObject, stripFenceAndWhitespace } from "./llm-json.js";
 
-import { ClaudeCliNotFoundError, type Summarize } from "../journal/archivist-cli.js";
-import { errorMessage } from "../../utils/errors.js";
+import type { Summarize } from "../journal/archivist-cli.js";
 import { isRecord } from "../../utils/types.js";
-import { log } from "../../system/logger/index.js";
 
 const SYSTEM_PROMPT = `You are classifying a single bullet from a personal-memory file into one of four types.
 
@@ -46,26 +44,10 @@ interface DepsForLlmClassifier {
 }
 
 export function makeLlmMemoryClassifier(deps: DepsForLlmClassifier): MemoryClassifier {
+  // A failed call throws (CLI missing, quota, auth, timeout) so the migration can tell it apart from
+  // the LLM deliberately answering `null` — only the latter is a real skip.
   return async (candidate: MemoryCandidate) => {
-    const userPrompt = buildUserPrompt(candidate);
-    let raw: string;
-    try {
-      raw = await deps.summarize(SYSTEM_PROMPT, userPrompt);
-    } catch (err) {
-      // Let `ClaudeCliNotFoundError` escape so the caller can abort
-      // the whole migration. Without this, every candidate runs
-      // through the classifier, gets `null` back, and migrateLegacyMemory
-      // produces an empty result + (pre-#1091) renames the legacy file
-      // to `.backup`. Even with #1091 the user pays N classifier
-      // failures (each spawns claude) before realising the CLI is
-      // missing (#1061 review).
-      if (err instanceof ClaudeCliNotFoundError) throw err;
-      log.warn("memory", "llm classifier: summarize threw", {
-        preview: candidate.body.slice(0, 80),
-        error: errorMessage(err),
-      });
-      return null;
-    }
+    const raw = await deps.summarize(SYSTEM_PROMPT, buildUserPrompt(candidate));
     return parseClassifierVerdict(raw);
   };
 }

package/server/workspace/memory/migrate.ts

@@ -58,8 +58,13 @@ export interface MigrationResult {
    *  surface to the user. The migration continues past write errors
    *  so a single bad entry doesn't strand the whole batch. */
   writeErrors: number;
+  /** Candidates whose classifier call failed. Any failure aborts before writing or renaming,
+   *  so `memory.md` stays readable and the next start retries. */
+  classifierFailures: number;
 }
 
+type ClassifyOutcome = { kind: "classified"; classification: MemoryClassification } | { kind: "skipped" } | { kind: "failed" };
+
 // Number of in-flight `classify` calls. Each call spawns the Claude
 // CLI, so there's a real cost to going wide; 4 is empirically a
 // sweet spot — well above the 1-at-a-time baseline (~10× faster on
@@ -85,13 +90,35 @@ export async function migrateLegacyMemory(workspaceRoot: string, classify: Memor
     candidateCount: candidates.length,
     concurrency: CLASSIFY_CONCURRENCY,
   });
-  const classifications = await classifyInParallel(classify, candidates);
+  const outcomes = await classifyInParallel(classify, candidates);
 
   const result = emptyResult(false);
+  result.classifierFailures = outcomes.filter((outcome) => outcome.kind === "failed").length;
+  if (result.classifierFailures > 0) {
+    log.warn("memory", "migration: classifier failed, leaving memory.md in place for the next start", {
+      classifierFailures: result.classifierFailures,
+      candidateCount: candidates.length,
+    });
+    return result;
+  }
+  await writeClassifiedEntries(workspaceRoot, candidates, outcomes, result);
+
+  await regenerateIndex(workspaceRoot);
+  await renameToBackup(sourcePath);
+  return result;
+}
+
+async function writeClassifiedEntries(
+  workspaceRoot: string,
+  candidates: readonly MemoryCandidate[],
+  outcomes: readonly ClassifyOutcome[],
+  result: MigrationResult,
+): Promise<void> {
   const usedSlugs = new Set<string>();
 
   for (const [index, candidate] of candidates.entries()) {
-    const classification = classifications[index];
+    const outcome = outcomes[index];
+    const classification = outcome?.kind === "classified" ? outcome.classification : null;
     if (!classification) {
       result.skippedByClassifier += 1;
     } else {
@@ -119,32 +146,35 @@ export async function migrateLegacyMemory(workspaceRoot: string, classify: Memor
       });
     }
   }
-
-  await regenerateIndex(workspaceRoot);
-  await renameToBackup(sourcePath);
-  return result;
 }
 
 // Classify candidates with bounded concurrency. Workers pull
 // indices off a shared cursor and write into a pre-allocated array
 // so `result[i]` matches `candidates[i]`. Each await falls inside
-// `safeClassify`, which already swallows individual classifier
-// throws (logging once); a concurrent failure can therefore not
-// poison the rest of the batch.
-async function classifyInParallel(classify: MemoryClassifier, candidates: readonly MemoryCandidate[]): Promise<(MemoryClassification | null)[]> {
-  // `Array.from`, not `new Array(n).fill(null)`: `fill` on the `any[]` that
-  // `new Array(n)` produces keeps the element type `any`. Both build the same
-  // dense array of nulls.
-  const results: (MemoryClassification | null)[] = Array.from({ length: candidates.length }, () => null);
+// `safeClassify`, which turns an individual classifier throw into a
+// `failed` outcome (logging once); a concurrent failure can therefore
+// not poison the rest of the batch.
+async function classifyInParallel(classify: MemoryClassifier, candidates: readonly MemoryCandidate[]): Promise<ClassifyOutcome[]> {
+  const results: ClassifyOutcome[] = Array.from({ length: candidates.length }, (): ClassifyOutcome => ({ kind: "skipped" }));
   let nextIndex = 0;
+  // One failure already aborts the migration, so stop spending classifier calls on the rest.
+  let failed = false;
   const worker = async (): Promise<void> => {
-    while (true) {
+    while (!failed) {
       const index = nextIndex;
       nextIndex += 1;
       const candidate = candidates[index];
       // Absent element == the shared cursor ran past the end.
       if (candidate === undefined) return;
-      results[index] = await safeClassify(classify, candidate);
+      let outcome: ClassifyOutcome;
+      try {
+        outcome = await safeClassify(classify, candidate);
+      } catch (err) {
+        failed = true;
+        throw err;
+      }
+      results[index] = outcome;
+      if (outcome.kind === "failed") failed = true;
     }
   };
   const workers = Array.from({ length: Math.min(CLASSIFY_CONCURRENCY, candidates.length) }, () => worker());
@@ -158,6 +188,7 @@ function emptyResult(noop: boolean): MigrationResult {
     written: { preference: 0, interest: 0, fact: 0, reference: 0 },
     skippedByClassifier: 0,
     writeErrors: 0,
+    classifierFailures: 0,
   };
 }
 
@@ -167,7 +198,7 @@ function emptyResult(noop: boolean): MigrationResult {
 // rides along as `section` so the classifier can use it as context.
 // Parsing is character-driven (no regex) to keep sonar happy and to
 // make the bullet-vs-header classification obvious from the code.
-function parseCandidates(raw: string): MemoryCandidate[] {
+export function parseCandidates(raw: string): MemoryCandidate[] {
   const lines = raw.split("\n");
   let section = "";
   const out: MemoryCandidate[] = [];
@@ -200,11 +231,11 @@ function extractBullet(line: string): string | null {
   return body.length > 0 ? body : null;
 }
 
-async function safeClassify(classify: MemoryClassifier, candidate: MemoryCandidate): Promise<MemoryClassification | null> {
+async function safeClassify(classify: MemoryClassifier, candidate: MemoryCandidate): Promise<ClassifyOutcome> {
   try {
     const verdict = await classify(candidate);
-    if (verdict && isMemoryType(verdict.type)) return verdict;
-    return null;
+    if (verdict && isMemoryType(verdict.type)) return { kind: "classified", classification: verdict };
+    return { kind: "skipped" };
   } catch (err) {
     // Startup-wide failures (CLI missing) MUST escape so
     // `runMemoryMigrationOnce` can log once + leave the legacy file
@@ -216,7 +247,7 @@ async function safeClassify(classify: MemoryClassifier, candidate: MemoryCandida
       preview: candidate.body.slice(0, 80),
       error: errorMessage(err),
     });
-    return null;
+    return { kind: "failed" };
   }
 }
 

package/server/workspace/memory/run.ts

@@ -22,6 +22,9 @@ import path from "node:path";
 import { runClaudeCli, ClaudeCliNotFoundError, type Summarize } from "../journal/archivist-cli.js";
 import { makeLlmMemoryClassifier } from "./llm-classifier.js";
 import { migrateLegacyMemory } from "./migrate.js";
+import { decideLegacyMigration, type LegacyMemoryState, type LegacyMigrationSkipReason } from "./legacy-migration-gate.js";
+import { hasTopicFormat } from "./topic-detect.js";
+import { WORKSPACE_FILES } from "../paths.js";
 import { errorMessage } from "../../utils/errors.js";
 import { log } from "../../system/logger/index.js";
 
@@ -32,35 +35,11 @@ export interface RunMigrationDeps {
 }
 
 export async function runMemoryMigrationOnce(workspaceRoot: string, deps: RunMigrationDeps = {}): Promise<void> {
-  const legacyPath = path.join(workspaceRoot, "conversations", "memory.md");
-  if (!existsSync(legacyPath)) {
-    log.debug("memory", "migration: no legacy file, skipping");
-    return;
-  }
-  // If the file is suspiciously empty (just the placeholder we used
-  // to write at init), skip — the migration would yield zero entries
-  // and the rename to `.backup` is pointless.
-  const stat = statSync(legacyPath);
-  if (stat.size < 64) {
-    log.info("memory", "migration: legacy file is below the placeholder threshold, skipping");
-    return;
-  }
-  // The rename to `.backup` is the final step of `migrateLegacyMemory`,
-  // so its presence is the "migration completed" marker. A workspace
-  // where both `memory.md` AND `memory.md.backup` exist means the
-  // user re-introduced the legacy file after a previous successful
-  // migration (probably by mistake or by extracting the backup).
-  // Re-running here would re-classify the bullets and could clobber
-  // typed entries the user has been editing in place; skip with a
-  // clear log instead. The interrupted-migration retry case still
-  // works because no `.backup` exists in that state — the rename
-  // never ran.
+  const legacyPath = path.join(workspaceRoot, WORKSPACE_FILES.memory);
   const backupPath = `${legacyPath}.backup`;
-  if (existsSync(backupPath)) {
-    log.info("memory", "migration: legacy file present but .backup also exists — refusing to re-run", {
-      legacyPath,
-      backupPath,
-    });
+  const gate = decideLegacyMigration(readLegacyMemoryState(workspaceRoot, legacyPath, backupPath));
+  if (!gate.run) {
+    logSkip(gate.reason, legacyPath, backupPath);
     return;
   }
   const summarize = deps.summarize ?? runClaudeCli;
@@ -73,6 +52,7 @@ export async function runMemoryMigrationOnce(workspaceRoot: string, deps: RunMig
       written: result.written,
       skippedByClassifier: result.skippedByClassifier,
       writeErrors: result.writeErrors,
+      classifierFailures: result.classifierFailures,
     });
   } catch (err) {
     if (err instanceof ClaudeCliNotFoundError) {
@@ -82,3 +62,27 @@ export async function runMemoryMigrationOnce(workspaceRoot: string, deps: RunMig
     log.error("memory", "migration: threw, legacy memory left in place", { error: errorMessage(err) });
   }
 }
+
+function readLegacyMemoryState(workspaceRoot: string, legacyPath: string, backupPath: string): LegacyMemoryState {
+  let legacySizeBytes: number | null = null;
+  try {
+    legacySizeBytes = statSync(legacyPath).size;
+  } catch {
+    // ENOENT (or a rename racing us) → treat as absent.
+  }
+  return { legacySizeBytes, backupExists: existsSync(backupPath), topicFormat: hasTopicFormat(workspaceRoot) };
+}
+
+function logSkip(reason: LegacyMigrationSkipReason, legacyPath: string, backupPath: string): void {
+  if (reason === "no-legacy-file") {
+    log.debug("memory", "migration: no legacy file, skipping");
+  } else if (reason === "topic-format") {
+    log.info("memory", "migration: workspace uses topic format, leaving legacy file alone", { legacyPath });
+  } else if (reason === "placeholder") {
+    log.info("memory", "migration: legacy file is below the placeholder threshold, skipping");
+  } else {
+    // A previous run renamed memory.md to .backup as its last step, so the user re-introduced the
+    // file; re-classifying it could clobber typed entries they have been editing.
+    log.info("memory", "migration: legacy file present but .backup also exists — refusing to re-run", { legacyPath, backupPath });
+  }
+}

package/server/workspace/memory/seed-topic-layout-run.ts

@@ -0,0 +1,50 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../paths.js";
+import { MEMORY_TYPES } from "./types.js";
+import { shouldSeedTopicLayout, type MemoryLayoutState } from "./seed-topic-layout.js";
+import { errorMessage } from "../../utils/errors.js";
+import { log } from "../../system/logger/index.js";
+
+// `undefined` = could not be read for a reason other than absence.
+type ReadResult<T> = T | null | undefined;
+
+function isNotFound(err: unknown): boolean {
+  return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+
+function readOrMissing<T>(read: () => T): ReadResult<T> {
+  try {
+    return read();
+  } catch (err) {
+    return isNotFound(err) ? null : undefined;
+  }
+}
+
+function readMemoryLayoutState(workspaceRoot: string): MemoryLayoutState {
+  const entries = readOrMissing(() => readdirSync(path.join(workspaceRoot, WORKSPACE_DIRS.memoryDir)));
+  const legacyText = readOrMissing(() => readFileSync(path.join(workspaceRoot, WORKSPACE_FILES.memory), "utf-8"));
+  // lstat, not existsSync: a broken symlink or a permission error must not read as "no staging".
+  const staging = readOrMissing(() => lstatSync(path.join(workspaceRoot, WORKSPACE_DIRS.memoryStaging)));
+  return {
+    memoryDirEntries: entries ?? [],
+    legacyMemoryText: legacyText ?? null,
+    stagingExists: staging !== null,
+    unreadable: entries === undefined || legacyText === undefined || staging === undefined,
+  };
+}
+
+/** Create the topic-layout type directories when the workspace has no memory to lose. Returns whether it did.
+ *  Never throws: boot must not depend on it. */
+export function seedTopicLayoutIfFresh(workspaceRoot: string): boolean {
+  if (!shouldSeedTopicLayout(readMemoryLayoutState(workspaceRoot))) return false;
+  const memoryRoot = path.join(workspaceRoot, WORKSPACE_DIRS.memoryDir);
+  try {
+    MEMORY_TYPES.forEach((type) => mkdirSync(path.join(memoryRoot, type), { recursive: true }));
+    return true;
+  } catch (err) {
+    log.warn("memory", "could not create the topic memory layout; staying on the atomic one", { memoryRoot, error: errorMessage(err) });
+    return false;
+  }
+}

package/server/workspace/memory/seed-topic-layout.ts

@@ -0,0 +1,34 @@
+// Whether a workspace may start directly in the topic memory layout (#1070) instead of passing through the
+// atomic one. Only when there is no memory to lose: anything else must go through the migration chain.
+
+// What `initWorkspace` used to write into a fresh `memory.md` before #1029; it holds no facts.
+export const LEGACY_MEMORY_PLACEHOLDER = "# Memory\n\nDistilled facts about you and your work.\n";
+
+// Entries that can sit in an empty memory dir: the atomic layout's generated index and Finder metadata.
+// Anything else — including a `.atomic-backup-*` dir, which can hold entries — means there is memory to keep.
+const HARMLESS_MEMORY_DIR_ENTRIES: ReadonlySet<string> = new Set(["MEMORY.md", ".DS_Store"]);
+
+export interface MemoryLayoutState {
+  /** Names directly under `conversations/memory/`; empty when the directory is absent. */
+  memoryDirEntries: readonly string[];
+  /** Contents of `conversations/memory.md`, or null when absent. */
+  legacyMemoryText: string | null;
+  /** `conversations/memory.next/` exists — a topic migration is staged or mid-swap. */
+  stagingExists: boolean;
+  /** Something could not be read (other than "does not exist"), so the state is unknown. */
+  unreadable: boolean;
+}
+
+function normaliseText(text: string): string {
+  return text.replace(/^\uFEFF/u, "").replace(/\r\n/g, "\n");
+}
+
+export function isLegacyMemoryPlaceholder(text: string): boolean {
+  return normaliseText(text) === LEGACY_MEMORY_PLACEHOLDER;
+}
+
+export function shouldSeedTopicLayout(state: MemoryLayoutState): boolean {
+  if (state.unreadable || state.stagingExists) return false;
+  if (state.legacyMemoryText !== null && !isLegacyMemoryPlaceholder(state.legacyMemoryText)) return false;
+  return state.memoryDirEntries.every((name) => HARMLESS_MEMORY_DIR_ENTRIES.has(name));
+}

package/server/workspace/memory/startup.ts

@@ -0,0 +1,29 @@
+// Boot-time memory migration chain plus the promise other subsystems wait on before touching
+// `conversations/memory.md` — the journal's extractor appending mid-migration loses those bullets.
+
+import { runMemoryMigrationOnce } from "./run.js";
+import { runTopicMigrationOnce } from "./topic-run.js";
+
+export type MemoryMigrationRunner = (workspaceRoot: string) => Promise<void>;
+
+const DEFAULT_RUNNERS: readonly MemoryMigrationRunner[] = [runMemoryMigrationOnce, runTopicMigrationOnce];
+
+let migrationsSettled: Promise<void> = Promise.resolve();
+
+// Chained so a second start never lets the journal slip past a chain that is still running.
+export function startMemoryMigrations(workspaceRoot: string, runners: readonly MemoryMigrationRunner[] = DEFAULT_RUNNERS): void {
+  migrationsSettled = migrationsSettled.then(() => runInOrder(workspaceRoot, runners));
+}
+
+// Never rejects: a failed migration must not wedge the journal behind it.
+export function memoryMigrationsSettled(): Promise<void> {
+  return migrationsSettled;
+}
+
+async function runInOrder(workspaceRoot: string, runners: readonly MemoryMigrationRunner[]): Promise<void> {
+  try {
+    await runners.reduce<Promise<void>>((previous, runner) => previous.then(() => runner(workspaceRoot)), Promise.resolve());
+  } catch {
+    // Each runner logs its own failure; stopping the chain here matches the previous `.then(noop, noop)`.
+  }
+}