peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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

@@ -0,0 +1,817 @@
+import { closeSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { isInsidePath, isWindowsAbsolutePath, normalizePath, resolveInputPath, stablePath, stableRealPath } from '../../shared/path-utils.js';
+import { containsSensitiveConfigValue, isSensitiveConfigPath } from '../config/config-service.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+// Hot kinds: full body kept in index for always-available context
+const HOT_KINDS = new Set(['feedback', 'decision', 'rule', 'convention', 'module', 'lesson']);
+// ---------------------------------------------------------------------------
+// Internal helpers (kept from original, sorted by dependency order)
+// ---------------------------------------------------------------------------
+const START_MARKER = '<!-- peaks-memory:start -->';
+const END_MARKER = '<!-- peaks-memory:end -->';
+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);
+// Length bounds for index entry descriptions. The numbers were chosen when
+// summarizeMemoryBody was first introduced; locking them in as named
+// constants is a doc-as-code move so the truncation rule is no longer
+// "magic". Bump MAX_DESCRIPTION_LENGTH deliberately if downstream UIs grow.
+const MIN_BODY_SENTENCE_LENGTH = 20; // skip fragments shorter than this when picking a leading sentence
+const MAX_DESCRIPTION_LENGTH = 120; // hard cap on description length in the memory index entry
+const ELLIPSIS_RESERVE = 3; // length of the trailing "..." when truncating with an ellipsis
+function normalizeRoot(path) {
+    return resolveInputPath(path);
+}
+function normalizeRealRoot(path) {
+    return stableRealPath(path);
+}
+function realPathOrThrow(path, errorMessage) {
+    if (!existsSync(path)) {
+        throw new Error(errorMessage);
+    }
+    const stats = lstatSync(path);
+    if (stats.isSymbolicLink()) {
+        throw new Error(errorMessage);
+    }
+    return realpathSync(path);
+}
+function resolveProjectPath(path, projectRoot) {
+    if (isWindowsAbsolutePath(path))
+        return normalizePath(path);
+    if (isAbsolute(path))
+        return resolve(path);
+    const resolvedPath = join(projectRoot, path);
+    return isWindowsAbsolutePath(projectRoot) ? normalizePath(resolvedPath) : resolve(resolvedPath);
+}
+function assertInsideProject(path, projectRoot) {
+    const resolvedRoot = normalizeRoot(projectRoot);
+    const resolvedPath = resolveProjectPath(path, resolvedRoot);
+    const realProjectRoot = realPathOrThrow(resolvedRoot, 'Project root is not accessible');
+    const realArtifactPath = realPathOrThrow(resolvedPath, 'Artifact path must stay inside the project root');
+    if (!isInsidePath(realArtifactPath, realProjectRoot)) {
+        throw new Error('Artifact path must stay inside the project root');
+    }
+    return resolvedPath;
+}
+function assertSafeProjectMemoryDir(projectRoot) {
+    const resolvedRoot = normalizeRoot(projectRoot);
+    const realRoot = normalizeRealRoot(projectRoot);
+    const peaksDir = join(resolvedRoot, '.peaks');
+    if (existsSync(peaksDir) && lstatSync(peaksDir).isSymbolicLink()) {
+        throw new Error('Project memory directory must stay inside the project root');
+    }
+    const memoryDir = join(peaksDir, 'memory');
+    if (existsSync(memoryDir)) {
+        if (lstatSync(memoryDir).isSymbolicLink()) {
+            throw new Error('Project memory directory must stay inside the project root');
+        }
+        const realMemoryDir = realpathSync(memoryDir);
+        if (!isInsidePath(realMemoryDir, realRoot)) {
+            throw new Error('Project memory directory must stay inside the project root');
+        }
+        return memoryDir;
+    }
+    return memoryDir;
+}
+function slugify(title) {
+    const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return slug.length > 0 ? slug : 'project-memory';
+}
+function parseBlock(block, sourceArtifact) {
+    const normalizedBlock = block.replace(/\r\n/g, '\n');
+    const separatorIndex = normalizedBlock.indexOf('\n---\n');
+    if (separatorIndex < 0)
+        return null;
+    const header = normalizedBlock.slice(0, separatorIndex).trim();
+    const body = normalizedBlock.slice(separatorIndex + '\n---\n'.length).trim();
+    const fields = new Map();
+    for (const line of header.split('\n')) {
+        const [key, ...valueParts] = line.split(':');
+        const normalizedKey = key?.trim();
+        const value = valueParts.join(':').trim();
+        if (normalizedKey && value) {
+            fields.set(normalizedKey, value);
+        }
+    }
+    const title = fields.get('title')?.trim();
+    const kind = fields.get('kind')?.trim();
+    if (!title || !kind || !VALID_MEMORY_KINDS.has(kind) || body.length === 0)
+        return null;
+    return { title, kind, body, sourceArtifact };
+}
+function hasSensitiveMemoryContent(content) {
+    return /(?:api[_-]?key|token|secret|password|credential|bearer)\s*[:=]/i.test(content)
+        || /\bauthorization\s*:\s*bearer\s+\S+/i.test(content)
+        || /\bbearer\s+[A-Za-z0-9._~+/=-]{12,}\b/i.test(content)
+        || /\bsk-[A-Za-z0-9_-]{6,}\b/.test(content)
+        || /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/.test(content)
+        || /\bgithub_pat_[A-Za-z0-9_]{20,}\b/.test(content)
+        || /\bglpat-[A-Za-z0-9_-]{20,}\b/.test(content)
+        || /\bAKIA[0-9A-Z]{16}\b/.test(content)
+        || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(content)
+        || /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/.test(content);
+}
+function assertSafeMemory(memory) {
+    const content = `${memory.title}\n${memory.kind}\n${memory.body}`;
+    const metadata = { title: memory.title, kind: memory.kind, body: memory.body };
+    if (containsSensitiveConfigValue(metadata) || hasSensitiveMemoryContent(content)) {
+        throw new Error('Refusing to store sensitive memory content');
+    }
+    if (isSensitiveConfigPath(memory.title)) {
+        throw new Error('Refusing to store sensitive memory content');
+    }
+}
+function assertSafeMemoryFileContent(content) {
+    if (hasSensitiveMemoryContent(content)) {
+        throw new Error('Refusing to back up sensitive memory content');
+    }
+}
+function writeNewFile(path, content) {
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        writeFileSync(fd, content, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function renderMemoryFile(memory) {
+    const name = slugify(memory.title);
+    return [
+        '---',
+        `name: ${name}`,
+        `description: ${memory.title}`,
+        'metadata:',
+        `  type: ${memory.kind}`,
+        `  sourceArtifact: ${memory.sourceArtifact}`,
+        '---',
+        '',
+        memory.body,
+        ''
+    ].join('\n');
+}
+function parseStoredMemoryFile(content, filePath) {
+    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();
+    let name;
+    let description;
+    let kind;
+    let sourceArtifact;
+    for (const rawLine of frontmatter.split('\n')) {
+        const line = rawLine.trim();
+        if (line.startsWith('name:'))
+            name = line.slice('name:'.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('sourceArtifact:'))
+            sourceArtifact = line.slice('sourceArtifact:'.length).trim();
+    }
+    if (!name || !kind || !VALID_MEMORY_KINDS.has(kind) || body.length === 0)
+        return null;
+    return {
+        name,
+        title: description ?? name,
+        kind: kind,
+        sourceArtifact: sourceArtifact && sourceArtifact !== 'undefined' ? sourceArtifact : null,
+        body,
+        filePath
+    };
+}
+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));
+}
+// ---------------------------------------------------------------------------
+// Description summarization (deterministic, no LLM call)
+// ---------------------------------------------------------------------------
+function summarizeMemoryBody(body) {
+    const cleaned = body
+        .replace(/^#{1,6}\s+/gm, '')
+        .replace(/`{1,3}[^`]*`{1,3}/g, '')
+        .replace(/^\s*[-*+]\s+/gm, '')
+        .replace(/\n+/g, ' ')
+        .trim();
+    const sentences = cleaned.split(/(?<=[.!?])\s+/).filter((s) => s.length > MIN_BODY_SENTENCE_LENGTH && !/^\[.+\]$/.test(s));
+    if (sentences.length === 0) {
+        return cleaned.slice(0, MAX_DESCRIPTION_LENGTH) || 'Project memory';
+    }
+    const first = sentences[0];
+    if (first.length <= MAX_DESCRIPTION_LENGTH) {
+        return first;
+    }
+    return first.slice(0, MAX_DESCRIPTION_LENGTH - ELLIPSIS_RESERVE) + '...';
+}
+// ---------------------------------------------------------------------------
+// Session memory extraction (new extract path)
+// ---------------------------------------------------------------------------
+function assertSafeSessionDir(projectRoot, sessionId) {
+    const normalizedRoot = normalizeRoot(projectRoot);
+    const realRoot = normalizeRealRoot(projectRoot);
+    const sessionDir = getSessionDir(normalizedRoot, sessionId);
+    if (!existsSync(sessionDir)) {
+        // Distinguish "not found" (caller will treat as no-op) from "escapes project
+        // root" (caller must surface a hard error). We probe by checking whether the
+        // joined path, after realpath, would still be inside the project root.
+        if (isAbsolute(getSessionDir(normalizedRoot, sessionId))) {
+            const realJoined = safeRealpath(getSessionDir(normalizedRoot, sessionId));
+            if (realJoined && !isInsidePath(realJoined, realRoot)) {
+                throw new Error('Session directory must stay inside the project root');
+            }
+        }
+        throw new Error('SESSION_DIR_NOT_FOUND');
+    }
+    const stats = lstatSync(sessionDir);
+    if (stats.isSymbolicLink()) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    const realSessionDir = realpathSync(sessionDir);
+    if (!isInsidePath(realSessionDir, realRoot)) {
+        throw new Error('Session directory must stay inside the project root');
+    }
+    return sessionDir;
+}
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function readMemoryFileMtime(filePath) {
+    try {
+        return statSync(filePath).mtime.toISOString().slice(0, 10);
+    }
+    catch {
+        return new Date().toISOString().slice(0, 10);
+    }
+}
+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;
+}
+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);
+    }
+}
+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);
+}
+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
+    };
+}
+// ---------------------------------------------------------------------------
+// Old extract path (kept for core-artifact-commands.ts)
+// ---------------------------------------------------------------------------
+export function extractStableProjectMemories(content, sourceArtifact) {
+    const memories = [];
+    let searchStart = 0;
+    while (searchStart < content.length) {
+        const start = content.indexOf(START_MARKER, searchStart);
+        if (start < 0)
+            break;
+        const bodyStart = start + START_MARKER.length;
+        const end = content.indexOf(END_MARKER, bodyStart);
+        if (end < 0)
+            break;
+        const memory = parseBlock(content.slice(bodyStart, end).trim(), sourceArtifact);
+        if (memory) {
+            assertSafeMemory(memory);
+            memories.push(memory);
+        }
+        searchStart = end + END_MARKER.length;
+    }
+    return memories.sort((left, right) => slugify(left.title).localeCompare(slugify(right.title)));
+}
+function summarizeExtractResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupPolicy: result.backupPolicy,
+        extractedCount: result.extractedMemories.length,
+        plannedWrites: result.plannedWrites.map((write) => ({
+            filePath: write.filePath,
+            title: write.memory.title,
+            kind: write.memory.kind,
+            sourceArtifact: write.memory.sourceArtifact
+        })),
+        writtenFiles: result.writtenFiles
+    };
+}
+function summarizeBackupResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        artifactWorkspacePath: result.artifactWorkspacePath,
+        primaryMemoryDir: result.primaryMemoryDir,
+        backupMemoryDir: result.backupMemoryDir,
+        plannedCopies: result.plannedCopies,
+        copiedFiles: result.copiedFiles
+    };
+}
+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);
+}
+function emptyByKind() {
+    return {
+        project: [],
+        rule: [],
+        decision: [],
+        reference: [],
+        feedback: [],
+        convention: [],
+        module: [],
+        lesson: []
+    };
+}
+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: []
+        }
+    };
+}
+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;
+}