mulmoclaude 0.5.2 → 0.6.0

package/server/workspace/memory/topic-cluster.ts

@@ -0,0 +1,218 @@
+// LLM-driven clusterer that turns a flat list of legacy atomic
+// entries into a `<type, topic> → bullets[]` mapping (#1070 PR-A).
+// Library only — `topic-migrate` is the one that calls it and writes
+// to staging. The clusterer is pure async function shape so tests
+// can substitute a deterministic stub without touching the LLM.
+//
+// CLEANUP 2026-07-01: see `topic-run.ts` — this file is part of
+// the one-shot atomic → topic migration chain and goes when the
+// chain goes.
+
+import { errorMessage } from "../../utils/errors.js";
+import { log } from "../../system/logger/index.js";
+import type { Summarize } from "../journal/archivist-cli.js";
+import type { MemoryEntry, MemoryType } from "./types.js";
+import { isMemoryType } from "./types.js";
+import { isSafeTopicSlug, slugifyTopicName } from "./topic-types.js";
+
+export interface ClusterTopic {
+  /** Topic slug (filename without `.md`). Must pass `isSafeTopicSlug`. */
+  topic: string;
+  /** Optional H2 sub-categorisation. When empty, bullets sit under the
+   *  H1 directly. */
+  sections?: ClusterSection[];
+  /** Bullets that don't fit any section. They land directly under H1
+   *  ahead of any sectioned content. */
+  unsectionedBullets?: string[];
+}
+
+export interface ClusterSection {
+  /** H2 heading text (e.g. "Rock / Metal"). */
+  heading: string;
+  /** Bullet bodies. Order is preserved. */
+  bullets: string[];
+}
+
+export type ClusterMap = Record<MemoryType, ClusterTopic[]>;
+
+export type MemoryClusterer = (entries: readonly MemoryEntry[]) => Promise<ClusterMap | null>;
+
+const CLUSTER_SYSTEM_PROMPT = `You group personal-memory bullets into topic files for long-term storage.
+
+Input: a JSON array of bullets. Each has \`type\` (preference / interest / fact / reference), \`name\` (one-line label), and \`body\` (the raw bullet text).
+
+Task: cluster the bullets by type and topic.
+
+- Each \`type\` (preference / interest / fact / reference) gets its own section in the output.
+- Within a type, group bullets that share a subject into one topic. Topic names are short, lowercase ASCII slugs (e.g. "music", "art", "ai-research", "travel", "bootcamp", "dev", "food", "tasks", "paths"). Pick names that are descriptive of the cluster.
+- Inside a topic, you MAY further sub-categorise via H2 sections (e.g. \`music\` → "Rock / Metal", "Punk / Melodic"). Sections are optional — small topics with a handful of bullets can skip them and leave \`unsectionedBullets\`.
+- Keep bullets verbatim. Do NOT edit, paraphrase, summarise, or merge bullets. The output must be losslessly reconstructable.
+- Place each bullet into exactly ONE topic. No duplication across topics.
+- Aim for ~5–15 topic files per type. Avoid singletons unless the bullet has no peers.
+
+Output: ONE JSON object only, no prose, no markdown fences. Schema:
+
+{
+  "preference": [
+    { "topic": "<slug>", "sections": [ { "heading": "<H2 text>", "bullets": ["...", "..."] } ], "unsectionedBullets": ["..."] }
+  ],
+  "interest":  [ ... ],
+  "fact":      [ ... ],
+  "reference": [ ... ]
+}
+
+\`sections\` and \`unsectionedBullets\` are both optional per topic. Empty arrays are also OK. Every type key must be present even if its array is empty.`;
+
+export interface MakeClustererDeps {
+  summarize: Summarize;
+}
+
+export function makeLlmMemoryClusterer(deps: MakeClustererDeps): MemoryClusterer {
+  return async (entries) => {
+    if (entries.length === 0) {
+      return { preference: [], interest: [], fact: [], reference: [] };
+    }
+    const userPrompt = buildUserPrompt(entries);
+    let raw: string;
+    try {
+      raw = await deps.summarize(CLUSTER_SYSTEM_PROMPT, userPrompt);
+    } catch (err) {
+      log.warn("memory", "cluster: summarize threw", { error: errorMessage(err) });
+      return null;
+    }
+    return parseClusterMap(raw);
+  };
+}
+
+function buildUserPrompt(entries: readonly MemoryEntry[]): string {
+  const payload = entries.map((entry) => ({ type: entry.type, name: entry.name, body: entry.body }));
+  return `${entries.length} bullets to cluster:\n\n${JSON.stringify(payload, null, 2)}`;
+}
+
+// Tolerant parser: strips fences, picks the first balanced object,
+// validates schema, normalises slugs. Bullets with unknown types or
+// missing topics are dropped (logged so the migration's count of
+// unaccounted-for entries is visible).
+export function parseClusterMap(raw: string): ClusterMap | null {
+  const stripped = stripFenceAndWhitespace(raw);
+  const objectText = extractFirstObject(stripped);
+  if (!objectText) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(objectText);
+  } catch {
+    return null;
+  }
+  if (!isPlainObject(parsed)) return null;
+  const out: ClusterMap = { preference: [], interest: [], fact: [], reference: [] };
+  for (const type of ["preference", "interest", "fact", "reference"] as const) {
+    const list = (parsed as Record<string, unknown>)[type];
+    if (!Array.isArray(list)) continue;
+    for (const candidate of list) {
+      const topic = normaliseTopic(candidate);
+      if (topic) out[type].push(topic);
+    }
+  }
+  return out;
+}
+
+function normaliseTopic(value: unknown): ClusterTopic | null {
+  if (!isPlainObject(value)) return null;
+  const obj = value as Record<string, unknown>;
+  const slug = resolveTopicSlug(obj.topic);
+  if (!slug) return null;
+  const sections = normaliseSections(obj.sections);
+  const unsectionedBullets = normaliseBulletList(obj.unsectionedBullets);
+  if (sections.length === 0 && unsectionedBullets.length === 0) return null;
+  return {
+    topic: slug,
+    ...(sections.length > 0 ? { sections } : {}),
+    ...(unsectionedBullets.length > 0 ? { unsectionedBullets } : {}),
+  };
+}
+
+function resolveTopicSlug(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  if (isSafeTopicSlug(value)) return value;
+  const slugified = slugifyTopicName(value);
+  return slugified && isSafeTopicSlug(slugified) ? slugified : null;
+}
+
+function normaliseSections(value: unknown): ClusterSection[] {
+  if (!Array.isArray(value)) return [];
+  const out: ClusterSection[] = [];
+  for (const candidate of value) {
+    const section = normaliseSection(candidate);
+    if (section) out.push(section);
+  }
+  return out;
+}
+
+function normaliseBulletList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((bullet): bullet is string => typeof bullet === "string" && bullet.trim().length > 0);
+}
+
+function normaliseSection(value: unknown): ClusterSection | null {
+  if (!isPlainObject(value)) return null;
+  const obj = value as Record<string, unknown>;
+  const heading = typeof obj.heading === "string" ? obj.heading.trim() : "";
+  if (heading.length === 0) return null;
+  if (!Array.isArray(obj.bullets)) return null;
+  const bullets = obj.bullets.filter((bullet): bullet is string => typeof bullet === "string" && bullet.trim().length > 0);
+  if (bullets.length === 0) return null;
+  return { heading, bullets };
+}
+
+function stripFenceAndWhitespace(raw: string): string {
+  let text = raw.trim();
+  if (text.startsWith("```")) {
+    const firstNl = text.indexOf("\n");
+    if (firstNl >= 0) text = text.slice(firstNl + 1);
+    if (text.endsWith("```")) text = text.slice(0, -3);
+  }
+  return text.trim();
+}
+
+function extractFirstObject(text: string): string | null {
+  const start = text.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0;
+  let index = start;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === '"') {
+      index = skipStringBody(text, index + 1);
+      continue;
+    }
+    if (char === "{") depth += 1;
+    else if (char === "}") {
+      depth -= 1;
+      if (depth === 0) return text.slice(start, index + 1);
+    }
+    index += 1;
+  }
+  return null;
+}
+
+function skipStringBody(text: string, fromIndex: number): number {
+  let index = fromIndex;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    if (char === '"') return index + 1;
+    index += 1;
+  }
+  return text.length;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// Re-exported so migrate.ts can validate the clusterer's output
+// shape before writing.
+export { isMemoryType };

package/server/workspace/memory/topic-detect.ts

@@ -0,0 +1,67 @@
+// Format detection for the memory storage layer (#1070 PR-B).
+//
+// Two layouts can live at `<workspaceRoot>/conversations/memory/`:
+//
+//   atomic (#1029): flat `<type>_<slug>.md` files at the memory
+//     dir root, one fact per file.
+//   topic (#1070):  `<type>/<topic>.md` under per-type subdirs,
+//     one topic per file.
+//
+// Detection signal: topic format is active iff a canonical type
+// subdir (`preference/` / `interest/` / `fact/` / `reference/`)
+// exists under live `conversations/memory/`. The post-swap state.
+//
+// Special case for the swap window: `swapStagingIntoMemory` first
+// renames `memory/` out of the way and then renames `memory.next/`
+// into place. Inside that gap `memory/` does not exist at all, so
+// requests would otherwise fall back to atomic format and write
+// `<type>_<slug>.md` into the newly promoted topic tree (later
+// topic-mode reads silently ignore those). To bridge the gap, we
+// also accept `memory.next/<type>/` — but ONLY when `memory/` is
+// entirely absent (the actual swap window). When `memory/` still
+// exists with atomic files (staging-in-progress, before the swap),
+// `memory.next/<type>/` is just the clusterer filling staging and
+// must NOT flip detection to topic mode — atomic data is still
+// authoritative and the prompt has to keep reading it.
+// (#1076 / #1087 follow-up — review on prompt-routing regression.)
+//
+// The check is cheap (one stat per type plus a stat on `memory/`)
+// and reflects on-disk truth, so a manual swap immediately changes
+// behavior on the next request — no module-level cache.
+
+import { statSync } from "node:fs";
+import path from "node:path";
+
+import { WORKSPACE_DIRS } from "../paths.js";
+import { MEMORY_TYPES } from "./types.js";
+
+function isDirectorySafe(absPath: string): boolean {
+  try {
+    return statSync(absPath).isDirectory();
+  } catch {
+    // ENOENT / EACCES → treat as missing.
+    return false;
+  }
+}
+
+function hasAnyTypeSubdir(root: string): boolean {
+  for (const type of MEMORY_TYPES) {
+    if (isDirectorySafe(path.join(root, type))) return true;
+  }
+  return false;
+}
+
+export function hasTopicFormat(workspaceRoot: string): boolean {
+  const memoryRoot = path.join(workspaceRoot, WORKSPACE_DIRS.memoryDir);
+  // Live tree wins: any `memory/<type>/` → post-swap topic mode.
+  if (hasAnyTypeSubdir(memoryRoot)) return true;
+  // If live `memory/` still exists (with atomic files at the root,
+  // or empty), the staging dir is just being filled — atomic format
+  // is still authoritative until the swap renames memory/ out of
+  // the way. Don't let `memory.next/<type>/` flip detection here.
+  if (isDirectorySafe(memoryRoot)) return false;
+  // Live tree absent → could be the swap window OR a fresh
+  // workspace. Consult staging.
+  const stagingRoot = path.join(workspaceRoot, WORKSPACE_DIRS.memoryStaging);
+  return hasAnyTypeSubdir(stagingRoot);
+}

package/server/workspace/memory/topic-index-hook.ts

@@ -0,0 +1,128 @@
+// Auto-regenerate `conversations/memory/MEMORY.md` whenever a topic
+// file is written via an app route (#1032).
+//
+// Wired into `publishFileChange` — the single chokepoint every
+// route hits after a successful write. When the changed path looks
+// like a topic file, this kicks off `regenerateTopicIndex` async
+// so the index stays in sync with the bullets the user just edited
+// in the file explorer.
+//
+// Limitation: the agent's raw `Write` tool bypasses app routes, so
+// agent-driven edits do NOT trigger this hook. The prompt context
+// re-reads disk every turn (`loadAllTopicFilesSync`), so the agent
+// itself stays fresh; only the on-disk `MEMORY.md` lags between
+// agent writes. Acceptable today — revisit if a periodic refresh
+// proves needed.
+
+import { workspacePath } from "../workspace.js";
+import { regenerateTopicIndex } from "./topic-io.js";
+import { errorMessage } from "../../utils/errors.js";
+import { log } from "../../system/logger/index.js";
+import { MEMORY_TYPES } from "./types.js";
+import { isSafeTopicSlug } from "./topic-types.js";
+
+const TOPIC_PATH_PREFIXES: readonly string[] = MEMORY_TYPES.map((type) => `conversations/memory/${type}/`);
+
+// Returns true iff the relative path points at a topic file —
+// `conversations/memory/<type>/<slug>.md` where `<slug>` passes
+// `isSafeTopicSlug` (the same shape gate the writer uses). Files at
+// the memory root itself (e.g. `conversations/memory/MEMORY.md`,
+// the index this helper writes) are excluded so the regen doesn't
+// recurse on its own writes.
+//
+// Path is expected POSIX-normalised (the caller in `file-change.ts`
+// already does this) and workspace-relative. We reject:
+//   - absolute paths (`/foo` / `C:\\foo`)
+//   - backslash-using paths (raw Windows separators)
+//   - non-`.md` files
+//   - dotdir subtrees (`.atomic-backup/`, `.archived/`)
+//   - nested paths under a type subdir (the layout is flat)
+//   - basenames that fail `isSafeTopicSlug` — same contract the
+//     writer enforces, so a malformed file dropped manually under a
+//     type subdir won't trigger a regen for an entry the loader
+//     would later skip anyway.
+export function isTopicFilePath(relativePath: string): boolean {
+  if (typeof relativePath !== "string" || relativePath.length === 0) return false;
+  if (relativePath.startsWith("/")) return false;
+  if (relativePath.includes("\\")) return false;
+  if (!relativePath.endsWith(".md")) return false;
+  if (relativePath.includes("/.atomic-backup/")) return false;
+  if (relativePath.includes("/.archived/")) return false;
+  for (const prefix of TOPIC_PATH_PREFIXES) {
+    if (!relativePath.startsWith(prefix)) continue;
+    const tail = relativePath.slice(prefix.length);
+    if (tail.includes("/")) return false;
+    const slug = tail.slice(0, -".md".length);
+    if (!isSafeTopicSlug(slug)) return false;
+    return true;
+  }
+  return false;
+}
+
+/** Workspace-relative path to the index file the hook regenerates. */
+export const TOPIC_INDEX_RELATIVE_PATH = "conversations/memory/MEMORY.md";
+
+// Per-workspace FIFO chain. `regenerateTopicIndex` reads the topic
+// directory tree then writes `MEMORY.md` atomically — concurrent
+// invocations would race on the readdir scan, and a fast burst of
+// edits via the file explorer (saving 5 topic files in 200ms) could
+// produce overlapping rebuilds where the second writer overwrites
+// the first with a stale snapshot. The chain ensures one rebuild at
+// a time per workspace; later calls coalesce naturally because the
+// last finishing rebuild already saw every prior write to disk
+// (#1109 review).
+//
+// Keyed by absolute workspace path so a future multi-workspace
+// deployment doesn't cross-serialize unrelated work. In practice
+// `workspacePath` is a process-level constant today, so the map has
+// a single entry — the keying is forward-compatible insurance.
+const regenChains = new Map<string, Promise<unknown>>();
+
+function chainRegen(workspaceRoot: string): Promise<unknown> {
+  const previous = regenChains.get(workspaceRoot) ?? Promise.resolve();
+  const next = previous.then(
+    () => regenerateTopicIndex(workspaceRoot),
+    () => regenerateTopicIndex(workspaceRoot),
+  );
+  // Tail update is unconditional (then with both onFulfilled and
+  // onRejected) so a single failed rebuild doesn't permanently
+  // poison ordering for the next call.
+  regenChains.set(
+    workspaceRoot,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return next;
+}
+
+// Fire-and-forget index regeneration for a workspace-relative path.
+// Returns `true` when a regen actually ran — callers (specifically
+// `publishFileChange`) use this to decide whether to emit a follow-up
+// change event for the index file itself, so an open `MEMORY.md` tab
+// refreshes alongside the topic file the user just saved. Failures
+// log and resolve `false`.
+export async function maybeRegenerateTopicIndex(relativePath: string): Promise<boolean> {
+  if (!isTopicFilePath(relativePath)) return false;
+  try {
+    await chainRegen(workspacePath);
+    log.debug("memory", "topic-index-hook: regenerated", { trigger: relativePath });
+    return true;
+  } catch (err) {
+    log.warn("memory", "topic-index-hook: regenerate failed", {
+      trigger: relativePath,
+      error: errorMessage(err),
+    });
+    return false;
+  }
+}
+
+/** Test-only — drop the per-workspace regen chain so each test
+ *  starts with a fresh queue. Without this, a chain rejection from
+ *  one test could carry into the next (the .catch in `chainRegen`
+ *  swallows it for the next caller, but the test runner sees the
+ *  unhandled-rejection from the original promise). */
+export function _resetTopicIndexRegenChainForTesting(): void {
+  regenChains.clear();
+}

package/server/workspace/memory/topic-io.ts

@@ -0,0 +1,180 @@
+// Topic-based memory IO (#1070 PR-A).
+//
+// Reads and writes `<type>/<topic>.md` topic files. The directory
+// layout is:
+//
+//   conversations/memory/
+//     preference/dev.md
+//     interest/music.md
+//     ...
+//     MEMORY.md       # auto-generated index (sibling of the type subdirs)
+//
+// The async loader is for migration / batch use; the sync loader is
+// for the agent prompt builder, which runs in a sync code path.
+// Both loaders share the same parse helper so a malformed file
+// produces the same warning regardless of caller.
+
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+
+import { parseFrontmatter, serializeWithFrontmatter } from "../../utils/markdown/frontmatter.js";
+import { writeFileAtomic } from "../../utils/files/atomic.js";
+import { readDirSafe, readDirSafeAsync, readTextSafe, readTextSafeSync } from "../../utils/files/safe.js";
+import { log } from "../../system/logger/index.js";
+import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../paths.js";
+import { isMemoryType, MEMORY_TYPES, type MemoryType } from "./types.js";
+import { extractH2Sections, isSafeTopicSlug, type TopicMemoryFile } from "./topic-types.js";
+
+export function topicMemoryRoot(workspaceRoot: string): string {
+  return path.join(workspaceRoot, WORKSPACE_DIRS.memoryDir);
+}
+
+export function topicMemoryIndexPath(workspaceRoot: string): string {
+  return path.join(workspaceRoot, WORKSPACE_FILES.memoryIndex);
+}
+
+export function topicFilePath(workspaceRoot: string, type: MemoryType, topic: string): string {
+  return path.join(topicMemoryRoot(workspaceRoot), type, `${topic}.md`);
+}
+
+// Both loaders walk types in `MEMORY_TYPES` order (a stable
+// constant) and sort filenames within each type by name. This pins
+// the order of entries in the agent's system prompt so a `readdir`
+// reshuffle on a different filesystem or after a restart can't
+// destabilise the prompt content (and trash prompt cache hit rates).
+export async function loadAllTopicFiles(workspaceRoot: string): Promise<TopicMemoryFile[]> {
+  const root = topicMemoryRoot(workspaceRoot);
+  const collected: TopicMemoryFile[] = [];
+  for (const type of MEMORY_TYPES) {
+    const typeDir = path.join(root, type);
+    const dirents = await readDirSafeAsync(typeDir);
+    const filenames = candidateFilenamesSorted(dirents);
+    for (const name of filenames) {
+      const absPath = path.join(typeDir, name);
+      const raw = await readTextSafe(absPath);
+      const file = parseTopicFile(absPath, raw, type);
+      if (file) collected.push(file);
+    }
+  }
+  return collected;
+}
+
+export function loadAllTopicFilesSync(workspaceRoot: string): TopicMemoryFile[] {
+  const root = topicMemoryRoot(workspaceRoot);
+  const collected: TopicMemoryFile[] = [];
+  for (const type of MEMORY_TYPES) {
+    const typeDir = path.join(root, type);
+    const dirents = readDirSafe(typeDir);
+    const filenames = candidateFilenamesSorted(dirents);
+    for (const name of filenames) {
+      const absPath = path.join(typeDir, name);
+      const raw = readTextSafeSync(absPath);
+      const file = parseTopicFile(absPath, raw, type);
+      if (file) collected.push(file);
+    }
+  }
+  return collected;
+}
+
+function candidateFilenamesSorted(dirents: readonly { name: string }[]): string[] {
+  const names: string[] = [];
+  for (const dirent of dirents) {
+    if (isCandidateFilename(dirent.name)) names.push(dirent.name);
+  }
+  return names.sort();
+}
+
+export async function writeTopicFile(workspaceRoot: string, file: TopicMemoryFile): Promise<string> {
+  if (!isSafeTopicSlug(file.topic)) {
+    throw new Error(`refusing to write topic file with unsafe topic slug: ${JSON.stringify(file.topic)}`);
+  }
+  const dir = path.join(topicMemoryRoot(workspaceRoot), file.type);
+  await mkdir(dir, { recursive: true });
+  const absPath = path.join(dir, `${file.topic}.md`);
+  const content = serializeWithFrontmatter({ type: file.type, topic: file.topic }, file.body);
+  await writeFileAtomic(absPath, content, { uniqueTmp: true });
+  return path.posix.join(WORKSPACE_DIRS.memoryDir, file.type, `${file.topic}.md`);
+}
+
+// Rebuild `MEMORY.md` from the live topic files. Sorted by type
+// (preference / interest / fact / reference) then by topic name.
+// Each file renders as `- <type>/<topic>.md — <H2 csv>` (or just
+// the path when there are no H2 sections yet).
+export async function regenerateTopicIndex(workspaceRoot: string): Promise<void> {
+  await mkdir(topicMemoryRoot(workspaceRoot), { recursive: true });
+  const files = await loadAllTopicFiles(workspaceRoot);
+  const sorted = [...files].sort(compareFiles);
+  const lines: string[] = ["# Memory Index", ""];
+  for (const type of MEMORY_TYPES) {
+    const inType = sorted.filter((file) => file.type === type);
+    if (inType.length === 0) continue;
+    lines.push(`## ${type}`);
+    lines.push("");
+    for (const file of inType) {
+      lines.push(formatIndexLine(file));
+    }
+    lines.push("");
+  }
+  if (sorted.length === 0) lines.push("_(no entries yet)_", "");
+  await writeFileAtomic(topicMemoryIndexPath(workspaceRoot), lines.join("\n"), { uniqueTmp: true });
+}
+
+export function formatIndexLine(file: TopicMemoryFile): string {
+  const link = `${file.type}/${file.topic}.md`;
+  if (file.sections.length === 0) return `- ${link}`;
+  return `- ${link} — ${file.sections.join(", ")}`;
+}
+
+function compareFiles(left: TopicMemoryFile, right: TopicMemoryFile): number {
+  const typeDelta = MEMORY_TYPES.indexOf(left.type) - MEMORY_TYPES.indexOf(right.type);
+  if (typeDelta !== 0) return typeDelta;
+  return left.topic.localeCompare(right.topic);
+}
+
+function isCandidateFilename(name: string): boolean {
+  if (!name.endsWith(".md")) return false;
+  if (name.startsWith(".")) return false;
+  if (name === "MEMORY.md") return false;
+  return true;
+}
+
+function parseTopicFile(absPath: string, raw: string | null, expectedType: MemoryType): TopicMemoryFile | null {
+  if (raw === null) {
+    log.warn("memory", "topic-io: failed to read file", { path: absPath });
+    return null;
+  }
+  const parsed = parseFrontmatter(raw);
+  if (!parsed.hasHeader) {
+    log.warn("memory", "topic-io: missing frontmatter", { path: absPath });
+    return null;
+  }
+  const { type, topic } = parsed.meta;
+  if (!isMemoryType(type)) {
+    log.warn("memory", "topic-io: unknown type", { path: absPath, type: String(type) });
+    return null;
+  }
+  if (type !== expectedType) {
+    log.warn("memory", "topic-io: type / directory mismatch", { path: absPath, type, expectedType });
+    return null;
+  }
+  if (typeof topic !== "string" || topic.trim().length === 0) {
+    log.warn("memory", "topic-io: missing topic", { path: absPath });
+    return null;
+  }
+  const topicTrimmed = topic.trim();
+  if (!isSafeTopicSlug(topicTrimmed)) {
+    log.warn("memory", "topic-io: unsafe topic slug", { path: absPath, topic });
+    return null;
+  }
+  // Filename is the source of truth — the index links to it.
+  // A frontmatter `topic` that disagrees with the basename produces
+  // dangling index entries (`type/topic.md` doesn't exist on disk),
+  // which the swap promotes verbatim.
+  const fileTopic = path.basename(absPath, ".md");
+  if (topicTrimmed !== fileTopic) {
+    log.warn("memory", "topic-io: topic / filename mismatch", { path: absPath, topic: topicTrimmed, fileTopic });
+    return null;
+  }
+  const sections = extractH2Sections(parsed.body);
+  return { type, topic: topicTrimmed, body: parsed.body, sections };
+}