@cruxy/cli 0.17.0 → 0.19.0

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,160 @@ 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>;
+/** A per-tier price, in the user's own currency, PER MILLION TOKENS (C.22). */
+export declare const TierPriceSchema: z.ZodObject<{
+    /** Price per 1,000,000 input tokens. */
+    input: z.ZodNumber;
+    /** Price per 1,000,000 output tokens. */
+    output: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    input: number;
+    output: number;
+}, {
+    input: number;
+    output: number;
+}>;
+/**
+ * Usage telemetry + cost tracking (C.22): LOCAL usage accounting only — nothing
+ * here is ever transmitted. Costs are opt-in and honest: prices are per-TIER and
+ * per-million-tokens, configured by the user; with none set, tokens are shown
+ * and cost is omitted (cruxy ships no bundled price table). The `prices` keys are
+ * the fixed {@link MODEL_TIERS}, so an upstream model name can never appear here
+ * (U.8 gag holds by construction) and a mistyped tier is rejected at config load.
+ */
+export declare const UsageConfigSchema: z.ZodObject<{
+    /** Master switch. When false, no usage is collected, persisted, or shown. */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Currency label to prefix costs with (e.g. "$", "€"). Empty ⇒ no symbol is
+     * assumed — a bare number is shown, since the user configured the prices. */
+    currency: z.ZodDefault<z.ZodString>;
+    /** How many past runs to keep in the store; older ones are pruned oldest-first. */
+    retention: z.ZodDefault<z.ZodNumber>;
+    /** Per-tier prices. Any tier omitted is simply unpriced (cost omitted for it). */
+    prices: z.ZodDefault<z.ZodObject<{
+        kavi: z.ZodOptional<z.ZodObject<{
+            /** Price per 1,000,000 input tokens. */
+            input: z.ZodNumber;
+            /** Price per 1,000,000 output tokens. */
+            output: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            input: number;
+            output: number;
+        }, {
+            input: number;
+            output: number;
+        }>>;
+        vaani: z.ZodOptional<z.ZodObject<{
+            /** Price per 1,000,000 input tokens. */
+            input: z.ZodNumber;
+            /** Price per 1,000,000 output tokens. */
+            output: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            input: number;
+            output: number;
+        }, {
+            input: number;
+            output: number;
+        }>>;
+        mira: z.ZodOptional<z.ZodObject<{
+            /** Price per 1,000,000 input tokens. */
+            input: z.ZodNumber;
+            /** Price per 1,000,000 output tokens. */
+            output: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            input: number;
+            output: number;
+        }, {
+            input: number;
+            output: number;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        kavi?: {
+            input: number;
+            output: number;
+        } | undefined;
+        vaani?: {
+            input: number;
+            output: number;
+        } | undefined;
+        mira?: {
+            input: number;
+            output: number;
+        } | undefined;
+    }, {
+        kavi?: {
+            input: number;
+            output: number;
+        } | undefined;
+        vaani?: {
+            input: number;
+            output: number;
+        } | undefined;
+        mira?: {
+            input: number;
+            output: number;
+        } | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    retention: number;
+    currency: string;
+    prices: {
+        kavi?: {
+            input: number;
+            output: number;
+        } | undefined;
+        vaani?: {
+            input: number;
+            output: number;
+        } | undefined;
+        mira?: {
+            input: number;
+            output: number;
+        } | undefined;
+    };
+}, {
+    enabled?: boolean | undefined;
+    retention?: number | undefined;
+    currency?: string | undefined;
+    prices?: {
+        kavi?: {
+            input: number;
+            output: number;
+        } | undefined;
+        vaani?: {
+            input: number;
+            output: number;
+        } | undefined;
+        mira?: {
+            input: number;
+            output: number;
+        } | undefined;
+    } | undefined;
+}>;
+export type UsageConfig = z.infer<typeof UsageConfigSchema>;
 /** 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 +721,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 +735,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 +837,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 +885,130 @@ 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;
+    }>>;
+    usage: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, no usage is collected, persisted, or shown. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Currency label to prefix costs with (e.g. "$", "€"). Empty ⇒ no symbol is
+         * assumed — a bare number is shown, since the user configured the prices. */
+        currency: z.ZodDefault<z.ZodString>;
+        /** How many past runs to keep in the store; older ones are pruned oldest-first. */
+        retention: z.ZodDefault<z.ZodNumber>;
+        /** Per-tier prices. Any tier omitted is simply unpriced (cost omitted for it). */
+        prices: z.ZodDefault<z.ZodObject<{
+            kavi: z.ZodOptional<z.ZodObject<{
+                /** Price per 1,000,000 input tokens. */
+                input: z.ZodNumber;
+                /** Price per 1,000,000 output tokens. */
+                output: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                input: number;
+                output: number;
+            }, {
+                input: number;
+                output: number;
+            }>>;
+            vaani: z.ZodOptional<z.ZodObject<{
+                /** Price per 1,000,000 input tokens. */
+                input: z.ZodNumber;
+                /** Price per 1,000,000 output tokens. */
+                output: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                input: number;
+                output: number;
+            }, {
+                input: number;
+                output: number;
+            }>>;
+            mira: z.ZodOptional<z.ZodObject<{
+                /** Price per 1,000,000 input tokens. */
+                input: z.ZodNumber;
+                /** Price per 1,000,000 output tokens. */
+                output: z.ZodNumber;
+            }, "strict", z.ZodTypeAny, {
+                input: number;
+                output: number;
+            }, {
+                input: number;
+                output: number;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            kavi?: {
+                input: number;
+                output: number;
+            } | undefined;
+            vaani?: {
+                input: number;
+                output: number;
+            } | undefined;
+            mira?: {
+                input: number;
+                output: number;
+            } | undefined;
+        }, {
+            kavi?: {
+                input: number;
+                output: number;
+            } | undefined;
+            vaani?: {
+                input: number;
+                output: number;
+            } | undefined;
+            mira?: {
+                input: number;
+                output: number;
+            } | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        retention: number;
+        currency: string;
+        prices: {
+            kavi?: {
+                input: number;
+                output: number;
+            } | undefined;
+            vaani?: {
+                input: number;
+                output: number;
+            } | undefined;
+            mira?: {
+                input: number;
+                output: number;
+            } | undefined;
+        };
+    }, {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+        currency?: string | undefined;
+        prices?: {
+            kavi?: {
+                input: number;
+                output: number;
+            } | undefined;
+            vaani?: {
+                input: number;
+                output: number;
+            } | undefined;
+            mira?: {
+                input: number;
+                output: number;
+            } | undefined;
+        } | 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 +1027,37 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy: {
         gatewayUrl: string;
     };
+    memory: {
+        enabled: boolean;
+        maxRecallTokens: number;
+    };
+    usage: {
+        enabled: boolean;
+        retention: number;
+        currency: string;
+        prices: {
+            kavi?: {
+                input: number;
+                output: number;
+            } | undefined;
+            vaani?: {
+                input: number;
+                output: number;
+            } | undefined;
+            mira?: {
+                input: number;
+                output: number;
+            } | undefined;
+        };
+    };
     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 +1113,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 +1143,37 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy?: {
         gatewayUrl?: string | undefined;
     } | undefined;
+    memory?: {
+        enabled?: boolean | undefined;
+        maxRecallTokens?: number | undefined;
+    } | undefined;
+    usage?: {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+        currency?: string | undefined;
+        prices?: {
+            kavi?: {
+                input: number;
+                output: number;
+            } | undefined;
+            vaani?: {
+                input: number;
+                output: number;
+            } | undefined;
+            mira?: {
+                input: number;
+                output: number;
+            } | undefined;
+        } | 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 +1229,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,60 @@ 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();
+/** A per-tier price, in the user's own currency, PER MILLION TOKENS (C.22). */
+export const TierPriceSchema = z
+    .object({
+    /** Price per 1,000,000 input tokens. */
+    input: z.number().nonnegative(),
+    /** Price per 1,000,000 output tokens. */
+    output: z.number().nonnegative(),
+})
+    .strict();
+/**
+ * Usage telemetry + cost tracking (C.22): LOCAL usage accounting only — nothing
+ * here is ever transmitted. Costs are opt-in and honest: prices are per-TIER and
+ * per-million-tokens, configured by the user; with none set, tokens are shown
+ * and cost is omitted (cruxy ships no bundled price table). The `prices` keys are
+ * the fixed {@link MODEL_TIERS}, so an upstream model name can never appear here
+ * (U.8 gag holds by construction) and a mistyped tier is rejected at config load.
+ */
+export const UsageConfigSchema = z
+    .object({
+    /** Master switch. When false, no usage is collected, persisted, or shown. */
+    enabled: z.boolean().default(true),
+    /** Currency label to prefix costs with (e.g. "$", "€"). Empty ⇒ no symbol is
+     * assumed — a bare number is shown, since the user configured the prices. */
+    currency: z.string().default(""),
+    /** How many past runs to keep in the store; older ones are pruned oldest-first. */
+    retention: z.number().int().positive().default(50),
+    /** Per-tier prices. Any tier omitted is simply unpriced (cost omitted for it). */
+    prices: z
+        .object({
+        kavi: TierPriceSchema.optional(),
+        vaani: TierPriceSchema.optional(),
+        mira: TierPriceSchema.optional(),
+    })
+        .strict()
+        .default({}),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -298,6 +352,8 @@ export const CruxyConfigSchema = z
     sandbox: SandboxConfigSchema.default({}),
     hooks: HooksConfigSchema.default({}),
     routing: RoutingConfigSchema.default({}),
+    memory: MemoryConfigSchema.default({}),
+    usage: UsageConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/constants.d.ts

@@ -30,6 +30,24 @@ 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";
+/**
+ * Usage telemetry + cost tracking (C.22). Per-run/per-session usage records live
+ * in the GLOBAL dir only (`~/.cruxy/usage/runs.json`), `0600` — LOCAL accounting
+ * of your own usage, never transmitted. Pure data, validated, never eval'd.
+ */
+export declare const USAGE_DIR_NAME = "usage";
+export declare const USAGE_FILE_NAME = "runs.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,24 @@ 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";
+/**
+ * Usage telemetry + cost tracking (C.22). Per-run/per-session usage records live
+ * in the GLOBAL dir only (`~/.cruxy/usage/runs.json`), `0600` — LOCAL accounting
+ * of your own usage, never transmitted. Pure data, validated, never eval'd.
+ */
+export const USAGE_DIR_NAME = "usage";
+export const USAGE_FILE_NAME = "runs.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,27 @@ 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;
+/**
+ * The local usage store (`~/.cruxy/usage/runs.json`) is corrupt or unreadable
+ * (C.22). Never fatal: usage accounting is best-effort, so the read is SKIPPED
+ * and this is surfaced. The fix is always to reset the file — its only content
+ * is your own local usage history, so deleting it loses nothing but history.
+ */
+export declare function usageRead(path: string, reason: string, underlying?: unknown): 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,70 @@ 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`",
+        ],
+    });
+}
+// ── usage telemetry (exit 2) — C.22 ───────────────────────────────────────────
+/**
+ * The local usage store (`~/.cruxy/usage/runs.json`) is corrupt or unreadable
+ * (C.22). Never fatal: usage accounting is best-effort, so the read is SKIPPED
+ * and this is surfaced. The fix is always to reset the file — its only content
+ * is your own local usage history, so deleting it loses nothing but history.
+ */
+export function usageRead(path, reason, underlying) {
+    return new CruxyError({
+        code: ErrorCode.UsageRead,
+        title: "could not read the local usage store",
+        cause: reason,
+        nextSteps: [
+            `delete ${path} to reset it (it holds only your local usage history)`,
+        ],
+        underlying,
+        meta: { path },
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({