claude-memory-admin 1.0.0

package/src/model.mjs

@@ -0,0 +1,241 @@
+// Builds the full view model for one project: its index, its memory files, the
+// wikilink graph between them, and the consistency problems worth surfacing.
+//
+// The whole store is a few hundred kilobytes, so this runs per request. No
+// cache, no watcher, no invalidation bugs.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseIndex, parseFrontmatter, extractWikilinks } from './parse.mjs';
+import { listMemoryFiles, memoryDir, resolveProjectPath, shortLabel } from './projects.mjs';
+import { ageInDays, estimateTokens, findDuplicates, indexStats } from './stats.mjs';
+
+export const TRASH_DIR = '.trash';
+
+function readIfExists(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** Parse one memory file into its metadata, body and outbound wikilinks. */
+export function loadMemory(dir, file) {
+  const raw = readIfExists(path.join(dir, file));
+  if (raw === null) return null;
+
+  const { data, body, hasFrontmatter } = parseFrontmatter(raw);
+
+  // Two frontmatter shapes exist in the wild: most files nest everything under
+  // `metadata:`, but some write `type:`/`originSessionId:` at the root instead.
+  // Root-level extras are merged in first so a nested block still wins.
+  const nested = (data.metadata && typeof data.metadata === 'object') ? data.metadata : {};
+  const rootExtras = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (key === 'name' || key === 'description' || key === 'metadata') continue;
+    if (value && typeof value === 'object') continue;
+    rootExtras[key] = value;
+  }
+  const metadata = { ...rootExtras, ...nested };
+  const stem = file.replace(/\.md$/, '');
+  const name = typeof data.name === 'string' && data.name ? data.name : stem;
+
+  let stat = null;
+  try {
+    stat = fs.statSync(path.join(dir, file));
+  } catch { /* raced with a delete */ }
+
+  return {
+    file,
+    stem,
+    name,
+    description: typeof data.description === 'string' ? data.description : '',
+    type: metadata.type || 'unknown',
+    metadata,
+    hasFrontmatter,
+    // `name` and the filename usually agree but not always, so both are kept
+    // and the mismatch is reported under health.
+    nameMatchesFile: name === stem,
+    body,
+    raw,
+    bytes: stat ? stat.size : raw.length,
+    modified: metadata.modified || (stat ? new Date(stat.mtimeMs).toISOString() : null),
+    tokens: estimateTokens(raw),
+    outbound: extractWikilinks(body).map((w) => w.target),
+  };
+}
+
+/**
+ * Resolve a wikilink target to a memory file. Targets normally match a `name`,
+ * but fall back to the filename stem, which is what the mismatching files need.
+ */
+function buildResolver(memories) {
+  const byName = new Map();
+  const byStem = new Map();
+  for (const memory of memories) {
+    if (!byName.has(memory.name)) byName.set(memory.name, memory.file);
+    if (!byStem.has(memory.stem)) byStem.set(memory.stem, memory.file);
+  }
+  return (target) => byName.get(target) || byStem.get(target) || null;
+}
+
+export function buildProject(root, slug) {
+  const dir = memoryDir(root, slug);
+  const projectDir = path.join(root, slug);
+  const resolved = resolveProjectPath(projectDir, slug);
+  const hasMemoryDir = fs.existsSync(dir);
+
+  const indexRaw = readIfExists(path.join(dir, 'MEMORY.md'));
+  const index = indexRaw === null ? null : parseIndex(indexRaw);
+  const files = hasMemoryDir ? listMemoryFiles(dir) : [];
+  const memories = files.map((file) => loadMemory(dir, file)).filter(Boolean);
+
+  const indexedFiles = index ? index.indexedFiles : new Set();
+  const referencedFiles = index ? index.referencedFiles : new Set();
+  const resolve = buildResolver(memories);
+
+  // Outbound edges first, then inbound derived from them, so the two can never
+  // disagree.
+  const inbound = new Map(memories.map((m) => [m.file, []]));
+  const danglingWikilinks = [];
+  const edges = [];
+
+  for (const memory of memories) {
+    memory.outboundResolved = [];
+    for (const target of memory.outbound) {
+      const targetFile = resolve(target);
+      if (targetFile && targetFile !== memory.file) {
+        memory.outboundResolved.push({ target, file: targetFile });
+        edges.push({ from: memory.file, to: targetFile });
+        inbound.get(targetFile).push({ from: memory.file, target });
+      } else if (!targetFile) {
+        memory.outboundResolved.push({ target, file: null });
+        danglingWikilinks.push({ from: memory.file, fromName: memory.name, target });
+      }
+    }
+  }
+
+  for (const memory of memories) {
+    memory.ageDays = ageInDays(memory.modified);
+    memory.inbound = inbound.get(memory.file) || [];
+    memory.entry = index ? index.entries.find((e) => e.file === memory.file) || null : null;
+    memory.section = memory.entry ? memory.entry.section : null;
+    memory.status = indexedFiles.has(memory.file)
+      ? 'indexed'
+      : referencedFiles.has(memory.file)
+        ? 'referenced'
+        : 'orphan';
+  }
+
+  const existingFiles = new Set(files);
+  const danglingIndex = index
+    ? index.links
+        .filter((l) => !existingFiles.has(l.file))
+        .map((l) => ({ index: l.index, file: l.file, label: l.label, text: l.text }))
+    : [];
+
+  const health = {
+    orphans: memories.filter((m) => m.status === 'orphan').map((m) => m.file),
+    referencedOnly: memories.filter((m) => m.status === 'referenced').map((m) => m.file),
+    danglingIndex,
+    danglingWikilinks,
+    nameMismatches: memories
+      .filter((m) => !m.nameMatchesFile)
+      .map((m) => ({ file: m.file, name: m.name })),
+    missingFrontmatter: memories.filter((m) => !m.hasFrontmatter).map((m) => m.file),
+    longHooks: index ? indexStats(indexRaw, index.entries).longHooks : [],
+  };
+  // Must count every category the Health tab renders, or the badge disagrees
+  // with the list underneath it.
+  // One flat list is the single source of truth for both the badge and the tab.
+  // Keeping a separate count in sync with what the UI renders failed twice: a
+  // category counted but not rendered shows a badge over an empty tab.
+  health.issues = [
+    ...health.danglingIndex.map((entry) => ({ kind: 'dangling-index', severity: 'bad', entry })),
+    ...health.danglingWikilinks.map((link) => ({ kind: 'dangling-wikilink', severity: 'bad', link })),
+    ...health.orphans.map((file) => ({ kind: 'orphan', severity: 'warn', file })),
+    ...health.referencedOnly.map((file) => ({ kind: 'referenced-only', severity: 'warn', file })),
+    ...health.nameMismatches.map((mismatch) => ({ kind: 'name-mismatch', severity: 'warn', mismatch })),
+    ...health.missingFrontmatter.map((file) => ({ kind: 'missing-frontmatter', severity: 'warn', file })),
+    ...(health.longHooks.length
+      ? [{ kind: 'long-hooks', severity: 'warn', count: health.longHooks.length, longest: health.longHooks[0] }]
+      : []),
+  ];
+  health.issueCount = health.issues.length;
+
+  return {
+    slug,
+    path: resolved.path,
+    label: shortLabel(resolved.path),
+    resolvedBy: resolved.resolvedBy,
+    hasMemoryDir,
+    hasIndex: index !== null,
+    index: index
+      ? { raw: indexRaw, lines: index.parsedLines, entries: index.entries, inlineLinks: index.inlineLinks }
+      : null,
+    memories: memories.map(({ raw, ...rest }) => rest),
+    graph: {
+      nodes: memories.map((m) => ({
+        id: m.file,
+        label: m.name,
+        type: m.type,
+        status: m.status,
+        degree: m.inbound.length + m.outboundResolved.filter((o) => o.file).length,
+      })),
+      edges,
+      dangling: danglingWikilinks,
+    },
+    health,
+    stats: {
+      index: indexStats(indexRaw, index ? index.entries : []),
+      memoryBytes: memories.reduce((sum, m) => sum + m.bytes, 0),
+      memoryTokens: memories.reduce((sum, m) => sum + m.tokens, 0),
+    },
+    duplicates: findDuplicates(memories),
+    trash: listTrash(dir),
+  };
+}
+
+/** Restore records left behind by soft deletes, newest first. */
+export function listTrash(dir) {
+  const trashPath = path.join(dir, TRASH_DIR);
+  let entries;
+  try {
+    entries = fs.readdirSync(trashPath);
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((name) => name.endsWith('.restore.json'))
+    .map((name) => {
+      const record = readIfExists(path.join(trashPath, name));
+      if (!record) return null;
+      try {
+        const parsed = JSON.parse(record);
+        // Records written before batching had a single trashedFile at the root.
+        const entries = parsed.files?.length
+          ? parsed.files
+          : parsed.trashedFile
+            ? [{ file: parsed.memoryFile, trashedFile: parsed.trashedFile }]
+            : [];
+        const backups = [
+          ...entries.map((e) => e.trashedFile),
+          parsed.indexTrashedFile,
+          parsed.backupFile,
+        ].filter(Boolean);
+        return {
+          ...parsed,
+          kind: parsed.kind || 'memories',
+          files: entries,
+          label: parsed.label || parsed.name || parsed.memoryFile || parsed.id,
+          recordFile: name,
+          present: backups.length > 0 && backups.every((f) => fs.existsSync(path.join(trashPath, f))),
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.deletedAt).localeCompare(String(a.deletedAt)));
+}

package/src/mutate.mjs

@@ -0,0 +1,414 @@
+// The only code in the app that writes. Everything else is read-only.
+//
+// Deletes are soft: the file moves into memory/.trash/ and a restore record
+// captures the MEMORY.md lines that were removed, with their original indices,
+// so the whole operation can be undone.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseIndex, removeIndexEntries, removeLine, insertLines, unwrapWikilink } from './parse.mjs';
+import { listMemoryFiles, memoryDir } from './projects.mjs';
+import { TRASH_DIR, loadMemory } from './model.mjs';
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-').replace(/Z$/, '');
+}
+
+/**
+ * Reject anything that is not a plain filename inside this project's memory dir.
+ * Checked before touching the filesystem, and again via realpath after, so a
+ * symlink cannot be used to escape.
+ */
+export function safeMemoryPath(dir, file) {
+  if (typeof file !== 'string' || !file || file.includes('\0')) {
+    throw new Error('Invalid filename');
+  }
+  if (file !== path.basename(file) || file.startsWith('.') || !file.endsWith('.md')) {
+    throw new Error(`Refusing to touch "${file}": must be a plain .md filename`);
+  }
+  const full = path.join(dir, file);
+  const rel = path.relative(dir, full);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error('Path escapes the memory directory');
+  }
+  if (fs.existsSync(full)) {
+    const realDir = fs.realpathSync(dir);
+    const realFull = fs.realpathSync(full);
+    if (path.relative(realDir, realFull).startsWith('..')) {
+      throw new Error('Path escapes the memory directory');
+    }
+  }
+  return full;
+}
+
+function indexPath(dir) {
+  return path.join(dir, 'MEMORY.md');
+}
+
+function readIndex(dir) {
+  try {
+    return fs.readFileSync(indexPath(dir), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Replace MEMORY.md atomically: write a sibling temp file, fsync it, rename over
+ * the target. A .backup copy is kept for the duration and restored if anything
+ * throws, so a crash can never leave a truncated index.
+ */
+function writeFileAtomic(dir, name, text) {
+  const target = path.join(dir, name);
+  const tmp = path.join(dir, `.${name}.tmp-${process.pid}`);
+  const backup = path.join(dir, `.${name}.backup`);
+  const original = fs.existsSync(target) ? fs.readFileSync(target) : null;
+
+  if (original !== null) fs.writeFileSync(backup, original);
+  try {
+    const fd = fs.openSync(tmp, 'w');
+    try {
+      fs.writeFileSync(fd, text, 'utf8');
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    if (original !== null) fs.writeFileSync(target, original);
+    try { fs.unlinkSync(tmp); } catch { /* already gone */ }
+    throw err;
+  } finally {
+    try { if (fs.existsSync(backup)) fs.unlinkSync(backup); } catch { /* best effort */ }
+  }
+}
+
+const writeIndexAtomic = (dir, text) => writeFileAtomic(dir, 'MEMORY.md', text);
+
+/**
+ * What a delete would do, without doing it. This is what the confirm dialog
+ * renders, so it has to be exhaustive about the collateral.
+ */
+export function deletePreview(root, slug, file) {
+  const dir = memoryDir(root, slug);
+  const full = safeMemoryPath(dir, file);
+  const exists = fs.existsSync(full);
+  const indexText = readIndex(dir);
+  const parsed = indexText === null ? null : parseIndex(indexText);
+
+  const indexLines = parsed
+    ? parsed.entries.filter((e) => e.file === file).map((e) => ({ index: e.index, text: e.text }))
+    : [];
+
+  // Continuation lines get removed along with their bullet.
+  const continuations = [];
+  if (parsed) {
+    for (const entry of indexLines) {
+      for (let i = entry.index + 1; i < parsed.lines.length; i++) {
+        const line = parsed.lines[i];
+        if (!line.trim() || !/^[ \t]/.test(line)) break;
+        continuations.push({ index: i, text: line });
+      }
+    }
+  }
+
+  // Links inside prose are deliberately left alone: cutting them out would
+  // mangle the sentence around them. They are reported so they can be fixed
+  // by hand.
+  const inlineRefs = parsed
+    ? parsed.inlineLinks.filter((l) => l.file === file).map((l) => ({ index: l.index, text: l.text }))
+    : [];
+
+  const target = exists ? loadMemory(dir, file) : null;
+  const inboundWikilinks = [];
+  if (target) {
+    const dirFiles = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'MEMORY.md' && f !== file);
+    for (const other of dirFiles) {
+      const memory = loadMemory(dir, other);
+      if (!memory) continue;
+      for (const outbound of memory.outbound) {
+        if (outbound === target.name || outbound === target.stem) {
+          const entry = parsed ? parsed.entries.find((e) => e.file === other) : null;
+          inboundWikilinks.push({
+            from: other,
+            fromName: memory.name,
+            description: memory.description,
+            target: outbound,
+            indexLine: entry ? { index: entry.index, text: entry.text } : null,
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    file,
+    exists,
+    name: target ? target.name : null,
+    description: target ? target.description : null,
+    indexLines,
+    continuations,
+    inlineRefs,
+    inboundWikilinks,
+    hasIndex: indexText !== null,
+  };
+}
+
+/**
+ * Trash one or more memories and drop their index bullets as ONE undoable
+ * operation. Cascading deletes (a memory plus the memories linking to it) and
+ * clearing a whole project both come through here, so there is a single restore
+ * path rather than three.
+ */
+export function deleteMemories(root, slug, files, { includeIndex = false, label = null } = {}) {
+  const dir = memoryDir(root, slug);
+  const wanted = [...new Set([].concat(files))];
+  if (!wanted.length) throw new Error('Nothing selected to delete');
+
+  const targets = wanted.map((file) => {
+    const full = safeMemoryPath(dir, file);
+    if (!fs.existsSync(full)) throw new Error(`No such memory: ${file}`);
+    const memory = loadMemory(dir, file);
+    return { file, full, name: memory?.name || file, description: memory?.description || '' };
+  });
+
+  const trashPath = path.join(dir, TRASH_DIR);
+  fs.mkdirSync(trashPath, { recursive: true });
+  const stamp = timestamp();
+  const indexBefore = readIndex(dir);
+
+  // All index lines are computed against the original text in one pass, so the
+  // recorded indices still describe the file we started from.
+  let removed = [];
+  let indexAfter = indexBefore;
+  if (indexBefore !== null && !includeIndex) {
+    const result = removeIndexEntries(indexBefore, wanted);
+    removed = result.removed;
+    indexAfter = result.text;
+  }
+
+  // Files move first: if a later step fails they are recoverable from .trash
+  // rather than lost, and the moves already made are rolled back.
+  const moved = [];
+  try {
+    for (const target of targets) {
+      const trashedFile = `${stamp}_${target.file}`;
+      fs.renameSync(target.full, path.join(trashPath, trashedFile));
+      moved.push({ ...target, trashedFile });
+    }
+    if (includeIndex && indexBefore !== null) {
+      const trashedIndex = `${stamp}_MEMORY.md`;
+      fs.renameSync(indexPath(dir), path.join(trashPath, trashedIndex));
+      moved.indexTrashed = trashedIndex;
+    } else if (indexBefore !== null && indexAfter !== indexBefore) {
+      writeIndexAtomic(dir, indexAfter);
+    }
+  } catch (err) {
+    for (const entry of moved) {
+      try { fs.renameSync(path.join(trashPath, entry.trashedFile), entry.full); } catch { /* best effort */ }
+    }
+    throw err;
+  }
+
+  const record = {
+    version: 2,
+    kind: includeIndex ? 'project' : 'memories',
+    id: `${stamp}_${includeIndex ? 'project' : targets[0].file}`,
+    label: label || (targets.length === 1 ? targets[0].name : `${targets.length} memories`),
+    deletedAt: new Date().toISOString(),
+    slug,
+    files: moved.map(({ file, trashedFile, name, description }) => ({ file, trashedFile, name, description })),
+    indexTrashedFile: moved.indexTrashed || null,
+    removedLines: removed,
+    indexSha256Before: indexBefore === null ? null : sha256(indexBefore),
+    indexSha256After: indexAfter === null || includeIndex ? null : sha256(indexAfter),
+  };
+  fs.writeFileSync(path.join(trashPath, `${record.id}.restore.json`), JSON.stringify(record, null, 2));
+  return { deleted: true, record };
+}
+
+/** Single-memory delete, optionally cascading to the memories that link to it. */
+export function deleteMemory(root, slug, file, alsoDelete = []) {
+  const extra = [].concat(alsoDelete).filter((f) => f && f !== file);
+  return deleteMemories(root, slug, [file, ...extra]);
+}
+
+/** What clearing a whole project would remove. */
+export function projectDeletePreview(root, slug) {
+  const dir = memoryDir(root, slug);
+  const files = listMemoryFiles(dir);
+  const indexText = readIndex(dir);
+  return {
+    slug,
+    files: files.map((file) => {
+      const memory = loadMemory(dir, file);
+      return { file, name: memory?.name || file, description: memory?.description || '' };
+    }),
+    hasIndex: indexText !== null,
+    indexLines: indexText === null ? 0 : indexText.split('\n').length,
+  };
+}
+
+/** Trash every memory in a project, MEMORY.md included, as one operation. */
+export function deleteProject(root, slug) {
+  const dir = memoryDir(root, slug);
+  const files = listMemoryFiles(dir);
+  const indexText = readIndex(dir);
+  if (!files.length && indexText === null) throw new Error('This project has no memory to delete');
+
+  if (!files.length) {
+    // Only MEMORY.md exists: trash it on its own.
+    const trashPath = path.join(dir, TRASH_DIR);
+    fs.mkdirSync(trashPath, { recursive: true });
+    const stamp = timestamp();
+    const trashedIndex = `${stamp}_MEMORY.md`;
+    fs.renameSync(indexPath(dir), path.join(trashPath, trashedIndex));
+    const record = {
+      version: 2,
+      kind: 'project',
+      id: `${stamp}_project`,
+      label: 'MEMORY.md',
+      deletedAt: new Date().toISOString(),
+      slug,
+      files: [],
+      indexTrashedFile: trashedIndex,
+      removedLines: [],
+      indexSha256Before: sha256(indexText),
+      indexSha256After: null,
+    };
+    fs.writeFileSync(path.join(trashPath, `${record.id}.restore.json`), JSON.stringify(record, null, 2));
+    return { deleted: true, record };
+  }
+
+  return deleteMemories(root, slug, files, {
+    includeIndex: indexText !== null,
+    label: `whole project (${files.length} memories)`,
+  });
+}
+
+/**
+ * Turn a broken `[[target]]` into plain text in one memory. The original file
+ * is copied into .trash first so the edit can be undone like any delete.
+ */
+export function removeWikilink(root, slug, file, target) {
+  const dir = memoryDir(root, slug);
+  const full = safeMemoryPath(dir, file);
+  if (!fs.existsSync(full)) throw new Error(`No such memory: ${file}`);
+  if (typeof target !== 'string' || !target.trim()) throw new Error('No link target given');
+
+  const original = fs.readFileSync(full, 'utf8');
+  const { text, count } = unwrapWikilink(original, target);
+  if (count === 0) throw new Error(`No [[${target}]] found in ${file}`);
+
+  const trashPath = path.join(dir, TRASH_DIR);
+  fs.mkdirSync(trashPath, { recursive: true });
+  const stamp = timestamp();
+  const backupFile = `${stamp}_${file}.before-unlink.md`;
+  fs.writeFileSync(path.join(trashPath, backupFile), original);
+
+  try {
+    writeFileAtomic(dir, file, text);
+  } catch (err) {
+    try { fs.unlinkSync(path.join(trashPath, backupFile)); } catch { /* best effort */ }
+    throw err;
+  }
+
+  const record = {
+    version: 2,
+    kind: 'wikilink',
+    id: `${stamp}_${file}.unlink`,
+    label: `[[${target}]] in ${file}`,
+    deletedAt: new Date().toISOString(),
+    slug,
+    sourceFile: file,
+    target,
+    occurrences: count,
+    backupFile,
+    files: [],
+    removedLines: [],
+  };
+  fs.writeFileSync(path.join(trashPath, `${record.id}.restore.json`), JSON.stringify(record, null, 2));
+  return { removed: true, occurrences: count, record };
+}
+
+/** Undo any trashed operation: a delete, a cascade, a project clear, or an unlink. */
+export function restoreMemory(root, slug, id) {
+  const dir = memoryDir(root, slug);
+  const trashPath = path.join(dir, TRASH_DIR);
+  const recordPath = path.join(trashPath, `${id}.restore.json`);
+  if (!fs.existsSync(recordPath)) throw new Error('No such trash record');
+
+  const record = JSON.parse(fs.readFileSync(recordPath, 'utf8'));
+
+  if (record.kind === 'wikilink') {
+    safeMemoryPath(dir, record.sourceFile);
+    const backup = path.join(trashPath, record.backupFile);
+    if (!fs.existsSync(backup)) throw new Error('The backup copy is gone');
+    writeFileAtomic(dir, record.sourceFile, fs.readFileSync(backup, 'utf8'));
+    fs.unlinkSync(backup);
+    fs.unlinkSync(recordPath);
+    return { restored: true, file: record.sourceFile, indexRestored: 'n/a', kind: 'wikilink' };
+  }
+
+  // Older single-file records used `memoryFile`/`trashedFile` at the top level.
+  const entries = record.files?.length
+    ? record.files
+    : [{ file: record.memoryFile, trashedFile: record.trashedFile }];
+
+  for (const entry of entries) {
+    const target = safeMemoryPath(dir, entry.file);
+    if (fs.existsSync(target)) throw new Error(`${entry.file} already exists - not overwriting it`);
+    if (!fs.existsSync(path.join(trashPath, entry.trashedFile))) {
+      throw new Error(`The trashed copy of ${entry.file} is gone`);
+    }
+  }
+
+  for (const entry of entries) {
+    fs.renameSync(path.join(trashPath, entry.trashedFile), path.join(dir, entry.file));
+  }
+
+  let indexRestored = 'skipped';
+  if (record.indexTrashedFile) {
+    // A whole-project clear took MEMORY.md with it.
+    if (fs.existsSync(indexPath(dir))) {
+      indexRestored = 'skipped';
+    } else {
+      fs.renameSync(path.join(trashPath, record.indexTrashedFile), indexPath(dir));
+      indexRestored = 'exact';
+    }
+  } else {
+    const current = readIndex(dir);
+    if (current !== null && record.removedLines?.length) {
+      // Only splice lines back at their exact positions if MEMORY.md is still
+      // what the delete left behind; otherwise append and say so.
+      if (sha256(current) === record.indexSha256After) {
+        writeIndexAtomic(dir, insertLines(current, record.removedLines));
+        indexRestored = 'exact';
+      } else {
+        const suffix = record.removedLines.map((l) => l.text).join('\n');
+        const separator = current.endsWith('\n') ? '' : '\n';
+        writeIndexAtomic(dir, `${current}${separator}${suffix}\n`);
+        indexRestored = 'appended';
+      }
+    }
+  }
+
+  fs.unlinkSync(recordPath);
+  return { restored: true, files: entries.map((e) => e.file), indexRestored, kind: record.kind || 'memories' };
+}
+
+/** Drop a single MEMORY.md line, used to clear a pointer whose file is gone. */
+export function deleteIndexLine(root, slug, lineIndex, expectedText) {
+  const dir = memoryDir(root, slug);
+  const current = readIndex(dir);
+  if (current === null) throw new Error('This project has no MEMORY.md');
+
+  const { text, removed } = removeLine(current, lineIndex, expectedText);
+  writeIndexAtomic(dir, text);
+  return { removed };
+}