@cruxy/cli 0.16.0 → 0.18.0

package/dist/agent/loop.d.ts

@@ -2,6 +2,7 @@ import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
 import type { HookEvent } from "../hooks/index.js";
 import type { StreamRenderer } from "../render/index.js";
+import { type Router, type TaskClass } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
 /** The lifecycle-hook firing seam (C.19). Structural so the loop stays
@@ -39,6 +40,9 @@ export interface RunAgentArgs {
     } | null;
     /** Project instructions (e.g. from CRUXY.md) folded into the system prompt. */
     projectInstructions?: string | null;
+    /** Persistent memory (C.29): the pre-rendered recall block for the system
+     * prompt, or null. Reference data only — never influences the U.3 gate. */
+    recalledMemory?: string | null;
     /** Plan mode's propose phase (C.31): inject the plan-first system directive. */
     planMode?: boolean;
     /** Subagent runs (C.14): inject the bounded-subtask system directive. */
@@ -57,6 +61,17 @@ export interface RunAgentArgs {
      * no-hooks path, so their tools never fire hooks.
      */
     hooks?: LifecycleHookRunner;
+    /**
+     * Multi-model routing (C.30): when set, the tier for `taskClass` is resolved
+     * ONCE up front (fail loud before any model turn) and its wire model overrides
+     * the provider default for every turn in this run; the tier is surfaced on the
+     * live line. Omitted → no override, the provider's default model is used
+     * (unchanged behavior).
+     */
+    router?: Router;
+    /** The declared task class for routing; defaults to `main-turn`. Ignored
+     * unless `router` is set. */
+    taskClass?: TaskClass;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps

package/dist/agent/loop.js

@@ -1,4 +1,5 @@
 import { CruxyError, providerUnsupported } from "../errors/index.js";
+import { resolveTaskModel, } from "../routing/index.js";
 import { buildSystemPrompt } from "./prompts.js";
 /** Tools whose successful call is a file change (drives the `on-file-change`
  * hook). Kept in sync with the file-mutating tool set. */
@@ -17,9 +18,16 @@ export async function runAgent(args) {
     if (!provider.supportsTools) {
         throw providerUnsupported(config.model.provider);
     }
+    // Resolve the routing tier ONCE, before any model turn (C.30). A tier the
+    // gateway does not offer throws CRUXY_E_ROUTING_TIER_UNAVAILABLE here — so a
+    // misrouted run never reaches provider.stream (no request sent with the wrong
+    // tier), and never silently falls back to a different one.
+    const routed = args.router
+        ? resolveTaskModel(args.router, args.taskClass ?? "main-turn")
+        : null;
     renderer?.beginTurn();
     try {
-        return await driveLoop(args, renderer);
+        return await driveLoop(args, renderer, routed);
     }
     finally {
         // Always leave the terminal clean: no orphaned status line, no held text —
@@ -28,7 +36,7 @@ export async function runAgent(args) {
     }
 }
 /** The body of {@link runAgent}, split out so turn cleanup lives in one finally. */
-async function driveLoop(args, renderer) {
+async function driveLoop(args, renderer, routed) {
     const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
@@ -48,6 +56,7 @@ async function driveLoop(args, renderer) {
             .map((tool) => ({ name: tool.name, description: tool.description })),
         git: args.git ?? null,
         projectInstructions: args.projectInstructions ?? null,
+        recalledMemory: args.recalledMemory ?? null,
         planMode: args.planMode ?? false,
         subagent: args.subagent ?? false,
     });
@@ -80,11 +89,13 @@ async function driveLoop(args, renderer) {
             tokens: usage.input_tokens + usage.output_tokens > 0
                 ? { input: usage.input_tokens, output: usage.output_tokens }
                 : undefined,
+            tier: routed?.tier,
         });
         for await (const ev of provider.stream({
             system,
             messages,
             tools,
+            ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
                 case "text_delta":

package/dist/agent/prompts.d.ts

@@ -28,6 +28,13 @@ export interface PromptContext {
     } | null;
     /** Optional extra instructions (e.g. from a project CRUXY.md). */
     projectInstructions?: string | null;
+    /**
+     * Persistent memory (C.29): the pre-rendered, demarcated recall block injected
+     * at session start. It is REFERENCE DATA, not instructions — the block carries
+     * its own data-only framing (see memory/recall.ts) and is appended as an
+     * ordinary section; the U.3 gate never reads it. Null when nothing is recalled.
+     */
+    recalledMemory?: string | null;
     /** Plan mode's propose phase (C.31): inject the plan-first directive. */
     planMode?: boolean;
     /** Subagent run (C.14): inject the bounded-subtask directive. */

package/dist/agent/prompts.js

@@ -91,6 +91,12 @@ export function buildSystemPrompt(ctx) {
     if (ctx.projectInstructions?.trim()) {
         sections.push(`## Project instructions\nThe following came from this project's configuration; honor it unless it conflicts with the rules above:\n\n${ctx.projectInstructions.trim()}`);
     }
+    // Persistent memory (C.29). Appended last, as reference DATA — the block is
+    // pre-rendered with its own un-spoofable data-only demarcation, so it is added
+    // verbatim (never re-wrapped as an instruction). Absent when nothing recalled.
+    if (ctx.recalledMemory?.trim()) {
+        sections.push(ctx.recalledMemory.trim());
+    }
     return sections.join("\n\n");
 }
 /**

package/dist/agent/session.d.ts

@@ -1,6 +1,7 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
 import type { StreamRenderer } from "../render/index.js";
+import { type Router } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
 import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
@@ -13,6 +14,7 @@ import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
 export type PlanRunner = (args: {
     messages: Message[];
     projectInstructions: string | null;
+    recalledMemory: string | null;
     renderer?: StreamRenderer;
 }) => Promise<AgentResult>;
 export interface SessionArgs {
@@ -31,6 +33,13 @@ export interface SessionArgs {
     } | null;
     /** Project instructions (e.g. CRUXY.md) folded into every turn's system prompt. */
     projectInstructions?: string | null;
+    /**
+     * Persistent memory (C.29): the pre-rendered recall block, injected into every
+     * turn's system prompt as reference data. Built once at session start (user
+     * memory + trusted project memory); null when memory is off or empty. Fixed
+     * for the session — it does not re-read mid-session.
+     */
+    recalledMemory?: string | null;
     /** Start in plan mode (C.31). Toggleable at runtime via `setPlanMode`. */
     planMode?: boolean;
     /** The plan-mode turn runner; required for plan mode to actually engage. */
@@ -42,6 +51,11 @@ export interface SessionArgs {
      * `before-tool`/`after-tool`/`on-file-change`.
      */
     hooks?: LifecycleHookRunner;
+    /**
+     * Multi-model routing (C.30). When set, main turns route on `main-turn` and
+     * context compaction on `summarize`; omitted → the provider default (unchanged).
+     */
+    router?: Router;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic

package/dist/agent/session.js

@@ -1,4 +1,5 @@
 import { loadProjectInstructions } from "../config/index.js";
+import { resolveTaskModel } from "../routing/index.js";
 import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
@@ -98,11 +99,13 @@ export class Session {
             ? await this.args.planRunner({
                 messages: this.messages,
                 projectInstructions: this.projectInstructions,
+                recalledMemory: this.args.recalledMemory ?? null,
                 renderer,
             })
             : await runAgent({
                 messages: this.messages,
-                ...this.args,
+                ...this.args, // carries `router` through to the loop
+                taskClass: "main-turn",
                 // After the spread so a mid-session `/reload` wins over the initial value.
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
@@ -226,9 +229,15 @@ export class Session {
         const transcript = renderTranscript(prefix);
         const usage = { input_tokens: 0, output_tokens: 0 };
         let text = "";
+        // Compaction is mechanical work — route it on `summarize` (C.30) when routing
+        // is active; omitted → the provider default, unchanged.
+        const routed = this.args.router
+            ? resolveTaskModel(this.args.router, "summarize")
+            : null;
         for await (const ev of this.args.provider.stream({
             system: SUMMARY_SYSTEM,
             messages: [{ role: "user", content: transcript }],
+            ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
                 case "text_delta":

package/dist/brand/index.d.ts

@@ -1 +1 @@
-export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, type ForbiddenTerm, type LexiconViolation, } from "./voice.js";
+export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_NAME_PLACEHOLDER, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, scrubModelNames, type ForbiddenTerm, type LexiconViolation, } from "./voice.js";

package/dist/brand/index.js

@@ -1 +1 @@
-export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, } from "./voice.js";
+export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_NAME_PLACEHOLDER, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, scrubModelNames, } from "./voice.js";

package/dist/brand/voice.d.ts

@@ -59,6 +59,26 @@ export declare const FORBIDDEN_TERMS: readonly ForbiddenTerm[];
  * absent: they are real bring-your-own-provider config values, not model names.
  */
 export declare const FORBIDDEN_MODEL_NAMES: RegExp;
+/** The neutral token an upstream model name is replaced with in user-facing copy. */
+export declare const MODEL_NAME_PLACEHOLDER = "\u00ABmodel\u00BB";
+/**
+ * Replace every upstream model IDENTIFIER in an arbitrary, externally-sourced
+ * string with {@link MODEL_NAME_PLACEHOLDER}, collapsing a whole `name-name-vers`
+ * run to a single token.
+ *
+ * The U.8 gag is structural *inside the process* (the routing package can't
+ * produce an upstream id — see `resolveModelId`), but a gateway/provider error
+ * body is an arbitrary external string that bypasses that guarantee. This is the
+ * scrub applied at the error-construction boundary so no upstream id reaches a
+ * user-facing `CruxyError.cause`.
+ *
+ * Scrubs model ids as whole TOKENS, never a bare vendor word or a substring
+ * inside an unrelated word/path — so legitimate output (`/home/claude`, the
+ * `opus` codec, a `claude-bot` username) is left intact (see {@link isModelId}).
+ * Provider names (`anthropic`/`openai`) are absent from the set, so bring-your-own
+ * provider config values survive too.
+ */
+export declare function scrubModelNames(text: string): string;
 /** One lexicon violation found in a scanned string. */
 export interface LexiconViolation {
     /** The forbidden term (or "model-name" for a gag violation). */

package/dist/brand/voice.js

@@ -55,6 +55,60 @@ export const FORBIDDEN_TERMS = [
  * absent: they are real bring-your-own-provider config values, not model names.
  */
 export const FORBIDDEN_MODEL_NAMES = /\b(claude|sonnet|opus|haiku|gpt-?\d|gemini|llama|mistral)\b/i;
+/** The neutral token an upstream model name is replaced with in user-facing copy. */
+export const MODEL_NAME_PLACEHOLDER = "«model»";
+/**
+ * A model-id-SHAPED run in free text: a self-identifying `gpt-4`/`gpt-4o`, or a
+ * model word carrying a hyphen/dot tail (`claude-sonnet-4-6`, `gemini-1.5-pro`).
+ * Deliberately GENEROUS — it also matches bare words and non-model hyphenated
+ * tokens; {@link isModelId} does the real filtering in the scrub callback, and
+ * matching the whole run (not each word) is what collapses `claude-sonnet-4-6`
+ * to ONE placeholder instead of `«model»-«model»-4-6`. The leading
+ * `(?<![/\\\w])` stops it firing inside a longer word (`gptools`) or on a path
+ * segment (`/home/claude/…`) — both of which the bare `\b` form corrupts.
+ */
+const MODEL_ID_CANDIDATE = /(?<![/\\\w])(?:gpt-?\d[a-z0-9]*(?:[-.][a-z0-9]+)*|(?:claude|sonnet|opus|haiku|gemini|llama|mistral|gpt)(?:[-.][a-z0-9]+)*)/gi;
+/** The bare model words, for the digitless-compound test in {@link isModelId}. */
+const MODEL_WORD = /(?:claude|sonnet|opus|haiku|gemini|llama|mistral|gpt)/gi;
+/**
+ * Is a {@link MODEL_ID_CANDIDATE} run an actual upstream model reference (scrub),
+ * or a legitimate token that merely contains a model word (keep)? A reference is:
+ * a self-identifying `gpt-<n>`; OR a hyphen/dot run carrying a version digit
+ * (`claude-sonnet-4-6`, `gemini-1.5-pro`); OR a digitless compound of ≥2 distinct
+ * model words (`claude-sonnet`). A bare word (`opus`, `haiku`), a path segment
+ * (`/home/claude`), or a plain hyphenated token (`claude-bot`) is none of these,
+ * so it survives verbatim — the gag scrubs model IDS, never legitimate output.
+ */
+function isModelId(run) {
+    if (/^gpt-?\d/i.test(run))
+        return true; // gpt-4, gpt4, gpt-4o
+    if (!/[-.]/.test(run))
+        return false; // bare word — never a model reference here
+    if (/\d/.test(run))
+        return true; // version digit ⇒ an id
+    const words = run.match(MODEL_WORD) ?? [];
+    return new Set(words.map((w) => w.toLowerCase())).size >= 2; // claude-sonnet
+}
+/**
+ * Replace every upstream model IDENTIFIER in an arbitrary, externally-sourced
+ * string with {@link MODEL_NAME_PLACEHOLDER}, collapsing a whole `name-name-vers`
+ * run to a single token.
+ *
+ * The U.8 gag is structural *inside the process* (the routing package can't
+ * produce an upstream id — see `resolveModelId`), but a gateway/provider error
+ * body is an arbitrary external string that bypasses that guarantee. This is the
+ * scrub applied at the error-construction boundary so no upstream id reaches a
+ * user-facing `CruxyError.cause`.
+ *
+ * Scrubs model ids as whole TOKENS, never a bare vendor word or a substring
+ * inside an unrelated word/path — so legitimate output (`/home/claude`, the
+ * `opus` codec, a `claude-bot` username) is left intact (see {@link isModelId}).
+ * Provider names (`anthropic`/`openai`) are absent from the set, so bring-your-own
+ * provider config values survive too.
+ */
+export function scrubModelNames(text) {
+    return text.replace(MODEL_ID_CANDIDATE, (run) => isModelId(run) ? MODEL_NAME_PLACEHOLDER : run);
+}
 /**
  * Scan one user-facing string for lexicon violations — deprecated synonyms and
  * upstream model names. Returns every violation (empty ⇒ on-voice). Pure; the

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

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy memory` — inspect and control persistent memory (C.29). `list` shows
+ * user + project entries and whether project memory is trusted (recalled);
+ * `forget`/`clear` remove entries; `trust` records the explicit decision to
+ * recall a repo's project memory, bound to its current fingerprint.
+ */
+export declare function memoryCommand(): Command;

package/dist/cli/commands/memory.js

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../../config/index.js";
+import { shouldUseColor } from "../../errors/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { MemoryService } from "../../memory/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy memory` — inspect and control persistent memory (C.29). `list` shows
+ * user + project entries and whether project memory is trusted (recalled);
+ * `forget`/`clear` remove entries; `trust` records the explicit decision to
+ * recall a repo's project memory, bound to its current fingerprint.
+ */
+export function memoryCommand() {
+    const cmd = new Command("memory").description("inspect and control persistent memory recalled across sessions");
+    const service = () => {
+        const { config } = loadConfig();
+        return new MemoryService({ cwd: process.cwd(), config: config.memory });
+    };
+    cmd
+        .command("list", { isDefault: true })
+        .description("list saved memory entries and project-memory trust status")
+        .action(() => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const status = service().status();
+        logger.print(`${t.strong("memory:")} ${config.memory.enabled ? t.success("enabled") : t.warning("disabled (memory.enabled = false)")}`);
+        logger.print(`\n${t.heading("user memory")} ${t.muted("(trusted)")}`);
+        printEntries(status.user, t);
+        const trustLabel = status.projectTrusted
+            ? t.success("trusted — recalled")
+            : t.danger("NOT trusted — not recalled; run `cruxy memory trust .`");
+        logger.print(`\n${t.heading("project memory")} ${trustLabel}`);
+        printEntries(status.project, t);
+        if (status.errors.length > 0) {
+            logger.print(`\n${t.danger(t.heading("excluded (invalid or secret — never recalled):"))}`);
+            for (const e of status.errors) {
+                logger.print(`  ${t.muted(`[${e.scope}]`)} ${t.strong(e.id)} — ${e.message}`);
+            }
+        }
+    });
+    cmd
+        .command("forget <id>")
+        .description("forget one saved memory entry by id")
+        .action((id) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const removed = service().forget(id);
+        logger.print(removed
+            ? `${t.success("forgotten")} — entry ${t.strong(id)} removed`
+            : t.warning(`no memory entry with id ${id}`));
+    });
+    cmd
+        .command("clear")
+        .description("clear saved memory entries in a scope")
+        .option("--scope <scope>", "which scope to clear: user | project | all", "all")
+        .action((opts) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const scope = opts.scope;
+        if (scope !== "user" && scope !== "project" && scope !== "all") {
+            logger.print(t.danger(`invalid --scope ${scope} (use user | project | all)`));
+            process.exitCode = 2;
+            return;
+        }
+        const removed = service().clear(scope);
+        const where = scope === "all" ? "across all scopes" : `from ${scope} memory`;
+        logger.print(`${t.success("cleared")} — removed ${removed} ` +
+            `entr${removed === 1 ? "y" : "ies"} ${where}`);
+    });
+    cmd
+        .command("trust [path]")
+        .description("trust this repo's project memory after reviewing it (records the decision)")
+        .action((target) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const root = path.resolve(target ?? process.cwd());
+        const svc = new MemoryService({ cwd: root, config: config.memory });
+        const status = svc.status();
+        if (status.project.length === 0) {
+            logger.print(t.muted(`no project memory found under ${root}`));
+            return;
+        }
+        logger.print(t.strong(`trusting ${status.project.length} project entr${status.project.length === 1 ? "y" : "ies"}:`));
+        printEntries(status.project, t);
+        const count = svc.trustProject();
+        logger.print(`${t.success("trusted")} — ${count} project entr${count === 1 ? "y" : "ies"} will now be recalled for ${root}. ` +
+            t.muted("changing them will require re-trusting."));
+    });
+    return cmd;
+}
+function printEntries(entries, t) {
+    if (entries.length === 0) {
+        logger.print(t.muted("  (none)"));
+        return;
+    }
+    for (const e of entries) {
+        logger.print(`  ${t.muted(e.id.slice(0, 8))} ${t.strong(`(${e.kind})`)} ${e.content}`);
+    }
+}

package/dist/cli/commands/pr.js

@@ -5,6 +5,7 @@ import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, shouldUseColor } from "../../errors/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { ApprovalService } from "../../approval/index.js";
+import { resolveTaskModel, routerForConfig } from "../../routing/index.js";
 import { createForgeProvider, createPrService, generateWithLlm, loadCommitGuidance, resolveForgeToken, } from "../../vcs/index.js";
 /**
  * `cruxy pr` — turn the current changes into a pull request (C.15). Generates the
@@ -37,6 +38,13 @@ export function prCommand() {
             temperature: config.model.temperature,
             gatewayUrl: config.cruxy.gatewayUrl,
         });
+        // Multi-model routing (C.30): PR/commit text is `commit-msg` work. Null
+        // unless routing is configured → the provider default, unchanged. A
+        // misrouted tier fails loud here before any request.
+        const router = routerForConfig(config);
+        const genModel = router
+            ? resolveTaskModel(router, "commit-msg").model
+            : undefined;
         // resolveForgeToken throws CRUXY_E_FORGE_AUTH (exit 4) if none is found.
         const forge = createForgeProvider(resolveForgeToken());
         const guidance = await loadCommitGuidance(cwd);
@@ -53,7 +61,7 @@ export function prCommand() {
                 ...i,
                 scopes: guidance.scopes,
                 skillBody: guidance.skillBody,
-            }),
+            }, { model: genModel }),
         });
         logger.info(t.muted("generating pull request content…"));
         const outcome = await service.openPullRequest({

package/dist/cli/program.js

@@ -15,6 +15,7 @@ import { checkpointCommand } from "./commands/checkpoint.js";
 import { rollbackCommand } from "./commands/rollback.js";
 import { testCommand } from "./commands/test.js";
 import { hooksCommand } from "./commands/hooks.js";
+import { memoryCommand } from "./commands/memory.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -45,6 +46,7 @@ export function buildProgram() {
     program.addCommand(rollbackCommand());
     program.addCommand(testCommand());
     program.addCommand(hooksCommand());
+    program.addCommand(memoryCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/session-factory.js

@@ -7,6 +7,8 @@ import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry } from "../tools/index.js";
 import { Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
+import { routerForConfig } from "../routing/index.js";
+import { MemoryService, rememberTool } from "../memory/index.js";
 import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
  * Wrap a PromptIO so the live region yields before any prompt text lands
@@ -96,9 +98,30 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         temperature: config.model.temperature,
         gatewayUrl: config.cruxy.gatewayUrl,
     });
+    // Multi-model routing (C.30): null unless routing is configured on a cruxy
+    // session, so the default path threads `undefined` and behaves exactly as
+    // before. One router is shared by the main loop, subagents, and plan mode.
+    const router = routerForConfig(config) ?? undefined;
     const execRegistry = buildDefaultRegistry();
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
+    // Persistent memory (C.29): register the write tool and build the recall block
+    // ONCE at session start. User memory is always eligible; project memory is
+    // recalled only when trusted (a cloned repo's notes never inject silently).
+    // Fully inert when disabled. Recall is best-effort — a load problem degrades to
+    // "no memory", never a hard failure at session start.
+    let recalledMemory = null;
+    if (config.memory.enabled) {
+        execRegistry.register(rememberTool);
+        const recall = new MemoryService({ cwd, config: config.memory }).recall();
+        recalledMemory = recall.block;
+        if (recall.projectPresentButUntrusted) {
+            logger.info("project memory found but not trusted — run `cruxy memory trust .` to recall it");
+        }
+        for (const e of recall.errors) {
+            logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
+        }
+    }
     // One io shared by every prompt in the session (plan approval, the U.3 gate,
     // and any gate inside a subagent), so they all coordinate with the same live
     // region. The full wrapper stack around an ApprovalService is factored here
@@ -114,6 +137,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     const orchestrator = new SubagentOrchestrator({
         provider,
         config,
+        router,
         parentRegistry: execRegistry,
         cwd,
         logger,
@@ -144,7 +168,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             requestApproval: gate(approval),
             sandbox,
         };
-        const planRunner = ({ messages, projectInstructions, renderer: turnRenderer, }) => runPlanSession({
+        const planRunner = ({ messages, projectInstructions, recalledMemory: turnMemory, renderer: turnRenderer, }) => runPlanSession({
             provider,
             config,
             ctx,
@@ -155,7 +179,9 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             messages,
             git,
             projectInstructions,
+            recalledMemory: turnMemory,
             renderer: turnRenderer,
+            router,
         });
         return new Session({
             provider,
@@ -164,9 +190,11 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             ctx,
             git,
             projectInstructions,
+            recalledMemory,
             planMode: true,
             planRunner,
             hooks,
+            router,
         });
     }
     const approval = new ApprovalService({
@@ -182,6 +210,8 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         ctx,
         git,
         projectInstructions,
+        recalledMemory,
         hooks,
+        router,
     });
 }