mulmoclaude 0.5.2 → 0.6.0

package/server/workspace/journal/indexFile.ts

@@ -1,25 +1,13 @@
-// Pure builder for summaries/_index.md. Takes in-memory listings of
-// the journal's current topic / daily files and returns the full
-// markdown for the index. All filesystem walking happens in the
-// caller; this function is deterministic and easy to snapshot-test.
-
 import { isoDateOnly } from "../../utils/date.js";
 
 export interface IndexTopicEntry {
-  // Filesystem slug (matches topics/<slug>.md).
   slug: string;
-  // Optional human-readable title extracted from the topic file's
-  // first H1 heading. Falls back to `slug` if absent so the index
-  // row always reads sensibly.
   title?: string;
-  // ISO timestamp of the last write to the topic file. Rendered
-  // for "stale topic" visibility.
   lastUpdatedIso?: string;
 }
 
 export interface IndexDailyEntry {
-  // YYYY-MM-DD in local time. Matches the folder layout.
-  date: string;
+  date: string; // YYYY-MM-DD local
 }
 
 export interface IndexInputs {
@@ -27,8 +15,6 @@ export interface IndexInputs {
   days: readonly IndexDailyEntry[];
   archivedTopicCount: number;
   builtAtIso: string;
-  // How many "Recent days" rows to list before collapsing the
-  // remainder. The full listing still lives under daily/ on disk.
   maxRecentDays?: number;
 }
 
@@ -56,8 +42,7 @@ export function renderTopicsSection(topics: readonly IndexTopicEntry[]): string[
     lines.push("_No topics yet._");
     return lines;
   }
-  // Newest-first by last update (topics with no timestamp sort
-  // last, ordered alphabetically among themselves for stability).
+  // Newest-first; topics with no timestamp sort last, alphabetical among themselves for stability.
   const sorted = [...topics].sort(compareTopicsNewestFirst);
   for (const topicEntry of sorted) {
     lines.push(renderTopicRow(topicEntry));
@@ -71,7 +56,6 @@ export function renderRecentDaysSection(days: readonly IndexDailyEntry[], maxRec
     lines.push("_No daily entries yet._");
     return lines;
   }
-  // Newest-first by date string (YYYY-MM-DD sorts lexically).
   const sorted = [...days].sort((leftDay, rightDay) => {
     if (leftDay.date < rightDay.date) return 1;
     if (leftDay.date > rightDay.date) return -1;
@@ -100,8 +84,7 @@ export function renderArchiveSection(archivedTopicCount: number): string[] {
   return lines;
 }
 
-// Parse an ISO timestamp into a numeric sort key. Invalid or missing
-// timestamps get -Infinity so they sort to the bottom (oldest).
+// Invalid/missing ISO → -Infinity so they sort to the bottom.
 function topicSortKey(entry: IndexTopicEntry): number {
   if (!entry.lastUpdatedIso) return -Infinity;
   const timestampMs = Date.parse(entry.lastUpdatedIso);
@@ -117,14 +100,10 @@ function compareBySlug(leftEntry: IndexTopicEntry, rightEntry: IndexTopicEntry):
 function compareTopicsNewestFirst(leftEntry: IndexTopicEntry, rightEntry: IndexTopicEntry): number {
   const leftKey = topicSortKey(leftEntry);
   const rightKey = topicSortKey(rightEntry);
-  // Both valid timestamps → compare numerically.
-  // One or both invalid (-Infinity) → valid wins; if both invalid,
-  // fall through to the slug tie-breaker.
   const leftIsValid = Number.isFinite(leftKey);
   const rightIsValid = Number.isFinite(rightKey);
   if (leftIsValid && rightIsValid && rightKey !== leftKey) return rightKey - leftKey;
   if (leftIsValid !== rightIsValid) return leftIsValid ? -1 : 1;
-  // Tie-break on slug for determinism.
   return compareBySlug(leftEntry, rightEntry);
 }
 

package/server/workspace/journal/latestDaily.ts

@@ -0,0 +1,51 @@
+// #876 top-bar "today's journal" shortcut falls back to the most recent existing day when today's summary is missing.
+// Backtracks YYYY → MM → DD.md so an empty 2026/05/ still finds 2026/04. Bounded I/O: O(years × months) worst case.
+
+import path from "node:path";
+import fsp from "node:fs/promises";
+import { isEnoent } from "../../utils/files/safe.js";
+import { summariesRoot, DAILY_DIR } from "./paths.js";
+
+export interface LatestDailyResult {
+  /** Workspace-relative path, e.g. "conversations/summaries/daily/2026/04/26.md" */
+  path: string;
+  /** ISO-ish date "YYYY-MM-DD" matching the file's location. */
+  isoDate: string;
+}
+
+const YEAR_RE = /^\d{4}$/;
+const MONTH_RE = /^\d{2}$/;
+const DAY_FILE_RE = /^(\d{2})\.md$/;
+
+async function listSorted(dir: string, pattern: RegExp): Promise<string[]> {
+  let entries: string[];
+  try {
+    entries = await fsp.readdir(dir);
+  } catch (err) {
+    if (isEnoent(err)) return [];
+    throw err;
+  }
+  return entries
+    .filter((name) => pattern.test(name))
+    .sort()
+    .reverse();
+}
+
+export async function findLatestDaily(workspaceRoot: string): Promise<LatestDailyResult | null> {
+  const dailyRoot = path.join(summariesRoot(workspaceRoot), DAILY_DIR);
+  const years = await listSorted(dailyRoot, YEAR_RE);
+  for (const year of years) {
+    const months = await listSorted(path.join(dailyRoot, year), MONTH_RE);
+    for (const month of months) {
+      const days = await listSorted(path.join(dailyRoot, year, month), DAY_FILE_RE);
+      if (days.length === 0) continue;
+      const [dayFile] = days;
+      const dayMatch = DAY_FILE_RE.exec(dayFile);
+      if (!dayMatch) continue;
+      const [, day] = dayMatch;
+      const relPath = path.posix.join("conversations", "summaries", DAILY_DIR, year, month, dayFile);
+      return { path: relPath, isoDate: `${year}-${month}-${day}` };
+    }
+  }
+  return null;
+}

package/server/workspace/journal/memoryExtractor.ts

@@ -1,11 +1,5 @@
-// Extracts durable user facts from chat session excerpts and
-// appends them to memory.md. Called at the end of the journal
-// daily pass so new facts are picked up even if the agent didn't
-// write them during the conversation.
-//
-// Only appends facts that aren't already in memory.md — the LLM
-// receives the current memory content as context and is instructed
-// to return ONLY new facts.
+// Run at end of the journal daily pass so durable user facts are picked up even if the agent didn't memo them in-conversation.
+// LLM receives existing memory.md as context and is instructed to return ONLY new facts (we still de-dupe defensively).
 
 import { readFileSync, existsSync } from "fs";
 import path from "path";
@@ -40,16 +34,10 @@ Rules:
 
 export interface MemoryExtractionDeps {
   workspaceRoot: string;
-  /** The excerpts from today's dirty sessions, concatenated. */
   excerpts: string;
-  /** Spawns claude CLI and returns stdout. Injectable for tests. */
   summarize: (systemPrompt: string, userPrompt: string) => Promise<string>;
 }
 
-/**
- * Extract new user facts from chat excerpts and append to memory.md.
- * Returns the number of facts appended (0 if none found or on error).
- */
 export async function extractAndAppendMemory(deps: MemoryExtractionDeps): Promise<number> {
   const memoryPath = path.join(deps.workspaceRoot, WORKSPACE_FILES.memory);
   const existingMemory = existsSync(memoryPath) ? readFileSync(memoryPath, "utf-8") : "";
@@ -80,18 +68,16 @@ export async function extractAndAppendMemory(deps: MemoryExtractionDeps): Promis
   return factsToAppend.length;
 }
 
-/** Build the user prompt with existing memory + new excerpts. */
 export function buildUserPrompt(existingMemory: string, excerpts: string): string {
   const parts: string[] = [];
   if (existingMemory.trim()) {
-    parts.push("## Already known (do NOT repeat these):\n\n" + existingMemory);
+    parts.push(`## Already known (do NOT repeat these):\n\n${existingMemory}`);
   }
-  parts.push("## New chat excerpts:\n\n" + excerpts);
+  parts.push(`## New chat excerpts:\n\n${excerpts}`);
   parts.push("\nExtract any NEW user facts not already in the 'Already known' section above. If none, output: NONE");
   return parts.join("\n\n");
 }
 
-/** Parse LLM output into a list of fact strings. */
 export function parseExtractedFacts(raw: string): string[] {
   const trimmed = raw.trim();
   if (trimmed === "NONE" || trimmed === "") return [];
@@ -106,7 +92,6 @@ function normalizeFact(fact: string): string {
   return fact.replace(/^- /, "").trim().toLowerCase();
 }
 
-/** Remove facts that already exist in the current memory content. */
 export function filterNewFacts(existingMemory: string, facts: readonly string[]): string[] {
   const seen = new Set(parseExtractedFacts(existingMemory).map(normalizeFact));
   const out: string[] = [];
@@ -119,7 +104,6 @@ export function filterNewFacts(existingMemory: string, facts: readonly string[])
   return out;
 }
 
-/** Append facts to existing memory content. */
 export function appendFacts(existing: string, facts: string[]): string {
   const trimmed = existing.trimEnd();
   const factsBlock = facts.join("\n");

package/server/workspace/journal/optimizationPass.ts

@@ -1,8 +1,3 @@
-// Weekly-ish topic optimization pass: merge near-duplicates, move
-// stale topics into archive/. Separate file from dailyPass so the
-// two can evolve independently and so the optimizer stays opt-in
-// from the top-level runner.
-
 import { workspacePath as defaultWorkspacePath } from "../workspace.js";
 import { writeTopicFile, readAllTopicFiles, archiveTopic } from "../../utils/files/journal-io.js";
 import {
@@ -17,7 +12,6 @@ import { slugify } from "./paths.js";
 import type { JournalState } from "./state.js";
 import { log } from "../../system/logger/index.js";
 
-// How many characters of each topic file we hand to the optimizer.
 // Enough to judge duplication without blowing up the prompt.
 const OPTIMIZER_HEAD_CHARS = 500;
 
@@ -33,10 +27,7 @@ export interface OptimizationPassResult {
   skippedReason?: string;
 }
 
-// Pure planner: turns the optimizer's raw merge instructions into a
-// concrete list of slug-level operations. Empty merges (where every
-// source resolves to the merge target itself) are dropped, and slugs
-// are normalized via slugify so the I/O layer never has to.
+// Drops empty merges (every source resolves to the target itself); normalizes via slugify so the I/O layer never has to.
 export interface MergePlanItem {
   intoSlug: string;
   fromSlugs: string[];
@@ -60,8 +51,6 @@ export function planMerges(merges: readonly RawMerge[]): MergePlanItem[] {
   return plans;
 }
 
-// Pure transform: returns the next JournalState with any slug in
-// `removed` filtered out of knownTopics.
 export function applyRemovedTopics(state: JournalState, removed: ReadonlySet<string>): JournalState {
   return {
     ...state,
@@ -73,10 +62,7 @@ async function executeMergePlans(workspaceRoot: string, plans: MergePlanItem[],
   for (const plan of plans) {
     await writeTopicFile(plan.intoSlug, plan.newContent, workspaceRoot);
     for (const src of plan.fromSlugs) {
-      // Only record the merge as successful if the source file
-      // actually moved. If archiveTopic fails (missing file, IO
-      // error) we leave the source out of the removed set so the
-      // in-memory knownTopics state stays accurate.
+      // Skip on archive failure so in-memory knownTopics stays accurate (the source file didn't actually move).
       if (!(await archiveTopic(src, workspaceRoot))) continue;
       removed.add(src);
       mergedSlugs.push(src);
@@ -107,9 +93,7 @@ export async function runOptimizationPass(
 
   const topics = await loadTopicHeads(workspaceRoot);
   if (topics.length < 2) {
-    // Nothing to optimise — need at least 2 topics for a merge to
-    // be meaningful, and archiving a single topic would leave an
-    // empty journal which feels wrong.
+    // Need at least 2 topics for a merge to be meaningful; archiving a sole topic would leave an empty journal.
     result.skipped = true;
     result.skippedReason = "fewer than 2 topics";
     return { nextState: { ...state }, result };
@@ -138,8 +122,7 @@ export async function runOptimizationPass(
 
   const removed = new Set<string>();
 
-  // Apply merges first, then archives (which skip slugs already
-  // removed by a merge).
+  // Merges first, then archives (which skip slugs already removed by a merge).
   await executeMergePlans(workspaceRoot, planMerges(parsed.merges), removed, result.mergedSlugs);
   await executeArchives(workspaceRoot, parsed.archives, removed, result.archivedSlugs);
 

package/server/workspace/journal/paths.ts

@@ -1,15 +1,8 @@
-// Pure path / slug helpers for the workspace journal. Nothing here
-// touches the filesystem — every function is a straightforward
-// string transformation so it can be exhaustively unit-tested.
-
 import path from "node:path";
 import { WORKSPACE_DIRS } from "../paths.js";
 import { isValidIsoDate } from "../../utils/date.js";
 import { slugify as slugifyCanonical } from "../../utils/slug.js";
 
-// Directory layout under workspace/conversations/summaries/ is an
-// implementation detail of the journal module; keep it centralised
-// here so tests and callers all agree on the structure.
 export const SUMMARIES_DIR = WORKSPACE_DIRS.summaries;
 export const STATE_FILE = "_state.json";
 export const INDEX_FILE = "_index.md";
@@ -17,16 +10,12 @@ export const DAILY_DIR = "daily";
 export const TOPICS_DIR = "topics";
 export const ARCHIVE_DIR = "archive";
 
-// Absolute path to the summaries root inside a workspace.
 export function summariesRoot(workspaceRoot: string): string {
   return path.join(workspaceRoot, SUMMARIES_DIR);
 }
 
-// summaries/daily/YYYY/MM/DD.md for a given ISO-ish date ("YYYY-MM-DD").
-// Throws if `isoDate` is not exactly YYYY-MM-DD — catches typos at
-// the boundary instead of producing "undefined/undefined.md" paths
-// downstream.
 export function dailyPathFor(workspaceRoot: string, isoDate: string): string {
+  // Throw at the boundary so a typo doesn't produce "undefined/undefined.md".
   if (!isValidIsoDate(isoDate)) {
     throw new Error(`[journal] dailyPathFor: expected YYYY-MM-DD, got "${isoDate}"`);
   }
@@ -34,27 +23,19 @@ export function dailyPathFor(workspaceRoot: string, isoDate: string): string {
   return path.join(summariesRoot(workspaceRoot), DAILY_DIR, year, month, `${day}.md`);
 }
 
-// summaries/topics/<slug>.md
 export function topicPathFor(workspaceRoot: string, slug: string): string {
   return path.join(summariesRoot(workspaceRoot), TOPICS_DIR, `${slug}.md`);
 }
 
-// summaries/archive/topics/<slug>.md — where the optimizer moves
-// merged or stale topic files.
 export function archivedTopicPathFor(workspaceRoot: string, slug: string): string {
   return path.join(summariesRoot(workspaceRoot), ARCHIVE_DIR, TOPICS_DIR, `${slug}.md`);
 }
 
-// Re-export for backwards compatibility — callers that import
-// toIsoDate from journal/paths keep working.
 export { toLocalIsoDate as toIsoDate } from "../../utils/date.js";
 
-// Convert a free-form topic name into a filesystem-safe slug. Thin
-// wrapper around the canonical `slugify` (server/utils/slug.ts) with
-// the journal-specific fallback "topic". See #732 for why journal
-// stopped using its own ASCII-only impl: pure-non-ASCII topic names
-// (e.g. "プロジェクトA" / "プロジェクトB") all collapsed to "topic"
-// and silently overwrote each other's summary files.
+// Falls through to slugifyCanonical with a journal-specific "topic" fallback.
+// #732 retired the journal's own ASCII-only impl that collapsed every
+// non-ASCII topic name onto a single overwriting "topic".
 export function slugify(raw: string): string {
   return slugifyCanonical(raw, "topic");
 }

package/server/workspace/journal/state.ts

@@ -1,12 +1,3 @@
-// Journal state file schema + persistence. The state file tracks
-// what the archivist has already done so we only re-process new or
-// changed sessions on each run.
-//
-// The pure bits (default creation, schema validation, interval
-// arithmetic) live at the top of the file so tests can exercise
-// them without touching disk. Filesystem helpers at the bottom wrap
-// those pure functions with atomic read/write.
-
 import {
   readJournalState as readJournalStateRaw,
   writeJournalState as writeJournalStateRaw,
@@ -16,16 +7,12 @@ import { ONE_HOUR_MS, ONE_DAY_MS } from "../../utils/time.js";
 import { log } from "../../system/logger/index.js";
 import { isRecord } from "../../utils/types.js";
 
-// Bump this when the schema changes in a backwards-incompatible way.
-// Older state files are treated as corrupted and replaced with a
-// fresh default (ingest everything from scratch) — cheap because it
-// only costs one extra archivist pass.
+// Bump on backwards-incompatible schema changes — older state files
+// are discarded and rebuilt (one extra archivist pass).
 export const JOURNAL_STATE_VERSION = 1;
 
 export interface ProcessedSessionRecord {
-  // mtime (ms since epoch) of the session's .jsonl file when we
-  // last ingested it. If mtime advances on the next run, the session
-  // has appended events and needs re-ingest.
+  // mtime at last ingest; advance triggers re-ingest of appended events.
   lastMtimeMs: number;
 }
 
@@ -42,8 +29,6 @@ export interface JournalState {
 export const DEFAULT_DAILY_INTERVAL_HOURS = 1;
 export const DEFAULT_OPTIMIZATION_INTERVAL_DAYS = 7;
 
-// --- Pure helpers (unit-testable without disk) ---------------------
-
 export function defaultState(): JournalState {
   return {
     version: JOURNAL_STATE_VERSION,
@@ -56,17 +41,13 @@ export function defaultState(): JournalState {
   };
 }
 
-// Narrow an `unknown` into a JournalState. Accepts partial / missing
-// fields and fills defaults — users can hand-edit the file to change
-// intervals and we want to be forgiving.
+// Forgiving toward partial / hand-edited input — fill defaults instead of throwing.
 export function parseState(raw: unknown): JournalState {
   if (!isRecord(raw)) return defaultState();
   const obj = raw as Record<string, unknown>;
 
-  // Version mismatch → throw it all out. Cheap to rebuild — but
-  // surface the event in the log so a postmortem can distinguish a
-  // forced re-ingest from "first run after install" / a deleted
-  // state file. (#799 PR1)
+  // Log the version-mismatch reset (#799 PR1) so postmortems can tell
+  // it apart from a missing-file first run.
   if (obj.version !== JOURNAL_STATE_VERSION) {
     log.info("journal", "state schema version mismatch — resetting", {
       from: obj.version,
@@ -101,8 +82,6 @@ function parseProcessedSessions(raw: unknown): Record<string, ProcessedSessionRe
   return out;
 }
 
-// Has the configured daily interval elapsed since the last run? A
-// null lastDailyRunAt means "never run" → always due.
 export function isDailyDue(state: JournalState, nowMs: number): boolean {
   if (state.lastDailyRunAt === null) return true;
   const last = Date.parse(state.lastDailyRunAt);
@@ -119,8 +98,6 @@ export function isOptimizationDue(state: JournalState, nowMs: number): boolean {
   return nowMs - last >= intervalMs;
 }
 
-// --- Filesystem helpers (delegated to journal-io) --------------------
-
 export async function readState(workspaceRoot: string): Promise<JournalState> {
   const raw = await readJournalStateRaw<unknown>(null, workspaceRoot);
   return parseState(raw);

package/server/workspace/memory/io.ts

@@ -0,0 +1,213 @@
+// Memory storage IO (#1029 PR-A).
+//
+// Read all entries, write a single entry, regenerate the index file.
+// Reader is forgiving: a corrupt frontmatter on one entry logs and
+// is skipped, the rest still load. Writer is atomic.
+//
+// `MEMORY.md` is rebuilt from the live frontmatters whenever
+// `regenerateIndex` is called — so every write that changes name /
+// description / type should be followed by a regenerate. The legacy
+// `memory.md` is intentionally NOT touched here; migration handles it.
+
+import { mkdir } from "node:fs/promises";
+import type { Stats } from "node:fs";
+import path from "node:path";
+
+import { parseFrontmatter, serializeWithFrontmatter } from "../../utils/markdown/frontmatter.js";
+import { writeFileAtomic } from "../../utils/files/atomic.js";
+import { WORKSPACE_DIRS, WORKSPACE_FILES } from "../paths.js";
+import { readDirSafe, readDirSafeAsync, readTextSafe, readTextSafeSync, statSafe, statSafeAsync } from "../../utils/files/safe.js";
+import { log } from "../../system/logger/index.js";
+import { isMemoryType, type MemoryEntry, type MemoryType } from "./types.js";
+
+// On-disk directory and index file for typed memory entries.
+// Callers pass the workspace root; this returns the absolute paths.
+export function memoryDirOf(workspaceRoot: string): string {
+  return path.join(workspaceRoot, WORKSPACE_DIRS.memoryDir);
+}
+
+export function memoryIndexOf(workspaceRoot: string): string {
+  return path.join(workspaceRoot, WORKSPACE_FILES.memoryIndex);
+}
+
+// Load every entry from `<workspaceRoot>/conversations/memory/`. The
+// index file (`MEMORY.md`) and any sub-directory (e.g. future
+// `archived/` from #1033) are skipped. Files that fail frontmatter
+// parsing or carry an unknown `type` are logged and excluded.
+export async function loadAllMemoryEntries(workspaceRoot: string): Promise<MemoryEntry[]> {
+  const dir = memoryDirOf(workspaceRoot);
+  const filenames = await listEntryFiles(dir);
+  const loaded: MemoryEntry[] = [];
+  for (const filename of filenames) {
+    const parsed = await readMemoryFile(path.join(dir, filename));
+    if (parsed) loaded.push(parsed);
+  }
+  return loaded;
+}
+
+// Persist a single entry. Filename is `<slug>.md`. Returns the
+// workspace-relative path that was written so callers can log /
+// reference the destination. Slugs are validated against
+// `isSafeMemorySlug` — `..` segments, separators, dotfiles, and
+// reserved filenames are rejected so a caller-supplied slug cannot
+// escape the memory directory or collide with `MEMORY.md`. PR-B
+// will surface this same check at the agent-write boundary.
+export async function writeMemoryEntry(workspaceRoot: string, entry: MemoryEntry): Promise<string> {
+  if (!isSafeMemorySlug(entry.slug)) {
+    throw new Error(`refusing to write memory entry with unsafe slug: ${JSON.stringify(entry.slug)}`);
+  }
+  const dir = memoryDirOf(workspaceRoot);
+  await mkdir(dir, { recursive: true });
+  const filename = `${entry.slug}.md`;
+  const absPath = path.join(dir, filename);
+  const content = serializeWithFrontmatter({ name: entry.name, description: entry.description, type: entry.type }, entry.body);
+  await writeFileAtomic(absPath, content, { uniqueTmp: true });
+  return path.posix.join(WORKSPACE_DIRS.memoryDir, filename);
+}
+
+// Slug shape gate. Allows arbitrary unicode (so non-ASCII names slug
+// fine via `slugifyMemoryName`'s hash fallback) but rejects anything
+// that would let a caller escape the memory directory or shadow
+// reserved filenames.
+export function isSafeMemorySlug(slug: string): boolean {
+  if (typeof slug !== "string") return false;
+  if (slug.length === 0) return false;
+  if (slug.length > 200) return false;
+  if (slug.includes("/") || slug.includes("\\")) return false;
+  if (slug.includes("\0")) return false;
+  // `.`, `..`, leading `.` (dotfiles), or any case-fold of `MEMORY`
+  // would conflict with how the reader scans the directory. The
+  // case-fold covers `Memory` / `memory` collisions on macOS /
+  // Windows where the filesystem is case-insensitive — a case-
+  // sensitive comparison would let `slug = "Memory"` produce
+  // `Memory.md`, which aliases `MEMORY.md` and shadows the index.
+  if (slug.startsWith(".")) return false;
+  if (slug.toUpperCase() === "MEMORY") return false;
+  return true;
+}
+
+// Rebuild `MEMORY.md` from current entry frontmatters. Sorted by type
+// (preference / interest / fact / reference order) then by name so
+// the index reads consistently. Empty memory directory writes a
+// placeholder index (still useful as the marker that the new layout
+// is in effect).
+export async function regenerateIndex(workspaceRoot: string): Promise<void> {
+  const dir = memoryDirOf(workspaceRoot);
+  await mkdir(dir, { recursive: true });
+  const all = await loadAllMemoryEntries(workspaceRoot);
+  const sorted = [...all].sort(compareEntries);
+  const lines: string[] = ["# Memory", ""];
+  for (const entry of sorted) {
+    lines.push(`- [${entry.name}](${entry.slug}.md) — ${entry.description}`);
+  }
+  if (sorted.length === 0) lines.push("_(no entries yet)_");
+  lines.push("");
+  await writeFileAtomic(memoryIndexOf(workspaceRoot), lines.join("\n"), { uniqueTmp: true });
+}
+
+const TYPE_ORDER: readonly MemoryType[] = ["preference", "interest", "fact", "reference"];
+
+function typeOrderKey(type: MemoryType): number {
+  const idx = TYPE_ORDER.indexOf(type);
+  return idx < 0 ? TYPE_ORDER.length : idx;
+}
+
+function compareEntries(left: MemoryEntry, right: MemoryEntry): number {
+  const typeDelta = typeOrderKey(left.type) - typeOrderKey(right.type);
+  if (typeDelta !== 0) return typeDelta;
+  return left.name.localeCompare(right.name);
+}
+
+async function listEntryFiles(dir: string): Promise<string[]> {
+  // Missing memory dir → treat as empty. `readDirSafeAsync` already
+  // returns `[]` on ENOENT, so no explicit branch needed.
+  const dirents = await readDirSafeAsync(dir);
+  const candidates: string[] = [];
+  for (const dirent of dirents) {
+    if (!isCandidateName(dirent.name)) continue;
+    if (dirent.isFile()) {
+      candidates.push(dirent.name);
+      continue;
+    }
+    // Symlinks / non-regular entries: stat to resolve, skip on
+    // failure or non-file. A corrupt entry should not poison the
+    // read path.
+    const stat = await statSafeAsync(path.join(dir, dirent.name));
+    if (stat?.isFile()) candidates.push(dirent.name);
+  }
+  return candidates.sort();
+}
+
+// Synchronous mirror of `loadAllMemoryEntries` for the agent prompt
+// builder, which is sync all the way up. Same skip rules and
+// frontmatter validation — corrupt entries log once and are excluded
+// instead of leaking raw markdown into the system prompt.
+export function loadAllMemoryEntriesSync(workspaceRoot: string): MemoryEntry[] {
+  const dir = memoryDirOf(workspaceRoot);
+  const dirents = readDirSafe(dir);
+  const filenames: string[] = [];
+  for (const dirent of dirents) {
+    if (!isCandidateName(dirent.name)) continue;
+    if (dirent.isFile()) {
+      filenames.push(dirent.name);
+      continue;
+    }
+    const stat: Stats | null = statSafe(path.join(dir, dirent.name));
+    if (stat?.isFile()) filenames.push(dirent.name);
+  }
+  filenames.sort();
+  const loaded: MemoryEntry[] = [];
+  for (const filename of filenames) {
+    const absPath = path.join(dir, filename);
+    const raw = readTextSafeSync(absPath);
+    if (raw === null) {
+      log.warn("memory", "failed to read entry", { path: absPath });
+      continue;
+    }
+    const entry = parseMemoryFile(absPath, raw);
+    if (entry) loaded.push(entry);
+  }
+  return loaded;
+}
+
+function isCandidateName(name: string): boolean {
+  if (name === "MEMORY.md") return false;
+  if (!name.endsWith(".md")) return false;
+  if (name.startsWith(".")) return false;
+  return true;
+}
+
+async function readMemoryFile(absPath: string): Promise<MemoryEntry | null> {
+  const raw = await readTextSafe(absPath);
+  if (raw === null) {
+    log.warn("memory", "failed to read entry", { path: absPath });
+    return null;
+  }
+  return parseMemoryFile(absPath, raw);
+}
+
+// Shared frontmatter validator used by both async and sync loaders.
+// Returns null on missing envelope / unknown type / blank required
+// fields; callers log + skip.
+function parseMemoryFile(absPath: string, raw: string): MemoryEntry | null {
+  const parsed = parseFrontmatter(raw);
+  if (!parsed.hasHeader) {
+    log.warn("memory", "entry missing frontmatter", { path: absPath });
+    return null;
+  }
+  const name = stringField(parsed.meta.name);
+  const description = stringField(parsed.meta.description);
+  const { type } = parsed.meta;
+  if (!name || !description || !isMemoryType(type)) {
+    log.warn("memory", "entry frontmatter incomplete", { path: absPath });
+    return null;
+  }
+  const slug = path.basename(absPath, ".md");
+  return { name, description, type, body: parsed.body, slug };
+}
+
+function stringField(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}