@cruxy/cli 0.17.0 → 0.18.0

package/dist/agent/loop.d.ts

@@ -40,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. */

package/dist/agent/loop.js

@@ -56,6 +56,7 @@ async function driveLoop(args, renderer, routed) {
             .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,
     });

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

@@ -14,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 {
@@ -32,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. */

package/dist/agent/session.js

@@ -99,6 +99,7 @@ export class Session {
             ? await this.args.planRunner({
                 messages: this.messages,
                 projectInstructions: this.projectInstructions,
+                recalledMemory: this.args.recalledMemory ?? null,
                 renderer,
             })
             : await runAgent({

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/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

@@ -8,6 +8,7 @@ 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
@@ -104,6 +105,23 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     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
@@ -150,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,
@@ -161,6 +179,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             messages,
             git,
             projectInstructions,
+            recalledMemory: turnMemory,
             renderer: turnRenderer,
             router,
         });
@@ -171,6 +190,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             ctx,
             git,
             projectInstructions,
+            recalledMemory,
             planMode: true,
             planRunner,
             hooks,
@@ -190,6 +210,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         ctx,
         git,
         projectInstructions,
+        recalledMemory,
         hooks,
         router,
     });

package/dist/config/schema.d.ts

@@ -182,7 +182,7 @@ export declare const IndexConfigSchema: z.ZodObject<{
     };
     enabled: boolean;
     embedder: "fastembed";
-    store: "auto" | "sqlite" | "memory";
+    store: "memory" | "auto" | "sqlite";
     maxFileBytes: number;
     chunk: {
         windowLines: number;
@@ -196,7 +196,7 @@ export declare const IndexConfigSchema: z.ZodObject<{
     } | undefined;
     enabled?: boolean | undefined;
     embedder?: "fastembed" | undefined;
-    store?: "auto" | "sqlite" | "memory" | undefined;
+    store?: "memory" | "auto" | "sqlite" | undefined;
     maxFileBytes?: number | undefined;
     chunk?: {
         windowLines?: number | undefined;
@@ -320,18 +320,18 @@ export declare const SandboxConfigSchema: z.ZodObject<{
      */
     mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
+    memory: string;
     image: string;
     enabled: boolean;
-    memory: string;
     network: "none" | "host-loopback" | "full";
     pids: number;
     cpus: number;
     mounts: string[];
     timeout?: number | undefined;
 }, {
+    memory?: string | undefined;
     image?: string | undefined;
     enabled?: boolean | undefined;
-    memory?: string | undefined;
     network?: "none" | "host-loopback" | "full" | undefined;
     pids?: number | undefined;
     cpus?: number | undefined;
@@ -386,6 +386,28 @@ export declare const RoutingConfigSchema: z.ZodObject<{
     map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
     default?: "kavi" | "vaani" | "mira" | undefined;
 }>;
+/**
+ * Persistent memory (C.29): structured notes recalled across sessions. ON by
+ * default and safe to be so — user memory is self-authored (nothing you didn't
+ * write is injected) and project memory still requires an explicit
+ * `cruxy memory trust`, so a cloned repo never auto-injects. Recall is bounded
+ * by a token budget; the `remember` tool refuses to persist secrets.
+ */
+export declare const MemoryConfigSchema: z.ZodObject<{
+    /** Master switch. When false, nothing is recalled and the `remember` tool
+     * is not registered (memory stays fully inert). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Token budget for the recalled block injected at session start; entries
+     * beyond it are pruned oldest-first (the omission is stated, never silent). */
+    maxRecallTokens: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    maxRecallTokens: number;
+}, {
+    enabled?: boolean | undefined;
+    maxRecallTokens?: number | undefined;
+}>;
+export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -567,7 +589,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         };
         enabled: boolean;
         embedder: "fastembed";
-        store: "auto" | "sqlite" | "memory";
+        store: "memory" | "auto" | "sqlite";
         maxFileBytes: number;
         chunk: {
             windowLines: number;
@@ -581,7 +603,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         } | undefined;
         enabled?: boolean | undefined;
         embedder?: "fastembed" | undefined;
-        store?: "auto" | "sqlite" | "memory" | undefined;
+        store?: "memory" | "auto" | "sqlite" | undefined;
         maxFileBytes?: number | undefined;
         chunk?: {
             windowLines?: number | undefined;
@@ -683,18 +705,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
          */
         mounts: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
+        memory: string;
         image: string;
         enabled: boolean;
-        memory: string;
         network: "none" | "host-loopback" | "full";
         pids: number;
         cpus: number;
         mounts: string[];
         timeout?: number | undefined;
     }, {
+        memory?: string | undefined;
         image?: string | undefined;
         enabled?: boolean | undefined;
-        memory?: string | undefined;
         network?: "none" | "host-loopback" | "full" | undefined;
         pids?: number | undefined;
         cpus?: number | undefined;
@@ -731,6 +753,20 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
         default?: "kavi" | "vaani" | "mira" | undefined;
     }>>;
+    memory: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, nothing is recalled and the `remember` tool
+         * is not registered (memory stays fully inert). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Token budget for the recalled block injected at session start; entries
+         * beyond it are pruned oldest-first (the omission is stated, never silent). */
+        maxRecallTokens: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        maxRecallTokens: number;
+    }, {
+        enabled?: boolean | undefined;
+        maxRecallTokens?: number | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -749,14 +785,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy: {
         gatewayUrl: string;
     };
+    memory: {
+        enabled: boolean;
+        maxRecallTokens: number;
+    };
     checkpoint: {
         enabled: boolean;
         retention: number;
     };
     sandbox: {
+        memory: string;
         image: string;
         enabled: boolean;
-        memory: string;
         network: "none" | "host-loopback" | "full";
         pids: number;
         cpus: number;
@@ -812,7 +852,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         };
         enabled: boolean;
         embedder: "fastembed";
-        store: "auto" | "sqlite" | "memory";
+        store: "memory" | "auto" | "sqlite";
         maxFileBytes: number;
         chunk: {
             windowLines: number;
@@ -842,14 +882,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy?: {
         gatewayUrl?: string | undefined;
     } | undefined;
+    memory?: {
+        enabled?: boolean | undefined;
+        maxRecallTokens?: number | undefined;
+    } | undefined;
     checkpoint?: {
         enabled?: boolean | undefined;
         retention?: number | undefined;
     } | undefined;
     sandbox?: {
+        memory?: string | undefined;
         image?: string | undefined;
         enabled?: boolean | undefined;
-        memory?: string | undefined;
         network?: "none" | "host-loopback" | "full" | undefined;
         pids?: number | undefined;
         cpus?: number | undefined;
@@ -905,7 +949,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         } | undefined;
         enabled?: boolean | undefined;
         embedder?: "fastembed" | undefined;
-        store?: "auto" | "sqlite" | "memory" | undefined;
+        store?: "memory" | "auto" | "sqlite" | undefined;
         maxFileBytes?: number | undefined;
         chunk?: {
             windowLines?: number | undefined;

package/dist/config/schema.js

@@ -273,6 +273,23 @@ export const RoutingConfigSchema = z
     map: z.record(z.enum(TASK_CLASSES), z.enum(MODEL_TIERS)).default({}),
 })
     .strict();
+/**
+ * Persistent memory (C.29): structured notes recalled across sessions. ON by
+ * default and safe to be so — user memory is self-authored (nothing you didn't
+ * write is injected) and project memory still requires an explicit
+ * `cruxy memory trust`, so a cloned repo never auto-injects. Recall is bounded
+ * by a token budget; the `remember` tool refuses to persist secrets.
+ */
+export const MemoryConfigSchema = z
+    .object({
+    /** Master switch. When false, nothing is recalled and the `remember` tool
+     * is not registered (memory stays fully inert). */
+    enabled: z.boolean().default(true),
+    /** Token budget for the recalled block injected at session start; entries
+     * beyond it are pruned oldest-first (the omission is stated, never silent). */
+    maxRecallTokens: z.number().int().positive().default(1000),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -298,6 +315,7 @@ export const CruxyConfigSchema = z
     sandbox: SandboxConfigSchema.default({}),
     hooks: HooksConfigSchema.default({}),
     routing: RoutingConfigSchema.default({}),
+    memory: MemoryConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/constants.d.ts

@@ -30,6 +30,17 @@ export declare const COMMANDS_DIR_NAME = "commands";
 /** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
  * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
 export declare const TRUST_FILE_NAME = "trust.json";
+/**
+ * Persistent memory (C.29). Structured entries live under the memory subdir of
+ * the project dir (`<cwd>/.cruxy/memory`) and the global dir (`~/.cruxy/memory`),
+ * one JSON file per scope — pure data, validated, never eval'd.
+ */
+export declare const MEMORY_DIR_NAME = "memory";
+export declare const MEMORY_FILE_NAME = "entries.json";
+/** Per-repo PROJECT-memory trust record, in the GLOBAL dir only
+ * (`~/.cruxy/memory-trust.json`) — its own file, independent of hook trust, so
+ * cloning a repo carries zero memory trust (C.29 supply-chain safety). */
+export declare const MEMORY_TRUST_FILE_NAME = "memory-trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/constants.js

@@ -50,6 +50,17 @@ export const COMMANDS_DIR_NAME = "commands";
 /** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
  * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
 export const TRUST_FILE_NAME = "trust.json";
+/**
+ * Persistent memory (C.29). Structured entries live under the memory subdir of
+ * the project dir (`<cwd>/.cruxy/memory`) and the global dir (`~/.cruxy/memory`),
+ * one JSON file per scope — pure data, validated, never eval'd.
+ */
+export const MEMORY_DIR_NAME = "memory";
+export const MEMORY_FILE_NAME = "entries.json";
+/** Per-repo PROJECT-memory trust record, in the GLOBAL dir only
+ * (`~/.cruxy/memory-trust.json`) — its own file, independent of hook trust, so
+ * cloning a repo carries zero memory trust (C.29 supply-chain safety). */
+export const MEMORY_TRUST_FILE_NAME = "memory-trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/errors/constructors.d.ts

@@ -136,6 +136,20 @@ export declare function subagentFailed(underlying?: unknown): CruxyError;
  * invents a test command — the fix is always to declare one.
  */
 export declare function testCommandNotFound(): CruxyError;
+/**
+ * A memory write was refused because the content matched a known secret shape
+ * (C.29). Secrets are NEVER persisted to memory — the fix is to remember a
+ * non-secret description, not the secret itself.
+ */
+export declare function memorySecretRefused(kind: string): CruxyError;
+/**
+ * A repo's project memory is present but has not been trusted on this machine
+ * (C.29). It is never recalled into the model's context silently — a cloned repo
+ * cannot inject notes until you review and trust them.
+ */
+export declare function memoryUntrusted(root: string): CruxyError;
+/** A malformed memory entry was rejected (C.29) — excluded, never eval'd. */
+export declare function memoryInvalid(detail: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -602,6 +602,51 @@ export function testCommandNotFound() {
         ],
     });
 }
+// ── persistent memory (exit 14) — C.29 ────────────────────────────────────────
+/**
+ * A memory write was refused because the content matched a known secret shape
+ * (C.29). Secrets are NEVER persisted to memory — the fix is to remember a
+ * non-secret description, not the secret itself.
+ */
+export function memorySecretRefused(kind) {
+    return new CruxyError({
+        code: ErrorCode.MemorySecret,
+        title: "refused to save that note — it looks like it contains a secret",
+        cause: `the content matched a ${kind}; secrets are never written to memory`,
+        nextSteps: [
+            "remember a non-secret description instead (e.g. “the deploy key lives in 1Password”, not the key)",
+        ],
+        meta: { kind },
+    });
+}
+/**
+ * A repo's project memory is present but has not been trusted on this machine
+ * (C.29). It is never recalled into the model's context silently — a cloned repo
+ * cannot inject notes until you review and trust them.
+ */
+export function memoryUntrusted(root) {
+    return new CruxyError({
+        code: ErrorCode.MemoryUntrusted,
+        title: "this project's memory has not been trusted",
+        cause: "project memory can arrive with a cloned repo (another author), so it is not recalled until you trust it",
+        nextSteps: [
+            "review the entries with `cruxy memory list`",
+            "then trust them with `cruxy memory trust .` (re-trust is required if they change)",
+        ],
+        meta: { root },
+    });
+}
+/** A malformed memory entry was rejected (C.29) — excluded, never eval'd. */
+export function memoryInvalid(detail) {
+    return new CruxyError({
+        code: ErrorCode.MemoryInvalid,
+        title: "a memory entry is malformed and was excluded",
+        cause: detail,
+        nextSteps: [
+            "inspect the file with `cruxy memory list`, or clear it with `cruxy memory clear`",
+        ],
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -71,6 +71,15 @@ export declare const ErrorCode: {
     readonly HookInvalid: "CRUXY_E_HOOK_INVALID";
     /** A malformed custom slash-command definition — excluded and surfaced. */
     readonly SlashInvalid: "CRUXY_E_SLASH_INVALID";
+    /** A malformed memory entry — excluded from recall/writes and surfaced,
+     * never eval'd. */
+    readonly MemoryInvalid: "CRUXY_E_MEMORY_INVALID";
+    /** A repo's project memory has not been trusted — it is never recalled into
+     * context silently (supply-chain safety). */
+    readonly MemoryUntrusted: "CRUXY_E_MEMORY_UNTRUSTED";
+    /** A memory write was refused because the content matched a secret shape —
+     * secrets are never persisted (defense in depth over C.17). */
+    readonly MemorySecret: "CRUXY_E_MEMORY_SECRET";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -85,6 +85,16 @@ export const ErrorCode = {
     HookInvalid: "CRUXY_E_HOOK_INVALID",
     /** A malformed custom slash-command definition — excluded and surfaced. */
     SlashInvalid: "CRUXY_E_SLASH_INVALID",
+    // persistent memory (exit 14) — C.29
+    /** A malformed memory entry — excluded from recall/writes and surfaced,
+     * never eval'd. */
+    MemoryInvalid: "CRUXY_E_MEMORY_INVALID",
+    /** A repo's project memory has not been trusted — it is never recalled into
+     * context silently (supply-chain safety). */
+    MemoryUntrusted: "CRUXY_E_MEMORY_UNTRUSTED",
+    /** A memory write was refused because the content matched a secret shape —
+     * secrets are never persisted (defense in depth over C.17). */
+    MemorySecret: "CRUXY_E_MEMORY_SECRET",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -146,6 +156,12 @@ const EXIT_CODES = {
     [ErrorCode.HookUntrusted]: 13,
     [ErrorCode.HookInvalid]: 13,
     [ErrorCode.SlashInvalid]: 13,
+    // Persistent memory (C.29). A malformed entry and an untrusted project are
+    // data-safety problems; a refused secret write is a security stop — grouped
+    // for a greppable exit code.
+    [ErrorCode.MemoryInvalid]: 14,
+    [ErrorCode.MemoryUntrusted]: 14,
+    [ErrorCode.MemorySecret]: 14,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/hooks/types.d.ts

@@ -103,8 +103,8 @@ export declare const SlashFrontmatterSchema: z.ZodObject<{
     command?: string | undefined;
 }, {
     description: string;
-    command?: string | undefined;
     kind?: "shell" | "prompt" | undefined;
+    command?: string | undefined;
 }>;
 export type SlashFrontmatter = z.infer<typeof SlashFrontmatterSchema>;
 /** A validated custom slash command, tagged with source. */