@gamaze/hicortex 0.17.1 → 0.17.2

package/dist/nightly.js

@@ -214,6 +214,10 @@ async function runNightly(options = {}) {
     const dryRun = options.dryRun ?? false;
     let captureOnly = options.captureOnly ?? false;
     const watchdog = options.watchdog ?? false;
+    const consolidateOnly = options.consolidateOnly ?? false;
+    if (captureOnly && consolidateOnly) {
+        throw new Error("runNightly: captureOnly and consolidateOnly are mutually exclusive");
+    }
     const stateDir = options.stateDir ?? HICORTEX_HOME;
     const recaptureWindowDays = options.recaptureWindowDays;
     rotateNightlyLog(stateDir);
@@ -240,7 +244,9 @@ async function runNightly(options = {}) {
     // capture-only and falls through to the normal capture path (the capture
     // lock with waitMs=0 provides single-flight; writeLastRun advances the
     // cooldown marker on success).
-    if (watchdog && !dryRun) {
+    // consolidateOnly skips the watchdog gate (the watchdog is a capture mechanism;
+    // consolidateOnly is the opposite — skip capture, run consolidation only).
+    if (watchdog && !dryRun && !consolidateOnly) {
         captureOnly = true; // the watchdog captures only — never consolidates.
         // Success-cooldown: lastNightly is advanced ONLY on a clean capture
         // (writeLastRun is success-gated), so reusing it gives SUCCESS-based
@@ -280,9 +286,9 @@ async function runNightly(options = {}) {
         console.log(`[hicortex] watchdog: cooldown elapsed + ${target} reachable — capturing`);
     }
     if (savedConfig?.mode === "client") {
-        // --capture-only is accepted in client mode but irrelevant: client nightly
-        // is already capture-only (no consolidation step). (If watchdog-gated, the
-        // gate above already ran.)
+        // --capture-only and --consolidate-only are both accepted in client mode but
+        // irrelevant: client nightly is already capture-only (no consolidation step),
+        // and consolidation-only makes no sense without a local DB.
         await runClientNightly(savedConfig, dryRun, stateDir, recaptureWindowDays, watchdog);
         return;
     }
@@ -292,7 +298,7 @@ async function runNightly(options = {}) {
     (0, retrieval_js_1.configureDecay)({ halfLifeDays: savedConfig?.decayHalfLifeDays });
     (0, retrieval_js_1.configureRecall)(savedConfig);
     (0, retrieval_js_1.configureScoring)(savedConfig);
-    const modeLabel = captureOnly ? " (capture-only)" : dryRun ? " (dry run)" : "";
+    const modeLabel = consolidateOnly ? " (consolidate-only)" : captureOnly ? " (capture-only)" : dryRun ? " (dry run)" : "";
     console.log(`[hicortex] Nightly pipeline starting${modeLabel}`);
     if (captureOnly) {
         console.log(`[hicortex] capture-only run — consolidation skipped`);
@@ -326,136 +332,248 @@ async function runNightly(options = {}) {
         let batches = [];
         let memoriesIngested = 0;
         let hadTransientFailure = false;
-        // Full nightly waits out a transient --capture-only overlap (each segment
-        // POST can block up to 20 min); capture-only fails fast. dry-run writes
-        // nothing so it needs no lock.
-        const lockWaitMs = captureLockWaitMs();
-        const releaseLock = dryRun
-            ? (() => { })
-            : await (0, capture_js_1.acquireCaptureLock)(stateDir, captureOnly ? 0 : lockWaitMs);
-        if (!releaseLock) {
-            if (captureOnly) {
-                console.warn("[hicortex] Another capture run holds the lock — skipping this capture-only run.");
-                return;
-            }
-            // Full nightly couldn't get the lock even after waiting: skip capture and
-            // hold the watermark, but STILL run consolidation + telemetry below so an
-            // overlapping capture-only run never silently starves consolidation (fix 10).
-            console.warn(`[hicortex] Capture lock still held after waiting ${Math.round(lockWaitMs / 60000)} min — ` +
-                `skipping capture this run (watermark held), consolidation still runs.`);
-            hadTransientFailure = true;
+        // consolidateOnly (hosted service): skip capture entirely. The hosted
+        // consolidation timer uses this so per-tenant nightly runs don't ingest the
+        // operator's local sessions into the tenant's DB.
+        if (consolidateOnly) {
+            console.log("[hicortex] consolidate-only run — capture skipped");
         }
         else {
-            try {
-                // Step 1: Read new transcripts (CC + Hermes + Pi + OpenClaw). Discovery
-                // is whole-session by mtime/ended_at; per-session cursors slice each
-                // discovered session down to its unseen delta (#189).
-                const since = computeSince(stateDir, recaptureWindowDays);
-                if (recaptureWindowDays) {
-                    console.log(`[hicortex] --recapture-window ${recaptureWindowDays}d: reading transcripts since ${since.toISOString()}`);
+            // Full nightly waits out a transient --capture-only overlap (each segment
+            // POST can block up to 20 min); capture-only fails fast. dry-run writes
+            // nothing so it needs no lock.
+            const lockWaitMs = captureLockWaitMs();
+            const releaseLock = dryRun
+                ? (() => { })
+                : await (0, capture_js_1.acquireCaptureLock)(stateDir, captureOnly ? 0 : lockWaitMs);
+            if (!releaseLock) {
+                if (captureOnly) {
+                    console.warn("[hicortex] Another capture run holds the lock — skipping this capture-only run.");
+                    return;
+                }
+                // Full nightly couldn't get the lock even after waiting: skip capture and
+                // hold the watermark, but STILL run consolidation + telemetry below so an
+                // overlapping capture-only run never silently starves consolidation (fix 10).
+                console.warn(`[hicortex] Capture lock still held after waiting ${Math.round(lockWaitMs / 60000)} min — ` +
+                    `skipping capture this run (watermark held), consolidation still runs.`);
+                hadTransientFailure = true;
+            }
+            else {
+                try {
+                    // Step 1: Read new transcripts (CC + Hermes + Pi + OpenClaw). Discovery
+                    // is whole-session by mtime/ended_at; per-session cursors slice each
+                    // discovered session down to its unseen delta (#189).
+                    const since = computeSince(stateDir, recaptureWindowDays);
+                    if (recaptureWindowDays) {
+                        console.log(`[hicortex] --recapture-window ${recaptureWindowDays}d: reading transcripts since ${since.toISOString()}`);
+                    }
+                    else {
+                        console.log(`[hicortex] Reading transcripts since ${since.toISOString()}`);
+                    }
+                    const cursorStore = (0, capture_cursors_js_1.openCursorStore)(stateDir);
+                    const cursorMap = cursorStore.map();
+                    ccBatches = (0, transcript_reader_js_1.readCcTranscripts)(since, undefined, cursorMap);
+                    hermesBatches = (0, hermes_transcript_reader_js_1.readHermesSessions)(since, undefined, cursorMap);
+                    // Pi is a supported harness (readPiTranscripts no-ops when
+                    // ~/.pi/agent/sessions is absent). Retired only on specific deployments
+                    // by simply having no Pi session files — not removed from the pipeline.
+                    piBatches = (0, pi_transcript_reader_js_1.readPiTranscripts)(since, undefined, cursorMap);
+                    // OpenClaw persists sessions in the Pi v3 format at ~/.openclaw/agents/;
+                    // no-ops when OC isn't installed.
+                    ocBatches = (0, oc_transcript_reader_js_1.readOcTranscripts)(since, undefined, cursorMap);
+                    batches = [...ccBatches, ...hermesBatches, ...piBatches, ...ocBatches];
+                    if (ccBatches.length > 0)
+                        console.log(`[hicortex] Found ${ccBatches.length} CC session(s)`);
+                    if (hermesBatches.length > 0)
+                        console.log(`[hicortex] Found ${hermesBatches.length} Hermes session(s)`);
+                    if (piBatches.length > 0)
+                        console.log(`[hicortex] Found ${piBatches.length} Pi session(s)`);
+                    if (ocBatches.length > 0)
+                        console.log(`[hicortex] Found ${ocBatches.length} OpenClaw session(s)`);
+                    console.log(`[hicortex] Total: ${batches.length} new session(s)`);
+                    if (batches.length === 0 && !dryRun) {
+                        console.log(captureOnly
+                            ? `[hicortex] No new transcripts. Nothing to capture.`
+                            : `[hicortex] No new transcripts. Running consolidation only.`);
+                    }
+                    // Step 2: pack each session's delta into ≤60K segments and POST to the
+                    // local daemon via /distill; cursors advance on confirmed success.
+                    // source_agent_id / source_domain are per-client provenance from
+                    // config.json (agentId / sourceDomain) — attribution only, no filtering.
+                    const result = await (0, capture_js_1.captureBatches)(batches, {
+                        post: makeLocalPost(port),
+                        cursorStore,
+                        dryRun,
+                        sourceAgentId: savedConfig?.agentId,
+                        sourceDomain: savedConfig?.sourceDomain,
+                    });
+                    memoriesIngested = result.memoriesIngested;
+                    // A 429/401 stop must hold the watermark too (fix 1): the loop abandoned
+                    // the remaining sessions, and mtime discovery would never re-find them.
+                    hadTransientFailure = result.hadTransientFailure || result.stopped !== undefined;
                 }
-                else {
-                    console.log(`[hicortex] Reading transcripts since ${since.toISOString()}`);
+                finally {
+                    releaseLock();
                 }
-                const cursorStore = (0, capture_cursors_js_1.openCursorStore)(stateDir);
-                const cursorMap = cursorStore.map();
-                ccBatches = (0, transcript_reader_js_1.readCcTranscripts)(since, undefined, cursorMap);
-                hermesBatches = (0, hermes_transcript_reader_js_1.readHermesSessions)(since, undefined, cursorMap);
-                // Pi is a supported harness (readPiTranscripts no-ops when
-                // ~/.pi/agent/sessions is absent). Retired only on specific deployments
-                // by simply having no Pi session files — not removed from the pipeline.
-                piBatches = (0, pi_transcript_reader_js_1.readPiTranscripts)(since, undefined, cursorMap);
-                // OpenClaw persists sessions in the Pi v3 format at ~/.openclaw/agents/;
-                // no-ops when OC isn't installed.
-                ocBatches = (0, oc_transcript_reader_js_1.readOcTranscripts)(since, undefined, cursorMap);
-                batches = [...ccBatches, ...hermesBatches, ...piBatches, ...ocBatches];
-                if (ccBatches.length > 0)
-                    console.log(`[hicortex] Found ${ccBatches.length} CC session(s)`);
-                if (hermesBatches.length > 0)
-                    console.log(`[hicortex] Found ${hermesBatches.length} Hermes session(s)`);
-                if (piBatches.length > 0)
-                    console.log(`[hicortex] Found ${piBatches.length} Pi session(s)`);
-                if (ocBatches.length > 0)
-                    console.log(`[hicortex] Found ${ocBatches.length} OpenClaw session(s)`);
-                console.log(`[hicortex] Total: ${batches.length} new session(s)`);
-                if (batches.length === 0 && !dryRun) {
-                    console.log(captureOnly
-                        ? `[hicortex] No new transcripts. Nothing to capture.`
-                        : `[hicortex] No new transcripts. Running consolidation only.`);
+                console.log(`[hicortex] Capture complete: ${memoriesIngested} new memories`);
+                // Prune aged-out cursors (90d) — only on a clean run so a transient
+                // failure doesn't drop a still-needed cursor.
+                if (!dryRun && !hadTransientFailure) {
+                    const pruned = (0, capture_cursors_js_1.pruneCursors)(stateDir);
+                    if (pruned > 0)
+                        console.log(`[hicortex] Pruned ${pruned} stale capture cursor(s)`);
                 }
-                // Step 2: pack each session's delta into ≤60K segments and POST to the
-                // local daemon via /distill; cursors advance on confirmed success.
-                // source_agent_id / source_domain are per-client provenance from
-                // config.json (agentId / sourceDomain) — attribution only, no filtering.
-                const result = await (0, capture_js_1.captureBatches)(batches, {
-                    post: makeLocalPost(port),
-                    cursorStore,
-                    dryRun,
-                    sourceAgentId: savedConfig?.agentId,
-                    sourceDomain: savedConfig?.sourceDomain,
-                });
-                memoriesIngested = result.memoriesIngested;
-                // A 429/401 stop must hold the watermark too (fix 1): the loop abandoned
-                // the remaining sessions, and mtime discovery would never re-find them.
-                hadTransientFailure = result.hadTransientFailure || result.stopped !== undefined;
-            }
-            finally {
-                releaseLock();
-            }
-            console.log(`[hicortex] Capture complete: ${memoriesIngested} new memories`);
-            // Prune aged-out cursors (90d) — only on a clean run so a transient
-            // failure doesn't drop a still-needed cursor.
-            if (!dryRun && !hadTransientFailure) {
-                const pruned = (0, capture_cursors_js_1.pruneCursors)(stateDir);
-                if (pruned > 0)
-                    console.log(`[hicortex] Pruned ${pruned} stale capture cursor(s)`);
             }
-        }
+        } // end capture block (consolidateOnly else)
         // Step 3: Consolidation — skipped in capture-only mode, dry-run, or no LLM.
         // Runs even if capture had transient failures (opens DB directly, independent
         // of the HTTP capture path). Full nightly only — capture-only runs are
         // intended to run more frequently than once daily.
         let lessonsGenerated; // hoisted for telemetry; undefined when reflection didn't run (skipped) — bucketed apart from a real 0
+        // #245: memories evicted by the capacity stage (hoisted for the dashboard
+        // snapshot). 0 is a real value (under cap), so this stays undefined only
+        // when consolidation didn't run at all (capture-only / no_llm / skipped).
+        let evictedCount;
+        // Resolved cap (#245) for the dashboard snapshot. Hoisted so the snapshot
+        // writer (outside the consolidation block) can stamp `capacity` even when
+        // consolidation was skipped (the cap is still "in force" config-wise).
+        const memorySoftCapResolved = (0, config_read_js_1.readNonNegativeConfig)(savedConfig ?? {}, "memorySoftCap", consolidate_js_1.DEFAULT_MEMORY_SOFT_CAP);
         // Consolidation outcome for telemetry (0.17). undefined on capture-only runs
         // (which send no nightly ping). "skipped" = runConsolidation's built-in
         // nothing-to-do short-circuit (zero LLM calls), NOT a failure.
+        // "throttled" (#246) = the llmTokensPerMonth fair-use cap was projected to
+        // be exceeded, so consolidation was skipped before any LLM call.
         let consolidationStatus;
+        // #246: total consolidation tokens consumed this run (hoisted for telemetry
+        // + the dashboard snapshot). Undefined when consolidation didn't run at all
+        // (capture-only / no_llm / throttled) so the optional field is omitted.
+        let tokensThisRun;
+        // #246: per-stage token breakdown (hoisted for the dashboard snapshot).
+        let tokensByStage;
         if (!dryRun && !captureOnly) {
             if (!llm || !llmConfig) {
                 console.error("[hicortex] consolidation skipped: no LLM configured — run npx @gamaze/hicortex init");
                 consolidationStatus = "no_llm";
             }
             else {
-                // One model serves all phases (#231) — there is no separate endpoint to
-                // pre-flight. If the model doesn't answer, `complete()` already retries at
-                // 30s/60s/120s (~3.5 min); anything still failing after that is an outage,
-                // not a blip. A failed phase costs latency, not data: capture cursors hold
-                // on failure (dup-over-loss), and consolidation has resumable cursors
-                // (domainCursor, supersessionCursor). The nightly runs 2-4×/day, so the
-                // wait is hours — no polling, no new config. (Issue #231.)
-                const cfgDomains = (0, domain_classify_js_1.parseConfigDomains)(savedConfig);
-                console.log(`[hicortex] Running consolidation...`);
-                const report = await (0, consolidate_js_1.runConsolidation)(db, llm, embedder_js_1.embed, dryRun, false, undefined, {
-                    domains: cfgDomains,
-                    contentDomainsReady: true,
-                    weakPrimaryFloor: (0, nofit_js_1.resolveWeakPrimaryFloor)(savedConfig),
-                }, {
-                    minSimilarity: savedConfig?.supersessionMinSimilarity,
-                    maxCalls: savedConfig?.supersessionMaxCalls,
-                }, 
-                // #241: config-driven total LLM-call ceiling (default 5000, was 200).
-                (0, config_read_js_1.readPositiveConfig)(savedConfig ?? {}, "consolidateMaxLlmCalls", consolidate_js_1.CONSOLIDATE_MAX_LLM_CALLS));
-                console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
-                    (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
-                consolidationStatus = report.status;
-                // Only set when reflection actually RAN (not skipped). A skipped stage
-                // (e.g. endpoint offline, #232 fail-soft) must NOT collapse to 0 — that
-                // would make "endpoint down" indistinguishable from "prompt too tight"
-                // in the fleet aggregate. Leave undefined so the optional field is
-                // omitted and the aggregate buckets skipped runs separately.
-                const refl = report.stages.reflection;
-                if (refl && !refl.skipped)
-                    lessonsGenerated = refl.lessons_generated;
+                // #246: fair-use cap. Default 0 = unlimited (self-hosted default —
+                // never throttles). When > 0, project this run's cost against the
+                // period running total. The estimate = the PREVIOUS run's actual usage
+                // (state.llmTokensLastRun, 0/absent on the first metered run = never
+                // throttle the first run, since there's no baseline yet). Conservative:
+                // over-throttle vs over-spend, since a throttled night just defers work
+                // to the next period (the corpus is not lost — consolidation has
+                // resumable cursors and runs 2-4×/day on the 0.17 timer).
+                const tokenCap = (0, config_read_js_1.readNonNegativeConfig)(savedConfig ?? {}, "llmTokensPerMonth", 0);
+                if (tokenCap > 0) {
+                    // Pure decision lives in consolidate.ts (shouldThrottleTokens) so it
+                    // can be unit-tested without spinning up the nightly. Monthly reset
+                    // + last-run estimate are handled inside the helper.
+                    const periodState = (0, state_js_1.loadState)(stateDir).llmTokensThisPeriod;
+                    const lastRunTokens = (0, state_js_1.loadState)(stateDir).llmTokensLastRun ?? 0;
+                    const decision = (0, consolidate_js_1.shouldThrottleTokens)(tokenCap, periodState, lastRunTokens);
+                    if (decision.throttle) {
+                        console.warn(`[hicortex] Consolidation throttled: token fair-use cap reached ` +
+                            `(${decision.used.toLocaleString()} used + ~${lastRunTokens.toLocaleString()} estimated / ${tokenCap.toLocaleString()} this period).`);
+                        consolidationStatus = "throttled";
+                        // Month-boundary reset even when throttled (#246 CR): without this,
+                        // llmTokensLastRun stays stale from the prior month → soft-locks
+                        // every subsequent run forever. Reset the period + the last-run
+                        // estimate so the next month starts clean.
+                        if (!dryRun) {
+                            (0, state_js_1.updateState)((s) => {
+                                const now = new Date();
+                                const cur = s.llmTokensThisPeriod;
+                                const startD = cur?.periodStart ? new Date(cur.periodStart) : now;
+                                if (startD.getUTCFullYear() !== now.getUTCFullYear() ||
+                                    startD.getUTCMonth() !== now.getUTCMonth()) {
+                                    s.llmTokensThisPeriod = { prompt: 0, completion: 0, total: 0, periodStart: now.toISOString() };
+                                    s.llmTokensLastRun = 0;
+                                    console.log("[hicortex] Token fair-use period reset (new month) — throttle cleared.");
+                                }
+                            }, stateDir);
+                        }
+                    }
+                }
+                if (consolidationStatus !== "throttled") {
+                    // One model serves all phases (#231) — there is no separate endpoint to
+                    // pre-flight. If the model doesn't answer, `complete()` already retries at
+                    // 30s/60s/120s (~3.5 min); anything still failing after that is an outage,
+                    // not a blip. A failed phase costs latency, not data: capture cursors hold
+                    // on failure (dup-over-loss), and consolidation has resumable cursors
+                    // (domainCursor, supersessionCursor). The nightly runs 2-4×/day, so the
+                    // wait is hours — no polling, no new config. (Issue #231.)
+                    const cfgDomains = (0, domain_classify_js_1.parseConfigDomains)(savedConfig);
+                    console.log(`[hicortex] Running consolidation...`);
+                    const report = await (0, consolidate_js_1.runConsolidation)(db, llm, embedder_js_1.embed, dryRun, false, undefined, {
+                        domains: cfgDomains,
+                        contentDomainsReady: true,
+                        weakPrimaryFloor: (0, nofit_js_1.resolveWeakPrimaryFloor)(savedConfig),
+                    }, {
+                        minSimilarity: savedConfig?.supersessionMinSimilarity,
+                        maxCalls: savedConfig?.supersessionMaxCalls,
+                    }, 
+                    // #241: config-driven total LLM-call ceiling (default 5000, was 200).
+                    (0, config_read_js_1.readPositiveConfig)(savedConfig ?? {}, "consolidateMaxLlmCalls", consolidate_js_1.CONSOLIDATE_MAX_LLM_CALLS), 
+                    // #245: soft cap on the corpus (default 10000; 0 disables eviction).
+                    memorySoftCapResolved);
+                    console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
+                        (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
+                    consolidationStatus = report.status;
+                    // #245: capture the eviction count for the dashboard snapshot. The
+                    // stage always returns `evicted` (0 when under cap / disabled); report
+                    // it as 0 (a real value), not undefined, when the stage ran.
+                    evictedCount = report.stages.memory_cap?.evicted ?? 0;
+                    // Only set when reflection actually RAN (not skipped). A skipped stage
+                    // (e.g. endpoint offline, #232 fail-soft) must NOT collapse to 0 — that
+                    // would make "endpoint down" indistinguishable from "prompt too tight"
+                    // in the fleet aggregate. Leave undefined so the optional field is
+                    // omitted and the aggregate buckets skipped runs separately.
+                    const refl = report.stages.reflection;
+                    if (refl && !refl.skipped)
+                        lessonsGenerated = refl.lessons_generated;
+                    // #246: surface token totals for telemetry + dashboard snapshot. Both
+                    // fields stay undefined on a skipped/failed run (no metered calls →
+                    // nothing to report; the optional fields are omitted from the ping).
+                    const tokensTotal = report.budget?.tokens_total;
+                    if (tokensTotal && tokensTotal.total > 0) {
+                        tokensThisRun = tokensTotal.total;
+                        tokensByStage = report.budget?.tokens_by_stage;
+                    }
+                    // #246: accrue to state.json (monthly reset + last-run estimate for
+                    // the next throttle check). Written even on a failed run — a partial
+                    // run that made metered calls before the failure still spent tokens,
+                    // and the next run's estimate should reflect that.
+                    if (!dryRun) {
+                        (0, state_js_1.updateState)((s) => {
+                            const now = new Date();
+                            const cur = s.llmTokensThisPeriod;
+                            let periodStart = cur?.periodStart ?? now.toISOString();
+                            let prompt = cur?.prompt ?? 0;
+                            let completion = cur?.completion ?? 0;
+                            let total = cur?.total ?? 0;
+                            // Monthly reset: if periodStart is in a previous calendar month,
+                            // zero the accrual before adding this run's contribution.
+                            const startD = new Date(periodStart);
+                            if (startD.getUTCFullYear() !== now.getUTCFullYear() ||
+                                startD.getUTCMonth() !== now.getUTCMonth()) {
+                                periodStart = now.toISOString();
+                                prompt = 0;
+                                completion = 0;
+                                total = 0;
+                            }
+                            if (tokensTotal) {
+                                prompt += tokensTotal.prompt;
+                                completion += tokensTotal.completion;
+                                total += tokensTotal.total;
+                            }
+                            s.llmTokensThisPeriod = {
+                                prompt, completion, total, periodStart,
+                            };
+                            s.llmTokensLastRun = tokensTotal?.total ?? 0;
+                        }, stateDir);
+                    }
+                }
             }
         }
         // Step 4: Update last-run timestamp.
@@ -510,7 +628,12 @@ async function runNightly(options = {}) {
                     lessonsGenerated,
                     dedup,
                     supersession,
-                });
+                    evicted: evictedCount,
+                    // #246: token accounting from this run's consolidation (undefined
+                    // when consolidation didn't run or made no metered calls).
+                    tokensThisRun,
+                    tokensByStage,
+                }, memorySoftCapResolved);
             }
             catch (snapErr) {
                 // The snapshot is a monitoring side-effect — a failure here must NOT
@@ -549,6 +672,9 @@ async function runNightly(options = {}) {
                 lessons: storage.getLessons(db, 365).length,
                 lessonsGenerated,
                 consolidation: consolidationStatus,
+                // #246: total tokens consumed by this run's consolidation (absent on
+                // capture-only / throttled / no_llm / skipped — no metered calls).
+                tokens_this_run: tokensThisRun,
                 sessions: batches.length,
                 ok: !hadTransientFailure,
                 shown: adoption.shown,
@@ -574,12 +700,13 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
     // the whole run — the pre-flight only needs the link back, which can take
     // ~1 min after wake.
     //
-    // Config-overridable (#163): a wired Pi vs a sleeping/roaming laptop want
-    // different values. Defaults: 20s per-attempt timeout, 3 attempts, 60s gap.
-    // The 20s per-attempt (bumped from 15s in 0.17) absorbs a cold Tailscale
-    // handshake to a home server (DERP relay + NAT traversal can take 5–30s on a
-    // roaming laptop). For a genuinely DOWN link (`fetch failed`) no timeout
-    // length helps — the capture watchdog's frequent retry handles that (#239).
+    // Config-overridable (#163): a wired/well-connected client vs one whose link
+    // is slow to re-establish after wake want different values. Defaults: 20s
+    // per-attempt timeout, 3 attempts, 60s gap. The 20s per-attempt (bumped from
+    // 15s in 0.17) absorbs a slow link coming back after the client wakes — a
+    // remote server reached over a mesh/VPN link can take several seconds to
+    // answer on the first request. For a genuinely DOWN link (`fetch failed`) no
+    // timeout length helps — the capture watchdog's frequent retry handles that (#239).
     //
     // WALL-CLOCK NOTE: setTimeout and AbortSignal.timeout do NOT advance while
     // macOS is asleep, so the ~3m worst case (3×20s + 2×60s) is wall-clock-

package/dist/state.d.ts

@@ -60,6 +60,28 @@ export interface HicortexState {
      * gradually over many nights.
      */
     supersessionCursor?: number;
+    /**
+     * LLM token usage accrued this billing period (#246). Period reset is
+     * monthly: when `periodStart` is in a previous calendar month, the totals
+     * reset to 0 + a new periodStart (handled in nightly.ts after each run).
+     * The fair-use cap (`config.llmTokensPerMonth`) consults `.total` before
+     * each consolidation to throttle when over budget. Absent = no usage
+     * recorded yet (treated as 0 by the throttle).
+     */
+    llmTokensThisPeriod?: {
+        prompt: number;
+        completion: number;
+        total: number;
+        /** ISO timestamp of the start of the current accrual period. */
+        periodStart: string;
+    };
+    /**
+     * Total tokens consumed by the previous nightly's consolidation (#246).
+     * Used as the ESTIMATE for the next run's fair-use check (this-period total
+     * + last-run total > cap → throttle). 0/absent on the first metered run,
+     * which means the first run is never throttled (correct: no baseline yet).
+     */
+    llmTokensLastRun?: number;
 }
 /**
  * Load the state file. Returns an empty state if the file is missing

package/dist/telemetry.d.ts

@@ -89,13 +89,23 @@ export interface TelemetryPayload {
      * Consolidation outcome for THIS full nightly (server mode only —
      * capture-only runs send no nightly ping, so the field is absent there).
      * `runConsolidation`'s status: "completed" | "skipped" | "failed", plus
-     * "no_llm" when consolidation was skipped because no LLM was configured.
+     * "no_llm" when consolidation was skipped because no LLM was configured, and
+     * "throttled" (#246) when the run was skipped because the
+     * `llmTokensPerMonth` fair-use cap was projected to be exceeded.
      * "skipped" = the built-in nothing-to-do short-circuit (no new + no unscored
      * memories → zero LLM calls), NOT a failure. Lets the fleet aggregate tell a
      * real consolidation run from a no-op without repurposing `ok` (which is the
      * capture-health signal). 0.17+.
      */
-    consolidation?: "completed" | "skipped" | "failed" | "no_llm";
+    consolidation?: "completed" | "skipped" | "failed" | "no_llm" | "throttled";
+    /**
+     * Total LLM tokens consumed by THIS nightly's consolidation (#246) — the
+     * BudgetTracker total. Server-mode only (capture-only + client runs make no
+     * consolidation LLM calls). Absent on a throttled/no-LLM/skipped run (no
+     * calls → nothing to meter). Aggregate-only: no per-stage breakdown on the
+     * wire (that lives in the dashboard snapshot, not the telemetry ping).
+     */
+    tokens_this_run?: number;
 }
 /**
  * Check if telemetry is enabled. Disabled by:

package/dist/types.d.ts

@@ -146,12 +146,38 @@ export interface ConsolidationReport {
             pruned: number;
             failed: number;
         };
+        /** Capacity eviction (#245) — runs after decay_prune. When the corpus
+         *  exceeds `memorySoftCap`, the lowest-effectiveStrength memories are
+         *  evicted until under the cap. `cap = 0` (disabled) → evicted = 0. */
+        memory_cap?: {
+            /** The configured cap (always reported, including 0 = disabled). */
+            cap: number;
+            /** Memories deleted this run (0 when under cap, dry-run, or disabled). */
+            evicted: number;
+        };
     };
     budget?: {
         max_calls: number;
         calls_used: number;
         calls_remaining: number;
         calls_by_stage: Record<string, number>;
+        /**
+         * Token usage per stage (#246). Each value sums prompt + completion +
+         * total across every metered LLM call in that stage this run. A stage with
+         * no metered calls (claude-cli path, or stage didn't run) is absent — the
+         * dashboard treats absent as "no signal", distinct from zero.
+         */
+        tokens_by_stage?: Record<string, {
+            prompt: number;
+            completion: number;
+            total: number;
+        }>;
+        /** Run-wide token totals (#246) — sum of every recordUsage call this run. */
+        tokens_total?: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
     };
 }
 /** Plugin configuration from openclaw.plugin.json configSchema. */
@@ -345,6 +371,32 @@ export interface HicortexConfig {
      * leaner system prompts.
      */
     lessonsLimit?: number;
+    /**
+     * Soft cap on the memory corpus (default 10000). When the corpus exceeds this,
+     * the nightly's capacity-eviction stage (#245) removes the lowest-
+     * `effectiveStrength` memories (ties broken by oldest access) until under the
+     * cap. `0` = disabled (indefinite growth — the pre-#245 behaviour). This is
+     * the active forgetting mechanism that replaces the inert time-based prune
+     * (`effectiveStrength < 0.01` in stageDecayPrune, which essentially never
+     * fires given the strength floor + 365-day half-life). At 10K memories the
+     * load + JS sort is <100 ms. The evicted tail is cold by construction
+     * (effectiveStrength is the same decay-weighted score used in recall ranking,
+     * so these were not surfacing in the top-k anyway).
+     */
+    memorySoftCap?: number;
+    /**
+     * Monthly fair-use ceiling on consolidation LLM token consumption (#246).
+     * Default `0` = unlimited (the self-hosted default — no cap, never throttled).
+     * When > 0: before each consolidation run, the nightly checks
+     * `llmTokensThisPeriod.total + llmTokensLastRun > llmTokensPerMonth`; if so,
+     * consolidation is skipped and telemetry reports `consolidation: "throttled"`.
+     * The estimate uses the previous run's actual usage as a proxy — conservative
+     * (over-throttle vs over-spend) since a throttled night just defers work to
+     * the next period. The hosted service sets this per-tenant to defend against
+     * noisy neighbors; a self-hosted user on a free local model has no reason to
+     * set it. Period resets monthly (state.json `llmTokensThisPeriod.periodStart`).
+     */
+    llmTokensPerMonth?: number;
 }
 /** A config-owned life-sphere domain (see HicortexConfig.domains). */
 export interface DomainDef {

package/hermes-plugin/hicortex/README.md

@@ -89,7 +89,7 @@ Env overrides: `HICORTEX_URL`, `HICORTEX_AUTH_TOKEN`.
 ## Topology
 
 - **Server host:** runs Hicortex. Set `hicortex_url: http://localhost:8787` (localhost bypasses auth).
-- **Other Hermes boxes:** set `hicortex_url` to the server's Tailscale hostname (e.g. `http://memory-server:8787`) and `HICORTEX_AUTH_TOKEN` to the server's token. Each box recalls from the same shared brain.
+- **Other Hermes boxes:** set `hicortex_url` to the server's hostname (e.g. `http://memory-server:8787`) and `HICORTEX_AUTH_TOKEN` to the server's token. Each box recalls from the same shared brain.
 
 ## Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "Self-learning memory for AI agents — experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {