@gamaze/hicortex 0.17.1 → 0.17.3

package/dist/consolidate.js

@@ -38,8 +38,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SUPERSESSION_MAX_CALLS = exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = exports.CONSOLIDATE_MAX_LLM_CALLS = void 0;
+exports.DEFAULT_MEMORY_SOFT_CAP = exports.DEFAULT_SUPERSESSION_MAX_CALLS = exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = exports.CONSOLIDATE_MAX_LLM_CALLS = void 0;
 exports.isContradictionCandidate = isContradictionCandidate;
+exports.shouldThrottleTokens = shouldThrottleTokens;
 exports.parseJsonLenient = parseJsonLenient;
 exports.rebuildContentModuleIndex = rebuildContentModuleIndex;
 exports.discoverLinkCandidates = discoverLinkCandidates;
@@ -49,6 +50,7 @@ exports.buildSupersessionPrompt = buildSupersessionPrompt;
 exports.parseSupersessionReply = parseSupersessionReply;
 exports.stageSupersession = stageSupersession;
 exports.stageDecayPrune = stageDecayPrune;
+exports.stageMemoryCapEviction = stageMemoryCapEviction;
 exports.runConsolidation = runConsolidation;
 exports.msUntilHour = msUntilHour;
 exports.scheduleConsolidation = scheduleConsolidation;
@@ -125,6 +127,19 @@ class BudgetTracker {
     maxCalls;
     callsUsed = 0;
     callsByStage = {};
+    /**
+     * Token usage per stage (#246). Keys are the same stage labels passed to
+     * `use()`. A stage that made no metered calls (no usage returned — never the
+     * path on a healthy openai/ollama endpoint) is absent, NOT zero, so the
+     * dashboard can distinguish "nothing spent" from "no signal".
+     */
+    tokensByStage = {};
+    /** Run-wide totals — the sum of every recordUsage() call this run. */
+    totalTokens = {
+        prompt: 0,
+        completion: 0,
+        total: 0,
+    };
     constructor(maxCalls) {
         this.maxCalls = maxCalls;
     }
@@ -144,17 +159,73 @@ class BudgetTracker {
         this.callsByStage[stage] = (this.callsByStage[stage] ?? 0) + count;
         return true;
     }
+    /**
+     * Record token usage from one LLM call (#246). Called by the consolidation
+     * stages after each metered completion. `undefined` usage (claude-cli path,
+     * or a non-conforming endpoint that returned no usage object) is a no-op —
+     * never recorded as zero, which would silently undercount real spend.
+     */
+    recordUsage(stage, usage) {
+        if (!usage)
+            return;
+        const cur = this.tokensByStage[stage] ?? { prompt: 0, completion: 0, total: 0 };
+        cur.prompt += usage.prompt_tokens;
+        cur.completion += usage.completion_tokens;
+        cur.total += usage.total_tokens;
+        this.tokensByStage[stage] = cur;
+        this.totalTokens.prompt += usage.prompt_tokens;
+        this.totalTokens.completion += usage.completion_tokens;
+        this.totalTokens.total += usage.total_tokens;
+    }
     summary() {
         return {
             max_calls: this.maxCalls,
             calls_used: this.callsUsed,
             calls_remaining: this.remaining,
             calls_by_stage: { ...this.callsByStage },
+            tokens_by_stage: Object.fromEntries(Object.entries(this.tokensByStage).map(([k, v]) => [k, { ...v }])),
+            tokens_total: { ...this.totalTokens },
         };
     }
 }
 exports.BudgetTracker = BudgetTracker;
 // ---------------------------------------------------------------------------
+// Token fair-use throttle decision (#246)
+// ---------------------------------------------------------------------------
+/**
+ * Decide whether consolidation should be throttled this run based on the
+ * `llmTokensPerMonth` fair-use cap. Pure (no I/O) so it can be unit-tested
+ * independently of the nightly wiring.
+ *
+ * Returns `{ throttle: true, used, cap }` when the projected post-run total
+ * would exceed the cap; `{ throttle: false }` otherwise. The estimate is the
+ * previous run's actual usage (`llmTokensLastRun`, 0/absent on the first
+ * metered run = never throttle the first run — no baseline yet).
+ *
+ * `cap = 0` (the self-hosted default) → never throttle (unlimited).
+ * `periodStart` in a previous calendar month → period resets to 0 first
+ * (mirrors the reset logic in nightly.ts; both sides agree because both read
+ * the same state + clock).
+ */
+function shouldThrottleTokens(cap, period, lastRunTokens, now = new Date()) {
+    if (cap <= 0)
+        return { throttle: false };
+    let periodTotal = period?.total ?? 0;
+    const periodStart = period?.periodStart;
+    if (periodStart) {
+        const start = new Date(periodStart);
+        if (start.getUTCFullYear() !== now.getUTCFullYear() ||
+            start.getUTCMonth() !== now.getUTCMonth()) {
+            // Stale period → reset accrual to 0 before the check.
+            periodTotal = 0;
+        }
+    }
+    if (periodTotal + lastRunTokens > cap) {
+        return { throttle: true, used: periodTotal, cap };
+    }
+    return { throttle: false };
+}
+// ---------------------------------------------------------------------------
 // JSON parsing helper
 // ---------------------------------------------------------------------------
 /**
@@ -239,8 +310,9 @@ async function stageImportance(db, memories, llm, budget, dryRun) {
             break;
         }
         try {
-            const raw = await llm.completeFast(prompt, 256);
-            let scores = parseJsonLenient(raw, null);
+            const r = await llm.completeFast(prompt, 256);
+            budget.recordUsage("importance", r.usage);
+            let scores = parseJsonLenient(r.text, null);
             if (!Array.isArray(scores)) {
                 scores = new Array(batch.length).fill(0.5);
             }
@@ -300,8 +372,9 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
         return { lessons_generated: 0, skipped: true, reason: "budget_exhausted" };
     }
     try {
-        const raw = await llm.completeReflect(prompt, 2048);
-        const lessons = parseJsonLenient(raw, []);
+        const r = await llm.completeReflect(prompt, 2048);
+        budget.recordUsage("reflection", r.usage);
+        const lessons = parseJsonLenient(r.text, []);
         if (!Array.isArray(lessons)) {
             return { lessons_generated: 0, failed: true };
         }
@@ -349,9 +422,14 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                     const existingText = similarLessons[0].content.slice(0, 300);
                     const newText = content.slice(0, 300);
                     try {
-                        const verdict = await llm.completeFast(`Two lessons from an AI memory system. Do they CONTRADICT each other (opposite advice on the same topic)?\n\n` +
+                        const verdictR = await llm.completeFast(`Two lessons from an AI memory system. Do they CONTRADICT each other (opposite advice on the same topic)?\n\n` +
                             `EXISTING: ${existingText}\n\nNEW: ${newText}\n\n` +
                             `Answer ONLY "yes" or "no". If the new lesson updates/refines the existing one (not contradicts), answer "no".`, 16);
+                        // Stage label "contradiction_check" matches the budget.use() call
+                        // above (separate counter from the reflection call proper). Token
+                        // accounting follows the same stage partition as the call counter.
+                        budget.recordUsage("contradiction_check", verdictR.usage);
+                        const verdict = verdictR.text;
                         if (verdict.toLowerCase().trim().startsWith("yes")) {
                             contradicted = true;
                             console.log(`[hicortex] Lesson suppressed (contradicts existing): "${lessonText.slice(0, 80)}"`);
@@ -462,7 +540,10 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
             // classifyMemoryTags returns null ONLY on infra error (throws after retry) —
             // skip that memory, leaving domain/tags/strength untouched so a later
             // run retries it (issue #150: never file or decay on infra errors).
-            const result = await (0, domain_classify_js_1.classifyMemoryTags)(row.content, row.project, domains, llm);
+            // The onUsage callback (#246) wires the metered call's token accounting
+            // into this stage's BudgetTracker slot — same stage label the budget.use
+            // call above uses, so call count + tokens stay aligned.
+            const result = await (0, domain_classify_js_1.classifyMemoryTags)(row.content, row.project, domains, llm, (u) => budget.recordUsage("content_domain", u));
             if (result === null) {
                 console.warn(`[hicortex] content-domain: infra error classifying ${row.id} — skipped (will retry)`);
                 continue;
@@ -599,8 +680,9 @@ async function stageDomainCuration(db, llm, budget, dryRun, stateDir) {
             .map((r) => `${r.project}: ${r.cnt} / ${lessonsByProject.get(r.project) ?? 0}`)
             .join("\n");
         try {
-            const raw = await llm.completeFast((0, prompts_js_1.domainCuration)(projectLines), 1024);
-            const parsed = parseJsonLenient(raw, []);
+            const r = await llm.completeFast((0, prompts_js_1.domainCuration)(projectLines), 1024);
+            budget.recordUsage("domain_curation", r.usage);
+            const parsed = parseJsonLenient(r.text, []);
             if (!Array.isArray(parsed) || parsed.length === 0) {
                 console.warn("[hicortex] Domain curation: LLM returned empty/invalid response, using fallback");
                 domains = projectRows.map((r) => ({
@@ -934,16 +1016,19 @@ function parseSupersessionReply(reply) {
 }
 /**
  * ONE classify-tier LLM call judging whether `newContent` supersedes
- * `oldContent`. Returns null on any infra error or unparseable reply — the
- * caller treats null as "skip this pair" (never mis-links on ambiguity).
+ * `oldContent`. Returns `{verdict, usage}` — verdict is null on any infra error
+ * or unparseable reply (the caller treats null as "skip this pair", never
+ * mis-links on ambiguity). `usage` is the call's token accounting (#246),
+ * surfaced even on a null verdict so the BudgetTracker still meters a
+ * network-round-tripped attempt (the cost is real even if the parse failed).
  */
 async function classifySupersession(llm, oldContent, newContent) {
     try {
-        const raw = await llm.completeClassify(buildSupersessionPrompt(oldContent, newContent), 32);
-        return parseSupersessionReply(raw);
+        const r = await llm.completeClassify(buildSupersessionPrompt(oldContent, newContent), 32);
+        return { verdict: parseSupersessionReply(r.text), usage: r.usage };
     }
     catch {
-        return null;
+        return { verdict: null, usage: undefined };
     }
 }
 /**
@@ -1033,7 +1118,10 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
             if (callsUsed >= maxCalls || !budget.use("supersession"))
                 break;
             callsUsed++;
-            const verdict = await classifySupersession(llm, neighbor.content, candidate.content);
+            const { verdict, usage } = await classifySupersession(llm, neighbor.content, candidate.content);
+            // Meter every round-tripped attempt (#246) — even a null verdict spent
+            // real tokens. The stage label matches the budget.use() above.
+            budget.recordUsage("supersession", usage);
             evaluated++;
             if (verdict === null) {
                 skippedInfra++;
@@ -1111,11 +1199,100 @@ function stageDecayPrune(db, dryRun) {
     }
     return { candidates, pruned, failed };
 }
+// ---------------------------------------------------------------------------
+// Stage 4.5: Memory cap eviction (#245)
+// ---------------------------------------------------------------------------
+//
+// The active forgetting mechanism. The pre-#245 prune (stageDecayPrune above)
+// is inert by design — the strength floor (~0.3162) + the `< 0.01` threshold +
+// the 365-day decay half-life means a never-accessed memory takes ~3 years to
+// become eligible, so the corpus grew without bound. This stage bounds it:
+// when the count exceeds `memorySoftCap`, the lowest-effectiveStrength
+// memories are evicted until under the cap.
+//
+// Eviction reuses the SAME effectiveStrength() the recall ranker uses — no
+// formula duplication, so the eviction criterion cannot drift from what
+// surfaces in the top-k. The evicted tail is, by construction, the tail that
+// was not surfacing anyway (cold, decayed). Ties are broken by oldest
+// COALESCE(last_accessed, created_at) — i.e. the memories that have gone
+// longest without anyone looking at them.
+//
+// `cap = 0` disables the stage (indefinite growth — the pre-#245 default is
+// preserved opt-out). The JS-side sort is O(n log n); at 10K memories the
+// load + compute is <100 ms, a rounding error against the LLM-bound phases.
+/**
+ * Default soft cap on the memory corpus (#245). Above this the lowest-value
+ * memories are evicted each nightly. 10000 balances headroom for a busy
+ * self-hosted install against the noise cost of a bloated vector index
+ * (recall top-k competes against the long tail). Override via `memorySoftCap`.
+ */
+exports.DEFAULT_MEMORY_SOFT_CAP = 10000;
+function stageMemoryCapEviction(db, dryRun, cap) {
+    // `0` = explicitly disabled (current/legacy behaviour). The guard is on `<=`
+    // not `===` to also absorb a stray negative (readNonNegativeConfig already
+    // rejects negatives at the boundary, but this stage is callable directly).
+    if (cap <= 0)
+        return { cap, evicted: 0 };
+    const count = storage.countMemories(db);
+    if (count <= cap)
+        return { cap, evicted: 0 };
+    const surplus = count - cap;
+    // Load the fields effectiveStrength needs + the tiebreak. base_strength is
+    // NOT NULL after scoring; the `?? 0.5` mirrors stageDecayPrune's defensive
+    // default for unscored rows (inserts at 0.5). last_accessed is NULL until
+    // first /recall-index exposure — COALESCE to created_at for the tiebreak so
+    // never-shown memories sort by when they entered the corpus.
+    const rows = db
+        .prepare(`SELECT id, base_strength, last_accessed, access_count, created_at
+         FROM memories`)
+        .all();
+    const linkCounts = storage.getAllLinkCounts(db);
+    const now = new Date();
+    // Decorate + sort: lowest effectiveStrength first; ties broken by oldest
+    // COALESCE(last_accessed, created_at). The victims are the first `surplus`.
+    const decorated = rows.map((r) => {
+        const eff = (0, retrieval_js_1.effectiveStrength)(r.base_strength ?? 0.5, r.last_accessed, now, {
+            accessCount: r.access_count ?? 0,
+            linkCount: linkCounts.get(r.id) ?? 0,
+        });
+        return {
+            id: r.id,
+            eff,
+            lastTouch: r.last_accessed ?? r.created_at,
+        };
+    });
+    decorated.sort((a, b) => 
+    // ASC by effectiveStrength, then ASC by lastTouch (oldest first = evict).
+    a.eff !== b.eff ? a.eff - b.eff
+        : a.lastTouch < b.lastTouch ? -1 : a.lastTouch > b.lastTouch ? 1 : 0);
+    const victims = decorated.slice(0, surplus);
+    if (dryRun) {
+        console.log(`[hicortex] Memory cap eviction (dry-run): would remove ${victims.length} ` +
+            `lowest-value memories (corpus ${count}, cap ${cap}).`);
+        return { cap, evicted: victims.length };
+    }
+    // deleteMemory cascades: memory_links (both directions), memory_tags,
+    // memory_vectors, and the FTS index (via the AFTER DELETE trigger on
+    // memories, db.ts — no manual FTS cleanup needed). Wrap the batch in a
+    // transaction so a failure leaves the corpus consistent (all-or-nothing).
+    const tx = db.transaction(() => {
+        for (const v of victims)
+            storage.deleteMemory(db, v.id);
+    });
+    tx();
+    console.log(`[hicortex] Memory cap eviction: removed ${victims.length} lowest-value ` +
+        `memories (corpus was ${count}, cap ${cap}).`);
+    return { cap, evicted: victims.length };
+}
 async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection = false, stateDir, domainOptions, supersessionOptions, 
 /** Total LLM-call ceiling across classify-tier stages (#241). The caller
  *  reads `consolidateMaxLlmCalls` from config and passes it; unset → the
  *  exported `CONSOLIDATE_MAX_LLM_CALLS` default (5000). */
-budgetMaxCalls) {
+budgetMaxCalls, 
+/** Soft cap on the corpus (#245). Nightly.ts reads `memorySoftCap` from
+ *  config and passes it; unset → `DEFAULT_MEMORY_SOFT_CAP` (10000). `0`
+ *  disables eviction (indefinite growth). */
+memorySoftCap) {
     const start = new Date();
     const report = {
         started_at: start.toISOString(),
@@ -1141,6 +1318,10 @@ budgetMaxCalls) {
         new_memory_count: precheck.newMemories.length,
         unscored_count: scoreMemories.length - precheck.newMemories.length,
     };
+    // Memory cap eviction (#245) — runs BEFORE the precheck skip so the corpus
+    // is bounded even on quiet nights (no new memories → precheck would skip,
+    // but the cap stage is pure DB: cheap, idempotent when under cap).
+    report.stages.memory_cap = stageMemoryCapEviction(db, dryRun, memorySoftCap ?? exports.DEFAULT_MEMORY_SOFT_CAP);
     if (skip) {
         report.status = "skipped";
         report.completed_at = new Date().toISOString();
@@ -1192,6 +1373,7 @@ budgetMaxCalls) {
         report.stages.supersession = await stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, supersessionOptions);
         // Stage 4: Decay & Prune
         report.stages.decay_prune = stageDecayPrune(db, dryRun);
+        // (Memory cap eviction moved before the precheck skip — see above.)
     }
     catch (err) {
         report.status = "failed";

package/dist/dashboard.d.ts

@@ -38,6 +38,27 @@ export interface DashboardMetrics {
         lessonsGenerated?: number;
         dedup: number;
         supersession: number;
+        /** Memories evicted by the capacity stage this run (#245). 0 when under
+         *  cap; undefined on backfill rows (a stage outcome, not reconstructable). */
+        evicted?: number;
+        /**
+         * Total LLM tokens consumed by this run's consolidation (#246). Undefined
+         * in lockstep with `tokens_by_stage` (and on backfill rows, which can't
+         * reconstruct a per-run meter).
+         */
+        tokens?: number;
+        /** Per-stage breakdown of `tokens` (#246). Undefined on backfill rows. */
+        tokens_by_stage?: Record<string, {
+            prompt: number;
+            completion: number;
+            total: number;
+        }>;
+    };
+    /** Corpus capacity (#245). `memory_soft_cap` is the configured ceiling (0 =
+     *  disabled); always present in real snapshots, undefined on backfilled
+     *  rows (the historical config isn't recoverable from created_at). */
+    capacity?: {
+        memory_soft_cap: number;
     };
     /** Recall adoption aggregate. Null in backfilled rows. uses_per_showing is
      *  null when shown_sum = 0 (divide-by-zero guard). */
@@ -55,12 +76,28 @@ export interface DashboardSnapshot {
 }
 /** The /dashboard/data response — the full payload the page renders. */
 export interface DashboardData {
-    range: "7d" | "30d" | "90d" | "all";
     headline: {
         total_memories: number;
         uses_per_showing: number | null;
         cold_count: number;
+        /** Corpus vs cap (#245). `memory_soft_cap` is 0 when the cap is disabled
+         *  (indefinite growth); the page renders no gauge in that case. */
+        memory_soft_cap: number;
+        /**
+         * LLM token usage this billing period (#246). `used` is the running total
+         * (state.llmTokensThisPeriod.total after monthly reset); `cap` is the
+         * configured `llmTokensPerMonth` (0 = unlimited, page renders no cap).
+         * `used` is 0 when no consolidation has metered tokens yet — the page
+         * hides the stat in that case. `period_start` is the ISO timestamp of the
+         * current accrual period (for the "X this month" label).
+         */
+        tokens: {
+            used: number;
+            cap: number;
+            period_start: string | null;
+        };
     };
+    range: "7d" | "30d" | "90d" | "all";
     series: DashboardSnapshot[];
     composition: {
         by_type: Record<string, number>;
@@ -85,6 +122,15 @@ export interface DashboardData {
             dedup: number;
             supersession: number;
             added: number;
+            evicted?: number;
+            /** Total tokens consumed that run (#246). Undefined = no metered run. */
+            tokens?: number;
+            /** Per-stage breakdown of `tokens` (#246). */
+            tokens_by_stage?: Record<string, {
+                prompt: number;
+                completion: number;
+                total: number;
+            }>;
         };
         dedup_merges: {
             loser_id: string;
@@ -105,14 +151,37 @@ export interface NightlyDelta {
     lessonsGenerated?: number;
     dedup: number;
     supersession: number;
+    /** Memories evicted by the capacity stage this run (#245). */
+    evicted?: number;
+    /**
+     * Total LLM tokens consumed by this run's consolidation (#246). Undefined
+     * when consolidation didn't run (capture-only / no_llm / throttled / skipped)
+     * or made no metered calls. Stamped into the snapshot so the dashboard can
+     * show a usage trend.
+     */
+    tokensThisRun?: number;
+    /**
+     * Per-stage breakdown of `tokensThisRun` (#246) — same shape as
+     * ConsolidationReport.budget.tokens_by_stage. Undefined in lockstep with
+     * `tokensThisRun`.
+     */
+    tokensByStage?: Record<string, {
+        prompt: number;
+        completion: number;
+        total: number;
+    }>;
 }
 /**
  * Write one snapshot row for `runAt` (an ISO timestamp the caller chooses —
  * nightly.ts passes `now`). OR-replace on the PRIMARY KEY is intentional: a
  * manual re-run for the same instant overwrites, the nightly never produces
  * two rows for the same instant. Returns the row that was written.
+ *
+ * `memorySoftCap` (#245) is the resolved cap (0 = disabled) from the config;
+ * it is stamped into `metrics.capacity` so a historical snapshot records what
+ * cap produced its eviction count. Optional for callers that don't track it.
  */
-export declare function writeSnapshot(db: Database.Database, runAt: string, delta: NightlyDelta): DashboardSnapshot;
+export declare function writeSnapshot(db: Database.Database, runAt: string, delta: NightlyDelta, memorySoftCap?: number): DashboardSnapshot;
 /**
  * When the dashboard_snapshots table is empty, synthesize one row per day from
  * existing memories. Idempotent (only runs when the table is empty — the

package/dist/dashboard.js

@@ -27,6 +27,8 @@ exports.handleDashboardData = handleDashboardData;
 exports.dashboardDataHandler = dashboardDataHandler;
 const recall_index_js_1 = require("./recall-index.js");
 const config_read_js_1 = require("./config-read.js");
+const consolidate_js_1 = require("./consolidate.js");
+const state_js_1 = require("./state.js");
 // ---------------------------------------------------------------------------
 // Metric computation — one SELECT each, prepared inline. Pure: takes a db,
 // returns a value. No side effects, no I/O beyond the open db handle.
@@ -83,15 +85,28 @@ function computeDashboardMetrics(db) {
  * nightly.ts passes `now`). OR-replace on the PRIMARY KEY is intentional: a
  * manual re-run for the same instant overwrites, the nightly never produces
  * two rows for the same instant. Returns the row that was written.
+ *
+ * `memorySoftCap` (#245) is the resolved cap (0 = disabled) from the config;
+ * it is stamped into `metrics.capacity` so a historical snapshot records what
+ * cap produced its eviction count. Optional for callers that don't track it.
  */
-function writeSnapshot(db, runAt, delta) {
+function writeSnapshot(db, runAt, delta, memorySoftCap) {
     const metrics = computeDashboardMetrics(db);
     metrics.new_this_run = {
         added: delta.added,
         lessonsGenerated: delta.lessonsGenerated,
         dedup: delta.dedup,
         supersession: delta.supersession,
+        evicted: delta.evicted,
+        // #246: forward only when consolidation actually metered tokens this run.
+        // Absent on capture-only / throttled / no-LLM / no-metered-call runs — the
+        // page treats undefined as "no data for this day", matching adoption.
+        ...(delta.tokensThisRun !== undefined ? { tokens: delta.tokensThisRun } : {}),
+        ...(delta.tokensByStage !== undefined ? { tokens_by_stage: delta.tokensByStage } : {}),
     };
+    if (memorySoftCap !== undefined) {
+        metrics.capacity = { memory_soft_cap: memorySoftCap };
+    }
     db.prepare("INSERT OR REPLACE INTO dashboard_snapshots (run_at, metrics) VALUES (?, ?)").run(runAt, JSON.stringify(metrics));
     return { run_at: runAt, metrics };
 }
@@ -295,10 +310,25 @@ function handleDashboardData(db, query, config) {
     // Live composition (so day-one with no snapshots still shows the corpus).
     const live = computeDashboardMetrics(db);
     // Headline = live corpus (the chart shows history; the headline shows now).
+    // `memory_soft_cap` (#245): resolve from the live config (the source of
+    // truth for "what cap is in force right now"), defaulting to the production
+    // default. The page renders no gauge when it's 0 (disabled).
+    //
+    // `tokens` (#246): period accrual from state.json (the same single source
+    // the throttle check reads, so the dashboard always agrees with the runtime
+    // decision). The cap is `llmTokensPerMonth` (0 = unlimited). The page hides
+    // the stat entirely when `used` is 0 (no metered run yet).
+    const tokenState = (0, state_js_1.loadState)().llmTokensThisPeriod;
     const headline = {
         total_memories: live.totals.mem,
         uses_per_showing: live.adoption?.uses_per_showing ?? null,
         cold_count: live.adoption?.cold_count ?? 0,
+        memory_soft_cap: (0, config_read_js_1.readNonNegativeConfig)(config ?? {}, "memorySoftCap", consolidate_js_1.DEFAULT_MEMORY_SOFT_CAP),
+        tokens: {
+            used: tokenState?.total ?? 0,
+            cap: (0, config_read_js_1.readNonNegativeConfig)(config ?? {}, "llmTokensPerMonth", 0),
+            period_start: tokenState?.periodStart ?? null,
+        },
     };
     // Digest: pick the day to summarize. `date` (YYYY-MM-DD) wins; else the most
     // recent snapshot's day (real nightly OR backfill — both carry valid ISO
@@ -369,6 +399,11 @@ function handleDashboardData(db, query, config) {
             dedup: dayMetrics?.new_this_run?.dedup ?? dedupRows.length,
             supersession: dayMetrics?.new_this_run?.supersession ?? supersessionCount,
             added: dayMetrics?.new_this_run?.added ?? sampleRows.length,
+            evicted: dayMetrics?.new_this_run?.evicted,
+            // #246: only present when the day's nightly metered tokens. Both fields
+            // are forwarded together — the page renders either the breakdown or nothing.
+            tokens: dayMetrics?.new_this_run?.tokens,
+            tokens_by_stage: dayMetrics?.new_this_run?.tokens_by_stage,
         },
         dedup_merges: dedupRows.map((r) => ({
             loser_id: r.loser_id,

package/dist/distiller.js

@@ -312,7 +312,7 @@ async function distillChunk(llm, transcript, projectName, date) {
     // failures, 4xx/5xx, model-not-found, timeouts) propagate up to the caller
     // so the nightly pipeline can treat them as "retry later" instead of
     // "processed successfully with zero extractions".
-    const result = await llm.completeDistill(prompt);
+    const { text: result } = await llm.completeDistill(prompt);
     if (!result)
         return { entries: [], dropped: [] };
     if (result === "NO_EXTRACT" || result.slice(0, 20).includes("NO_EXTRACT")) {

package/dist/domain-classify.d.ts

@@ -50,7 +50,7 @@
  *   Work, Ventures, Hardware, Finances, Property, Vehicles, Boating, Health,
  *   Family, People, Travel
  */
-import type { LlmClient } from "./llm.js";
+import type { LlmClient, LlmUsage } from "./llm.js";
 import type { DomainDef } from "./types.js";
 export type { DomainDef };
 /** Max characters of memory content fed to the classifier prompt. */
@@ -160,5 +160,11 @@ export declare function parseTagReply(reply: string, domains: DomainDef[]): TagR
  *
  * @returns {tags} on success (all members of the vocabulary; empty = no-fit),
  *          or null on infra error.
+ *
+ * `onUsage` (#246) is an optional callback fired ONCE with the LlmUsage from
+ * the SUCCESSFUL attempt (the one whose reply parsed). Throwing/unparseable
+ * attempts don't fire it — only the call that produced the kept result is
+ * metered. The consolidation caller wires this to BudgetTracker.recordUsage;
+ * the CLI caller (classify-domains) has no tracker and omits it.
  */
-export declare function classifyMemoryTags(content: string, project: string | null | undefined, domains: DomainDef[], llm: LlmClient): Promise<TagResult | null>;
+export declare function classifyMemoryTags(content: string, project: string | null | undefined, domains: DomainDef[], llm: LlmClient, onUsage?: (usage: LlmUsage) => void): Promise<TagResult | null>;

package/dist/domain-classify.js

@@ -257,8 +257,14 @@ function parseTagReply(reply, domains) {
  *
  * @returns {tags} on success (all members of the vocabulary; empty = no-fit),
  *          or null on infra error.
+ *
+ * `onUsage` (#246) is an optional callback fired ONCE with the LlmUsage from
+ * the SUCCESSFUL attempt (the one whose reply parsed). Throwing/unparseable
+ * attempts don't fire it — only the call that produced the kept result is
+ * metered. The consolidation caller wires this to BudgetTracker.recordUsage;
+ * the CLI caller (classify-domains) has no tracker and omits it.
  */
-async function classifyMemoryTags(content, project, domains, llm) {
+async function classifyMemoryTags(content, project, domains, llm, onUsage) {
     if (domains.length === 0)
         return { tags: [] };
     const prompt = buildClassifyPrompt(content, project, domains);
@@ -268,8 +274,19 @@ async function classifyMemoryTags(content, project, domains, llm) {
         let raw;
         try {
             // ~64 tokens covers a short JSON object with a handful of tags.
-            raw = await llm.completeClassify(prompt, 64);
+            const r = await llm.completeClassify(prompt, 64);
+            raw = r.text;
             threw = false;
+            // Surface the usage ONLY when this attempt's reply parses (below). Hold
+            // the value across the parse check so the metered call is the one whose
+            // result is actually kept.
+            const heldUsage = r.usage;
+            const parsed = parseTagReply(raw, domains);
+            if (parsed) {
+                if (heldUsage && onUsage)
+                    onUsage(heldUsage);
+                return parsed;
+            }
         }
         catch (err) {
             threw = true;
@@ -278,9 +295,6 @@ async function classifyMemoryTags(content, project, domains, llm) {
             console.warn(`[hicortex] tag classify LLM error: ${err instanceof Error ? err.message : String(err)} — aborting this memory (will retry)`);
             return null; // infra error → abort untouched (never filed, never decayed)
         }
-        const parsed = parseTagReply(raw, domains);
-        if (parsed)
-            return parsed;
         if (attempt === 0) {
             console.warn(`[hicortex] tag classify: unparseable reply "${raw.slice(0, 60)}" — retrying once`);
         }

package/dist/init.js

@@ -246,7 +246,7 @@ function allowHicortexTools() {
     // Only EDIT an existing CC settings file — never invent one. On a host with
     // no CC client (a server, or a Hermes-only box) ~/.claude/settings.json is
     // absent; creating a stub there is wrong, and the earlier mkdir+write was the
-    // ENOENT throw on bedrock's init. Without this entry CC just PROMPTS before
+    // ENOENT throw on a host with no CC client. Without this entry CC just PROMPTS before
     // tool use instead of auto-allowing — the MCP still works either way.
     if (!(0, node_fs_1.existsSync)(CC_SETTINGS)) {
         console.log(`  ℹ ${CC_SETTINGS} not found — skipping CC tool permissions (no CC client here; ` +