@gamaze/hicortex 0.17.6 → 0.18.0

package/README.md

@@ -67,7 +67,7 @@ The plugin connects to `http://127.0.0.1:8787` by default. For a remote server,
 
 | When | What | How |
 |------|------|-----|
-| Agent start | Standing context (`## Context`) + recent lessons fetched fresh and injected | CC SessionStart hook (calls `hicortex lessons-context`) / Hermes plugin `system_prompt_block` / OC `before_agent_start` hook |
+| Agent start | Standing identity (`## Identity`) + recent lessons fetched fresh and injected | CC SessionStart hook (calls `hicortex learnings-identity`; `lessons-context` kept as an alias so existing installed hooks don't break) / Hermes plugin `system_prompt_block` / OC `before_agent_start` hook |
 | Every prompt (0.14) | A compact **recall index** of relevant memories is injected — one line per memory; the agent lazy-loads full content with `hicortex_get` only when needed | All three harnesses call server `POST /recall-index` per turn: CC UserPromptSubmit hook (`hicortex recall-hook`), Hermes plugin `prefetch` (0.7.0; falls back to `/search` injection against a pre-0.14 server), OC `before_agent_start` hook (fires per inbound message). Turn-based dedup per session; resets on new session/compaction. Fail-soft |
 | Nightly | Denoise sessions → POST /distill → server distills + embeds + stores → consolidate (score, reflect, link, decay) | Automatic pipeline — no manual steps |
 
@@ -132,28 +132,28 @@ The run is resumable — interrupt it any time and it continues where it stopped
 
 Explicit learnings: call `hicortex_ingest` directly (capture is otherwise automatic, nightly).
 
-## Context Layer
+## Identity Layer
 
-Beyond auto-distilled memories and lessons, Hicortex holds a **hand-edited context layer** — standing "who you are + how to work" Markdown injected into every session at start. Unlike memories, it is **never distilled, scored, or decayed**: what you write stays verbatim until you change it.
+Beyond auto-distilled memories and lessons, Hicortex holds a **hand-edited identity layer** — standing "who you are + how to work" Markdown injected into every session at start. Unlike memories, it is **never distilled, scored, or decayed**: what you write stays verbatim until you change it.
 
-- **Storage:** plain files on the server at `~/.hicortex/context/*.md` — one file per section (recommended starter sections `user.md` + `rules.md`, which you create — nothing is pre-populated; add more by dropping in a file). It lives outside the memories table; consolidation never touches it.
-- **Edit:** the web editor at `http://localhost:8787/context/ui` (one tab per section, Save), or the CLI `hicortex context show [name]` / `hicortex context edit <name>`.
-- **Delivery:** injected into the harnesses listed in `contextClients` (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc` — all three are supported since 0.13).
+- **Storage:** plain files on the server at `~/.hicortex/identity/*.md` — one file per section (recommended starter sections `user.md` + `rules.md`, which you create — nothing is pre-populated; add more by dropping in a file). It lives outside the memories table; consolidation never touches it.
+- **Edit:** the web editor at `http://localhost:8787/identity/ui` (one tab per section, Save), or the CLI `hicortex identity show [name]` / `hicortex identity edit <name>`.
+- **Delivery:** injected into the harnesses listed in `identityClients` (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc` — all three are supported since 0.13).
 - **Deletion** is filesystem-only — remove the file on the server (as the daemon user).
 
-### Per-agent context (0.13)
+### Per-agent identity (0.13)
 
-One server serves a fleet of distinct-persona agents. Each agent can have its **own** context, resolved server-side into one of three modes:
+One server serves a fleet of distinct-persona agents. Each agent can have its **own** identity, resolved server-side into one of three modes:
 
 - **`override`** (default when an `agents/<id>/` dir exists) — the agent's sections win **per section name**, falling back to the global set for any section it doesn't define.
 - **`global`** — the shared global set (the 0.12 behavior).
 - **`off`** — inject nothing for that agent.
 
-- **Agent id:** Hermes and OC scope per profile/agent automatically. **CC is global by default** — it sends no `?agent=`, so all your CC machines share one global context (one user = one identity across machines). `agentName` is an explicit opt-in: set it with `init --agent-name <name>` and CC will send `?agent=<config.agentName>`; clear it with `init --agent-name ""` to return to global. The id is on the same strict allowlist as section names (it becomes a path). Shown by `hicortex status` (or `(not set — global context)` when unset).
-- **Storage:** per-agent sections live at `~/.hicortex/context/agents/<id>/*.md`; the global reader never descends into `agents/`.
-- **Config:** `contextAgents` maps agent id → mode; a dropped-in `agents/<id>/` dir alone means `override` with no config. Editing `contextAgents` needs a daemon restart; dropping in a dir takes effect immediately.
-- **Edit:** the web editor's scope selector (`Global` | `<agent>`; inherited sections shown dimmed), or `hicortex context show|edit --agent <id>`.
-- **Backward compatible:** no `?agent=` and no `contextAgents`/`agents/` dir → every agent gets the global set.
+- **Agent id:** Hermes and OC scope per profile/agent automatically. **CC is global by default** — it sends no `?agent=`, so all your CC machines share one global identity (one user = one identity across machines). `agentName` is an explicit opt-in: set it with `init --agent-name <name>` and CC will send `?agent=<config.agentName>`; clear it with `init --agent-name ""` to return to global. The id is on the same strict allowlist as section names (it becomes a path). Shown by `hicortex status` (or `(not set — global identity)` when unset).
+- **Storage:** per-agent sections live at `~/.hicortex/identity/agents/<id>/*.md`; the global reader never descends into `agents/`.
+- **Config:** `identityAgents` maps agent id → mode; a dropped-in `agents/<id>/` dir alone means `override` with no config. Editing `identityAgents` needs a daemon restart; dropping in a dir takes effect immediately.
+- **Edit:** the web editor's scope selector (`Global` | `<agent>`; inherited sections shown dimmed), or `hicortex identity show|edit --agent <id>`.
+- **Backward compatible:** no `?agent=` and no `identityAgents`/`agents/` dir → every agent gets the global set.
 
 ## CLI Commands
 
@@ -168,11 +168,11 @@ npx @gamaze/hicortex classify-domains          # Backfill domain tags over the c
 npx @gamaze/hicortex classify-types            # Reclassify memory types (episode/fact/decision)
 npx @gamaze/hicortex dedup                     # Preview near-duplicate memory clusters (dry run, no changes)
 npx @gamaze/hicortex dedup --apply             # Merge near-duplicate clusters (backs up the DB first)
-npx @gamaze/hicortex context show [name]       # Print the standing context layer (see Context Layer)
-npx @gamaze/hicortex context edit <name>       # Edit a context section in $EDITOR
-npx @gamaze/hicortex context show --agent <id> # Show a specific agent's resolved context (0.13)
-npx @gamaze/hicortex init --agent-name <name>  # Opt in to a per-agent context id (default: unset — shared global context)
-npx @gamaze/hicortex init --agent-name ""      # Clear it back to global context
+npx @gamaze/hicortex identity show [name]       # Print the standing identity layer (see Identity Layer)
+npx @gamaze/hicortex identity edit <name>       # Edit an identity section in $EDITOR
+npx @gamaze/hicortex identity show --agent <id> # Show a specific agent's resolved identity (0.13)
+npx @gamaze/hicortex init --agent-name <name>   # Opt in to a per-agent identity id (default: unset — shared global identity)
+npx @gamaze/hicortex init --agent-name ""       # Clear it back to global identity
 npx @gamaze/hicortex init --repair-config      # Recover from a malformed config.json (see below)
 npx @gamaze/hicortex telemetry                 # Show exactly what anonymous telemetry sends
 npx @gamaze/hicortex status                    # Show config, DB stats
@@ -215,17 +215,18 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `ollamaFlushEvery` | Flush ollama's accumulated memory every N scoring calls. **Off by default (0)** — opt-in only for an **ollama** install whose runner RSS growth (~171 MB/call) swap-thrashes long consolidations on a RAM-constrained box; N=15 caps a cycle at ~2.5 GB. Gated on the provider being ollama (local **or** remote) — no effect for non-ollama providers. Only you can judge whether your ollama endpoint actually suffers the growth (a managed/cloud ollama host may not), so it stays off until you set it. |
 | `ollamaFlushWaitMs` | Milliseconds to wait after an ollama flush for the runner to exit + release memory (default 180000 = 3 min). |
 | `authToken` | Bearer token for endpoint auth. Generated on first `init` in server mode. Find the active token with `hicortex status` or in `~/.hicortex/config.json`. |
-| `corsAllowedOrigins` | Browser origins allowed to read cross-origin responses, e.g. `["https://ui.example.com"]`. **Empty by default** — the server sends no `Access-Control-Allow-Origin` and never `Allow-Credentials`, so no external web page can read its data. The bundled `/viz` and `/context/ui` pages are same-origin and need no entry. |
+| `corsAllowedOrigins` | Browser origins allowed to read cross-origin responses, e.g. `["https://ui.example.com"]`. **Empty by default** — the server sends no `Access-Control-Allow-Origin` and never `Allow-Credentials`, so no external web page can read its data. The bundled `/viz` and `/identity/ui` pages are same-origin and need no entry. |
 | `licenseKey` | Commercial license key (optional; for display in `hicortex status`) |
 | `domains` | Your memory domain list (`[{name, description}]`). Scaffolded by `init`; edit freely — see [Memory Domains & Tags](#memory-domains--tags) |
 | `weakPrimaryFloor` | Minimum similarity for a no-fit memory to keep a weak domain association (default: 0.45) |
 | `moduleIndexTokenBudget` | Max tokens for domain index in lessons context (default: 500) |
 | `lessonsLimit` | Max lessons injected into an agent's session-start context (default: 10). Lessons are ranked per session by project/domain affinity + recency + strength + access, so each session sees its most-relevant slice. Lower = leaner system prompts. |
-| `contextClients` | Which harnesses inject the [context layer](#context-layer) at session start (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc`) |
-| `contextAgents` | Per-agent context modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent context](#per-agent-context-013) |
-| `agentName` | This install's per-agent context id sent as `?agent=`. **Unset by default** (CC shares the global context — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |
+| `identityClients` | Which harnesses inject the [identity layer](#identity-layer) at session start (default `["cc"]`; `"all"` or any subset of `cc`/`hermes`/`oc`) |
+| `identityAgents` | Per-agent identity modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent identity](#per-agent-identity-013) |
+| `agentName` | This install's per-agent identity id sent as `?agent=`. **Unset by default** (CC shares the global identity — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |
 | `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 |
+| `timerJitterSeconds` | Max random delay (seconds) added to **generated** consolidation timers (#256), so a fleet doesn't all fire on the same minute (thundering-herd → LLM-backend contention). systemd: a single `RandomizedDelaySec=<n>`; launchd has no native equivalent so a per-install randomized `Minute` offset is baked into every `StartCalendarInterval` dict (sub-60s values no-op on launchd). Default `3600` (≈±30 min spread on the 2-slot/day cadence); `0` disables. Affects timers on the next `init` (re-init rewrites the unit files; installs that don't re-init keep their existing timers) |
 | `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) |
@@ -268,8 +269,8 @@ Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze
 | `/recall-index` | POST | Yes | Pushed recall index (0.14): `{session_id, prompt}` → compact one-line-per-memory block (or `null`); `{session_id, reset: true}` clears the session's dedup state. Appearing in the index marks memories *shown*, never *used* |
 | `/memory` | GET | Yes | Fetch one memory by `?id=` (0.14). Marks it as used (strengthens) — the lazy-load counterpart of `/recall-index`. Response includes a server-rendered `citation` (id, date, origin agent) — agents are instructed to cite memories that shape their answers, so memory influence is always visible to the user (0.14.1) |
 | `/recent` | GET | Yes | Recent memories, queryless recall (renamed from `/context` in 0.12) |
-| `/context` | GET / PUT | Yes | Standing [context layer](#context-layer): read all sections / partial-upsert named sections. `?agent=<id>` selects a [per-agent scope](#per-agent-context-013) (server resolves override/global/off + merge); invalid id → 400. Recall-style query params on GET → 400 (use `/recent`) |
-| `/context/ui` | GET | No* | Web editor for the context layer (shell served without auth, like `/viz`; data via `/context`) |
+| `/identity` | GET / PUT | Yes | Standing [identity layer](#identity-layer): read all sections / partial-upsert named sections. `?agent=<id>` selects a [per-agent scope](#per-agent-identity-013) (server resolves override/global/off + merge); invalid id → 400. Recall-style query params on GET → 400 (use `/recent`). (`/context` remains as a backcompat alias.) |
+| `/identity/ui` | GET | No* | Web editor for the identity layer (shell served without auth, like `/viz`; data via `/identity`) |
 | `/lessons` | GET | Yes | Lessons + memory index (used by CC SessionStart hook) |
 | `/ingest` | POST | Yes | Legacy: accept a single pre-distilled memory from older clients |
 | `/sse` | GET | Yes | MCP SSE stream for agent connections |
@@ -311,7 +312,7 @@ LLM selection is **user-controlled**: `npx @gamaze/hicortex init` detects candid
 | Custom provider | `llmBaseUrl` + `llmApiKey` | Any OpenAI-compatible endpoint |
 | Hicortex env vars | `HICORTEX_LLM_BASE_URL` + `HICORTEX_LLM_API_KEY` | Override at runtime |
 
-If no LLM is configured, the server starts in **recall-only mode**: search, lessons, and context work; `/distill` and consolidation are disabled. Run `npx @gamaze/hicortex init` to configure.
+If no LLM is configured, the server starts in **recall-only mode**: search, lessons, and identity work; `/distill` and consolidation are disabled. Run `npx @gamaze/hicortex init` to configure.
 
 ## Database
 

package/assets/dashboard.html

@@ -122,7 +122,7 @@
   <div class="hc-nav-links">
     <a href="/dashboard" data-nav-active>Dashboard</a>
     <a href="/viz">Graph</a>
-    <a href="/context/ui">Context</a>
+    <a href="/identity/ui">Identity</a>
     <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
   </div>
 </nav>
@@ -183,6 +183,10 @@
   <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 id="digest-budget-section" style="margin-top:16px;display:none;">
+    <div class="sub" style="margin-bottom:6px;">Consolidation + LLM usage — two usage-vs-budget bars: per-run LLM calls spent vs the consolidation ceiling, and this billing period's tokens vs the monthly fair-use cap. The amber pill appears only when the call cap was hit. The tokens bar renders only when a monthly cap is configured (cap &gt; 0); uncapped installs (the self-hosted default) show the absolute token count instead.</div>
+    <div id="digest-budget"></div>
+  </div>
 </div>
 
 <div class="sub muted" style="margin-top:24px;">
@@ -194,7 +198,7 @@
 <script>
 "use strict";
 // ---------------------------------------------------------------------------
-// Token handling — mirror /viz + /context/ui: ?token= handoff (stripped on
+// Token handling — mirror /viz + /identity/ui: ?token= handoff (stripped on
 // load), localStorage persistence, 401 prompt. Same-origin fetch only.
 // ---------------------------------------------------------------------------
 const TOKEN_KEY = "hicortex-dashboard-token";
@@ -234,6 +238,17 @@ let compKey = "by_type";
 
 const $ = (id) => document.getElementById(id);
 
+// #264 WS2: human-term labels for the internal memory_type enum. The data
+// blob carries the RAW enum keys (a stable JSON contract, also relied on by
+// tests); only the rendered label changes. Unknown keys pass through.
+const TYPE_LABELS = {
+  fact: "Knowledge",
+  episode: "Experience",
+  decision: "Decisions",
+  lesson: "Learnings"
+};
+function labelForType(t) { return TYPE_LABELS[t] || t; }
+
 // ---------------------------------------------------------------------------
 // Render: headline
 // ---------------------------------------------------------------------------
@@ -419,7 +434,10 @@ function renderComposition(comp, key) {
     // attacker-influenced (any authenticated /distill client sets source_agent
     // verbatim). Injected into both a title="..." attribute and text — close
     // the attribute and add an on* handler otherwise.
-    const ek = escapeHtml(k);
+    // #264 WS2: when the composition key is by_type, show the human-term label
+    // (Knowledge/Experience/...) instead of the raw enum value.
+    const display = compKey === "by_type" ? labelForType(k) : k;
+    const ek = escapeHtml(display);
     return `<div class="bar-row"><span class="k" title="${ek}">${ek}</span><span class="track"><span class="fill" style="width:${pct}%"></span></span><span class="n">${v}</span></div>`;
   }).join("");
 }
@@ -434,7 +452,7 @@ function linkId(id) {
   // is a server hex token but escape the text anyway (defense-in-depth).
   return `<a href="/memory?id=${encodeURIComponent(id)}" title="Open memory">${escapeHtml(id.slice(0, 8))}</a>`;
 }
-function renderDigest(digest) {
+function renderDigest(digest, tokens) {
   $("digest-date").textContent = digest.date || "—";
   const s = digest.stages;
   const stages = [
@@ -444,6 +462,8 @@ function renderDigest(digest) {
     `<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>` : "",
+    // #255 CR: budget exhaustion pill lives in the dedicated budget-usage bar
+    // below (alert state on top of the continuous used/max bar), not here.
   ].join(" ");
   $("digest-stages").innerHTML = stages;
   // Per-stage token breakdown (#246) — only when the day's run metered tokens
@@ -464,6 +484,102 @@ function renderDigest(digest) {
     $("digest-tokens-section").style.display = "none";
   }
 
+  // #255 CR + tokens-vs-cap: TWO usage-vs-budget bars in this section.
+  //
+  // Bar 1 — Consolidation calls (per-run): budget_calls_used / budget_max_calls.
+  //   Renders whenever the day's run carried both (consolidation ran). The
+  //   amber "budget exhausted" pill sits on top as the alert state.
+  //
+  // Bar 2 — LLM tokens (monthly): tokens.used / tokens.cap, where cap is the
+  //   configured `llmTokensPerMonth` fair-use cap. CONDITIONAL (see the
+  //   section doc): cap > 0 → render a used/cap bar in the SAME green/amber/
+  //   red style; cap <= 0 (the self-hosted default, "unlimited") → render the
+  //   absolute usage figure only (no broken "X / 0" bar). Hidden entirely
+  //   when used is 0 (no metered run yet) — mirroring the headline stat.
+  //
+  // The section shows when EITHER bar renders. XSS-safe: only numbers flow
+  // in (Number + toLocaleString / formatTokens), the only string (deferred
+  // JSON) is escapeHtml'd.
+  const used = s.budget_calls_used;
+  const cap = s.budget_max_calls;
+  const haveCallsBar = typeof used === "number" && typeof cap === "number" && cap > 0;
+
+  // Tokens monthly accrual comes from headline.tokens (state.llmTokensThisPeriod,
+  // the same source the throttle check reads). cap <= 0 = unlimited.
+  const tokUsed = tokens && typeof tokens.used === "number" ? tokens.used : 0;
+  const tokCap = tokens && typeof tokens.cap === "number" ? tokens.cap : 0;
+  const haveTokensBar = tokUsed > 0 && tokCap > 0;
+  const haveTokensAbsolute = tokUsed > 0 && !(tokCap > 0); // uncapped: figure only
+
+  if (haveCallsBar || haveTokensBar || haveTokensAbsolute) {
+    const pieces = [];
+
+    // Bar 1: Consolidation calls.
+    if (haveCallsBar) {
+      const pct = Math.min(100, (used / cap) * 100);
+      const exhausted = s.budget_exhausted === true;
+      const over = used >= cap;
+      const near = pct >= 85 && !over;
+      const barColor = over ? "var(--bad, #e05555)" : near ? "var(--warn, #e0b055)" : "var(--ok, #61c98f)";
+      const deferred = s.budget_deferred_by_stage ?? {};
+      const pill = exhausted
+        ? ` <span class="stage-pill warn" title="Consolidation budget exhausted — LLM-bound stages deferred remaining work. Per-stage refused-request counts: ${escapeHtml(JSON.stringify(deferred))}">budget exhausted</span>`
+        : "";
+      pieces.push(`
+        <div style="margin-bottom:10px;">
+          <div class="muted" style="font-size:12px;margin-bottom:4px;text-transform:uppercase;letter-spacing:0.04em;">Consolidation calls (this run)</div>
+          <div style="display:flex;align-items:center;gap:12px;flex-wrap:wrap;">
+            <div style="flex:1;min-width:200px;">
+              <div class="muted" style="font-size:13px;margin-bottom:4px;">
+                ${used.toLocaleString()} / ${cap.toLocaleString()} LLM calls${exhausted ? " — exhausted" : ""}
+              </div>
+              <div style="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>${pill}
+          </div>
+        </div>`);
+    }
+
+    // Bar 2: LLM tokens (monthly). Conditional on cap > 0 for the bar form;
+    // otherwise show the absolute usage figure (uncapped installs).
+    if (haveTokensBar) {
+      const pct = Math.min(100, (tokUsed / tokCap) * 100);
+      const over = tokUsed >= tokCap;
+      const near = pct >= 85 && !over;
+      const barColor = over ? "var(--bad, #e05555)" : near ? "var(--warn, #e0b055)" : "var(--ok, #61c98f)";
+      pieces.push(`
+        <div>
+          <div class="muted" style="font-size:12px;margin-bottom:4px;text-transform:uppercase;letter-spacing:0.04em;">LLM tokens (monthly)</div>
+          <div style="display:flex;align-items:center;gap:12px;flex-wrap:wrap;">
+            <div style="flex:1;min-width:200px;">
+              <div class="muted" style="font-size:13px;margin-bottom:4px;">
+                ${escapeHtml(formatTokens(tokUsed))} / ${escapeHtml(formatTokens(tokCap))} tokens${over ? " — over cap" : ""}
+              </div>
+              <div style="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>
+          </div>
+        </div>`);
+    } else if (haveTokensAbsolute) {
+      // Unlimited case (cap <= 0, the self-hosted default): no denominator to
+      // draw a bar against, so show the absolute usage figure only. Never
+      // render a broken "X / 0" bar.
+      pieces.push(`
+        <div>
+          <div class="muted" style="font-size:12px;margin-bottom:4px;text-transform:uppercase;letter-spacing:0.04em;">LLM tokens (monthly) <span style="text-transform:none;letter-spacing:0;">— uncapped</span></div>
+          <div class="muted" style="font-size:13px;">${escapeHtml(formatTokens(tokUsed))} tokens this month</div>
+        </div>`);
+    }
+
+    $("digest-budget").innerHTML = pieces.join("");
+    $("digest-budget-section").style.display = "";
+  } else {
+    $("digest-budget").innerHTML = "";
+    $("digest-budget-section").style.display = "none";
+  }
+
   if (digest.sample.length === 0) {
     $("digest-sample").innerHTML = `<div class="empty">No new memories that day.</div>`;
   } else {
@@ -517,7 +633,7 @@ async function load() {
   renderHeadline(state.headline);
   renderGrowth(state.series, $("split").value, $("filter").value);
   renderComposition(state.composition, compKey);
-  renderDigest(state.digest);
+  renderDigest(state.digest, state.headline.tokens);
 
   // Populate the growth-filter from source_agent + domain union (best-effort —
   // a v1 affordance; the series already carries per-day totals, so the filter

package/assets/{context.html → identity.html}

@@ -3,18 +3,18 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Hicortex — context</title>
+<title>Hicortex — identity</title>
 <!--
-  Hicortex standing-context editor (#165, 0.12 — spec 2026-07-12 §5).
-  Self-contained: inline CSS/JS, ZERO external requests (CSP-safe). The PRIMARY
-  edit surface for the context layer.
+  Hicortex standing-identity editor (#165, 0.12 — spec 2026-07-12 §5; renamed
+  from "context" in 0.18 #264). Self-contained: inline CSS/JS, ZERO external
+  requests (CSP-safe). The PRIMARY edit surface for the identity layer.
 
-  One tab per section, tabs built dynamically from GET /context `sections`
+  One tab per section, tabs built dynamically from GET /identity `sections`
   (the server serves any allowlist-named *.md as a section — nothing hardcoded).
   Each tab is a <textarea>; Save PUTs only the active section (partial upsert).
 
   The page SHELL is public (exempted in createAuthMiddleware like /viz); the
-  GET/PUT /context data calls are bearer-only with a localhost bypass, so on the
+  GET/PUT /identity data calls are bearer-only with a localhost bypass, so on the
   server box no token is needed. Remote browsers hand off a token via
   ?token=<t> (stripped from the URL on load), localStorage, or a 401 prompt.
 
@@ -192,14 +192,14 @@
   <div class="hc-nav-links">
     <a href="/dashboard">Dashboard</a>
     <a href="/viz">Graph</a>
-    <a href="/context/ui" data-nav-active>Context</a>
+    <a href="/identity/ui" data-nav-active>Identity</a>
     <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
   </div>
 </nav>
 <header>
-  <h1>Hicortex — context</h1>
+  <h1>Hicortex — identity</h1>
   <label class="meta" for="scope">scope</label>
-  <select id="scope" title="Which agent's context to edit"></select>
+  <select id="scope" title="Which agent's identity to edit"></select>
   <input type="text" id="newagent" placeholder="new-agent-id" autocomplete="off" spellcheck="false">
   <button class="btn secondary small" id="addagent">Add agent</button>
   <span class="meta" id="clients"></span>
@@ -251,7 +251,7 @@
 "use strict";
 (function () {
   // =========================================================================
-  // Section-name allowlist — mirrors the server contract (context-store.ts
+  // Section-name allowlist — mirrors the server contract (identity-store.ts
   // SECTION_NAME_RE / SECTION_NAME_MAX). Client check is UX; the server also
   // enforces it and is the authority.
   // =========================================================================
@@ -346,14 +346,14 @@
   var afterAuth = null;     // action to retry after a successful token prompt
 
   // Per-agent scope (0.13). scope = null → the global set; otherwise an agent
-  // id, and edits target PUT /context?agent=<id>. `agents` is the id -> mode
+  // id, and edits target PUT /identity?agent=<id>. `agents` is the id -> mode
   // map from the bare (global) GET; `origins` is the id -> "global"|"agent"
   // provenance from an agent-scope GET (used to dim inherited tabs).
   var scope = null;
   var agents = {};
   var origins = {};
 
-  // ?agent= query for the active scope. Written so the literal fetch("/context"
+  // ?agent= query for the active scope. Written so the literal fetch("/identity"
   // survives the self-containment test; the server does the resolution.
   function scopeQS() {
     return scope ? "?agent=" + encodeURIComponent(scope) : "";
@@ -447,11 +447,11 @@
   }
 
   // =========================================================================
-  // Load — GET /context, build tabs from the returned sections keys.
+  // Load — GET /identity, build tabs from the returned sections keys.
   // =========================================================================
   function load() {
     setMsg("Loading…", "dim");
-    fetch("/context" + scopeQS(), { headers: authHeaders() })
+    fetch("/identity" + scopeQS(), { headers: authHeaders() })
       .then(function (resp) {
         if (resp.status === 401) { afterAuth = load; showTokenPrompt(); throw new Error("unauthorized"); }
         if (!resp.ok) {
@@ -497,7 +497,7 @@
   }
 
   // =========================================================================
-  // Save — PUT /context with ONLY the active section (partial upsert).
+  // Save — PUT /identity with ONLY the active section (partial upsert).
   // =========================================================================
   function save() {
     if (!active) return;
@@ -515,7 +515,7 @@
 
     saveBtn.disabled = true;
     setMsg("Saving…", "dim");
-    fetch("/context" + scopeQS(), {
+    fetch("/identity" + scopeQS(), {
       method: "PUT",
       headers: authHeaders({ "Content-Type": "application/json" }),
       body: JSON.stringify(payload),
@@ -576,7 +576,7 @@
   }
 
   // =========================================================================
-  // Scope switching — reload the selected agent's (or the global) context.
+  // Scope switching — reload the selected agent's (or the global) identity.
   // Warns before discarding unsaved edits in the current scope.
   // =========================================================================
   function anyDirty() {
@@ -623,7 +623,7 @@
     try { localStorage.setItem("hicortexToken", v); } catch (e) { /* ignore */ }
     tokenErr.style.display = "none";
     // Verify with a cheap GET before closing; retry the pending action on success.
-    fetch("/context", { headers: authHeaders() }).then(function (resp) {
+    fetch("/identity", { headers: authHeaders() }).then(function (resp) {
       if (resp.status === 401) { tokenErr.style.display = "block"; return; }
       overlay.classList.remove("open");
       var next = afterAuth || load;

package/assets/viz.html

@@ -249,7 +249,7 @@
   <nav class="hc-nav-links">
     <a href="/dashboard">Dashboard</a>
     <a href="/viz" data-nav-active>Graph</a>
-    <a href="/context/ui">Context</a>
+    <a href="/identity/ui">Identity</a>
     <span class="hc-nav-disabled" title="Coming soon — #250">Self-improvement</span>
   </nav>
 </div>
@@ -259,7 +259,7 @@
   <div class="row" data-tip="Show only memories from one knowledge domain. Node colors match domains (see legend)."><label for="f-domain">Domain</label>
     <select id="f-domain"><option value="">all</option></select>
   </div>
-  <div class="row" data-tip="Show only one memory type (episode, lesson, fact…)."><label for="f-type">Type</label>
+  <div class="row" data-tip="Show only one memory type (Knowledge, Experience, Decisions, Learnings)."><label for="f-type">Type</label>
     <select id="f-type"><option value="">all</option></select>
   </div>
   <div class="row" data-tip="Hide memories weaker than this. Strength decays over time and grows with use and links — node size shows it."><label for="f-strength">Min strength</label>
@@ -388,6 +388,18 @@
   var metaEl = document.getElementById("meta");
   var selDomain = document.getElementById("f-domain");
   var selType = document.getElementById("f-type");
+
+  // #264 WS2: human-term labels for the internal memory_type enum. Node data
+  // carries the RAW enum (the /graph JSON contract filters on it); only the
+  // rendered strings change. Unknown values pass through unchanged.
+  var TYPE_LABELS = {
+    fact: "Knowledge",
+    episode: "Experience",
+    decision: "Decisions",
+    lesson: "Learnings"
+  };
+  function labelForType(t) { return TYPE_LABELS[t] || t; }
+
   var rngStrength = document.getElementById("f-strength");
   var rngStrengthVal = document.getElementById("f-strength-val");
   var inpLimit = document.getElementById("f-limit");
@@ -604,7 +616,7 @@
     dataVersion++;
 
     fillSelect(selDomain, data.domains || []);
-    fillSelect(selType, data.types || []);
+    fillSelect(selType, data.types || [], labelForType);
     buildDomainLegend(data.domains || []);
     buildEdgeLegend(data.edges || []);
     computeLabeled();
@@ -697,12 +709,12 @@
     }
   }
 
-  function fillSelect(sel, values) {
+  function fillSelect(sel, values, labeler) {
     var current = sel.value;
     while (sel.options.length > 1) sel.remove(1);
     values.forEach(function (v) {
       var opt = document.createElement("option");
-      opt.value = v; opt.textContent = v;
+      opt.value = v; opt.textContent = labeler ? labeler(v) : v;
       sel.appendChild(opt);
     });
     sel.value = values.indexOf(current) >= 0 ? current : "";
@@ -733,7 +745,7 @@
 
   function tooltipHtml(n) {
     return "<b>" + esc(labelText(n)) + "</b><br>" +
-      esc((n.domain || "no domain") + " · " + (n.memory_type || "?") +
+      esc((n.domain || "no domain") + " · " + labelForType(n.memory_type || "?") +
           " · strength " + (typeof n.strength === "number" ? n.strength.toFixed(2) : "?"));
   }
 
@@ -1070,7 +1082,7 @@
       ["ID", n.id],
       ["Domain", n.domain || "—"],
       ["Project", n.project || "—"],
-      ["Type", n.memory_type || "—"],
+      ["Type", labelForType(n.memory_type || "—")],
       ["Strength", typeof n.strength === "number" ? n.strength.toFixed(3) : "—"],
       ["Links", String(n.linkCount) + (n.isHub ? " (hub)" : "")],
       ["Created", n.created_at || "—"]

package/dist/claude-md.d.ts

@@ -2,7 +2,8 @@
  * CLAUDE.md block management — removeLessonsBlock only (0.9.0+).
  *
  * Lesson injection was removed in 0.9.0: lessons are now fetched at query time
- * via the CC SessionStart hook (`hicortex lessons-context`) and by the Hermes
+ * via the CC SessionStart hook (`hicortex learnings-identity`, aliased as the
+ * legacy `lessons-context`) and by the Hermes
  * plugin's prefetch/system_prompt_block. File-based injection caused EPERM
  * errors on macOS, stale blocks, and unwinnable multi-file bookkeeping.
  *

package/dist/claude-md.js

@@ -3,7 +3,8 @@
  * CLAUDE.md block management — removeLessonsBlock only (0.9.0+).
  *
  * Lesson injection was removed in 0.9.0: lessons are now fetched at query time
- * via the CC SessionStart hook (`hicortex lessons-context`) and by the Hermes
+ * via the CC SessionStart hook (`hicortex learnings-identity`, aliased as the
+ * legacy `lessons-context`) and by the Hermes
  * plugin's prefetch/system_prompt_block. File-based injection caused EPERM
  * errors on macOS, stale blocks, and unwinnable multi-file bookkeeping.
  *

package/dist/cli-args.d.ts

@@ -14,3 +14,12 @@ export declare class MissingFlagValueError extends Error {
  * `--server` as the agent name — a typo must be loud.
  */
 export declare function readValueFlag(argv: string[], flag: string): string | undefined;
+/**
+ * Normalize a raw CLI command word. Hidden aliases resolve to their canonical
+ * name so the cli.ts dispatch switch only spells the canonical form. Aliases
+ * today (#264 rename): `context` → `identity` and `lessons-context` →
+ * `learnings-identity`; kept so old scripts, installed hooks, and muscle memory
+ * keep working. Pure + side-effect-free (unlike cli.ts, which dispatches on
+ * import) so it can be unit-tested directly.
+ */
+export declare function resolveCommandAlias(raw: string | undefined): string | undefined;

package/dist/cli-args.js

@@ -7,6 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MissingFlagValueError = void 0;
 exports.readValueFlag = readValueFlag;
+exports.resolveCommandAlias = resolveCommandAlias;
 /** Thrown when a value-flag is present but missing its value. */
 class MissingFlagValueError extends Error {
 }
@@ -28,3 +29,18 @@ function readValueFlag(argv, flag) {
     }
     return val;
 }
+/**
+ * Normalize a raw CLI command word. Hidden aliases resolve to their canonical
+ * name so the cli.ts dispatch switch only spells the canonical form. Aliases
+ * today (#264 rename): `context` → `identity` and `lessons-context` →
+ * `learnings-identity`; kept so old scripts, installed hooks, and muscle memory
+ * keep working. Pure + side-effect-free (unlike cli.ts, which dispatches on
+ * import) so it can be unit-tested directly.
+ */
+function resolveCommandAlias(raw) {
+    if (raw === "context")
+        return "identity";
+    if (raw === "lessons-context")
+        return "learnings-identity";
+    return raw;
+}