@gamaze/hicortex 0.17.1 → 0.17.2

package/README.md

@@ -218,9 +218,10 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `captureCooldownHours` | Success-cooldown (hours) for the **capture watchdog** (0.17). The capture timer polls every ~20 min; the watchdog captures only if more than this has elapsed since the last *successful* capture (`state.lastNightly`). Default `6` (≈4 captures/day). A failed preflight retries on the next poll (~20 min) — so a transient fire-instant network miss costs minutes, not a day (#239) |
 | `consolidationHours` | Hours (0–23, local) for the **consolidation** timer — the full nightly (capture + distill + score + reflect + link). Installed for **server/co-located only** (clients have no local DB). Default `[10, 22]`: the 22:00 evening slot runs after the day's capture waves (same-day results); the 10:00 morning slot runs *after* the morning capture so wake-up pushes are caught. Omitted on clients |
 | `consolidateMaxLlmCalls` | Ceiling on total LLM calls across all classify-tier consolidation stages (content-domain, link discovery, supersession) per run. A runaway **backstop**, not a throughput throttle — on a free local model the binding constraint is the nightly unit's wall-clock timeout, not call count. Default `5000` (was a hard-coded 200 that starved link/supersession during a classification backlog) |
+| `memorySoftCap` | Soft cap on the memory corpus (default 10000). When the corpus exceeds this, the nightly's capacity-eviction stage removes the lowest-`effectiveStrength` memories (ties broken by oldest access) until under the cap — the active forgetting mechanism that bounds DB size, vector-index RAM, and consolidation workload. `0` disables eviction (indefinite growth — the pre-#245 behaviour). The evicted tail is cold by construction (effectiveStrength is the same decay-weighted score the recall ranker uses, so these were not surfacing in the top-k anyway). At 10K memories the load + JS sort is <100 ms |
 | `updateChannel` | Release channel pinned into the generated daemon/timer ExecStart for **npx-thin** installs (global-binary installs use the absolute binary and are unaffected). A dist-tag (`"rc"`, `"next"`) or an exact version (`"0.17.1"`). E.g. `"rc"` → the timer runs `npx -y @gamaze/hicortex@rc nightly`, so the host tracks the rc dist-tag (an internal fleet can ride rc through a pre-promotion soak). Validated as `[\w.\-]+` (rejects anything that'd break the unit/plist templates). Absent → auto-detect (bare on `latest`, else `@next`). (0.17.1) |
 | `nightlyHour` | **Deprecated (0.17) single-slot fallback.** Local hour (0–23) honoured only when `consolidationHours` is absent — yields one daily consolidation slot at that hour (preserves the pre-0.17 "one daily job" intent). New installs should use `consolidationHours` |
-| `preflightTimeoutMs` | **Client mode only.** Per-attempt timeout for the nightly's server-reachability check before it starts capturing (default: 20000 ms, bumped from 15000 in 0.17 to absorb a cold Tailscale handshake on a roaming laptop) |
+| `preflightTimeoutMs` | **Client mode only.** Per-attempt timeout for the nightly's server-reachability check before it starts capturing (default: 20000 ms, bumped from 15000 in 0.17 to absorb a slow link re-establishing after the client wakes) |
 | `preflightAttempts` | **Client mode only.** Reachability-check retries before the nightly aborts (default: 3; floored at 1). `1` = single try, no retry |
 | `preflightRetryGapMs` | **Client mode only.** Delay between reachability retries (default: 60000 ms). Note: timers don't advance while the machine is asleep, so on a sleeping laptop this gap counts awake-time, not wall-clock |
 | `scoreSimilarityWeight` | Weight of semantic similarity in the ranking score (default: 0.50) |

package/assets/dashboard.html

@@ -147,6 +147,8 @@
   <div id="digest-lessons"></div>
   <h2 style="margin-top:16px;">Dedup merges</h2>
   <div id="digest-dedup"></div>
+  <h2 id="digest-tokens-section" style="margin-top:16px;display:none;">Token usage breakdown by stage</h2>
+  <div id="digest-tokens"></div>
 </div>
 
 <div class="sub muted" style="margin-top:24px;">
@@ -205,13 +207,71 @@ function renderHeadline(h) {
   const ups = h.uses_per_showing === null || h.uses_per_showing === undefined
     ? "—"
     : (h.uses_per_showing * 100).toFixed(1) + "%";
+  // Capacity gauge (#245): X / cap memories. Amber at ≥85% of cap, red at ≥100%.
+  // Hidden when the cap is 0 (disabled — indefinite growth, the pre-#245 default).
+  let capStat = "";
+  if (h.memory_soft_cap && h.memory_soft_cap > 0) {
+    const cap = h.memory_soft_cap;
+    const n = h.total_memories;
+    const pct = Math.min(100, (n / cap) * 100);
+    const over = n >= cap;
+    const near = pct >= 85 && !over;
+    const barColor = over ? "var(--bad, #e05555)" : near ? "var(--warn, #e0b055)" : "var(--ok, #61c98f)";
+    capStat = `
+      <div class="stat" style="flex-basis:240px;">
+        <div class="v" style="font-size:18px;">${n.toLocaleString()} <span class="muted" style="font-size:13px;">/ ${cap.toLocaleString()}</span></div>
+        <div class="l">Memories vs soft cap ${over ? "(over cap)" : ""}</div>
+        <div style="margin-top:6px;height:6px;background:rgba(128,128,128,0.2);border-radius:3px;overflow:hidden;">
+          <div style="width:${pct.toFixed(1)}%;height:100%;background:${barColor};"></div>
+        </div>
+      </div>`;
+  }
+  // LLM tokens this period (#246): hidden when `used` is 0 (no metered run yet
+  // — nothing to show). When capped (cap > 0), render a usage bar with the
+  // percentage; amber at ≥85%, red at ≥100%. When uncapped (self-hosted
+  // default), show just the count. Both shapes include "this month" so the
+  // billing-period framing is uniform.
+  let tokenStat = "";
+  const tok = h.tokens;
+  if (tok && tok.used > 0) {
+    const usedStr = formatTokens(tok.used);
+    if (tok.cap > 0) {
+      const pct = Math.min(100, (tok.used / tok.cap) * 100);
+      const over = tok.used >= tok.cap;
+      const near = pct >= 85 && !over;
+      const barColor = over ? "var(--bad, #e05555)" : near ? "var(--warn, #e0b055)" : "var(--ok, #61c98f)";
+      tokenStat = `
+        <div class="stat" style="flex-basis:240px;">
+          <div class="v" style="font-size:18px;">${escapeHtml(usedStr)} <span class="muted" style="font-size:13px;">/ ${escapeHtml(formatTokens(tok.cap))}</span></div>
+          <div class="l">LLM tokens this month ${over ? "(over cap)" : ""}</div>
+          <div style="margin-top:6px;height:6px;background:rgba(128,128,128,0.2);border-radius:3px;overflow:hidden;">
+            <div style="width:${pct.toFixed(1)}%;height:100%;background:${barColor};"></div>
+          </div>
+        </div>`;
+    } else {
+      tokenStat = `
+        <div class="stat">
+          <div class="v">${escapeHtml(usedStr)}</div>
+          <div class="l">LLM tokens this month</div>
+        </div>`;
+    }
+  }
   $("headline").innerHTML = `
     <div class="stat"><div class="v">${h.total_memories}</div><div class="l">Total memories</div></div>
     <div class="stat"><div class="v">${ups}</div><div class="l">Uses per showing (headline)</div></div>
     <div class="stat"><div class="v warn">${h.cold_count}</div><div class="l">Cold long-tail (never shown/used)</div></div>
+    ${capStat}
+    ${tokenStat}
   `;
 }
 
+/** Compact human-readable token count: 1234 → "1.2K", 1_500_000 → "1.5M". */
+function formatTokens(n) {
+  if (n >= 1e6) return (n / 1e6).toFixed(1) + "M";
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + "K";
+  return String(n);
+}
+
 // ---------------------------------------------------------------------------
 // Render: growth chart (hand-rolled inline SVG line chart)
 //
@@ -348,8 +408,27 @@ function renderDigest(digest) {
     s.lessonsGenerated !== undefined ? `<span class="stage-pill">lessons: ${s.lessonsGenerated}</span>` : "",
     `<span class="stage-pill">dedup: ${s.dedup}</span>`,
     `<span class="stage-pill">supersession: ${s.supersession}</span>`,
+    s.evicted !== undefined && s.evicted > 0 ? `<span class="stage-pill warn">evicted: ${s.evicted}</span>` : "",
+    s.tokens !== undefined ? `<span class="stage-pill">tokens: ${escapeHtml(formatTokens(s.tokens))}</span>` : "",
   ].join(" ");
   $("digest-stages").innerHTML = stages;
+  // Per-stage token breakdown (#246) — only when the day's run metered tokens
+  // and the breakdown was carried (always present together with `tokens`).
+  const tbs = s.tokens_by_stage;
+  if (tbs && Object.keys(tbs).length > 0) {
+    const rows = Object.entries(tbs)
+      .sort((a, b) => (b[1].total - a[1].total))
+      .map(([k, v]) =>
+        `<tr><td class="k">${escapeHtml(k)}</td>` +
+        `<td>${escapeHtml(formatTokens(v.total))}</td>` +
+        `<td class="muted">${escapeHtml(formatTokens(v.prompt))} in / ${escapeHtml(formatTokens(v.completion))} out</td></tr>`
+      ).join("");
+    $("digest-tokens").innerHTML = `<table class="digest"><tbody>${rows}</tbody></table>`;
+    $("digest-tokens-section").style.display = "";
+  } else {
+    $("digest-tokens").innerHTML = `<div class="empty">No token usage that day (no metered LLM run).</div>`;
+    $("digest-tokens-section").style.display = "none";
+  }
 
   if (digest.sample.length === 0) {
     $("digest-sample").innerHTML = `<div class="empty">No new memories that day.</div>`;

package/dist/cli.d.ts

@@ -6,8 +6,9 @@
  *   server     Start the MCP HTTP/SSE server (persistent daemon)
  *   init       Detect existing setup and configure for CC/OC
  *   nightly    Run capture + consolidate (manual trigger)
- *              nightly --capture-only  Capture only, skip consolidation
- *              nightly --status        Show nightly pipeline health check
+ *              nightly --capture-only     Capture only, skip consolidation
+ *              nightly --consolidate-only Consolidate only, skip capture (hosted service)
+ *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
  *   dedup      Cluster + merge near-duplicate memories (issue #100)
  *              dedup --apply           Execute the merge (default: dry run)

package/dist/cli.js

@@ -7,8 +7,9 @@
  *   server     Start the MCP HTTP/SSE server (persistent daemon)
  *   init       Detect existing setup and configure for CC/OC
  *   nightly    Run capture + consolidate (manual trigger)
- *              nightly --capture-only  Capture only, skip consolidation
- *              nightly --status        Show nightly pipeline health check
+ *              nightly --capture-only     Capture only, skip consolidation
+ *              nightly --consolidate-only Consolidate only, skip capture (hosted service)
+ *              nightly --status           Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
  *   dedup      Cluster + merge near-duplicate memories (issue #100)
  *              dedup --apply           Execute the merge (default: dry run)
@@ -69,7 +70,12 @@ switch (command) {
         else {
             const dryRun = args.includes("--dry-run");
             const captureOnly = args.includes("--capture-only");
+            const consolidateOnly = args.includes("--consolidate-only");
             const watchdog = args.includes("--watchdog");
+            if (captureOnly && consolidateOnly) {
+                console.error("[hicortex] nightly: --capture-only and --consolidate-only are mutually exclusive");
+                process.exit(1);
+            }
             // Timestamp every log line. The nightly writes to a file (launchd /
             // systemd StandardOutput append) with NO per-line timestamp, which made
             // diagnosing capture gaps impossible (the #239 investigation couldn't
@@ -92,7 +98,7 @@ switch (command) {
                 }
             }
             import("./nightly.js").then(({ runNightly }) => {
-                runNightly({ dryRun, captureOnly, watchdog, recaptureWindowDays }).catch((err) => {
+                runNightly({ dryRun, captureOnly, consolidateOnly, watchdog, recaptureWindowDays }).catch((err) => {
                     console.error("[hicortex] Nightly pipeline failed:", err);
                     process.exit(1);
                 });
@@ -285,6 +291,7 @@ Options:
   server --host <h>    Host (default: 127.0.0.1)
   nightly --dry-run         Preview without changes
   nightly --capture-only    Capture only, skip consolidation (safe to run multiple times/day)
+  nightly --consolidate-only  Consolidate only, skip capture (hosted-service per-tenant runs)
   nightly --recapture-window <days>   Re-discover sessions quiet since <days> ago (one-shot #189 recovery)
   nightly --status          Show nightly pipeline health
   relink --dry-run          Discovery + counts only, zero writes, cursor untouched

package/dist/consolidate.d.ts

@@ -63,12 +63,63 @@ export declare class BudgetTracker {
     maxCalls: number;
     callsUsed: number;
     callsByStage: Record<string, number>;
+    /**
+     * 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: Record<string, {
+        prompt: number;
+        completion: number;
+        total: number;
+    }>;
+    /** Run-wide totals — the sum of every recordUsage() call this run. */
+    totalTokens: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
     constructor(maxCalls: number);
     get exhausted(): boolean;
     get remaining(): number;
     use(stage: string, count?: number): boolean;
+    /**
+     * 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: string, usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    } | undefined): void;
     summary(): NonNullable<ConsolidationReport["budget"]>;
 }
+/**
+ * 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).
+ */
+export declare function shouldThrottleTokens(cap: number, period: {
+    total: number;
+    periodStart: string;
+} | undefined, lastRunTokens: number, now?: Date): {
+    throttle: boolean;
+    used?: number;
+    cap?: number;
+};
 /**
  * Parse JSON from LLM output, tolerating markdown fences and indexed formats.
  */
@@ -203,6 +254,17 @@ export declare function stageDecayPrune(db: Database.Database, dryRun: boolean):
     pruned: number;
     failed: number;
 };
+/**
+ * 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`.
+ */
+export declare const DEFAULT_MEMORY_SOFT_CAP = 10000;
+export declare function stageMemoryCapEviction(db: Database.Database, dryRun: boolean, cap: number): {
+    cap: number;
+    evicted: number;
+};
 /**
  * Run the full consolidation pipeline. Returns a structured report.
  */
@@ -232,7 +294,11 @@ export declare function runConsolidation(db: Database.Database, llm: LlmClient,
 /** 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?: number): Promise<ConsolidationReport>;
+budgetMaxCalls?: number, 
+/** 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?: number): Promise<ConsolidationReport>;
 /**
  * Calculate milliseconds until the next occurrence of a given hour (local time).
  */

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";