peaks-loop 4.0.0-beta.9 → 4.0.3

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

@@ -0,0 +1,253 @@
+// ---------------------------------------------------------------------------
+// Top-level write / dispatch surface for project memory.
+//
+// This module is the orchestrator. It composes the parsers + store +
+// ranking helpers into the four entry points the CLI calls into:
+//
+//   - `createProjectMemoryExtractPlan` / `executeProjectMemoryExtract` —
+//     `peaks memory extract` (artifact → .peaks/memory/<slug>.md).
+//   - `createProjectMemoryBackupPlan` / `executeProjectMemoryBackup` —
+//     `peaks memory backup` (.peaks/memory/ → backup workspace).
+//   - `extractSessionMemories` — session-dir → .peaks/memory/. Used by
+//     `peaks-txt` after a session ends.
+//   - `summarizeProjectMemoryExtractResult` /
+//     `summarizeProjectMemoryBackupResult` — projector to the small
+//     JSON-friendly shape the CLI serializes.
+//
+// Idempotency notes:
+//   - Both extract paths skip writes for slugs that already exist in
+//     `.peaks/memory/`. The original `peaks memory extract --apply` ran
+//     more than once during peaks-code / peaks-txt retries; without this
+//     skip the O_EXCL write throws EEXIST and aborts the whole batch.
+//   - On `--apply`, the index is regenerated whenever the write phase
+//     runs (even if every write was skipped) so the index is always
+//     rebuilt against the current directory.
+// ---------------------------------------------------------------------------
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { isInsidePath, resolveInputPath, stablePath, stableRealPath } from '../../../../shared/path-utils.js';
+import { renderMemoryFile, slugify } from '../parsers/frontmatter.js';
+import { extractStableProjectMemories, summarizeBackupResult, summarizeExtractResult } from '../parsers/markdown-pure.js';
+import { assertInsideProject, assertSafeProjectMemoryDir, assertSafeSessionDir, normalizeRoot, realPathOrThrow } from '../store/paths.js';
+import { assertSafeMemoryFileContent, writeNewFile } from '../store/atomic-write.js';
+import { generateMemoryIndexFile, readStoredMemoryNames } from './ranking.js';
+import { listMarkdownFiles } from './search.js';
+export function createProjectMemoryExtractPlan(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const extractedMemories = options.artifactPaths.flatMap((artifactPath) => {
+        const safeArtifactPath = assertInsideProject(artifactPath, projectRoot);
+        const relativeArtifactPath = relative(projectRoot, safeArtifactPath).replaceAll('\\', '/');
+        return extractStableProjectMemories(readFileSync(safeArtifactPath, 'utf8'), relativeArtifactPath);
+    }).sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
+    const slugCounts = new Map();
+    for (const memory of extractedMemories) {
+        const slug = slugify(memory.title);
+        slugCounts.set(slug, (slugCounts.get(slug) ?? 0) + 1);
+    }
+    const duplicateTitles = [...slugCounts.entries()].filter(([, count]) => count > 1).map(([slug]) => slug);
+    if (duplicateTitles.length > 0) {
+        throw new Error(`Duplicate memory titles are not allowed: ${duplicateTitles.join(', ')}`);
+    }
+    const plannedWrites = extractedMemories.map((memory) => ({
+        memory,
+        filePath: join(primaryMemoryDir, `${slugify(memory.title)}.md`),
+        content: renderMemoryFile(memory)
+    }));
+    return {
+        apply: options.apply ?? false,
+        projectRoot,
+        primaryMemoryDir,
+        backupPolicy: 'project-memory-primary-artifact-backup',
+        extractedMemories,
+        plannedWrites
+    };
+}
+export function executeProjectMemoryExtract(options) {
+    const plan = createProjectMemoryExtractPlan(options);
+    const writtenFiles = [];
+    if (plan.apply) {
+        mkdirSync(plan.primaryMemoryDir, { recursive: true });
+        const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
+        // Idempotency: skip writes for memories whose slug already lives in
+        // .peaks/memory/. Re-running `peaks memory extract --apply` on the
+        // same handoff is a normal peaks-code / peaks-txt retry pattern (the
+        // skill prompt may invoke extract more than once when a handoff is
+        // edited and re-extracted). Without this, writeNewFile's O_EXCL
+        // throws EEXIST and aborts the whole batch. Symmetric with
+        // extractSessionMemories (line ~614) which does the same skip.
+        const existingNames = readStoredMemoryNames(plan.primaryMemoryDir);
+        for (const write of plan.plannedWrites) {
+            const slug = slugify(write.memory.title);
+            if (existingNames.has(slug))
+                continue;
+            const targetPath = resolveInputPath(write.filePath);
+            const stableTargetPath = stablePath(targetPath);
+            if (!isInsidePath(stableTargetPath, stableRealPath(safeMemoryDir))) {
+                throw new Error('Project memory write target must stay inside the project memory directory');
+            }
+            writeNewFile(targetPath, write.content);
+            writtenFiles.push(targetPath);
+        }
+        // After writing any markdown, regenerate the index so downstream
+        // readers (peaks project memory-index, peaks-txt re-runs, the next
+        // session's presence-set bootstrap) see the new memory. Without
+        // this, `peaks memory extract --apply` would leave the index stale
+        // and `readMemoryIndex` would either return the empty bootstrap or
+        // — pre-bootstrap-fix — return null. Symmetric with
+        // extractSessionMemories, which already regenerates the index on
+        // apply (see line ~626). We regen whenever --apply is set, even
+        // if every write was skipped by idempotency, so the index is
+        // always rebuilt against the current .peaks/memory/ directory.
+        const indexPath = join(plan.primaryMemoryDir, 'index.json');
+        generateMemoryIndexFile(plan.projectRoot, plan.primaryMemoryDir, indexPath);
+    }
+    return { ...plan, writtenFiles };
+}
+export function createProjectMemoryBackupPlan(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const artifactWorkspacePath = normalizeRoot(options.artifactWorkspacePath);
+    if (isInsidePath(artifactWorkspacePath, projectRoot)) {
+        throw new Error('Artifact workspace must be outside the project root');
+    }
+    const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const backupMemoryDir = join(artifactWorkspacePath, '.peaks', 'memory-backups', 'project-memory-primary');
+    const plannedCopies = listMarkdownFiles(primaryMemoryDir).map((sourcePath) => {
+        assertSafeMemoryFileContent(readFileSync(sourcePath, 'utf8'));
+        const relativeMemoryPath = relative(primaryMemoryDir, sourcePath);
+        return {
+            sourcePath,
+            targetPath: join(backupMemoryDir, relativeMemoryPath)
+        };
+    });
+    return {
+        apply: options.apply ?? false,
+        projectRoot,
+        artifactWorkspacePath,
+        primaryMemoryDir,
+        backupMemoryDir,
+        plannedCopies
+    };
+}
+export function executeProjectMemoryBackup(options) {
+    const plan = createProjectMemoryBackupPlan(options);
+    const copiedFiles = [];
+    if (plan.apply) {
+        const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
+        mkdirSync(plan.backupMemoryDir, { recursive: true });
+        for (const copy of plan.plannedCopies) {
+            const sourcePath = realPathOrThrow(copy.sourcePath, 'Project memory source must stay inside the project memory directory');
+            if (!isInsidePath(sourcePath, stableRealPath(safeMemoryDir))) {
+                throw new Error('Project memory source must stay inside the project memory directory');
+            }
+            mkdirSync(dirname(copy.targetPath), { recursive: true });
+            copyFileSync(sourcePath, copy.targetPath);
+            copiedFiles.push(copy.targetPath);
+        }
+    }
+    return { ...plan, copiedFiles };
+}
+export function summarizeProjectMemoryExtractResult(result) {
+    return summarizeExtractResult(result);
+}
+export function summarizeProjectMemoryBackupResult(result) {
+    return summarizeBackupResult(result);
+}
+export function extractSessionMemories(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    const apply = options.apply ?? false;
+    const primaryMemoryDir = assertSafeProjectMemoryDir(projectRoot);
+    const memoryIndexPath = join(primaryMemoryDir, 'index.json');
+    // Resolve sessionDir through realpath + inside-project guard so a hostile
+    // sessionId (`..`, abs path, symlink chain) cannot walk the scanner outside
+    // the project root. A sentinel "SESSION_DIR_NOT_FOUND" distinguishes a
+    // benign miss from an escape attempt.
+    let sessionDir;
+    try {
+        sessionDir = assertSafeSessionDir(projectRoot, options.sessionId);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'SESSION_DIR_NOT_FOUND') {
+            return {
+                apply,
+                projectRoot,
+                sessionId: options.sessionId,
+                primaryMemoryDir,
+                memoryIndexPath,
+                scannedFiles: 0,
+                extractedCount: 0,
+                writtenFiles: [],
+                updatedIndex: false
+            };
+        }
+        throw error;
+    }
+    const scannedFiles = listMarkdownFiles(sessionDir, { maxDepth: 6, skipDotfiles: true });
+    const allExtracted = [];
+    for (const filePath of scannedFiles) {
+        try {
+            const content = readFileSync(filePath, 'utf8');
+            const relativePath = relative(projectRoot, filePath).replaceAll('\\', '/');
+            const extracted = extractStableProjectMemories(content, relativePath);
+            allExtracted.push(...extracted);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // skip unreadable files
+        }
+    }
+    if (allExtracted.length === 0) {
+        return {
+            apply,
+            projectRoot,
+            sessionId: options.sessionId,
+            primaryMemoryDir,
+            memoryIndexPath,
+            scannedFiles: scannedFiles.length,
+            extractedCount: 0,
+            writtenFiles: [],
+            updatedIndex: false
+        };
+    }
+    const slugCounts = new Map();
+    for (const memory of allExtracted) {
+        const slug = slugify(memory.title);
+        slugCounts.set(slug, (slugCounts.get(slug) ?? 0) + 1);
+    }
+    const duplicateTitles = [...slugCounts.entries()].filter(([, count]) => count > 1).map(([slug]) => slug);
+    if (duplicateTitles.length > 0) {
+        throw new Error(`Duplicate memory titles are not allowed: ${duplicateTitles.join(', ')}`);
+    }
+    // Idempotency: pre-read existing memory names so a re-run of the same
+    // session does not throw EEXIST. `writtenFiles` reports only the new
+    // writes so callers can still tell what the run actually produced.
+    const existingNames = apply ? readStoredMemoryNames(primaryMemoryDir) : new Set();
+    const writtenFiles = [];
+    if (apply) {
+        mkdirSync(primaryMemoryDir, { recursive: true });
+        for (const memory of allExtracted) {
+            const slug = slugify(memory.title);
+            if (existingNames.has(slug))
+                continue;
+            const targetPath = join(primaryMemoryDir, `${slug}.md`);
+            const safePath = resolveInputPath(targetPath);
+            const stableSafePath = stablePath(safePath);
+            if (!isInsidePath(stableSafePath, stableRealPath(primaryMemoryDir))) {
+                throw new Error('Project memory write target must stay inside the project memory directory');
+            }
+            writeNewFile(safePath, renderMemoryFile(memory));
+            writtenFiles.push(safePath);
+        }
+        generateMemoryIndexFile(projectRoot, primaryMemoryDir, memoryIndexPath);
+    }
+    return {
+        apply,
+        projectRoot,
+        sessionId: options.sessionId,
+        primaryMemoryDir,
+        memoryIndexPath,
+        scannedFiles: scannedFiles.length,
+        extractedCount: allExtracted.length,
+        writtenFiles,
+        updatedIndex: apply && writtenFiles.length > 0
+    };
+}

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

@@ -0,0 +1,6 @@
+import type { MemoryIndex } from '../types.js';
+export declare function readMemoryFileMtime(filePath: string): string;
+export declare function readStoredMemoryNames(memoryDir: string): Set<string>;
+export declare function generateMemoryIndexFile(projectRoot: string, memoryDir: string, indexPath: string): void;
+export declare function readExistingIndex(indexPath: string): MemoryIndex | null;
+export declare function readMemoryIndex(projectRoot: string): MemoryIndex | null;

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

@@ -0,0 +1,171 @@
+// ---------------------------------------------------------------------------
+// Index generation + hot/warm kind dispatch.
+//
+// The memory index is the always-available summary of every memory in
+// `.peaks/memory/`. This module owns its write path:
+//
+//   - `HOT_KINDS` — the kinds whose full body is kept in the index
+//     (`feedback`, `decision`, `rule`, `convention`, `module`, `lesson`).
+//     Anything not in `HOT_KINDS` lands in `warm` with the same shape.
+//   - `readMemoryFileMtime` / `readStoredMemoryNames` — small stat /
+//     filename helpers used by the index generator and by the slug-
+//     collision idempotency check.
+//   - `generateMemoryIndexFile` — rebuild `index.json` from the current
+//     directory contents. Called on every `--apply` extraction.
+//   - `shouldRegenerateIndex` — mtime-based guard: rebuild only when at
+//     least one memory.md has an mtime strictly newer than index.json.
+//   - `readExistingIndex` — best-effort read; returns null on any parse
+//     failure (caller will treat as "no index").
+//   - `readMemoryIndex` — top-level entry point. Decides whether to
+//     regenerate, falls back to whatever is on disk, and bootstraps the
+//     directory + index on first read of a stock project.
+// ---------------------------------------------------------------------------
+import { closeSync, constants, existsSync, openSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseStoredMemoryFile } from '../parsers/frontmatter.js';
+import { summarizeMemoryBody } from '../parsers/markdown-pure.js';
+import { assertSafeProjectMemoryDir, normalizeRoot } from '../store/paths.js';
+import { ensureMemoryBootstrap, listMarkdownFiles, readProjectMemories } from './search.js';
+// Hot kinds: full body kept in index for always-available context
+const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module', 'lesson']);
+export function readMemoryFileMtime(filePath) {
+    try {
+        return statSync(filePath).mtime.toISOString().slice(0, 10);
+    }
+    catch {
+        return new Date().toISOString().slice(0, 10);
+    }
+}
+export function readStoredMemoryNames(memoryDir) {
+    // Two source-of-truth fallbacks for the slug-collision check:
+    //   1. Parse frontmatter (the canonical form rendered by
+    //      renderMemoryFile / written by both extract paths).
+    //   2. Fall back to the bare filename stem, so user-dropped files
+    //      without frontmatter (e.g. hand-written memories, legacy
+    //      content) still count as a collision and are not overwritten
+    //      by an idempotent re-extract.
+    const names = new Set();
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        const stem = basename(filePath, '.md');
+        if (stem.length > 0 && stem !== 'index')
+            names.add(stem);
+        try {
+            const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+            if (parsed)
+                names.add(parsed.name);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // ignore unreadable files
+        }
+    }
+    return names;
+}
+export function generateMemoryIndexFile(projectRoot, memoryDir, indexPath) {
+    const memories = readProjectMemories(projectRoot);
+    const hot = {
+        feedback: [], decision: [], rule: [], convention: [], module: [], lesson: []
+    };
+    const warm = {
+        project: [], reference: []
+    };
+    for (const memory of memories.memories) {
+        const entry = {
+            name: memory.name,
+            kind: memory.kind,
+            description: memory.body ? summarizeMemoryBody(memory.body) : memory.title,
+            sourcePath: memory.filePath,
+            sourceArtifact: memory.sourceArtifact,
+            updatedAt: readMemoryFileMtime(memory.filePath)
+        };
+        if (HOT_KINDS.has(memory.kind)) {
+            hot[memory.kind].push(entry);
+        }
+        else {
+            warm[memory.kind].push(entry);
+        }
+    }
+    for (const kind of [...Object.keys(hot), ...Object.keys(warm)]) {
+        const arr = hot[kind] ?? warm[kind];
+        if (arr)
+            arr.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    const index = {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        hot: hot,
+        warm: warm
+    };
+    const fd = openSync(indexPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC, 0o644);
+    try {
+        writeFileSync(fd, JSON.stringify(index, null, 2), 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readExistingIndex(indexPath) {
+    if (!existsSync(indexPath))
+        return null;
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version === 1)
+            return parsed;
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+// Decide whether readMemoryIndex should rebuild the on-disk index.json.
+// The rule is: rebuild iff index.json is missing OR any memory.md has an
+// mtime strictly greater than index.json's mtime. Any statSync failure
+// falls back to "rebuild" — a safe default that matches the prior
+// always-rebuild behaviour and avoids serving a stale index from a
+// partially-corrupt dir.
+function shouldRegenerateIndex(indexPath, memoryFiles) {
+    let indexMtimeMs = 0;
+    try {
+        indexMtimeMs = statSync(indexPath).mtimeMs;
+    }
+    catch {
+        return true; // no index → must regenerate
+    }
+    for (const memoryPath of memoryFiles) {
+        try {
+            const memoryMtimeMs = statSync(memoryPath).mtimeMs;
+            if (memoryMtimeMs > indexMtimeMs)
+                return true;
+        }
+        catch {
+            return true; // unreadable file → safe default is regenerate
+        }
+    }
+    return false;
+}
+export function readMemoryIndex(projectRoot) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    const indexPath = join(memoryDir, 'index.json');
+    // Read-side bootstrap: if the memory dir is missing entirely, build it and
+    // return whatever index is on disk (likely null on a fresh project). We
+    // deliberately do NOT pre-write an empty index here: the mtime-based
+    // regeneration guard below is the sole authority on whether index.json
+    // gets materialised, and pre-writing an empty index would race the guard
+    // (giving it a current-time mtime that defeats "memory older than index"
+    // detection on the first read).
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+        return readExistingIndex(indexPath);
+    }
+    const files = listMarkdownFiles(memoryDir);
+    if (files.length > 0 && shouldRegenerateIndex(indexPath, files)) {
+        try {
+            generateMemoryIndexFile(normalizedRoot, memoryDir, indexPath);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // fall through to read existing
+        }
+    }
+    return readExistingIndex(indexPath);
+}

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

@@ -0,0 +1,34 @@
+import type { MemoryIndex, ProjectMemoryKind, ProjectMemoryReadResult, ProjectMemoryShowResult, StoredProjectMemory } from '../types.js';
+export declare function listMarkdownFiles(dirPath: string, options?: {
+    maxDepth?: number;
+    skipDotfiles?: boolean;
+}): string[];
+export declare function emptyByKind(): Record<ProjectMemoryKind, StoredProjectMemory[]>;
+export declare function emptyIndex(): MemoryIndex;
+export declare function renderEmptyIndex(): string;
+/**
+ * Ensure `.peaks/memory/` and its `index.json` exist for a project, with
+ * the same full-shape empty index the generator emits when there are zero
+ * memories. Idempotent — safe to call on every skill activation.
+ *
+ * Why this exists: before this helper, `.peaks/memory/` was only created
+ * by `extractSessionMemories` when at least one memory markdown was being
+ * written, and `index.json` was only emitted by the generator when at
+ * least one markdown was on disk. Stock projects therefore had no
+ * `.peaks/memory/` directory and no index, even after `peaks project
+ * memories` was read. Bootstrap closes that cold-start gap.
+ *
+ * This function is fail-open for the same reason the rest of the
+ * presence layer is fail-open: a failure here must NOT block skill
+ * activation. Any error is swallowed and surfaced only via the returned
+ * boolean. Callers that need the truth should check the result.
+ */
+export declare function ensureMemoryBootstrap(projectRoot: string): boolean;
+export declare function readProjectMemories(projectRoot: string): ProjectMemoryReadResult;
+/**
+ * Read a single project memory's full body by name. Returns null when
+ * the memory does not exist. The on-disk body is returned verbatim
+ * (pretty). The CLI layer applies `formatMdCompact` when `format: 'compact'`
+ * is requested. Slice 023 (R3).
+ */
+export declare function readProjectMemoryBody(projectRoot: string, name: string): ProjectMemoryShowResult | null;

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

@@ -0,0 +1,194 @@
+// ---------------------------------------------------------------------------
+// Search / read-side surface for project memories.
+//
+// This module owns the read path: enumerate memory files in
+// `.peaks/memory/`, parse each through the frontmatter parser, bucket by
+// kind, and surface the result. Bootstrap (creating the directory + a
+// full-shape empty index on a stock project) also lives here because the
+// read-side is the first caller that observes the absence.
+//
+// Exported:
+//   - `listMarkdownFiles` — bounded DFS of `.md` files, skipping dotfiles
+//     and symlinks, returning a sorted, repo-relative path list.
+//   - `readProjectMemories` — top-level read. Returns a
+//     `ProjectMemoryReadResult` with memories, total, and `byKind`.
+//   - `readProjectMemoryBody` — single-memory lookup by name; returns
+//     null when the memory does not exist.
+//   - `ensureMemoryBootstrap` — fail-open helper that materialises
+//     `.peaks/memory/` + `index.json` if they are missing. Used by
+//     presence / skill-bootstrap callers and from inside `readMemoryIndex`
+//     when the directory is empty.
+// ---------------------------------------------------------------------------
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseStoredMemoryFile } from '../parsers/frontmatter.js';
+import { assertSafeProjectMemoryDir, normalizeRoot } from '../store/paths.js';
+export function listMarkdownFiles(dirPath, options = {}) {
+    if (!existsSync(dirPath))
+        return [];
+    const { maxDepth = Infinity, skipDotfiles = true } = options;
+    const files = [];
+    const stack = [{ path: dirPath, depth: 0 }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.depth > maxDepth)
+            continue;
+        for (const entry of readdirSync(frame.path, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            if (skipDotfiles && entry.name.startsWith('.'))
+                continue;
+            const entryPath = join(frame.path, entry.name);
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                stack.push({ path: entryPath, depth: frame.depth + 1 });
+                continue;
+            }
+            if (entry.isFile() && entry.name.endsWith('.md')) {
+                files.push(entryPath);
+            }
+        }
+    }
+    return files.sort((left, right) => left.localeCompare(right));
+}
+export function emptyByKind() {
+    return {
+        project: [],
+        rule: [],
+        decision: [],
+        reference: [],
+        feedback: [],
+        convention: [],
+        module: [],
+        lesson: []
+    };
+}
+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.
+    return {
+        version: 1,
+        updatedAt: new Date().toISOString(),
+        hot: {
+            feedback: [],
+            decision: [],
+            rule: [],
+            convention: [],
+            module: [],
+            lesson: []
+        },
+        warm: {
+            project: [],
+            reference: []
+        }
+    };
+}
+export function renderEmptyIndex() {
+    return JSON.stringify(emptyIndex(), null, 2) + '\n';
+}
+/**
+ * Ensure `.peaks/memory/` and its `index.json` exist for a project, with
+ * the same full-shape empty index the generator emits when there are zero
+ * memories. Idempotent — safe to call on every skill activation.
+ *
+ * Why this exists: before this helper, `.peaks/memory/` was only created
+ * by `extractSessionMemories` when at least one memory markdown was being
+ * written, and `index.json` was only emitted by the generator when at
+ * least one markdown was on disk. Stock projects therefore had no
+ * `.peaks/memory/` directory and no index, even after `peaks project
+ * memories` was read. Bootstrap closes that cold-start gap.
+ *
+ * This function is fail-open for the same reason the rest of the
+ * presence layer is fail-open: a failure here must NOT block skill
+ * activation. Any error is swallowed and surfaced only via the returned
+ * boolean. Callers that need the truth should check the result.
+ */
+export function ensureMemoryBootstrap(projectRoot) {
+    try {
+        const normalizedRoot = normalizeRoot(projectRoot);
+        const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+        const indexPath = join(memoryDir, 'index.json');
+        mkdirSync(memoryDir, { recursive: true });
+        if (!existsSync(indexPath)) {
+            writeFileSync(indexPath, renderEmptyIndex(), { mode: 0o644 });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readProjectMemories(projectRoot) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    // Read-side bootstrap: on a stock project the directory does not exist
+    // yet. Reading must not return an error, but we also want the directory
+    // to materialise (along with a full-shape empty index) so subsequent
+    // `peaks project memories` invocations, `readMemoryIndex`, and any
+    // extraction call find a stable target. The helper is fail-open.
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+    }
+    const memories = [];
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+        if (parsed)
+            memories.push(parsed);
+    }
+    memories.sort((left, right) => left.name.localeCompare(right.name));
+    const byKind = emptyByKind();
+    for (const memory of memories) {
+        byKind[memory.kind].push(memory);
+    }
+    return {
+        projectRoot: normalizedRoot,
+        memoryDir,
+        total: memories.length,
+        byKind,
+        memories
+    };
+}
+/**
+ * Read a single project memory's full body by name. Returns null when
+ * the memory does not exist. The on-disk body is returned verbatim
+ * (pretty). The CLI layer applies `formatMdCompact` when `format: 'compact'`
+ * is requested. Slice 023 (R3).
+ */
+export function readProjectMemoryBody(projectRoot, name) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const memoryDir = assertSafeProjectMemoryDir(normalizedRoot);
+    if (!existsSync(memoryDir)) {
+        ensureMemoryBootstrap(normalizedRoot);
+    }
+    for (const filePath of listMarkdownFiles(memoryDir)) {
+        if (basename(filePath, '.md') !== name)
+            continue;
+        const parsed = parseStoredMemoryFile(readFileSync(filePath, 'utf8'), filePath);
+        if (parsed === null)
+            continue;
+        const updatedAt = readMemoryFileMtime(filePath);
+        return {
+            projectRoot: normalizedRoot,
+            memoryDir,
+            name: parsed.name,
+            body: parsed.body,
+            filePath,
+            updatedAt,
+            kind: parsed.kind,
+            title: parsed.title,
+            pretty: true
+        };
+    }
+    return null;
+}
+function readMemoryFileMtime(filePath) {
+    try {
+        return statSync(filePath).mtime.toISOString().slice(0, 10);
+    }
+    catch {
+        return new Date().toISOString().slice(0, 10);
+    }
+}

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

@@ -0,0 +1,9 @@
+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 { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.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 { 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 { createProjectMemoryBackupPlan, createProjectMemoryExtractPlan, executeProjectMemoryBackup, executeProjectMemoryExtract, extractSessionMemories, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from './index/kind-dispatch.js';