@cruxy/cli 0.17.0 → 0.19.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. */
@@ -69,6 +72,18 @@ export interface RunAgentArgs {
     /** The declared task class for routing; defaults to `main-turn`. Ignored
      * unless `router` is set. */
     taskClass?: TaskClass;
+    /**
+     * Usage telemetry (C.22): fired ONCE per completed model request with the
+     * routing tier (C.30) and the provider's usage for THAT request — or
+     * `usage: undefined` when the provider emitted no usage event, so the caller
+     * records it as unknown (never a fabricated zero). LOCAL accounting only:
+     * this is a callback into the process, nothing is transmitted. Omitted → no
+     * collection, behavior unchanged.
+     */
+    onRequestUsage?: (req: {
+        tier?: string;
+        usage?: Usage;
+    }) => void;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps

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,
     });
@@ -80,6 +81,12 @@ async function driveLoop(args, renderer, routed) {
         let turnText = "";
         const pending = new Map();
         const toolUses = [];
+        // Per-request usage capture for telemetry (C.22). `sawUsage` is the honesty
+        // pivot: a request that emits NO usage event stays `false`, so it is reported
+        // as unknown rather than a fabricated zero. A provider-reported 0 flips it
+        // true and is recorded as a real 0.
+        let sawUsage = false;
+        const reqUsage = { input_tokens: 0, output_tokens: 0 };
         // Live progress while waiting on the model; dismissed by the first delta.
         // Token context is whatever the loop has actually accumulated (U.4): zero
         // on the first turn → no figure shown, never a fabricated number.
@@ -120,6 +127,12 @@ async function driveLoop(args, renderer, routed) {
                 case "usage":
                     usage.input_tokens = ev.usage.input_tokens || usage.input_tokens;
                     usage.output_tokens += ev.usage.output_tokens;
+                    // Mirror the accumulation into the per-request figure the telemetry
+                    // callback reports (same last-non-zero-in / summed-out semantics).
+                    sawUsage = true;
+                    reqUsage.input_tokens =
+                        ev.usage.input_tokens || reqUsage.input_tokens;
+                    reqUsage.output_tokens += ev.usage.output_tokens;
                     break;
                 case "message_stop":
                     // Turn complete; the stream ends after this.
@@ -130,6 +143,14 @@ async function driveLoop(args, renderer, routed) {
                     break;
             }
         }
+        // Request complete: report its usage honestly — the real figure when a usage
+        // event arrived, or `undefined` (unknown) when the provider reported none. A
+        // stream that threw above never reaches here, so failed requests aren't
+        // recorded with a misleading zero.
+        args.onRequestUsage?.({
+            tier: routed?.tier,
+            usage: sawUsage ? { ...reqUsage } : undefined,
+        });
         // ── Record the assistant turn ───────────────────────────────────────────
         if (turnText) {
             // Streaming (renderer set): the text already reached the user delta by

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

@@ -4,6 +4,7 @@ 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 RequestUsage, type UsageRecord } from "../usage/index.js";
 import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
 /**
  * Plan-mode turn runner (C.31), injected so the agent package doesn't depend on
@@ -14,7 +15,12 @@ import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
 export type PlanRunner = (args: {
     messages: Message[];
     projectInstructions: string | null;
+    recalledMemory: string | null;
     renderer?: StreamRenderer;
+    /** Usage telemetry (C.22): forwarded to every model request the plan-mode
+     * turn drives (propose + each execution step), so plan runs are attributed
+     * exactly like a normal turn. */
+    onRequestUsage?: (req: RequestUsage) => void;
 }) => Promise<AgentResult>;
 export interface SessionArgs {
     /** A constructed provider to stream from. */
@@ -32,6 +38,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. */
@@ -48,6 +61,12 @@ export interface SessionArgs {
      * context compaction on `summarize`; omitted → the provider default (unchanged).
      */
     router?: Router;
+    /**
+     * Usage telemetry sink (C.22): called once per `send` with that run's
+     * {@link UsageRecord} (real per-request usage, tier-attributed). The sink
+     * persists it locally — it never transmits. Omitted → no persistence.
+     */
+    onRunUsage?: (record: UsageRecord) => void;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -72,6 +91,12 @@ export declare class Session {
     messages: Message[];
     /** Token usage summed across every `send` (and every compaction) in this session. */
     readonly usage: Usage;
+    /** Stable id for this session (C.22), so a run's usage record groups with the
+     * other runs of the same interactive session (`cruxy usage --session`). */
+    readonly sessionId: string;
+    /** The most recent run's usage record (C.22) — the one-shot path reads it to
+     * print the end-of-run summary. */
+    lastRun?: UsageRecord;
     private readonly args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     private projectInstructions;
@@ -112,7 +137,7 @@ export declare class Session {
      * returns the number of older messages folded into the summary; otherwise
      * returns `null` (under threshold, nothing safe to cut, or summary failed).
      */
-    maybeCompact(): Promise<number | null>;
+    maybeCompact(onRequestUsage?: (req: RequestUsage) => void): Promise<number | null>;
     /**
      * Force compaction regardless of the threshold (backs `/compact`). Returns the
      * number of older messages summarized, or `null` if there was nothing safe to

package/dist/agent/session.js

@@ -1,5 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { loadProjectInstructions } from "../config/index.js";
 import { resolveTaskModel } from "../routing/index.js";
+import { UsageCollector, } from "../usage/index.js";
 import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
@@ -47,6 +49,12 @@ export class Session {
     messages = [];
     /** Token usage summed across every `send` (and every compaction) in this session. */
     usage = { input_tokens: 0, output_tokens: 0 };
+    /** Stable id for this session (C.22), so a run's usage record groups with the
+     * other runs of the same interactive session (`cruxy usage --session`). */
+    sessionId = randomUUID();
+    /** The most recent run's usage record (C.22) — the one-shot path reads it to
+     * print the end-of-run summary. */
+    lastRun;
     args;
     /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
     projectInstructions;
@@ -86,8 +94,15 @@ export class Session {
      */
     async send(userPrompt, renderer) {
         this.messages.push({ role: "user", content: userPrompt });
+        // Usage telemetry (C.22): one collector per run. `onReq` is threaded into
+        // every real model request this turn drives — the main loop, compaction, and
+        // (in plan mode) the propose + execution steps — so usage is captured exactly
+        // where the provider reports it, honestly (unknown when it reports nothing).
+        const collector = new UsageCollector();
+        const startedAt = new Date().toISOString();
+        const onReq = (req) => collector.record(req);
         // Compact *before* the agent call so the turn runs against a bounded history.
-        await this.maybeCompact();
+        await this.maybeCompact(onReq);
         // before-run (C.19): a blocking pre-run hook — or an untrusted project's
         // hooks — throws here and aborts the turn before the model is engaged
         // (fail-closed). No-op when hooks are disabled or none are registered.
@@ -99,7 +114,9 @@ export class Session {
             ? await this.args.planRunner({
                 messages: this.messages,
                 projectInstructions: this.projectInstructions,
+                recalledMemory: this.args.recalledMemory ?? null,
                 renderer,
+                onRequestUsage: onReq,
             })
             : await runAgent({
                 messages: this.messages,
@@ -109,10 +126,17 @@ export class Session {
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
                 renderer,
+                onRequestUsage: onReq,
             });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;
+        // Publish the run's usage record (C.22): stash it for the one-shot summary
+        // and hand it to the persistence sink. Building the record never touches the
+        // network and never blocks the turn's result.
+        const record = collector.toRecord(randomUUID(), this.sessionId, startedAt);
+        this.lastRun = record;
+        this.args.onRunUsage?.(record);
         // after-run (C.19): advisory by default (a blocking after-run hook throws
         // and surfaces at the boundary). The turn already completed and its history
         // is adopted above — an advisory failure never rewrites it.
@@ -138,12 +162,12 @@ export class Session {
      * returns the number of older messages folded into the summary; otherwise
      * returns `null` (under threshold, nothing safe to cut, or summary failed).
      */
-    async maybeCompact() {
+    async maybeCompact(onRequestUsage) {
         const { maxTokens, compactThreshold } = this.args.config.context;
         if (estimateTokens(this.messages) <= compactThreshold * maxTokens) {
             return null;
         }
-        const n = await this.runCompaction();
+        const n = await this.runCompaction(onRequestUsage);
         if (n) {
             this.args.ctx.logger.info(`compacted ${n} older message${n === 1 ? "" : "s"} to stay within context`);
         }
@@ -163,7 +187,7 @@ export class Session {
      * failed summary call leaves the history untouched and returns `null` (fail
      * open — losing compaction is degraded, not unsafe).
      */
-    async runCompaction() {
+    async runCompaction(onRequestUsage) {
         const cut = this.findCut();
         if (cut === null)
             return null;
@@ -171,7 +195,7 @@ export class Session {
         const kept = this.messages.slice(cut);
         let synopsis;
         try {
-            const summary = await this.summarize(prefix);
+            const summary = await this.summarize(prefix, onRequestUsage);
             synopsis = summary.text;
             this.usage.input_tokens += summary.usage.input_tokens;
             this.usage.output_tokens += summary.usage.output_tokens;
@@ -224,7 +248,7 @@ export class Session {
      * Summarize a prefix via a standalone, tool-less provider call over a rendered
      * transcript. Throws on a stream error or empty output so callers fail open.
      */
-    async summarize(prefix) {
+    async summarize(prefix, onRequestUsage) {
         const transcript = renderTranscript(prefix);
         const usage = { input_tokens: 0, output_tokens: 0 };
         let text = "";
@@ -233,6 +257,9 @@ export class Session {
         const routed = this.args.router
             ? resolveTaskModel(this.args.router, "summarize")
             : null;
+        // Per-request usage capture for telemetry (C.22), same honesty pivot as the
+        // main loop: unknown unless a usage event actually arrives.
+        let sawUsage = false;
         for await (const ev of this.args.provider.stream({
             system: SUMMARY_SYSTEM,
             messages: [{ role: "user", content: transcript }],
@@ -245,6 +272,7 @@ export class Session {
                 case "usage":
                     usage.input_tokens = ev.usage.input_tokens || usage.input_tokens;
                     usage.output_tokens += ev.usage.output_tokens;
+                    sawUsage = true;
                     break;
                 case "error":
                     throw ev.error;
@@ -252,6 +280,11 @@ export class Session {
                     break;
             }
         }
+        // Attribute this compaction request to the `summarize` tier honestly.
+        onRequestUsage?.({
+            tier: routed?.tier,
+            usage: sawUsage ? { ...usage } : undefined,
+        });
         if (!text.trim())
             throw new Error("summary was empty");
         return { text: text.trim(), usage };

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/run.js

@@ -4,6 +4,7 @@ import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
+import { summarizeRuns, renderSummary, } from "../../usage/index.js";
 import { CheckpointService } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
 import { buildHooksService } from "../../hooks/index.js";
@@ -110,5 +111,23 @@ export function runCommand() {
         finally {
             renderer.close();
         }
+        // End-of-run usage summary (C.22): honest tokens + per-tier breakdown +
+        // cost (only when priced). Printed after the live region is torn down.
+        // Reaches here only on success — a thrown run propagates past it — and
+        // never affects the run's outcome.
+        if (config.usage.enabled && session.lastRun) {
+            printRunUsage(session.lastRun, config);
+        }
+    });
+}
+/** Render the just-finished run's usage as a single themed line (C.22). */
+function printRunUsage(record, config) {
+    if (record.entries.length === 0)
+        return;
+    const t = themeForColor(shouldUseColor(process.stdout));
+    const summary = summarizeRuns([record], {
+        prices: config.usage.prices,
+        currency: config.usage.currency,
     });
+    logger.print(renderSummary(summary, t));
 }

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

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+/**
+ * `cruxy usage` (C.22) — show LOCAL token usage and (when priced) cost, read
+ * back from `~/.cruxy/usage`. Read-only and local: it prints your own accounting
+ * and transmits nothing. Every figure is real — a request the provider never
+ * reported usage for is shown as unreported, never a fabricated number, and cost
+ * appears only for tiers you have priced.
+ */
+export declare function usageCommand(): Command;

package/dist/cli/commands/usage.js

@@ -0,0 +1,81 @@
+import { Command } from "commander";
+import { loadConfig } from "../../config/index.js";
+import { shouldUseColor, usageError } from "../../errors/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { logger } from "../../utils/logger.js";
+import { loadUsage, summarizeRuns, renderSummary, } from "../../usage/index.js";
+/**
+ * `cruxy usage` (C.22) — show LOCAL token usage and (when priced) cost, read
+ * back from `~/.cruxy/usage`. Read-only and local: it prints your own accounting
+ * and transmits nothing. Every figure is real — a request the provider never
+ * reported usage for is shown as unreported, never a fabricated number, and cost
+ * appears only for tiers you have priced.
+ */
+export function usageCommand() {
+    return new Command("usage")
+        .description("show token usage and cost for the session and recent runs")
+        .option("--session", "only the most recent session's runs")
+        .option("--last <n>", "only the last N runs")
+        .action((opts) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        // A corrupt/unreadable store is surfaced as CRUXY_E_USAGE_READ with an
+        // actionable fix — it is not silently ignored, and it never crashes.
+        const { data, error } = loadUsage();
+        if (error)
+            throw error;
+        const scoped = selectRuns(data.runs, opts);
+        if (scoped.length === 0) {
+            logger.print(t.muted("no usage recorded yet"));
+            if (!config.usage.enabled) {
+                logger.print(t.muted("usage tracking is off (usage.enabled = false)"));
+            }
+            return;
+        }
+        const summary = summarizeRuns(scoped, {
+            prices: config.usage.prices,
+            currency: config.usage.currency,
+        });
+        const scopeLabel = opts.session
+            ? "current session"
+            : opts.last
+                ? `last ${scoped.length} run${scoped.length === 1 ? "" : "s"}`
+                : `all ${scoped.length} run${scoped.length === 1 ? "" : "s"}`;
+        logger.print(t.heading(`usage — ${scopeLabel}`));
+        logger.print(renderSummary(summary, t));
+        // State when NO price is configured, so an absent cost never reads as $0.
+        if (!summary.priced) {
+            logger.print(t.muted("cost omitted — no prices configured (set usage.prices.<tier>.{input,output}, per million tokens)"));
+        }
+    });
+}
+/**
+ * Narrow the stored runs to the requested scope. `--last N` keeps the newest N;
+ * `--session` keeps the runs sharing the most recent run's session id; no flag
+ * keeps everything retained. `--session` and `--last` are mutually exclusive.
+ */
+function selectRuns(runs, opts) {
+    if (opts.session && opts.last !== undefined) {
+        throw usageError("pass only one of --session or --last", [
+            "cruxy usage --session   (the most recent session)",
+            "cruxy usage --last 5    (the last 5 runs)",
+        ]);
+    }
+    if (opts.last !== undefined) {
+        const n = Number(opts.last);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw usageError(`--last must be a positive integer (got "${opts.last}")`);
+        }
+        return runs.slice(-n);
+    }
+    if (opts.session) {
+        const latest = runs[runs.length - 1];
+        if (!latest)
+            return [];
+        // Runs without a session id can't be grouped; scope to the latest run alone.
+        if (latest.sessionId === undefined)
+            return [latest];
+        return runs.filter((r) => r.sessionId === latest.sessionId);
+    }
+    return [...runs];
+}

package/dist/cli/program.js

@@ -15,6 +15,8 @@ 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 { usageCommand } from "./commands/usage.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -45,6 +47,8 @@ export function buildProgram() {
     program.addCommand(rollbackCommand());
     program.addCommand(testCommand());
     program.addCommand(hooksCommand());
+    program.addCommand(memoryCommand());
+    program.addCommand(usageCommand());
     // 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,8 @@ 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 { appendRun } from "../usage/index.js";
 import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
  * Wrap a PromptIO so the live region yields before any prompt text lands
@@ -101,9 +103,39 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     // 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;
+    // Usage telemetry (C.22): when enabled, each run's usage record is persisted
+    // to the LOCAL store. Best-effort and non-fatal — a corrupt/unwritable store
+    // is downgraded to a warning (CRUXY_E_USAGE_READ) and NEVER takes a run down.
+    // Nothing is transmitted. Off → the sink is undefined and no usage is written.
+    const onRunUsage = config.usage.enabled
+        ? (record) => {
+            const { error } = appendRun(record, {
+                retention: config.usage.retention,
+            });
+            if (error)
+                logger.warn(`${error.code}: ${error.title} — ${error.cause}`);
+        }
+        : 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
@@ -150,7 +182,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, onRequestUsage, }) => runPlanSession({
             provider,
             config,
             ctx,
@@ -161,8 +193,10 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             messages,
             git,
             projectInstructions,
+            recalledMemory: turnMemory,
             renderer: turnRenderer,
             router,
+            onRequestUsage,
         });
         return new Session({
             provider,
@@ -171,10 +205,12 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             ctx,
             git,
             projectInstructions,
+            recalledMemory,
             planMode: true,
             planRunner,
             hooks,
             router,
+            onRunUsage,
         });
     }
     const approval = new ApprovalService({
@@ -190,7 +226,9 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         ctx,
         git,
         projectInstructions,
+        recalledMemory,
         hooks,
         router,
+        onRunUsage,
     });
 }