@gamaze/hicortex 0.17.1 → 0.17.3

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/context.html

@@ -34,6 +34,7 @@
     --danger: #c0392b;
     --ok: #2f8f4e;
     --tab-active: #ffffff;
+    --nav-bg: #f6f7f9;
   }
   @media (prefers-color-scheme: dark) {
     :root {
@@ -47,6 +48,7 @@
       --danger: #e05555;
       --ok: #5fbf77;
       --tab-active: #0f1117;
+      --nav-bg: #010409;
     }
   }
   /* Explicit theme override wins over the media default in BOTH directions. */
@@ -54,11 +56,13 @@
     --bg: #ffffff; --panel: #f6f7f9; --panel-border: #d9dce2;
     --text: #1c1f26; --text-dim: #656d7a; --accent: #2f6fb0;
     --accent-text: #ffffff; --danger: #c0392b; --ok: #2f8f4e; --tab-active: #ffffff;
+    --nav-bg: #f6f7f9;
   }
   :root[data-theme="dark"] {
     --bg: #0f1117; --panel: #161a23; --panel-border: #262c3a;
     --text: #d5dae4; --text-dim: #8b93a5; --accent: #5b9dd9;
     --accent-text: #0b0d12; --danger: #e05555; --ok: #5fbf77; --tab-active: #0f1117;
+    --nav-bg: #010409;
   }
 
   * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -165,9 +169,33 @@
     padding: 8px; font: inherit; margin-bottom: 10px;
   }
   #token-err { color: var(--danger); font-size: 13px; margin-top: 8px; display: none; }
+
+  /* ---- shared console nav (#249) ---- */
+  .hc-nav {
+    display: flex; align-items: center; gap: 16px;
+    height: 48px; padding: 0 18px; flex: none;
+    background: var(--nav-bg);
+    border-bottom: 1px solid var(--panel-border);
+    font-size: 14px;
+  }
+  .hc-nav-logo { color: var(--text); font-weight: 600; text-decoration: none; letter-spacing: 0.02em; }
+  .hc-nav-links { margin-left: auto; display: flex; align-items: center; gap: 16px; }
+  .hc-nav-links a { color: var(--text-dim); text-decoration: none; transition: color 0.12s; }
+  .hc-nav-links a:hover { color: var(--accent); }
+  .hc-nav-links a[data-nav-active] { color: var(--text); }
+  .hc-nav-disabled { color: var(--text-dim); opacity: 0.4; cursor: not-allowed; user-select: none; }
 </style>
 </head>
 <body>
+<nav class="hc-nav">
+  <a class="hc-nav-logo" href="/dashboard">Hicortex</a>
+  <div class="hc-nav-links">
+    <a href="/dashboard">Dashboard</a>
+    <a href="/viz">Graph</a>
+    <a href="/context/ui" data-nav-active>Context</a>
+    <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
+  </div>
+</nav>
 <header>
   <h1>Hicortex — context</h1>
   <label class="meta" for="scope">scope</label>
@@ -249,6 +277,22 @@
     }
   })();
 
+  // Shared console nav (#249): append ?token= to internal nav links on click
+  // so navigation between pages doesn't re-authenticate. Reads token from any
+  // page-scoped localStorage key (each page historically used its own).
+  document.querySelectorAll(".hc-nav-links a, .hc-nav-logo").forEach(function (a) {
+    a.addEventListener("click", function (e) {
+      var t = token
+        || localStorage.getItem("hicortexToken")
+        || localStorage.getItem("hicortex-dashboard-token");
+      if (!t) return;
+      e.preventDefault();
+      var u = new URL(a.getAttribute("href"), location.origin);
+      u.searchParams.set("token", t);
+      location.href = u.toString();
+    });
+  });
+
   function authHeaders(extra) {
     var h = extra ? Object.assign({}, extra) : {};
     if (token) h["Authorization"] = "Bearer " + token;

package/assets/dashboard.html

@@ -41,6 +41,7 @@
       --accent-2: #2f8f4e;
       --warn: #b08030;
       --danger: #c0392b;
+      --nav-bg: #f6f7f9;
     }
   }
   * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -89,9 +90,42 @@
   table.digest td.k { color: var(--text-dim); width: 180px; }
   .stage-pill { display: inline-block; padding: 1px 6px; border-radius: 10px; background: rgba(128,128,128,0.18); font-size: 11px; color: var(--text-dim); margin-right: 4px; }
   .empty { color: var(--text-dim); font-style: italic; padding: 12px 0; }
+
+  /* ---- shared console nav (#249) ---- */
+  .hc-nav {
+    position: sticky; top: 0; z-index: 50;
+    display: flex; align-items: center; gap: 16px;
+    height: 48px; padding: 0 20px;
+    margin: -20px -20px 20px;
+    background: var(--nav-bg, #010409);
+    border-bottom: 1px solid var(--panel-border);
+    font-size: 14px;
+  }
+  .hc-nav-logo {
+    color: var(--text); font-weight: 600; text-decoration: none;
+    letter-spacing: 0.02em;
+  }
+  .hc-nav-links { margin-left: auto; display: flex; align-items: center; gap: 16px; }
+  .hc-nav-links a {
+    color: var(--text-dim); text-decoration: none; transition: color 0.12s;
+  }
+  .hc-nav-links a:hover { color: var(--accent); }
+  .hc-nav-links a[data-nav-active] { color: var(--text); }
+  .hc-nav-disabled {
+    color: var(--text-dim); opacity: 0.4; cursor: not-allowed; user-select: none;
+  }
 </style>
 </head>
 <body>
+<nav class="hc-nav">
+  <a class="hc-nav-logo" href="/dashboard">Hicortex</a>
+  <div class="hc-nav-links">
+    <a href="/dashboard" data-nav-active>Dashboard</a>
+    <a href="/viz">Graph</a>
+    <a href="/context/ui">Context</a>
+    <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
+  </div>
+</nav>
 <h1>Hicortex — memory dashboard</h1>
 <div class="sub">View-only analytics. All metrics derived from the live corpus + nightly snapshots.</div>
 
@@ -147,6 +181,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 +241,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 +442,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>`;
@@ -427,6 +540,22 @@ async function load() {
 }
 
 document.addEventListener("DOMContentLoaded", () => {
+  // Shared console nav (#249): append ?token= to internal nav links on click
+  // so navigation between pages doesn't re-authenticate. Reads the token from
+  // any of the page-scoped localStorage keys (each page historically used its
+  // own key) — keeps the snippet identical across the three served pages.
+  document.querySelectorAll(".hc-nav-links a, .hc-nav-logo").forEach(function (a) {
+    a.addEventListener("click", function (e) {
+      var t = token
+        || localStorage.getItem("hicortexToken")
+        || localStorage.getItem("hicortex-dashboard-token");
+      if (!t) return;
+      e.preventDefault();
+      var u = new URL(a.getAttribute("href"), location.origin);
+      u.searchParams.set("token", t);
+      location.href = u.toString();
+    });
+  });
   // Seed the date picker to the digest date from the first load (today).
   $("reload").addEventListener("click", load);
   $("range").addEventListener("change", load);

package/assets/viz.html

@@ -55,17 +55,26 @@
   #topbar {
     position: fixed; top: 0; left: 0; right: 0;
     display: flex; align-items: center; gap: 10px;
-    padding: 8px 12px;
+    height: 48px;
+    padding: 0 12px;
     background: rgba(22, 26, 35, 0.94);
     border-bottom: 1px solid var(--panel-border);
     z-index: 10;
   }
   #topbar h1 { font-size: 14px; font-weight: 600; white-space: nowrap; }
-  #meta { color: var(--text-dim); margin-left: auto; white-space: nowrap; }
+  #meta { color: var(--text-dim); white-space: nowrap; margin-left: auto; }
+
+  /* ---- shared console nav links (#249), integrated into the viz topbar ---- */
+  .hc-nav-logo { color: var(--text); text-decoration: none; letter-spacing: 0.02em; }
+  .hc-nav-links { margin-left: 16px; display: flex; align-items: center; gap: 16px; font-size: 14px; }
+  .hc-nav-links a { color: var(--text-dim); text-decoration: none; transition: color 0.12s; }
+  .hc-nav-links a:hover { color: var(--accent); }
+  .hc-nav-links a[data-nav-active] { color: var(--text); }
+  .hc-nav-disabled { color: var(--text-dim); opacity: 0.4; cursor: not-allowed; user-select: none; }
 
   /* ---- left control panel ---- */
   #panel {
-    position: fixed; top: 46px; left: 12px; width: 236px;
+    position: fixed; top: 48px; left: 12px; width: 236px;
     background: rgba(22, 26, 35, 0.94);
     border: 1px solid var(--panel-border); border-radius: 8px;
     padding: 12px; z-index: 10;
@@ -235,8 +244,14 @@
 <div id="graph-2d"></div>
 
 <div id="topbar">
-  <h1>Hicortex — knowledge graph</h1>
+  <h1 class="hc-nav-logo"><a href="/dashboard" style="color:inherit;text-decoration:none">Hicortex</a></h1>
   <span id="meta"></span>
+  <nav class="hc-nav-links">
+    <a href="/dashboard">Dashboard</a>
+    <a href="/viz" data-nav-active>Graph</a>
+    <a href="/context/ui">Context</a>
+    <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
+  </nav>
 </div>
 
 <div id="panel">
@@ -343,6 +358,22 @@
     }
   })();
 
+  // Shared console nav (#249): append ?token= to internal nav links on click
+  // so navigation between pages doesn't re-authenticate. Reads token from any
+  // page-scoped localStorage key (each page historically used its own).
+  document.querySelectorAll(".hc-nav-links a, .hc-nav-logo").forEach(function (a) {
+    a.addEventListener("click", function (e) {
+      var t = token
+        || localStorage.getItem("hicortexToken")
+        || localStorage.getItem("hicortex-dashboard-token");
+      if (!t) return;
+      e.preventDefault();
+      var u = new URL(a.getAttribute("href"), location.origin);
+      u.searchParams.set("token", t);
+      location.href = u.toString();
+    });
+  });
+
   // =========================================================================
   // DOM references
   // =========================================================================

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).
  */