peaks-loop 4.0.34 → 4.0.35

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 4.0.35 — 2026-09-10 (记忆系统 overhaul — 写入合一 / 索引重建 / 按任务调取 / 漂移健康检查 / rotate)
+
+**Highlights**:
+
+1. **记忆写入单一权威** — `peaks memory ingest` 把 IDE 侧（Claude Code）记忆导入 `.peaks/memory/`，源目录只读、**绝不写 `~/.claude/`**；SKILL.md 明确：工作流内"沉淀记忆"落 `.peaks/memory/`，IDE 侧仅作会话笔记。
+
+2. **索引重建 + 根因修复** — `peaks memory reindex` 全量重扫并重建 `index.json`。**根因**：共享 frontmatter 解析器只认顶层 `type:`，按契约写 `metadata.type` 的文件被**静默丢弃**。现按 `metadata.type → kind → type` 解析，未识别值**输出清单**而非静默跳过。name 解析新增 `name → title → 文件名` 回退；重名冲突上报不覆盖。本仓库实测：索引 **231 → 276**。
+
+3. **调取按任务 + 分层预算** — preflight 此前 `fetchBlock(_taskTitle)` 的 `taskTitle` **完全未使用**，永远注入同一批 feedback+layerA。现按任务排序（per-token fuzzy，无网络/无 embedding），hot 必进、warm 按相关度入选，三重预算（条数/字节/时间）+ 可观测字段。warm 层首次可被注入。顺带修：读取器原来只扁平化 4 种 kind，丢了 decision/rule/convention/module/lesson。
+
+4. **kind 词表 8 → 21** — 纳入语料中实际使用的 13 个 kind（`bug`/`investigation`/`technical-pattern`/`project-rule`/`design`/`handoff`/`session-handoff`/`project-todo`/`publish-closure`/`project-closure`/`slice-closure`/`slice-pilot-findings`/`sediment`），单一常量驱动解析/索引/CLI/doctor。
+
+5. **`peaks memory rotate`（清除机制）** — 实现 2026-07-24 pruning policy 早已规定但从未实现的轮转：A/B 层永不入选（测试断言）、C 层满 **6 个月**且未被钉住 → 归档、D 层 → 报告待删（不删）、每个候选先过 `src/`+`skills/` 引用 grep。默认 dry-run。
+
+6. **doctor 漂移检查** — 新增 `l3-memory-coverage` / `l3-memory-orphans` / `l3-memory-unclassified`；此前只校验"index.json 是合法 JSON"，46% 不可见也报 ok。
+
+**验证**：build clean、tsc clean、全量 133 files / 1180 passed（1 skipped）；本仓库 rotate dry-run `A:22 B:146 C:138 D:12`。
+
 ## 4.0.34 — 2026-09-09 (mode 模型收敛 + auto-compact 死命令 + 上下文窗口覆盖 + 确认门去 TTY)
 
 **Highlights**:

package/dist/cli/commands/core/memory-command.js

@@ -1,6 +1,8 @@
-import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../../services/memory/project-memory-service.js';
+import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult, VALID_PROJECT_MEMORY_KINDS } from '../../../services/memory/project-memory-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+/** Derived from the canonical kind vocabulary — never hand-maintain a list here. */
+const KIND_HELP = VALID_PROJECT_MEMORY_KINDS.join(', ');
 export function registerMemoryCommand(program, io) {
     const memory = program.command('memory').description('Manage project-local Peaks memory');
     addJsonOption(memory
@@ -48,7 +50,7 @@ export function registerMemoryCommand(program, io) {
     addJsonOption(memory
         .command('list')
         .description('List all memory entries from .peaks/memory/index.json. Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/memory/picked.json.')
-        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)
         .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
         .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
         .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
@@ -72,10 +74,66 @@ export function registerMemoryCommand(program, io) {
                 process.exitCode = 1;
         });
     });
+    addJsonOption(memory
+        .command('reindex')
+        .description('Rebuild .peaks/memory/index.json from every memory file on disk and regenerate MEMORY.md; reports unclassified files and orphans both ways. Dry-run by default; pass --apply to write.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--dry-run', 'report drift without writing (default)')
+        .option('--apply', 'rebuild index.json and regenerate MEMORY.md')).action((options) => {
+        void import('../memory-commands.js').then(({ runMemoryReindex }) => {
+            void runMemoryReindex(io, {
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+                ...(options.apply === true ? { apply: true } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            printResult(io, fail('memory.reindex', 'MEMORY_REINDEX_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        });
+    });
+    addJsonOption(memory
+        .command('ingest')
+        .description('Import memories written by the IDE-side agent (~/.claude/projects/<hash>/memory/*.md) into the peaks-owned .peaks/memory store. The IDE-side dir is read-only. Dry-run by default; pass --apply to write.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--source-dir <path>', 'override the IDE-side memory directory')
+        .option('--dry-run', 'preview imports without writing (default)')
+        .option('--apply', 'write normalized memories into .peaks/memory')).action((options) => {
+        void import('../memory-commands.js').then(({ runMemoryIngest }) => {
+            void runMemoryIngest(io, {
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.sourceDir !== undefined ? { sourceDir: options.sourceDir } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+                ...(options.apply === true ? { apply: true } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            printResult(io, fail('memory.ingest', 'MEMORY_INGEST_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        });
+    });
+    addJsonOption(memory
+        .command('rotate')
+        .description('Tier-driven retention for .peaks/memory/ (sediment pruning policy, tier 1: archive only, never delete). Tier assignment: explicit `metadata.tier: A|B|C|D` wins; else files under archived/ are D, files pinned in MEMORY.md are B, kinds rule/convention/project-rule are A, kinds decision/reference/feedback/module/bug/investigation/technical-pattern are B, everything else is C. Tier C older than 6 months (frontmatter updatedAt/updated/modified, else file mtime) and not pinned is archived; tier D is reported as a delete-candidate only. Tier A/B are never selected, every candidate must pass a reference grep against src/ + skills/, and --apply refuses an empty plan or a failed gate. Dry-run by default.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--dry-run', 'report the rotation plan without moving anything (default)')
+        .option('--apply', 'move tier-C candidates into .peaks/memory/archived/')).action((options) => {
+        void import('../memory-commands.js').then(({ runMemoryRotate }) => {
+            void runMemoryRotate(io, {
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+                ...(options.apply === true ? { apply: true } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            printResult(io, fail('memory.rotate', 'MEMORY_ROTATE_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        });
+    });
     addJsonOption(memory
         .command('search <query>')
         .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6.')
-        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)
         .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
         .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
         // Lazy import avoids a top-of-file import cycle (memory-commands.ts

package/dist/cli/commands/dispatch-commands.js

@@ -36,7 +36,7 @@ import { writeLogEntry } from '../../services/log/logger.js';
 import { PROMPT_LIMIT_BYTES, RECOMMENDED_ROLES, validateRole } from './sub-agent-shared.js';
 import { runDispatchFromDag } from './dispatch-from-dag.js';
 import { TEST_TOOL_DETECTION_BLOCK, formatTestToolDetection } from '../../services/dispatch/test-tool-detection.js';
-import { MemoryPreflightService } from '../../services/context/memory-preflight-service.js';
+import { MemoryPreflightService, deriveMemoryQuery } from '../../services/context/memory-preflight-service.js';
 import { buildDispatchSystemPrompt } from '../../services/context/build-dispatch-system-prompt.js';
 import { computeUiLibraryDispatchBlock } from '../../services/standards/ui-library-dispatch-block.js';
 import { readFreshContextBlock } from '../../services/fresh-context/fresh-context-block.js';
@@ -373,7 +373,9 @@ export function registerDispatchCommand(parent, io) {
             // memory preflight block (or silently skip when unavailable) via the
             // pure-function builder.
             const preflightService = new MemoryPreflightService(projectRoot, projectPrefs);
-            const memoryBlock = await preflightService.fetchBlock(role);
+            // Slice 2026-09-09-memory-retrieval: rank the injected memory by the
+            // task at hand (role + first line of the brief), not the bare role.
+            const memoryBlock = await preflightService.fetchBlock(deriveMemoryQuery(role, options.prompt));
             // Slice 2026-09-03-codegraph-preread (Option A): pre-dispatch
             // codegraph preflight for RD planning. BEFORE the RD sub-agent's
             // prompt is composed, ensure the codegraph index exists (init +

package/dist/cli/commands/memory-commands.d.ts

@@ -13,9 +13,44 @@ export interface MemoryListCommandOptions {
     project?: string;
     json?: boolean;
 }
+export interface MemoryReindexCommandOptions {
+    project?: string;
+    dryRun?: boolean;
+    apply?: boolean;
+    json?: boolean;
+}
+export interface MemoryIngestCommandOptions {
+    project?: string;
+    sourceDir?: string;
+    dryRun?: boolean;
+    apply?: boolean;
+    json?: boolean;
+}
+export interface MemoryRotateCommandOptions {
+    project?: string;
+    dryRun?: boolean;
+    apply?: boolean;
+    json?: boolean;
+}
 export declare function runMemoryList(io: ProgramIO, options: MemoryListCommandOptions): Promise<void>;
 /**
  * Run the memory search subcommand. Extracted so unit tests can
  * exercise the full envelope without spawning a subprocess.
  */
 export declare function runMemorySearch(io: ProgramIO, options: MemorySearchCommandOptions): Promise<void>;
+/**
+ * `peaks memory reindex` — rebuild `.peaks/memory/index.json` from disk and
+ * regenerate `MEMORY.md`. Dry-run by default; `--apply` writes.
+ */
+export declare function runMemoryReindex(io: ProgramIO, options: MemoryReindexCommandOptions): Promise<void>;
+/**
+ * `peaks memory rotate` — tier-driven retention for `.peaks/memory/`.
+ * Implements the sediment pruning policy (tier 1: archive, never delete).
+ * Dry-run by default; `--apply` moves tier-C candidates into `archived/`.
+ */
+export declare function runMemoryRotate(io: ProgramIO, options: MemoryRotateCommandOptions): Promise<void>;
+/**
+ * `peaks memory ingest` — import memories written by the IDE-side agent into
+ * `.peaks/memory/`. The IDE-side source is read-only; dry-run by default.
+ */
+export declare function runMemoryIngest(io: ProgramIO, options: MemoryIngestCommandOptions): Promise<void>;

package/dist/cli/commands/memory-commands.js

@@ -1,20 +1,19 @@
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { loadMemoryIndex, searchMemory } from '../../services/memory/memory-search-service.js';
+import { executeMemoryReindex, VALID_PROJECT_MEMORY_KINDS } from '../../services/memory/project-memory-service.js';
+import { executeMemoryIngest } from '../../services/memory/memory-ingest-service.js';
+import { executeMemoryRotate } from '../../services/memory/memory-rotate-service.js';
 import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { getErrorMessage, printResult } from '../cli-helpers.js';
 import { join } from 'node:path';
-const VALID_KINDS = [
-    'project',
-    'rule',
-    'decision',
-    'reference',
-    'feedback',
-    'convention',
-    'module',
-    'lesson',
-];
+const VALID_KINDS = VALID_PROJECT_MEMORY_KINDS;
+function resolveMemoryProjectRoot(project) {
+    return project !== undefined
+        ? resolveCanonicalProjectRoot(project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+}
 export async function runMemoryList(io, options) {
     const projectRoot = options.project !== undefined
         ? resolveCanonicalProjectRoot(options.project)
@@ -124,3 +123,113 @@ export async function runMemorySearch(io, options) {
         process.exitCode = 1;
     }
 }
+/**
+ * `peaks memory reindex` — rebuild `.peaks/memory/index.json` from disk and
+ * regenerate `MEMORY.md`. Dry-run by default; `--apply` writes.
+ */
+export async function runMemoryReindex(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('memory.reindex', 'INVALID_MEMORY_REINDEX_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview the drift report, or pass --apply to rebuild']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const report = executeMemoryReindex({ projectRoot, apply: options.apply === true });
+        const nextActions = [];
+        if (options.apply !== true) {
+            nextActions.push('Preview only — re-run with --apply to rebuild index.json and regenerate MEMORY.md.');
+        }
+        if (report.unclassified.length > 0) {
+            nextActions.push(`${report.unclassified.length} file(s) have no resolvable kind; add \`metadata.type\` (or \`kind:\`) to index them.`);
+        }
+        if (report.orphanIndex.length > 0) {
+            nextActions.push(`${report.orphanIndex.length} previous index entry(ies) point at missing files; they are dropped from the rebuilt index.`);
+        }
+        if (report.nameConflicts.length > 0) {
+            nextActions.push(`${report.nameConflicts.length} name collision(s) across files; both entries are kept — rename one file to disambiguate.`);
+        }
+        printResult(io, ok('memory.reindex', report, [], nextActions), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_REINDEX_FAILED';
+        printResult(io, fail('memory.reindex', code, message, { projectRoot }, ['Check that the project has a readable .peaks/memory directory']), options.json);
+        process.exitCode = 1;
+    }
+}
+/**
+ * `peaks memory rotate` — tier-driven retention for `.peaks/memory/`.
+ * Implements the sediment pruning policy (tier 1: archive, never delete).
+ * Dry-run by default; `--apply` moves tier-C candidates into `archived/`.
+ */
+export async function runMemoryRotate(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('memory.rotate', 'INVALID_MEMORY_ROTATE_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview the rotation plan, or pass --apply to archive tier-C candidates']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const report = executeMemoryRotate({ projectRoot, apply: options.apply === true });
+        const nextActions = [];
+        if (report.refused) {
+            nextActions.push(`Refused to apply: ${report.refusalReasons.join('; ')}`);
+        }
+        else if (options.apply !== true) {
+            nextActions.push('Preview only — re-run with --apply to move the tier-C candidates into archived/.');
+        }
+        if (report.excluded.length > 0) {
+            nextActions.push(`${report.excluded.length} candidate(s) excluded by a safety gate (see \`excluded\`).`);
+        }
+        const deleteCandidates = report.candidates.filter((candidate) => candidate.action === 'delete-candidate');
+        if (deleteCandidates.length > 0) {
+            nextActions.push(`${deleteCandidates.length} tier-D file(s) are delete-candidates only; peaks never deletes them — remove by hand if you are sure.`);
+        }
+        printResult(io, ok('memory.rotate', report, report.warnings, nextActions), options.json);
+        if (report.refused)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_ROTATE_FAILED';
+        printResult(io, fail('memory.rotate', code, message, { projectRoot }, ['Check that the project has a readable .peaks/memory directory']), options.json);
+        process.exitCode = 1;
+    }
+}
+/**
+ * `peaks memory ingest` — import memories written by the IDE-side agent into
+ * `.peaks/memory/`. The IDE-side source is read-only; dry-run by default.
+ */
+export async function runMemoryIngest(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('memory.ingest', 'INVALID_MEMORY_INGEST_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview imports, or pass --apply to write them into .peaks/memory']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const report = executeMemoryIngest({
+            projectRoot,
+            ...(options.sourceDir !== undefined ? { sourceDir: options.sourceDir } : {}),
+            apply: options.apply === true
+        });
+        const nextActions = [];
+        if (options.apply !== true && report.imported.length > 0) {
+            nextActions.push('Preview only — re-run with --apply to write these memories into .peaks/memory.');
+        }
+        if (report.conflicts.length > 0) {
+            nextActions.push(`${report.conflicts.length} conflict(s) left both copies in place; resolve them by hand.`);
+        }
+        if (report.needsClassification.length > 0) {
+            nextActions.push(`${report.needsClassification.length} file(s) could not be classified; add \`metadata.type\` to the source before re-running.`);
+        }
+        printResult(io, ok('memory.ingest', report, report.warnings, nextActions), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_INGEST_FAILED';
+        printResult(io, fail('memory.ingest', code, message, { projectRoot }, ['Check the --source-dir path and that .peaks/memory is writable']), options.json);
+        process.exitCode = 1;
+    }
+}

package/dist/services/context/context-schema.d.ts

@@ -13,8 +13,8 @@ export declare const ContextJsonSchema: z.ZodObject<{
             path: z.ZodString;
             kind: z.ZodEnum<{
                 doc: "doc";
-                config: "config";
                 source: "source";
+                config: "config";
                 test: "test";
             }>;
             lines: z.ZodNumber;

package/dist/services/context/memory-index-reader.d.ts

@@ -1,8 +1,34 @@
 import type { MemoryIndexEntry } from '../memory/memory-search-service.js';
+/**
+ * Slice 2026-09-09-memory-retrieval: the two tiers the orchestrator
+ * preflight ranks over.
+ *
+ * - `hot`  — standing rules / feedback / decisions. Always eligible.
+ * - `warm` — project / reference memos. Injected only on task relevance.
+ *
+ * `cold` is deep storage and is deliberately NOT surfaced here.
+ */
+export interface MemoryTieredSelection {
+    hot: MemoryIndexEntry[];
+    warm: MemoryIndexEntry[];
+}
 export declare class MemoryIndexReader {
     private readonly projectRoot;
     private cache;
     constructor(projectRoot: string);
+    /**
+     * Flatten the whole index (all tiers, all buckets). Kept for
+     * back-compat with the pre-2026-09-09 callers.
+     */
     loadIfStale(): MemoryIndexEntry[];
+    /**
+     * Slice 2026-09-09-memory-retrieval: read the index as tiers.
+     *
+     * Returns `null` when `.peaks/memory/index.json` is absent or
+     * unreadable — the caller distinguishes "no index" from "index with
+     * zero entries" for its fail-soft reason code. Never throws.
+     */
+    selectTiered(): MemoryTieredSelection | null;
     selectFeedbackLayerA(cap: number): MemoryIndexEntry[];
+    private loadSnapshot;
 }

package/dist/services/context/memory-index-reader.js

@@ -7,24 +7,25 @@ export class MemoryIndexReader {
     constructor(projectRoot) {
         this.projectRoot = projectRoot;
     }
+    /**
+     * Flatten the whole index (all tiers, all buckets). Kept for
+     * back-compat with the pre-2026-09-09 callers.
+     */
     loadIfStale() {
-        const indexPath = join(this.projectRoot, '.peaks', 'memory', 'index.json');
-        if (!existsSync(indexPath))
-            return [];
-        const { mtimeMs } = statSync(indexPath);
-        if (this.cache && this.cache.mtimeMs === mtimeMs)
-            return this.cache.entries;
-        let raw;
-        try {
-            raw = JSON.parse(readFileSync(indexPath, 'utf8'));
-        }
-        catch {
-            this.cache = null;
-            return [];
-        }
-        const entries = flattenIndex(raw);
-        this.cache = { mtimeMs, entries };
-        return entries;
+        return this.loadSnapshot()?.entries ?? [];
+    }
+    /**
+     * Slice 2026-09-09-memory-retrieval: read the index as tiers.
+     *
+     * Returns `null` when `.peaks/memory/index.json` is absent or
+     * unreadable — the caller distinguishes "no index" from "index with
+     * zero entries" for its fail-soft reason code. Never throws.
+     */
+    selectTiered() {
+        const snapshot = this.loadSnapshot();
+        if (snapshot === null)
+            return null;
+        return snapshot.tiers;
     }
     selectFeedbackLayerA(cap) {
         const all = this.loadIfStale();
@@ -33,24 +34,55 @@ export class MemoryIndexReader {
             .filter((e) => LAYER_A_RE.test(e.description))
             .slice(0, Math.max(1, Math.trunc(cap)));
     }
+    loadSnapshot() {
+        const indexPath = join(this.projectRoot, '.peaks', 'memory', 'index.json');
+        try {
+            if (!existsSync(indexPath))
+                return null;
+            const { mtimeMs } = statSync(indexPath);
+            if (this.cache && this.cache.mtimeMs === mtimeMs)
+                return this.cache;
+            const raw = JSON.parse(readFileSync(indexPath, 'utf8'));
+            const tiers = {
+                hot: flattenBucket(raw, 'hot'),
+                warm: flattenBucket(raw, 'warm'),
+            };
+            const entries = [
+                ...tiers.hot,
+                ...tiers.warm,
+                ...flattenBucket(raw, 'cold'),
+            ];
+            this.cache = { mtimeMs, entries, tiers };
+            return this.cache;
+        }
+        catch {
+            // Fail-soft: a missing / unreadable / malformed index degrades to
+            // "no memory available" rather than throwing into a dispatch.
+            this.cache = null;
+            return null;
+        }
+    }
 }
-function flattenIndex(raw) {
+function bucketOf(raw, layer) {
     if (!raw || typeof raw !== 'object')
+        return null;
+    const bucket = raw[layer];
+    return bucket && typeof bucket === 'object'
+        ? bucket
+        : null;
+}
+function flattenBucket(raw, layer) {
+    const bucket = bucketOf(raw, layer);
+    if (!bucket)
         return [];
     const out = [];
-    const obj = raw;
-    for (const layer of ['hot', 'warm', 'cold']) {
-        const bucket = obj[layer];
-        if (!bucket || typeof bucket !== 'object')
+    for (const key of Object.keys(bucket)) {
+        const list = bucket[key];
+        if (!Array.isArray(list))
             continue;
-        for (const k of ['feedback', 'project', 'reference', 'user']) {
-            const list = bucket[k];
-            if (!Array.isArray(list))
-                continue;
-            for (const item of list) {
-                if (item && typeof item === 'object')
-                    out.push(item);
-            }
+        for (const item of list) {
+            if (item && typeof item === 'object')
+                out.push(item);
         }
     }
     return out;

package/dist/services/context/memory-preflight-config.d.ts

@@ -1,9 +1,42 @@
 import type { ProjectPreferences } from '../preferences/preferences-types.js';
 export interface MemoryPreflightConfig {
     readonly enabled: boolean;
+    /**
+     * Back-compat (slice 2026-07-22): the original single budget knob.
+     * Semantics are unchanged — it is the *token* cap, converted to bytes
+     * as `maxTokens * 4` when `maxBytes` is not set. Do NOT drop this key:
+     * existing `.peaks/preferences.json` files set it.
+     */
     readonly maxTokens: number;
+    /** Back-compat: hot-tier item cap fallback when `hotItemCap` is absent. */
     readonly listCap: number;
     readonly contentCacheBytes: number;
+    /** Hard byte cap on the composed block. Defaults to `maxTokens * 4`. */
+    readonly maxBytes: number;
+    /** Max hot (standing rule / feedback) items injected. Default 10. */
+    readonly hotItemCap: number;
+    /** Max warm (project / reference) items injected; 0 disables warm. Default 4. */
+    readonly warmItemCap: number;
+    /**
+     * Warm relevance gate: minimum number of distinct task-title tokens
+     * (length >= 4, stopwords removed) that must literally occur in the memo
+     * text before it is warm-eligible. 1 (default) means "at least one task
+     * word appears in the memo"; raise it to tighten the gate. Hot entries
+     * ignore this gate — they are always eligible.
+     */
+    readonly warmMinTokenHits: number;
+    /**
+     * Soft wall-clock budget (ms) for the whole selection step. When exceeded
+     * the preflight degrades to hot-only (or unranked hot) rather than
+     * blocking a dispatch. 0 forces the hot-only path deterministically.
+     */
+    readonly selectionTimeBudgetMs: number;
+    /**
+     * Gate for inlining memo *bodies* (via `cacheMemoContent`). Off by
+     * default: the preflight emits a compact index and the sub-agent drills
+     * down with `Read` against `sourcePath`.
+     */
+    readonly includeBodies: boolean;
 }
 /**
  * Loose input type for `resolveMemoryPreflightConfig`. Accepts either a

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

@@ -3,23 +3,53 @@ const DEFAULTS = Object.freeze({
     maxTokens: 1200,
     listCap: 12,
     contentCacheBytes: 6000,
+    hotItemCap: 10,
+    warmItemCap: 4,
+    warmMinTokenHits: 1,
+    selectionTimeBudgetMs: 200,
+    includeBodies: false,
 });
 const LIST_CAP_MIN = 1;
 const LIST_CAP_MAX = 50;
+const ITEM_CAP_MAX = 100;
 function asFiniteInt(value, fallback) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0
         ? Math.trunc(value)
         : fallback;
 }
+function asFiniteNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? value
+        : fallback;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
 export function resolveMemoryPreflightConfig(prefs) {
     const m = prefs.memoryPreflight ?? {};
     const listCapRaw = asFiniteInt(m.listCap, DEFAULTS.listCap);
+    const listCap = clamp(listCapRaw, LIST_CAP_MIN, LIST_CAP_MAX);
+    const maxTokens = m.maxTokens && m.maxTokens > 0 ? m.maxTokens : DEFAULTS.maxTokens;
     return {
         enabled: m.enabled === false ? false : DEFAULTS.enabled,
-        maxTokens: m.maxTokens && m.maxTokens > 0 ? m.maxTokens : DEFAULTS.maxTokens,
-        listCap: Math.min(LIST_CAP_MAX, Math.max(LIST_CAP_MIN, listCapRaw)),
+        maxTokens,
+        listCap,
         contentCacheBytes: m.contentCacheBytes && m.contentCacheBytes > 0
             ? m.contentCacheBytes
             : DEFAULTS.contentCacheBytes,
+        // `maxBytes` wins when explicitly set; otherwise the legacy token cap
+        // is preserved verbatim (maxTokens * 4 bytes).
+        maxBytes: m.maxBytes && m.maxBytes > 0 ? Math.trunc(m.maxBytes) : maxTokens * 4,
+        // `hotItemCap` falls back to the legacy `listCap` only when the caller
+        // explicitly set `listCap`; otherwise the tiered default (10) applies.
+        hotItemCap: clamp(m.hotItemCap !== undefined
+            ? asFiniteInt(m.hotItemCap, DEFAULTS.hotItemCap)
+            : m.listCap !== undefined
+                ? listCap
+                : DEFAULTS.hotItemCap, LIST_CAP_MIN, ITEM_CAP_MAX),
+        warmItemCap: clamp(asFiniteInt(m.warmItemCap, DEFAULTS.warmItemCap), 0, ITEM_CAP_MAX),
+        warmMinTokenHits: clamp(asFiniteInt(m.warmMinTokenHits, DEFAULTS.warmMinTokenHits), 1, ITEM_CAP_MAX),
+        selectionTimeBudgetMs: clamp(asFiniteNumber(m.selectionTimeBudgetMs, DEFAULTS.selectionTimeBudgetMs), 0, 10_000),
+        includeBodies: m.includeBodies === true ? true : DEFAULTS.includeBodies,
     };
 }

package/dist/services/context/memory-preflight-service.d.ts

@@ -2,11 +2,22 @@ import { type MemoryPreflightPrefsInput } from './memory-preflight-config.js';
 export interface MemoryPreflightResult {
     available: boolean;
     block?: string;
+    /** Back-compat: total items emitted (hot + warm). */
     feedbackListItems?: number;
     cachedItemCount?: number;
     reason?: string;
     truncated?: boolean | undefined;
     droppedCount?: number | undefined;
+    /** Slice 2026-09-09: hot items emitted. */
+    hotSelected?: number | undefined;
+    /** Slice 2026-09-09: warm items emitted. */
+    warmSelected?: number | undefined;
+    /** Slice 2026-09-09: bytes of the emitted block (utf8). */
+    bytesEmitted?: number | undefined;
+    /** Slice 2026-09-09: true when ANY budget (items / bytes / time) cut content. */
+    budgetTruncated?: boolean | undefined;
+    /** Slice 2026-09-09: true when the soft selection time budget was hit. */
+    timedOut?: boolean | undefined;
 }
 export declare class MemoryPreflightService {
     private readonly reader;
@@ -15,5 +26,13 @@ export declare class MemoryPreflightService {
     private readonly cachedMemoContents;
     constructor(projectRoot: string, prefs: MemoryPreflightPrefsInput);
     cacheMemoContent(path: string, content: string): void;
-    fetchBlock(_taskTitle: string): Promise<MemoryPreflightResult>;
+    fetchBlock(taskTitle: string): Promise<MemoryPreflightResult>;
+    private selectAndCompose;
 }
+/**
+ * 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 declare function deriveMemoryQuery(role: string, taskBody: string | undefined): string;