peaks-loop 4.0.34 → 4.0.35

package/dist/services/context/memory-preflight-service.js

@@ -3,25 +3,81 @@
  * "Orchestrator Memory Preflight" slice (see
  * docs/superpowers/specs/2026-07-22-orchestrator-memory-preflight-design.md).
  *
+ * Slice 2026-09-09-memory-retrieval (this revision) makes the preflight
+ * task-relevant and tiered:
+ *   - selection is ranked against `taskTitle` with the deterministic fuzzy
+ *     kernel (no network, no embeddings);
+ *   - hot entries (standing rules / feedback) are ALWAYS eligible, ranked
+ *     so the most relevant lead; warm entries (project / reference) are
+ *     gated on relevance and capped well below hot;
+ *   - three independent budgets are enforced — max items, max bytes, and a
+ *     soft wall-clock budget for the selection step;
+ *   - the emitted block stays a compact index (name + path + one-line) so
+ *     the sub-agent drills down with `Read` on demand instead of receiving
+ *     memo bodies wholesale (body inlining is opt-in via `includeBodies`).
+ *
  * Consumes:
  *   - resolveMemoryPreflightConfig (Task 1) — merged defaults + per-project overlay
- *   - MemoryIndexReader (Task 3)            — reads .peaks/memory/index.json + layer=A filter
- *   - MemoryLruCache (Task 2)               — constructed for capacity parity, but NOT used
- *                                            for memo content (see deviation note below)
+ *   - MemoryIndexReader (Task 3)            — reads .peaks/memory/index.json
+ *   - fuzzyMatchWithKey                     — deterministic relevance kernel
  *   - truncateToCap                         — byte-cap truncation of the composed block
  *
- * Deviation from brief — controller-accepted (pre-task 4):
- *   The brief mandated use of `MemoryLruCache` for memo content caching. The
- *   orchestrator dispatch flow only ever has at most a handful of explicit
- *   `cacheMemoContent` calls per task (typically 0-3), and ordering / explicit
- *   invalidation is preferred over LRU eviction by recency. To keep the
- *   semantic obvious and the byte budget check trivial, this implementation
- *   uses a plain `Map<path, body>` for memo path -> body content. The
- *   `MemoryLruCache` class remains as a separate, reusable LRU primitive
- *   (Task 2) and is not consumed by this service.
+ * Fail-soft contract: any selection error returns `available: false` with a
+ * reason; it never throws and never blocks a dispatch.
  */
+import { performance } from 'node:perf_hooks';
+import { fuzzyMatchWithKey } from '../fuzzy-matching/fuzzy-match-service.js';
 import { MemoryIndexReader } from './memory-index-reader.js';
 import { resolveMemoryPreflightConfig, } from './memory-preflight-config.js';
+/** Function words carry no selection signal. */
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'from', 'that', 'this', 'not', 'are', 'was',
+    'but', 'you', 'all', 'any', 'can', 'has', 'its', 'our', 'out', 'use', 'via',
+    'per', 'into', 'when', 'then', 'than', 'they', 'their', 'should', 'must',
+]);
+/**
+ * Tokens shorter than 4 chars are too promiscuous for literal containment
+ * ("add" is a substring of "padding"), so they rank but do not gate.
+ */
+const MIN_TOKEN_LENGTH = 4;
+const CJK_RE = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+function queryTokens(query) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of query.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+        if (raw.length < MIN_TOKEN_LENGTH || STOPWORDS.has(raw) || seen.has(raw))
+            continue;
+        seen.add(raw);
+        out.push(raw);
+    }
+    return out;
+}
+/**
+ * Absolute relevance gate: does the token literally occur in the entry?
+ *
+ * The fuzzy kernel's score is normalized per batch (best match = 1.0), so
+ * it cannot distinguish a strong match from the best of a bad lot — an
+ * absolute check is required for the warm gate. CJK titles have no word
+ * boundaries, so those tokens fall back to 2-char gram overlap.
+ */
+function tokenHits(text, tokens) {
+    let hits = 0;
+    for (const token of tokens) {
+        if (text.includes(token)) {
+            hits += 1;
+            continue;
+        }
+        if (!CJK_RE.test(token))
+            continue;
+        for (let i = 0; i + 2 <= token.length; i += 1) {
+            if (text.includes(token.slice(i, i + 2))) {
+                hits += 1;
+                break;
+            }
+        }
+    }
+    return hits;
+}
 function truncateToCap(text, capBytes) {
     if (Buffer.byteLength(text, 'utf8') <= capBytes) {
         return { text, truncated: false };
@@ -48,44 +104,155 @@ export class MemoryPreflightService {
         }
         this.cachedMemoContents.set(path, content);
     }
-    async fetchBlock(_taskTitle) {
+    async fetchBlock(taskTitle) {
         if (!this.config.enabled)
             return { available: false, reason: 'DISABLED' };
-        const selected = this.reader.selectFeedbackLayerA(this.config.listCap);
-        if (selected.length === 0) {
-            const any = this.reader.loadIfStale();
-            if (any.length === 0)
-                return { available: false, reason: 'MEMORY_INDEX_MISSING' };
-            return { available: false, reason: 'NO_FEEDBACK_LAYER_A' };
+        try {
+            return this.selectAndCompose(taskTitle ?? '');
+        }
+        catch (err) {
+            // Fail-soft: a selection failure must never block a dispatch.
+            return {
+                available: false,
+                reason: `SELECTION_ERROR: ${err.message ?? String(err)}`,
+            };
+        }
+    }
+    selectAndCompose(taskTitle) {
+        const startedAt = performance.now();
+        const tiered = this.reader.selectTiered();
+        if (tiered === null)
+            return { available: false, reason: 'MEMORY_INDEX_MISSING' };
+        // Rank the union once (one fuzzy pass per token over all candidates),
+        // then split by tier — cheaper than ranking each tier separately and
+        // order-preserving for both.
+        const hotSet = new Set(tiered.hot);
+        const tokens = queryTokens(taskTitle);
+        const rankedAll = rankByRelevance(taskTitle, [...tiered.hot, ...tiered.warm]);
+        // Hot is ALWAYS eligible — ranked so the most task-relevant lead, with
+        // unmatched standing rules appended in index order.
+        const hotRanked = rankedAll.filter((r) => hotSet.has(r.entry));
+        const hotSelected = hotRanked.slice(0, this.config.hotItemCap);
+        let timedOut = performance.now() - startedAt >= this.config.selectionTimeBudgetMs;
+        const warmSelected = [];
+        let warmEligibleCount = 0;
+        if (!timedOut && this.config.warmItemCap > 0) {
+            const warmRanked = rankedAll
+                .filter((r) => !hotSet.has(r.entry))
+                .filter((r) => tokenHits(`${r.entry.name} ${r.entry.description}`.toLowerCase(), tokens) >=
+                this.config.warmMinTokenHits);
+            warmEligibleCount = warmRanked.length;
+            for (const candidate of warmRanked) {
+                if (warmSelected.length >= this.config.warmItemCap)
+                    break;
+                if (performance.now() - startedAt >=
+                    this.config.selectionTimeBudgetMs) {
+                    timedOut = true;
+                    break;
+                }
+                warmSelected.push(candidate);
+            }
+        }
+        if (hotSelected.length === 0 && warmSelected.length === 0) {
+            return { available: false, reason: 'NO_RELEVANT_MEMORY' };
+        }
+        const sections = [];
+        if (hotSelected.length > 0) {
+            sections.push('### Standing memory (always applied)');
+            for (const r of hotSelected)
+                sections.push(renderEntry(r.entry));
+        }
+        if (warmSelected.length > 0) {
+            sections.push('### Task-relevant memory (drill down with Read)');
+            for (const r of warmSelected)
+                sections.push(renderEntry(r.entry));
         }
-        const listLines = selected
-            .map((e) => `- * ${e.name}\n    Path: ${e.sourcePath}\n    One-line: ${summarize(e.description)}`)
-            .join('\n');
         let tail = '\n';
         let cachedCount = 0;
-        if (this.cachedMemoContents.size > 0) {
-            const sections = [];
+        if (this.config.includeBodies && this.cachedMemoContents.size > 0) {
+            const bodies = [];
             for (const [path, body] of this.cachedMemoContents) {
-                sections.push(`### ${path}\n\n${body}`);
+                bodies.push(`### ${path}\n\n${body}`);
                 cachedCount += 1;
             }
-            tail = `\n\n## Requested memory details:\n${sections.join('\n\n')}\n`;
+            tail = `\n\n## Requested memory details:\n${bodies.join('\n\n')}\n`;
         }
         const header = '## Project memory relevant to this task\n';
-        const composed = `${header}${listLines}${tail}`;
-        const capBytes = Math.max(64, this.config.maxTokens * 4);
-        const { text, truncated } = truncateToCap(composed, capBytes);
-        const droppedCount = truncated ? selected.length - countItemsInBlock(text) : 0;
+        const composed = `${header}${sections.join('\n')}\n${tail}`;
+        const { text, truncated } = truncateToCap(composed, this.config.maxBytes);
+        const selectedCount = hotSelected.length + warmSelected.length;
+        const droppedByItemCap = hotRanked.length - hotSelected.length + (warmEligibleCount - warmSelected.length);
+        const droppedByBytes = truncated
+            ? Math.max(0, selectedCount - countItemsInBlock(text))
+            : 0;
+        const droppedCount = droppedByItemCap + droppedByBytes;
         return {
             available: true,
             block: text,
-            feedbackListItems: selected.length,
+            feedbackListItems: selectedCount,
             cachedItemCount: cachedCount,
+            hotSelected: hotSelected.length,
+            warmSelected: warmSelected.length,
+            bytesEmitted: Buffer.byteLength(text, 'utf8'),
+            budgetTruncated: truncated || droppedByItemCap > 0 || timedOut,
+            timedOut,
             truncated,
             droppedCount: droppedCount > 0 ? droppedCount : undefined,
         };
     }
 }
+/**
+ * Slice 2026-09-09-memory-retrieval: the query the dispatch site feeds
+ * `fetchBlock`. The bare role ("rd") carries almost no relevance signal,
+ * so the first line of the task brief is appended (truncated) to give the
+ * fuzzy kernel something to rank against. Pure and fail-soft.
+ */
+export function deriveMemoryQuery(role, taskBody) {
+    const firstLine = (taskBody ?? '').split('\n', 1)[0]?.trim() ?? '';
+    const trimmed = firstLine.length > 160 ? firstLine.slice(0, 160) : firstLine;
+    return trimmed === '' ? role : `${role} ${trimmed}`;
+}
+/**
+ * Rank entries against the task title with the deterministic fuzzy kernel.
+ *
+ * The kernel is invoked once PER TOKEN rather than once for the whole
+ * title: a whole-title query is a single fzf subsequence and realistic
+ * task titles match almost nothing that way (measured: 0 warm hits on
+ * the real 131-entry warm tier). Per-token accumulation keeps the kernel
+ * deterministic and gives a graded score — entries matching more task
+ * words, more strongly, rank higher.
+ *
+ * Every entry is returned: matched entries lead by score desc, unmatched
+ * entries follow in index order with score 0 — this is what keeps hot
+ * entries "always eligible". An empty/token-less task title degrades to
+ * index order.
+ */
+function rankByRelevance(query, entries) {
+    if (entries.length === 0)
+        return [];
+    const tokens = queryTokens(query);
+    if (tokens.length === 0) {
+        return entries.map((entry) => ({ entry, score: 0 }));
+    }
+    const accumulated = new Map();
+    for (const token of tokens) {
+        const matches = fuzzyMatchWithKey(token, entries, {
+            keyFn: (e) => `${e.name} ${e.description}`,
+            limit: entries.length,
+            caseSensitive: false,
+        });
+        for (const match of matches) {
+            accumulated.set(match.item, (accumulated.get(match.item) ?? 0) + match.score);
+        }
+    }
+    // Array#sort is stable (ES2019), so equal scores keep index order.
+    return entries
+        .map((entry) => ({ entry, score: accumulated.get(entry) ?? 0 }))
+        .sort((a, b) => b.score - a.score);
+}
+function renderEntry(entry) {
+    return `- * ${entry.name}\n    Path: ${entry.sourcePath}\n    One-line: ${summarize(entry.description)}`;
+}
 function summarize(description) {
     // Drop the <!-- peaks-feedback-promoted: layer=A --> marker, take the next 1 line.
     const cleaned = description.replace(/<!--[^>]*-->/g, '').trim();

package/dist/services/doctor/doctor-service/checks/l3-memory-health.d.ts

@@ -1,6 +1,5 @@
 /**
- * Check: `.peaks/memory/index.json` is well-formed JSON
- * (`L3:l3-memory-health`).
+ * Checks for `.peaks/memory/` health (`L3:l3-memory-health` and siblings).
  *
  * Slice 2026-06-13-repair-pre-existing-test-failures: the
  * production MemoryIndex schema (see
@@ -11,6 +10,24 @@
  *
  * When no `.peaks/memory/index.json` exists yet, the check passes
  * (fresh project — no memories have been extracted).
+ *
+ * Slice 2026-09-09-memory-system-overhaul (D) extends the check with the
+ * drift findings the original version could not see. It used to report
+ * `ok: true` for "index.json is well-formed JSON; 100 hot + 131 warm" and
+ * never looked at coverage, orphans, or unclassified files. It now emits,
+ * in addition to the unchanged well-formed-JSON assertion:
+ *
+ *   - `L3:l3-memory-coverage`      — disk files vs indexed entries (warning
+ *                                    when the gap exceeds a small threshold)
+ *   - `L3:l3-memory-orphans`       — index entries whose `sourcePath` is gone
+ *                                    (error) + disk files absent from the
+ *                                    index (warning)
+ *   - `L3:l3-memory-unclassified`  — files with no resolvable kind (warning,
+ *                                    count + first N names)
+ *
+ * All three are read-only and fail-soft: an inspection error degrades to a
+ * single warning instead of throwing, and none of them change the id or the
+ * `ok` semantics of the original `L3:l3-memory-health` assertion.
  */
 import type { DoctorCheckPlugin } from '../types.js';
 export declare const check: DoctorCheckPlugin;

package/dist/services/doctor/doctor-service/checks/l3-memory-health.js

@@ -1,6 +1,5 @@
 /**
- * Check: `.peaks/memory/index.json` is well-formed JSON
- * (`L3:l3-memory-health`).
+ * Checks for `.peaks/memory/` health (`L3:l3-memory-health` and siblings).
  *
  * Slice 2026-06-13-repair-pre-existing-test-failures: the
  * production MemoryIndex schema (see
@@ -11,12 +10,122 @@
  *
  * When no `.peaks/memory/index.json` exists yet, the check passes
  * (fresh project — no memories have been extracted).
+ *
+ * Slice 2026-09-09-memory-system-overhaul (D) extends the check with the
+ * drift findings the original version could not see. It used to report
+ * `ok: true` for "index.json is well-formed JSON; 100 hot + 131 warm" and
+ * never looked at coverage, orphans, or unclassified files. It now emits,
+ * in addition to the unchanged well-formed-JSON assertion:
+ *
+ *   - `L3:l3-memory-coverage`      — disk files vs indexed entries (warning
+ *                                    when the gap exceeds a small threshold)
+ *   - `L3:l3-memory-orphans`       — index entries whose `sourcePath` is gone
+ *                                    (error) + disk files absent from the
+ *                                    index (warning)
+ *   - `L3:l3-memory-unclassified`  — files with no resolvable kind (warning,
+ *                                    count + first N names)
+ *
+ * All three are read-only and fail-soft: an inspection error degrades to a
+ * single warning instead of throwing, and none of them change the id or the
+ * `ok` semantics of the original `L3:l3-memory-health` assertion.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { getErrorMessage } from 'peaks-loop-shared/result';
+import { listMarkdownFiles, MEMORY_MD_FILENAME, parseMemoryFrontmatter } from '../../../memory/project-memory-service/index.js';
+/** Warn when |disk - indexed| exceeds this. Small enough to catch real drift. */
+const COVERAGE_GAP_WARN_THRESHOLD = 2;
+/** How many offending names to inline before truncating the message. */
+const MAX_NAMES_IN_MESSAGE = 5;
+function countEntries(bucket) {
+    return Object.values(bucket ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
+}
+function previewNames(names) {
+    const shown = names.slice(0, MAX_NAMES_IN_MESSAGE);
+    const suffix = names.length > shown.length ? ` (+${names.length - shown.length} more)` : '';
+    return shown.join(', ') + suffix;
+}
+function readIndexSourcePaths(indexPath) {
+    const parsed = JSON.parse(readFileSync(indexPath, 'utf8'));
+    const fromBucket = (bucket) => Object.values(bucket ?? {}).flatMap((arr) => (Array.isArray(arr) ? arr : []));
+    return [...fromBucket(parsed.hot), ...fromBucket(parsed.warm), ...(parsed.cold ?? [])];
+}
+function inspectDrift(memoryDir, memoryIndexPath, indexedCount) {
+    const checks = [];
+    const diskFiles = listMarkdownFiles(memoryDir).filter((filePath) => basename(filePath) !== MEMORY_MD_FILENAME);
+    // --- coverage ---------------------------------------------------------
+    const gap = diskFiles.length - indexedCount;
+    if (Math.abs(gap) > COVERAGE_GAP_WARN_THRESHOLD) {
+        const direction = gap > 0
+            ? `${gap} file(s) on disk are not in the index`
+            : `${-gap} index entr(ies) have no matching file`;
+        checks.push({
+            id: 'L3:l3-memory-coverage',
+            ok: false,
+            severity: 'warning',
+            message: `Memory index coverage gap: ${diskFiles.length} file(s) on disk vs ${indexedCount} indexed — ${direction}. Run \`peaks memory reindex\` for the full drift report.`
+        });
+    }
+    else {
+        checks.push({
+            id: 'L3:l3-memory-coverage',
+            ok: true,
+            message: `Memory index coverage: ${diskFiles.length} file(s) on disk, ${indexedCount} indexed (within threshold ${COVERAGE_GAP_WARN_THRESHOLD})`
+        });
+    }
+    // --- orphans (both directions) ---------------------------------------
+    const missingSources = readIndexSourcePaths(memoryIndexPath)
+        .filter((entry) => typeof entry.sourcePath !== 'string' || entry.sourcePath.length === 0 || !existsSync(entry.sourcePath))
+        .map((entry) => entry.name ?? entry.sourcePath ?? '<unnamed>')
+        .sort((left, right) => left.localeCompare(right));
+    if (missingSources.length > 0) {
+        checks.push({
+            id: 'L3:l3-memory-orphans',
+            ok: false,
+            severity: 'error',
+            message: `${missingSources.length} index entr(ies) point at a missing sourcePath: ${previewNames(missingSources)}. Run \`peaks memory reindex\` to rebuild the index.`
+        });
+    }
+    else {
+        checks.push({
+            id: 'L3:l3-memory-orphans',
+            ok: true,
+            message: 'No memory index entries point at missing files'
+        });
+    }
+    // --- unclassified -----------------------------------------------------
+    const unclassified = [];
+    for (const filePath of diskFiles) {
+        try {
+            if (parseMemoryFrontmatter(readFileSync(filePath, 'utf8')).kind.kind === null) {
+                unclassified.push(basename(filePath, '.md'));
+            }
+        }
+        catch {
+            unclassified.push(`${basename(filePath, '.md')} (unreadable)`);
+        }
+    }
+    unclassified.sort((left, right) => left.localeCompare(right));
+    if (unclassified.length > 0) {
+        checks.push({
+            id: 'L3:l3-memory-unclassified',
+            ok: false,
+            severity: 'warning',
+            message: `${unclassified.length} memory file(s) have no resolvable kind (no metadata.type / kind / type): ${previewNames(unclassified)}. Add \`metadata.type\` then run \`peaks memory reindex\`.`
+        });
+    }
+    else {
+        checks.push({
+            id: 'L3:l3-memory-unclassified',
+            ok: true,
+            message: 'Every memory file on disk has a resolvable kind'
+        });
+    }
+    return checks;
+}
 function run({ resolvedL3Root }) {
-    const memoryIndexPath = join(resolvedL3Root, '.peaks/memory/index.json');
+    const memoryDir = join(resolvedL3Root, '.peaks/memory');
+    const memoryIndexPath = join(memoryDir, 'index.json');
     if (!existsSync(memoryIndexPath)) {
         return [{
                 id: 'L3:l3-memory-health',
@@ -24,32 +133,47 @@ function run({ resolvedL3Root }) {
                 message: 'No .peaks/memory/index.json yet (no memories extracted)'
             }];
     }
+    let parsed;
     try {
         const raw = readFileSync(memoryIndexPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        const schemaMarker = parsed.schema_version ?? parsed.version;
-        if (schemaMarker === undefined) {
-            return [{
-                    id: 'L3:l3-memory-health',
-                    ok: false,
-                    message: '.peaks/memory/index.json missing schema_version / version field'
-                }];
-        }
-        const hotCount = Object.values(parsed.hot ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
-        const warmCount = Object.values(parsed.warm ?? {}).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0);
+        parsed = JSON.parse(raw);
+    }
+    catch (parseError) {
         return [{
                 id: 'L3:l3-memory-health',
-                ok: true,
-                message: `.peaks/memory/index.json is well-formed JSON; version=${schemaMarker}; ${hotCount} hot + ${warmCount} warm memory entries`
+                ok: false,
+                message: `.peaks/memory/index.json is not valid JSON: ${getErrorMessage(parseError)}`
             }];
     }
-    catch (parseError) {
+    const schemaMarker = parsed.schema_version ?? parsed.version;
+    if (schemaMarker === undefined) {
         return [{
                 id: 'L3:l3-memory-health',
                 ok: false,
-                message: `.peaks/memory/index.json is not valid JSON: ${getErrorMessage(parseError)}`
+                message: '.peaks/memory/index.json missing schema_version / version field'
             }];
     }
+    const hotCount = countEntries(parsed.hot);
+    const warmCount = countEntries(parsed.warm);
+    const checks = [{
+            id: 'L3:l3-memory-health',
+            ok: true,
+            message: `.peaks/memory/index.json is well-formed JSON; version=${schemaMarker}; ${hotCount} hot + ${warmCount} warm memory entries`
+        }];
+    // Drift inspection is best-effort: a scan failure must not turn a
+    // well-formed index into a hard failure.
+    try {
+        checks.push(...inspectDrift(memoryDir, memoryIndexPath, hotCount + warmCount));
+    }
+    catch (error) {
+        checks.push({
+            id: 'L3:l3-memory-coverage',
+            ok: true,
+            severity: 'warning',
+            message: `Memory drift inspection skipped: ${getErrorMessage(error)}`
+        });
+    }
+    return checks;
 }
 export const check = {
     name: 'l3-memory-health',

package/dist/services/job/job-types.d.ts

@@ -6,8 +6,8 @@ export declare const SliceStateSchema: z.ZodObject<{
         pending: "pending";
         blocked: "blocked";
         failed: "failed";
-        skipped: "skipped";
         done: "done";
+        skipped: "skipped";
         "in-progress": "in-progress";
     }>;
     commitSha: z.ZodOptional<z.ZodString>;
@@ -48,8 +48,8 @@ export declare const JobStateSchema: z.ZodObject<{
             pending: "pending";
             blocked: "blocked";
             failed: "failed";
-            skipped: "skipped";
             done: "done";
+            skipped: "skipped";
             "in-progress": "in-progress";
         }>;
         commitSha: z.ZodOptional<z.ZodString>;
@@ -118,8 +118,8 @@ export declare const JobCheckpointInputSchema: z.ZodObject<{
     sliceId: z.ZodString;
     state: z.ZodEnum<{
         failed: "failed";
-        skipped: "skipped";
         done: "done";
+        skipped: "skipped";
     }>;
     commitSha: z.ZodOptional<z.ZodString>;
     reason: z.ZodOptional<z.ZodString>;

package/dist/services/memory/memory-ingest-service.d.ts

@@ -0,0 +1,79 @@
+import type { ProjectMemoryKind } from './project-memory-service/types.js';
+export interface MemoryIngestOptions {
+    projectRoot: string;
+    /** Override the IDE-side source dir (defaults to `~/.claude/projects/<encoded>/memory`). */
+    sourceDir?: string;
+    /** Injectable home dir (tests); defaults to `os.homedir()`. */
+    homeDir?: string;
+    apply?: boolean;
+}
+export interface MemoryIngestImported {
+    name: string;
+    kind: ProjectMemoryKind;
+    sourcePath: string;
+    targetPath: string;
+}
+export interface MemoryIngestSkipped {
+    name: string;
+    sourcePath: string;
+    targetPath: string;
+}
+export interface MemoryIngestConflict {
+    name: string;
+    sourcePath: string;
+    targetPath: string;
+    reason: string;
+}
+export interface MemoryIngestNeedsClassification {
+    name: string;
+    sourcePath: string;
+    rawKind: string | null;
+    reason: string;
+}
+export interface MemoryIngestRefused {
+    name: string;
+    sourcePath: string;
+    reason: string;
+}
+export interface MemoryIngestReport {
+    apply: boolean;
+    projectRoot: string;
+    sourceDir: string;
+    sourceExists: boolean;
+    memoryDir: string;
+    scannedFiles: number;
+    imported: MemoryIngestImported[];
+    skippedIdentical: MemoryIngestSkipped[];
+    conflicts: MemoryIngestConflict[];
+    needsClassification: MemoryIngestNeedsClassification[];
+    refused: MemoryIngestRefused[];
+    writtenFiles: string[];
+    warnings: string[];
+}
+/**
+ * Claude Code encodes a project cwd into its `~/.claude/projects/<name>/`
+ * directory by replacing every non-alphanumeric character with `-`
+ * (`D:\peaks-loop` → `D--peaks-loop`). Separator-agnostic, so the same
+ * encoding holds for POSIX paths.
+ */
+export declare function encodeIdeProjectDir(projectRoot: string): string;
+/** Default IDE-side memory dir for a project: `~/.claude/projects/<encoded>/memory`. */
+export declare function defaultIdeMemoryDir(projectRoot: string, homeDir?: string): string;
+/**
+ * Rewrite a source file's frontmatter to the peaks contract: `name` pinned to
+ * the destination filename stem, and `metadata.type` set to the resolved
+ * kind. Non-contract keys (e.g. `originSessionId`, `modified`, `node_type`)
+ * are preserved verbatim so provenance survives the import; `type` / `kind`
+ * are consumed by the normalization and not duplicated.
+ */
+export declare function renderNormalizedMemory(input: {
+    stem: string;
+    kind: ProjectMemoryKind;
+    frontmatter: string;
+    body: string;
+}): string;
+/**
+ * Import IDE-side memories into `.peaks/memory/`. Always returns the full
+ * envelope; `apply` only controls whether files are actually written.
+ */
+export declare function executeMemoryIngest(options: MemoryIngestOptions): MemoryIngestReport;