peaks-loop 4.0.34 → 4.0.36

package/dist/services/memory/project-memory-service/index/reindex.js

@@ -0,0 +1,207 @@
+// ---------------------------------------------------------------------------
+// `peaks memory reindex` — full rebuild of `.peaks/memory/index.json` from
+// the markdown files on disk, plus regeneration of the human/LLM-facing
+// `MEMORY.md` index and a drift report.
+//
+// Why this exists (slice 2026-09-09-memory-system-overhaul, B):
+//   - `peaks memory extract` only ever wrote memories FROM artifacts; it
+//     never re-scanned files already on disk, and there was no rebuild
+//     command. 78 top-level files were absent from index.json.
+//   - The index's `kind` came only from the nested `metadata.type` field;
+//     files using a top-level `kind:` were silently dropped.
+//   - `index.json` (machine) and `MEMORY.md` (human/LLM) were two
+//     unsynchronised indexes with nothing keeping them in sync.
+//
+// Contract:
+//   - read-only on the memory markdown files (never rewrites a memory body)
+//   - deterministic ordering: kinds in `KIND_ORDER`, entries by name
+//   - nothing is silently dropped: every file that could not be classified
+//     is reported with its path + raw value
+//   - `MEMORY.md` is regenerated with a "do not edit" banner (the previous
+//     hand-maintained index had drifted to 116 lines against 231 index
+//     entries; a derived view is the only way to keep them in sync)
+// ---------------------------------------------------------------------------
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { MEMORY_KIND_TIER } from '../types.js';
+import { parseMemoryFrontmatter, parseStoredMemoryFile } from '../parsers/frontmatter.js';
+import { assertSafeProjectMemoryDir, normalizeRoot } from '../store/paths.js';
+import { buildMemoryIndex, generateMemoryIndexFile, readExistingIndex } from './ranking.js';
+import { listMarkdownFiles, readProjectMemories } from './search.js';
+/** Marker line that owns `MEMORY.md`. Anything above it is machine output. */
+export const MEMORY_MD_BANNER = '<!-- generated by `peaks memory reindex` — do not edit -->';
+/** `MEMORY.md` is the generated index itself — never a memory source. */
+export const MEMORY_MD_FILENAME = 'MEMORY.md';
+/**
+ * Deterministic section order for the generated `MEMORY.md`: hot kinds
+ * first (mirrors `HOT_KINDS` in `ranking.ts`), warm kinds last. Derived
+ * from the insertion order of `MEMORY_KIND_TIER` so the vocabulary has
+ * exactly one definition.
+ */
+export const KIND_ORDER = Object.keys(MEMORY_KIND_TIER);
+function emptyKindCounts() {
+    const counts = {};
+    for (const kind of KIND_ORDER)
+        counts[kind] = 0;
+    return counts;
+}
+function readPreviousIndexEntries(indexPath) {
+    // `readExistingIndex` is fail-soft (null on missing / unparsable / wrong
+    // version), which is exactly what a drift report wants: a corrupt index
+    // simply yields no orphan-index findings instead of throwing.
+    const previous = readExistingIndex(indexPath);
+    if (previous === null)
+        return [];
+    return [
+        ...Object.values(previous.hot ?? {}).flat(),
+        ...Object.values(previous.warm ?? {}).flat(),
+        ...(previous.cold ?? [])
+    ];
+}
+function collectUnclassified(diskFiles) {
+    const unclassified = [];
+    for (const filePath of diskFiles) {
+        let parsed;
+        try {
+            parsed = parseMemoryFrontmatter(readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            // Unreadable file: still report it rather than dropping it silently.
+            unclassified.push({ name: basename(filePath, '.md'), filePath, rawKind: null, reason: 'file could not be read' });
+            continue;
+        }
+        if (parsed.kind.kind !== null)
+            continue;
+        const rawKind = parsed.kind.rawKind;
+        unclassified.push({
+            name: parsed.name ?? basename(filePath, '.md'),
+            filePath,
+            rawKind,
+            reason: rawKind === null
+                ? 'no metadata.type / kind / type field in frontmatter'
+                : `unrecognized kind value: ${rawKind}`
+        });
+    }
+    return unclassified.sort((left, right) => left.filePath.localeCompare(right.filePath));
+}
+/**
+ * Detect files that resolve to the same memory name. Only files the read
+ * path actually indexes participate (a file rejected for a missing kind is
+ * not an index entry and cannot collide with one).
+ *
+ * Deterministic: names sorted, each `filePaths` sorted. Never resolves the
+ * collision itself — the caller reports it; both files keep their entries.
+ */
+function collectNameConflicts(diskFiles) {
+    const byName = new Map();
+    for (const filePath of diskFiles) {
+        let parsed;
+        try {
+            parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+        }
+        catch {
+            continue; // unreadable files are reported by collectUnclassified
+        }
+        if (parsed === null)
+            continue;
+        const bucket = byName.get(parsed.name);
+        if (bucket === undefined)
+            byName.set(parsed.name, [filePath]);
+        else if (!bucket.includes(filePath))
+            bucket.push(filePath);
+    }
+    return [...byName.entries()]
+        .filter(([, filePaths]) => filePaths.length > 1)
+        .map(([name, filePaths]) => ({ name, filePaths: [...filePaths].sort((left, right) => left.localeCompare(right)) }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Render the human/LLM-facing `MEMORY.md` from a built index. Deterministic:
+ * kinds in `KIND_ORDER`, entries sorted by name, no timestamps.
+ */
+export function renderMemoryMarkdown(index, memoryDir) {
+    const lines = [
+        MEMORY_MD_BANNER,
+        '',
+        '# Peaks Memory Index',
+        '',
+        '> Auto-generated by `peaks memory reindex`. Do not edit by hand — the next',
+        '> reindex overwrites this file. Source of truth: `.peaks/memory/*.md`',
+        '> (bodies) and `.peaks/memory/index.json` (machine index).',
+        ''
+    ];
+    for (const kind of KIND_ORDER) {
+        const entries = [...(index.hot[kind] ?? []), ...(index.warm[kind] ?? [])]
+            .sort((left, right) => left.name.localeCompare(right.name));
+        if (entries.length === 0)
+            continue;
+        lines.push(`## ${kind} (${entries.length})`, '');
+        for (const entry of entries) {
+            const link = relative(memoryDir, entry.sourcePath).replaceAll('\\', '/');
+            lines.push(`- [${entry.name}](${link}) — ${entry.description}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n').replace(/\n+$/, '\n');
+}
+/**
+ * Rebuild `.peaks/memory/index.json` from disk and (on `--apply`) regenerate
+ * `MEMORY.md`. Always returns the drift report, even on a dry run.
+ */
+export function executeMemoryReindex(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const apply = options.apply ?? false;
+    const memoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const indexPath = join(memoryDir, 'index.json');
+    const memoryMdPath = join(memoryDir, MEMORY_MD_FILENAME);
+    const diskFiles = listMarkdownFiles(memoryDir).filter((filePath) => basename(filePath) !== MEMORY_MD_FILENAME);
+    const orphanIndex = readPreviousIndexEntries(indexPath)
+        .filter((entry) => typeof entry.sourcePath !== 'string' || entry.sourcePath.length === 0 || !existsSync(entry.sourcePath))
+        .map((entry) => ({ name: entry.name, kind: entry.kind, sourcePath: entry.sourcePath }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    const unclassified = collectUnclassified(diskFiles);
+    const nameConflicts = collectNameConflicts(diskFiles);
+    // Build once; reuse for the write, the counts, and MEMORY.md so all three
+    // views are guaranteed identical.
+    const index = buildMemoryIndex(projectRoot);
+    const writtenFiles = [];
+    if (apply) {
+        generateMemoryIndexFile(projectRoot, memoryDir, indexPath, index);
+        writtenFiles.push(indexPath);
+    }
+    // Authoritative post-rebuild view: read the memories back through the same
+    // read path every consumer uses, so `orphanDisk` is measured against the
+    // real index rather than against this module's own scan.
+    const memories = readProjectMemories(projectRoot);
+    const indexedFilePaths = new Set(memories.memories.map((memory) => memory.filePath));
+    const orphanDisk = diskFiles.filter((filePath) => !indexedFilePaths.has(filePath));
+    const indexedByKind = emptyKindCounts();
+    for (const memory of memories.memories) {
+        indexedByKind[memory.kind] = (indexedByKind[memory.kind] ?? 0) + 1;
+    }
+    let memoryMdRegenerated = false;
+    if (apply) {
+        const markdown = renderMemoryMarkdown(index, memoryDir);
+        // Plain write (not O_EXCL): MEMORY.md is a derived view and is expected
+        // to be overwritten on every reindex.
+        writeFileSync(memoryMdPath, markdown, 'utf8');
+        writtenFiles.push(memoryMdPath);
+        memoryMdRegenerated = true;
+    }
+    return {
+        apply,
+        projectRoot,
+        memoryDir,
+        indexPath,
+        memoryMdPath,
+        scannedFiles: diskFiles.length,
+        indexed: memories.memories.length,
+        indexedByKind,
+        unclassified,
+        nameConflicts,
+        orphanIndex,
+        orphanDisk,
+        memoryMd: { path: memoryMdPath, regenerated: memoryMdRegenerated },
+        writtenFiles
+    };
+}

package/dist/services/memory/project-memory-service/index/search.js

@@ -21,6 +21,7 @@
 // ---------------------------------------------------------------------------
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
+import { MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS } from '../types.js';
 import { parseStoredMemoryFile } from '../parsers/frontmatter.js';
 import { assertSafeProjectMemoryDir, normalizeRoot } from '../store/paths.js';
 export function listMarkdownFiles(dirPath, options = {}) {
@@ -52,38 +53,27 @@ export function listMarkdownFiles(dirPath, options = {}) {
     return files.sort((left, right) => left.localeCompare(right));
 }
 export function emptyByKind() {
-    return {
-        project: [],
-        rule: [],
-        decision: [],
-        reference: [],
-        feedback: [],
-        convention: [],
-        module: [],
-        lesson: []
-    };
+    const byKind = {};
+    for (const kind of PROJECT_MEMORY_KINDS)
+        byKind[kind] = [];
+    return byKind;
 }
 export function emptyIndex() {
     // Cast through unknown: we *intend* the two halves to together cover the
     // union `ProjectMemoryKind`, but TS does not know that. The `MemoryIndex`
     // type's `hot` / `warm` fields together cover the union; we split the
-    // construction so the JSON output mirrors the hot/warm layout the reader
-    // expects.
+    // construction from the canonical tier map so the JSON output mirrors the
+    // hot/warm layout the reader expects.
+    const hot = {};
+    const warm = {};
+    for (const kind of PROJECT_MEMORY_KINDS) {
+        (MEMORY_KIND_TIER[kind] === 'hot' ? hot : warm)[kind] = [];
+    }
     return {
         version: 1,
         updatedAt: new Date().toISOString(),
-        hot: {
-            feedback: [],
-            decision: [],
-            rule: [],
-            convention: [],
-            module: [],
-            lesson: []
-        },
-        warm: {
-            project: [],
-            reference: []
-        }
+        hot: hot,
+        warm: warm
     };
 }
 export function renderEmptyIndex() {

package/dist/services/memory/project-memory-service/index.d.ts

@@ -1,9 +1,13 @@
-export type { BackupPlanOptions, ExtractedProjectMemory, ExtractPlanOptions, ExtractSessionMemoriesOptions, ExtractSessionMemoriesResult, MemoryIndex, MemoryIndexEntry, ProjectMemoryBackupPlan, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryCopy, ProjectMemoryExtractPlan, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, ProjectMemoryKind, ProjectMemoryReadResult, ProjectMemoryShowResult, ProjectMemoryWrite, StoredProjectMemory } from './types.js';
+export type { BackupPlanOptions, ExtractedProjectMemory, MemoryKindTier, ExtractPlanOptions, ExtractSessionMemoriesOptions, ExtractSessionMemoriesResult, MemoryIndex, MemoryIndexEntry, ProjectMemoryBackupPlan, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryCopy, ProjectMemoryExtractPlan, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, ProjectMemoryKind, ProjectMemoryReadResult, ProjectMemoryShowResult, ProjectMemoryWrite, StoredProjectMemory } from './types.js';
 export { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.js';
+export { HOT_MEMORY_KINDS, MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS, WARM_MEMORY_KINDS } from './types.js';
 export { summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
-export { parseBlock, parseStoredMemoryFile, renderMemoryFile, slugify } from './parsers/frontmatter.js';
+export { parseBlock, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
+export type { MemoryKindResolution, MemoryKindSource, MemoryNameResolution, MemoryNameSource, ParsedMemoryFrontmatter } from './parsers/frontmatter.js';
 export { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRealRoot, normalizeRoot, realPathOrThrow, resolveProjectPath, safeRealpath } from './store/paths.js';
 export { assertSafeMemory, assertSafeMemoryFileContent, hasSensitiveMemoryContent, writeNewFile } from './store/atomic-write.js';
 export { ensureMemoryBootstrap, emptyByKind, emptyIndex, listMarkdownFiles, readProjectMemories, readProjectMemoryBody } from './index/search.js';
-export { generateMemoryIndexFile, readExistingIndex, readMemoryFileMtime, readMemoryIndex, readStoredMemoryNames } from './index/ranking.js';
+export { buildMemoryIndex, generateMemoryIndexFile, readExistingIndex, readMemoryFileMtime, readMemoryIndex, readStoredMemoryNames } from './index/ranking.js';
+export { executeMemoryReindex, renderMemoryMarkdown, KIND_ORDER, MEMORY_MD_BANNER, MEMORY_MD_FILENAME } from './index/reindex.js';
+export type { MemoryReindexOptions, MemoryReindexReport, ReindexNameConflict, ReindexOrphanEntry, ReindexUnclassified } from './index/reindex.js';
 export { createProjectMemoryBackupPlan, createProjectMemoryExtractPlan, executeProjectMemoryBackup, executeProjectMemoryExtract, extractSessionMemories, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from './index/kind-dispatch.js';

package/dist/services/memory/project-memory-service/index.js

@@ -11,14 +11,18 @@
 // `./types.ts` and are re-exported here.
 // ---------------------------------------------------------------------------
 export { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.js';
+// Canonical kind vocabulary + hot/warm tier map (slice E)
+export { HOT_MEMORY_KINDS, MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS, WARM_MEMORY_KINDS } from './types.js';
 // Pure markdown helpers
 export { summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
 // Frontmatter parser + renderer
-export { parseBlock, parseStoredMemoryFile, renderMemoryFile, slugify } from './parsers/frontmatter.js';
+export { parseBlock, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
 // Store: path safety + sensitive content
 export { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRealRoot, normalizeRoot, realPathOrThrow, resolveProjectPath, safeRealpath } from './store/paths.js';
 export { assertSafeMemory, assertSafeMemoryFileContent, hasSensitiveMemoryContent, writeNewFile } from './store/atomic-write.js';
 // Index: search / ranking / dispatch
 export { ensureMemoryBootstrap, emptyByKind, emptyIndex, listMarkdownFiles, readProjectMemories, readProjectMemoryBody } from './index/search.js';
-export { generateMemoryIndexFile, readExistingIndex, readMemoryFileMtime, readMemoryIndex, readStoredMemoryNames } from './index/ranking.js';
+export { buildMemoryIndex, generateMemoryIndexFile, readExistingIndex, readMemoryFileMtime, readMemoryIndex, readStoredMemoryNames } from './index/ranking.js';
+// Full index rebuild + drift report (`peaks memory reindex`)
+export { executeMemoryReindex, renderMemoryMarkdown, KIND_ORDER, MEMORY_MD_BANNER, MEMORY_MD_FILENAME } from './index/reindex.js';
 export { createProjectMemoryBackupPlan, createProjectMemoryExtractPlan, executeProjectMemoryBackup, executeProjectMemoryExtract, extractSessionMemories, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from './index/kind-dispatch.js';

package/dist/services/memory/project-memory-service/parsers/frontmatter.d.ts

@@ -1,9 +1,86 @@
 import type { ExtractedProjectMemory, ProjectMemoryKind, StoredProjectMemory } from '../types.js';
-export declare const VALID_MEMORY_KINDS: Set<ProjectMemoryKind>;
-/** Exported for guard tests + tooling that needs to enumerate the valid
- *  set without duplicating the literal. Single source of truth. */
+/** Accepted-kind set, derived from the canonical `PROJECT_MEMORY_KINDS`
+ *  tuple so the parser cannot drift from the union type / tier map. */
+export declare const VALID_MEMORY_KINDS: ReadonlySet<ProjectMemoryKind>;
+/** Exported for guard tests + tooling that needs to enumerate the accepted
+ *  set (CLI help text, `--kind` validation) without duplicating the literal. */
 export declare const VALID_PROJECT_MEMORY_KINDS: readonly ProjectMemoryKind[];
 export declare function slugify(title: string): string;
 export declare function parseBlock(block: string, sourceArtifact: string): ExtractedProjectMemory | null;
 export declare function renderMemoryFile(memory: ExtractedProjectMemory): string;
+/**
+ * Where a stored memory file's `kind` came from. `'none'` means the file
+ * has no resolvable kind (no `metadata.type`, no `kind:`, no `type:`, or
+ * the value present is not one of the accepted kinds in
+ * `PROJECT_MEMORY_KINDS`).
+ */
+export type MemoryKindSource = 'metadata.type' | 'kind' | 'type' | 'none';
+export interface MemoryKindResolution {
+    kind: ProjectMemoryKind | null;
+    source: MemoryKindSource;
+    /** The first raw value found in the frontmatter, even when it is not a valid kind. */
+    rawKind: string | null;
+}
+export interface ParsedMemoryFrontmatter {
+    hasFrontmatter: boolean;
+    name?: string;
+    /** Top-level `title:` frontmatter value. Never the nested `metadata.title`
+     *  (that is a different semantic); used only as a name fallback on the
+     *  read path — see `resolveMemoryName`. */
+    title?: string;
+    description?: string;
+    sourceArtifact?: string;
+    kind: MemoryKindResolution;
+    /** Raw frontmatter block text (without the `---` fences); '' when absent. */
+    frontmatter: string;
+    body: string;
+}
+/**
+ * Resolve the peaks memory kind from a stored memory file's frontmatter.
+ *
+ * Resolution order (first *valid* kind wins):
+ *   1. nested `metadata.type`   — the canonical peaks contract
+ *   2. top-level `kind:`        — the legacy alias (was silently dropped before)
+ *   3. top-level `type:`        — tolerated by the pre-existing trim-based reader
+ *   4. `none`                   — reported as unclassified; never invented
+ *
+ * Slice 2026-09-09-memory-system-overhaul (B): before this helper, files
+ * using a top-level `kind:` were silently dropped by the reader (defect
+ * #2). Falling through to `kind:` / `type:` is a strict superset of the
+ * old behaviour — no previously-indexed file changes kind.
+ */
+export declare function resolveMemoryKind(content: string): MemoryKindResolution;
+/**
+ * Single parse surface for stored memory frontmatter. Both
+ * `parseStoredMemoryFile` (read path) and the reindex / ingest / doctor
+ * classifiers consume this so there is exactly one kind-resolution rule
+ * in the codebase.
+ *
+ * Tolerates a leading run of HTML-comment lines (e.g. the
+ * `<!-- peaks-memory:start -->` sediment marker) before the opening `---`
+ * fence. The closing fence is still required and body extraction is
+ * unchanged: the body is the text after the closing fence.
+ */
+export declare function parseMemoryFrontmatter(content: string): ParsedMemoryFrontmatter;
+/** Which frontmatter field (or the filename) supplied a memory's name. */
+export type MemoryNameSource = 'name' | 'title' | 'stem' | 'none';
+export interface MemoryNameResolution {
+    /** The resolved name, or null when every fallback was empty. */
+    name: string | null;
+    source: MemoryNameSource;
+}
+/**
+ * Deterministic name fallback chain for the read path:
+ *
+ *   1. `name:`            — the canonical field written by `renderMemoryFile`
+ *   2. `title:`           — hand-written / legacy files (the 5 on-disk files
+ *                           this slice fixes carried only `title:` + `kind:`)
+ *   3. filename stem      — last resort, so a well-formed memory with a valid
+ *                           kind is never dropped just for missing a name
+ *
+ * Empty values are skipped rather than accepted: a `name:` of `''` still
+ * falls through, and a file whose stem is also empty resolves to null so the
+ * caller's validation is preserved (never invents a name).
+ */
+export declare function resolveMemoryName(parsed: ParsedMemoryFrontmatter, filePath: string): MemoryNameResolution;
 export declare function parseStoredMemoryFile(content: string, filePath: string): StoredProjectMemory | null;

package/dist/services/memory/project-memory-service/parsers/frontmatter.js

@@ -10,24 +10,23 @@
 //
 //   2. `parseStoredMemoryFile` — read-path side. Files in `.peaks/memory/`
 //      are stored as standard YAML frontmatter (name / description /
-//      metadata.type / metadata.sourceArtifact) followed by the body.
+//      metadata.type / metadata.sourceArtifact) followed by the body. A file
+//      may also open with HTML-comment lines (the `<!-- peaks-memory:start -->`
+//      sediment marker) before the frontmatter; `parseMemoryFrontmatter`
+//      skips that leading comment run before looking for the `---` fence.
 //
-// Both parsers share the 8-kind `VALID_MEMORY_KINDS` allow-list and the
+// Both parsers share the `VALID_MEMORY_KINDS` allow-list (derived from the
+// canonical `PROJECT_MEMORY_KINDS` tuple in `../types.ts`) and the
 // `slugify` helper used to derive filenames from titles.
 // ---------------------------------------------------------------------------
-export const VALID_MEMORY_KINDS = new Set([
-    'project',
-    'rule',
-    'decision',
-    'reference',
-    'feedback',
-    'convention',
-    'module',
-    'lesson'
-]);
-/** Exported for guard tests + tooling that needs to enumerate the valid
- *  set without duplicating the literal. Single source of truth. */
-export const VALID_PROJECT_MEMORY_KINDS = Array.from(VALID_MEMORY_KINDS);
+import { basename } from 'node:path';
+import { PROJECT_MEMORY_KINDS } from '../types.js';
+/** Accepted-kind set, derived from the canonical `PROJECT_MEMORY_KINDS`
+ *  tuple so the parser cannot drift from the union type / tier map. */
+export const VALID_MEMORY_KINDS = new Set(PROJECT_MEMORY_KINDS);
+/** Exported for guard tests + tooling that needs to enumerate the accepted
+ *  set (CLI help text, `--kind` validation) without duplicating the literal. */
+export const VALID_PROJECT_MEMORY_KINDS = PROJECT_MEMORY_KINDS;
 export function slugify(title) {
     const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
     return slug.length > 0 ? slug : 'project-memory';
@@ -69,36 +68,176 @@ export function renderMemoryFile(memory) {
         ''
     ].join('\n');
 }
-export function parseStoredMemoryFile(content, filePath) {
+/**
+ * Resolve the peaks memory kind from a stored memory file's frontmatter.
+ *
+ * Resolution order (first *valid* kind wins):
+ *   1. nested `metadata.type`   — the canonical peaks contract
+ *   2. top-level `kind:`        — the legacy alias (was silently dropped before)
+ *   3. top-level `type:`        — tolerated by the pre-existing trim-based reader
+ *   4. `none`                   — reported as unclassified; never invented
+ *
+ * Slice 2026-09-09-memory-system-overhaul (B): before this helper, files
+ * using a top-level `kind:` were silently dropped by the reader (defect
+ * #2). Falling through to `kind:` / `type:` is a strict superset of the
+ * old behaviour — no previously-indexed file changes kind.
+ */
+export function resolveMemoryKind(content) {
+    const parsed = parseMemoryFrontmatter(content);
+    return parsed.kind;
+}
+/** Start of an HTML comment line, allowing leading horizontal whitespace. */
+const LEADING_COMMENT_OPEN = /^[ \t]*<!--/;
+/**
+ * Length of the leading run of blank lines and standalone HTML-comment lines.
+ *
+ * A stored memory may be written with the documented sediment marker
+ * (`<!-- peaks-memory:start -->`) — or any HTML comment — BEFORE its YAML
+ * frontmatter. This helper reports how much of the file to skip so the fence
+ * can still be found. At least one comment line must be present: a file that
+ * merely starts with blank lines is not treated as marker-prefixed, so the
+ * pre-existing (fence-at-byte-0) behaviour is preserved exactly.
+ */
+function leadingCommentPrefixLength(normalized) {
+    let offset = 0;
+    let sawComment = false;
+    for (;;) {
+        const rest = normalized.slice(offset);
+        const blank = /^[ \t]*\n/.exec(rest);
+        if (blank !== null) {
+            offset += blank[0].length;
+            continue;
+        }
+        const open = LEADING_COMMENT_OPEN.exec(rest);
+        if (open === null)
+            break;
+        const closeIndex = rest.indexOf('-->', open[0].length);
+        if (closeIndex < 0)
+            break;
+        const afterClose = closeIndex + '-->'.length;
+        const lineEnd = rest.indexOf('\n', afterClose);
+        if (lineEnd < 0)
+            break;
+        // Only a whole comment line counts; trailing prose after `-->` means the
+        // file does not open with a comment block.
+        if (rest.slice(afterClose, lineEnd).trim() !== '')
+            break;
+        offset += lineEnd + 1;
+        sawComment = true;
+    }
+    return sawComment ? offset : 0;
+}
+/**
+ * Single parse surface for stored memory frontmatter. Both
+ * `parseStoredMemoryFile` (read path) and the reindex / ingest / doctor
+ * classifiers consume this so there is exactly one kind-resolution rule
+ * in the codebase.
+ *
+ * Tolerates a leading run of HTML-comment lines (e.g. the
+ * `<!-- peaks-memory:start -->` sediment marker) before the opening `---`
+ * fence. The closing fence is still required and body extraction is
+ * unchanged: the body is the text after the closing fence.
+ */
+export function parseMemoryFrontmatter(content) {
     const normalized = content.replace(/\r\n/g, '\n');
-    if (!normalized.startsWith('---\n'))
-        return null;
-    const endIndex = normalized.indexOf('\n---\n', 4);
-    if (endIndex < 0)
-        return null;
-    const frontmatter = normalized.slice(4, endIndex);
-    const body = normalized.slice(endIndex + '\n---\n'.length).trim();
+    const head = normalized.slice(leadingCommentPrefixLength(normalized));
+    if (!head.startsWith('---\n')) {
+        return { hasFrontmatter: false, kind: { kind: null, source: 'none', rawKind: null }, frontmatter: '', body: normalized.trim() };
+    }
+    const endIndex = head.indexOf('\n---\n', 4);
+    if (endIndex < 0) {
+        return { hasFrontmatter: false, kind: { kind: null, source: 'none', rawKind: null }, frontmatter: '', body: normalized.trim() };
+    }
+    const frontmatter = head.slice(4, endIndex);
+    const body = head.slice(endIndex + '\n---\n'.length).trim();
     let name;
+    let titleField;
     let description;
-    let kind;
     let sourceArtifact;
+    let nestedType;
+    let topType;
+    let kindField;
+    let inMetadata = false;
     for (const rawLine of frontmatter.split('\n')) {
+        const indented = /^\s/.test(rawLine);
         const line = rawLine.trim();
+        if (!indented) {
+            inMetadata = line === 'metadata:';
+        }
         if (line.startsWith('name:'))
             name = line.slice('name:'.length).trim();
+        else if (line.startsWith('title:')) {
+            if (!indented)
+                titleField = line.slice('title:'.length).trim();
+        }
         else if (line.startsWith('description:'))
             description = line.slice('description:'.length).trim();
-        else if (line.startsWith('type:'))
-            kind = line.slice('type:'.length).trim();
+        else if (line.startsWith('type:')) {
+            const value = line.slice('type:'.length).trim();
+            if (indented || inMetadata)
+                nestedType ??= value;
+            else
+                topType ??= value;
+        }
+        else if (line.startsWith('kind:'))
+            kindField ??= line.slice('kind:'.length).trim();
         else if (line.startsWith('sourceArtifact:'))
             sourceArtifact = line.slice('sourceArtifact:'.length).trim();
     }
-    if (!name || !kind || !VALID_MEMORY_KINDS.has(kind) || body.length === 0)
+    const candidates = [
+        ['metadata.type', nestedType],
+        ['kind', kindField],
+        ['type', topType]
+    ];
+    let kind = { kind: null, source: 'none', rawKind: null };
+    for (const [source, raw] of candidates) {
+        if (raw === undefined || raw === '')
+            continue;
+        if (kind.rawKind === null)
+            kind = { kind: null, source: 'none', rawKind: raw };
+        if (VALID_MEMORY_KINDS.has(raw)) {
+            kind = { kind: raw, source, rawKind: raw };
+            break;
+        }
+    }
+    return { hasFrontmatter: true, frontmatter, ...(name !== undefined ? { name } : {}), ...(titleField !== undefined ? { title: titleField } : {}), ...(description !== undefined ? { description } : {}), ...(sourceArtifact !== undefined ? { sourceArtifact } : {}), kind, body };
+}
+/**
+ * Deterministic name fallback chain for the read path:
+ *
+ *   1. `name:`            — the canonical field written by `renderMemoryFile`
+ *   2. `title:`           — hand-written / legacy files (the 5 on-disk files
+ *                           this slice fixes carried only `title:` + `kind:`)
+ *   3. filename stem      — last resort, so a well-formed memory with a valid
+ *                           kind is never dropped just for missing a name
+ *
+ * Empty values are skipped rather than accepted: a `name:` of `''` still
+ * falls through, and a file whose stem is also empty resolves to null so the
+ * caller's validation is preserved (never invents a name).
+ */
+export function resolveMemoryName(parsed, filePath) {
+    if (parsed.name !== undefined && parsed.name.length > 0)
+        return { name: parsed.name, source: 'name' };
+    if (parsed.title !== undefined && parsed.title.length > 0)
+        return { name: parsed.title, source: 'title' };
+    const stem = basename(filePath, '.md');
+    if (stem.length > 0)
+        return { name: stem, source: 'stem' };
+    return { name: null, source: 'none' };
+}
+export function parseStoredMemoryFile(content, filePath) {
+    const parsed = parseMemoryFrontmatter(content);
+    if (!parsed.hasFrontmatter)
+        return null;
+    const { description, sourceArtifact, body } = parsed;
+    const kind = parsed.kind.kind;
+    const { name } = resolveMemoryName(parsed, filePath);
+    if (name === null || kind === null || body.length === 0)
         return null;
     return {
         name,
         title: description ?? name,
-        kind: kind,
+        kind,
         sourceArtifact: sourceArtifact && sourceArtifact !== 'undefined' ? sourceArtifact : null,
         body,
         filePath