@gamaze/hicortex 0.17.6 → 0.18.0

package/dist/paths.js

@@ -8,7 +8,7 @@ exports.hicortexHome = hicortexHome;
  * HICORTEX_DB_PATH convention in db.ts); otherwise defaults to ~/.hicortex.
  * Every module that needs the home dir routes through here, so the override
  * behaves consistently across all commands instead of being honored by some
- * (context-cli, lessons-context) and hardcoded away by others.
+ * (identity-cli, learnings-identity) and hardcoded away by others.
  */
 const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");

package/dist/recall-hook-cli.d.ts

@@ -8,7 +8,7 @@
  *   - SessionStart (startup/resume/clear/compact): POST a reset so the
  *     server's per-session shown-set matches the fresh context window.
  *
- * Fail-soft like lessons-context: ANY failure (no config, timeout, non-2xx,
+ * Fail-soft like learnings-identity: ANY failure (no config, timeout, non-2xx,
  * parse error) prints nothing and exits 0 — a broken hook must never block or
  * slow a CC session beyond the fetch timeout (1000 ms, owner-set).
  */

package/dist/recall-hook-cli.js

@@ -9,14 +9,14 @@
  *   - SessionStart (startup/resume/clear/compact): POST a reset so the
  *     server's per-session shown-set matches the fresh context window.
  *
- * Fail-soft like lessons-context: ANY failure (no config, timeout, non-2xx,
+ * Fail-soft like learnings-identity: ANY failure (no config, timeout, non-2xx,
  * parse error) prints nothing and exits 0 — a broken hook must never block or
  * slow a CC session beyond the fetch timeout (1000 ms, owner-set).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildHookRequest = buildHookRequest;
 exports.runRecallHook = runRecallHook;
-const lessons_context_js_1 = require("./lessons-context.js");
+const learnings_identity_js_1 = require("./learnings-identity.js");
 const node_path_1 = require("node:path");
 const FETCH_TIMEOUT_MS = 1000;
 /** Read all of stdin (CC pipes the hook payload JSON). */
@@ -51,7 +51,7 @@ function buildHookRequest(payload, cwd = process.cwd()) {
     return { session_id: sessionId, prompt, project: (0, node_path_1.basename)(cwd) };
 }
 async function runRecallHook() {
-    const cfg = (0, lessons_context_js_1.resolveConfig)();
+    const cfg = (0, learnings_identity_js_1.resolveConfig)();
     if (!cfg)
         return;
     let payload;

package/dist/recall-index.js

@@ -62,6 +62,7 @@ exports.handleRecallIndex = handleRecallIndex;
 exports.handleMemoryGet = handleMemoryGet;
 exports.formatMemoryGetText = formatMemoryGetText;
 const storage = __importStar(require("./storage.js"));
+const type_labels_js_1 = require("./type-labels.js");
 /** Relevance-gate floor for vector-only candidates (config `recallMinSimilarity`).
  *  0.62 (was 0.55; raised 2026-08-03 on the fine-grain floor sweep — see the
  *  minSimilarity doc above). */
@@ -116,7 +117,7 @@ function formatIndexLine(r, maxLen = DEFAULT_TITLE_CHARS) {
         formatDate(r.created_at),
         r.domain ?? r.project ?? undefined,
         r.source_agent ?? undefined,
-        r.memory_type,
+        (0, type_labels_js_1.labelForType)(r.memory_type),
     ]
         .filter(Boolean)
         .join(", ");
@@ -281,7 +282,9 @@ function formatMemoryGetText(db, query) {
     const mem = r.body.memory;
     const citation = r.body.citation; // carries FETCHED (#204)
     const date = (mem.created_at ?? "").slice(0, 10);
-    const header = `[memory ${mem.id} | ${mem.memory_type ?? "episode"} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
+    // #264 WS2: render the human-term label (Knowledge/Experience/...), not the
+    // internal enum, in the citation header shown to the agent/user.
+    const header = `[memory ${mem.id} | ${(0, type_labels_js_1.labelForType)(mem.memory_type ?? "episode")} | ${mem.project ?? "-"} | from ${mem.source_agent ?? "unknown"} | ${date}]\n` +
         `Cite as ${citation} where this shapes your answer; it may be stale — newer memories supersede older.`;
     return { status: 200, text: `${header}\n\n${mem.content ?? ""}` };
 }

package/dist/status.d.ts

@@ -4,9 +4,9 @@
 /**
  * The value shown after "Agent name:" in `hicortex status` (#179, A3). Reports
  * EXACTLY what the CC hook resolves (shared `resolveAgentIdentity`), so the
- * operator never keys `contextAgents`/`agents/<id>/` on an id the install does
+ * operator never keys `identityAgents`/`agents/<id>/` on an id the install does
  * not actually send. Unset → the install sends no `?agent=` and shares the
- * global context (CC default). A configured-but-unsanitizable value is called
+ * global identity (CC default). A configured-but-unsanitizable value is called
  * out as invalid (the hook sends none) rather than silently accepted.
  */
 export declare function statusAgentLine(config: Record<string, unknown>): string;

package/dist/status.js

@@ -13,27 +13,27 @@ const node_child_process_1 = require("node:child_process");
 const db_js_1 = require("./db.js");
 const features_js_1 = require("./features.js");
 const state_js_1 = require("./state.js");
-const context_store_js_1 = require("./context-store.js");
+const identity_store_js_1 = require("./identity-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
 /**
  * The value shown after "Agent name:" in `hicortex status` (#179, A3). Reports
  * EXACTLY what the CC hook resolves (shared `resolveAgentIdentity`), so the
- * operator never keys `contextAgents`/`agents/<id>/` on an id the install does
+ * operator never keys `identityAgents`/`agents/<id>/` on an id the install does
  * not actually send. Unset → the install sends no `?agent=` and shares the
- * global context (CC default). A configured-but-unsanitizable value is called
+ * global identity (CC default). A configured-but-unsanitizable value is called
  * out as invalid (the hook sends none) rather than silently accepted.
  */
 function statusAgentLine(config) {
-    const id = (0, context_store_js_1.resolveAgentIdentity)(config);
+    const id = (0, identity_store_js_1.resolveAgentIdentity)(config);
     switch (id.source) {
         case "configured":
             return id.agentId;
         case "invalid-config":
             return `(invalid configured value "${id.rawConfigured}" — fix config.agentName; hook sends none)`;
         default: // unset
-            return "(not set — global context)";
+            return "(not set — global identity)";
     }
 }
 async function runStatus() {
@@ -87,8 +87,8 @@ async function runStatus() {
     else if (!isClientMode && !savedAuthToken) {
         console.log(`Auth token:   not configured (run: npx @gamaze/hicortex init)`);
     }
-    // Per-agent context id (#179) — the id this install sends as ?agent= and the
-    // key operators use for contextAgents / agents/<id>/ dirs.
+    // Per-agent identity id (#179) — the id this install sends as ?agent= and the
+    // key operators use for identityAgents / agents/<id>/ dirs.
     console.log(`Agent name:   ${statusAgentLine(parsedConfig)}`);
     console.log();
     // Adapters
@@ -119,11 +119,13 @@ async function runStatus() {
     catch { /* no CC settings */ }
     console.log(`  CC MCP:     ${ccRegistered ? `registered → ${ccUrl}` : "not registered"}`);
     console.log();
-    // Server status
+    // Server status. /health/detail carries the diagnostics (version, memories,
+    // llm) — /health itself is the public minimal {status:"ok"} probe (#253).
+    // localhost bypasses auth, so on-box `hicortex status` gets the fields.
     console.log("Server:");
     let serverRunning = false;
     try {
-        const resp = await fetch("http://127.0.0.1:8787/health", {
+        const resp = await fetch("http://127.0.0.1:8787/health/detail", {
             signal: AbortSignal.timeout(2000),
         });
         if (resp.ok) {

package/dist/telemetry.d.ts

@@ -106,6 +106,16 @@ export interface TelemetryPayload {
      * wire (that lives in the dashboard snapshot, not the telemetry ping).
      */
     tokens_this_run?: number;
+    /**
+     * True when the per-tenant consolidation budget (`consolidateMaxLlmCalls`)
+     * was exhausted this run (#255) — LLM-bound stages deferred remaining work.
+     * A quality-degradation signal concentrated on heavy users; absent on a
+     * pre-#255 ping, a capture-only/no-LLM/throttled/skipped run, or when the
+     * budget was NOT exhausted (additive optional — the aggregate treats absent
+     * as "no exhaustion / not measurable"). Per-stage deferred counts live in
+     * the dashboard snapshot, not on the wire (mirrors `tokens_this_run`).
+     */
+    budget_exhausted?: boolean;
 }
 /**
  * Check if telemetry is enabled. Disabled by:

package/dist/type-classify.js

@@ -45,6 +45,7 @@ const node_path_1 = require("node:path");
 const db_js_1 = require("./db.js");
 const state_js_1 = require("./state.js");
 const llm_js_1 = require("./llm.js");
+const type_labels_js_1 = require("./type-labels.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 /** Max chars of memory content fed to the classify prompt. */
 const CLASSIFY_CONTENT_MAX_CHARS = 1500;
@@ -293,7 +294,9 @@ async function runClassifyTypes(options = {}) {
             .all();
         for (const c of counts)
             report.byType[c.memory_type] = c.cnt;
-        const breakdown = counts.map((c) => `${c.memory_type}=${c.cnt}`).join(", ") || "none";
+        // #264 WS2: display the human-term label (Knowledge/Experience/...), not
+        // the internal enum — the operator reading the log sees human terms.
+        const breakdown = counts.map((c) => `${(0, type_labels_js_1.labelForType)(c.memory_type)}=${c.cnt}`).join(", ") || "none";
         console.log(`[hicortex] classify-types ${report.aborted ? "ABORTED" : "complete"}: ` +
             `${report.scanned} classified, ${report.reclassified} reclassified, ` +
             `${report.unchanged} unchanged, ${report.failed} infra-skipped`);

package/dist/type-labels.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Human-term labels for the internal `memory_type` enum (#264 WS2).
+ *
+ * The data model stores four types under unintuitive internal names
+ * (`fact` / `episode` / `decision` / `lesson`). Product-facing surfaces show
+ * the human terms instead — Knowledge / Experience / Decisions / Learnings —
+ * via this single label map. The enum values themselves are NEVER changed:
+ * no DB column, query, distiller tag, or storage path is altered. This is a
+ * DISPLAY rename only; every user-facing rendering routes through
+ * `labelForType`.
+ *
+ * Mapping (decided 2026-08-11, research/2026-08-11-identity-reframe-brainstorm.md):
+ *   fact     → Knowledge
+ *   episode  → Experience
+ *   decision → Decisions
+ *   lesson   → Learnings
+ *
+ * Unknown / future types fall back to the raw value (never silently remapped).
+ */
+/**
+ * The four documented memory types mapped to their human-term labels.
+ * Kept as a plain record so it can be iterated for coverage assertions.
+ */
+export declare const MEMORY_TYPE_LABELS: Record<string, string>;
+/**
+ * Return the human-term label for a `memory_type` enum value. Unknown or
+ * future types (including null/undefined) fall back to the raw input so new
+ * types are visible rather than silently mislabeled.
+ */
+export declare function labelForType(t: string | null | undefined): string;

package/dist/type-labels.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Human-term labels for the internal `memory_type` enum (#264 WS2).
+ *
+ * The data model stores four types under unintuitive internal names
+ * (`fact` / `episode` / `decision` / `lesson`). Product-facing surfaces show
+ * the human terms instead — Knowledge / Experience / Decisions / Learnings —
+ * via this single label map. The enum values themselves are NEVER changed:
+ * no DB column, query, distiller tag, or storage path is altered. This is a
+ * DISPLAY rename only; every user-facing rendering routes through
+ * `labelForType`.
+ *
+ * Mapping (decided 2026-08-11, research/2026-08-11-identity-reframe-brainstorm.md):
+ *   fact     → Knowledge
+ *   episode  → Experience
+ *   decision → Decisions
+ *   lesson   → Learnings
+ *
+ * Unknown / future types fall back to the raw value (never silently remapped).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_TYPE_LABELS = void 0;
+exports.labelForType = labelForType;
+/**
+ * The four documented memory types mapped to their human-term labels.
+ * Kept as a plain record so it can be iterated for coverage assertions.
+ */
+exports.MEMORY_TYPE_LABELS = {
+    fact: "Knowledge",
+    episode: "Experience",
+    decision: "Decisions",
+    lesson: "Learnings",
+};
+/**
+ * Return the human-term label for a `memory_type` enum value. Unknown or
+ * future types (including null/undefined) fall back to the raw input so new
+ * types are visible rather than silently mislabeled.
+ */
+function labelForType(t) {
+    if (!t)
+        return "—";
+    return exports.MEMORY_TYPE_LABELS[t] ?? t;
+}

package/dist/types.d.ts

@@ -161,6 +161,26 @@ export interface ConsolidationReport {
         calls_used: number;
         calls_remaining: number;
         calls_by_stage: Record<string, number>;
+        /**
+         * True when `calls_used >= max_calls` at run end (#255). The run continued
+         * to completion (no abort) but LLM-bound stages past the boundary deferred
+         * their remaining work — a quality-degradation signal, not a failure.
+         * Absent on pre-#255 reports; treat as false.
+         */
+        exhausted?: boolean;
+        /**
+         * Per-stage count of LLM-call REQUESTS refused because the budget was
+         * exhausted (#255). Keys are the same stage labels passed to
+         * `BudgetTracker.use()`. The value is the SUM of the `count` args passed
+         * to each refused `use()` call in that stage — in production every `use()`
+         * call passes count=1, so a stage present here with count N hit the
+         * boundary and had N further single-call requests denied (stages break on
+         * first refusal, so N is small per stage). For item-level "how many
+         * memories/pairs were skipped" see the per-stage reports (e.g.
+         * stages.importance.skipped_budget), which count MEMORIES not call
+         * requests. Absent on pre-#255 reports.
+         */
+        deferred_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
@@ -187,6 +207,14 @@ export interface HicortexConfig {
     serverUrl?: string;
     /** Bearer token for the Hicortex server. Localhost bypasses auth by default. */
     authToken?: string;
+    /**
+     * Optional PRIOR bearer token kept around during rotation (#254). When set,
+     * BOTH `authToken` and `authTokenPrevious` are accepted (constant-time,
+     * zero-downtime rotation). Absent/empty → single-token behaviour. Rotate by
+     * writing the new value to `authToken` and the old value here, then later
+     * clearing this key once all clients have switched.
+     */
+    authTokenPrevious?: string;
     /**
      * Stable per-install UUID generated by `init` (see ensureAgentId in init.ts;
      * never rotated). Attribution identity of the capturing client — stored on

package/dist/uninstall.d.ts

@@ -2,4 +2,16 @@
  * Hicortex uninstall — clean removal of CC integration.
  * Preserves the database (user data).
  */
+/**
+ * Matches a CC SessionStart hook `command` that runs the Hicortex
+ * identity/learnings hook — the canonical `learnings-identity` (#264) OR the
+ * legacy `lessons-context` alias. Exported so the uninstall behavior (which
+ * name variants get cleaned up) is unit-testable without spinning up CC.
+ * Word-boundary guard so "learnings-identity" never matches a hypothetical
+ * "learnings-identity-foo", the two names stay distinct from each other, and
+ * neither collides with the sibling `recall-hook` SessionStart hook.
+ */
+export declare const SESSION_START_HOOK_COMMAND_RE: RegExp;
+/** True when a CC hook `command` string runs the Hicortex SessionStart hook. */
+export declare function isHicortexSessionStartHook(command: string): boolean;
 export declare function runUninstall(): Promise<void>;

package/dist/uninstall.js

@@ -4,6 +4,8 @@
  * Preserves the database (user data).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_START_HOOK_COMMAND_RE = void 0;
+exports.isHicortexSessionStartHook = isHicortexSessionStartHook;
 exports.runUninstall = runUninstall;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -17,6 +19,20 @@ const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
 const CLAUDE_MD = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
+/**
+ * Matches a CC SessionStart hook `command` that runs the Hicortex
+ * identity/learnings hook — the canonical `learnings-identity` (#264) OR the
+ * legacy `lessons-context` alias. Exported so the uninstall behavior (which
+ * name variants get cleaned up) is unit-testable without spinning up CC.
+ * Word-boundary guard so "learnings-identity" never matches a hypothetical
+ * "learnings-identity-foo", the two names stay distinct from each other, and
+ * neither collides with the sibling `recall-hook` SessionStart hook.
+ */
+exports.SESSION_START_HOOK_COMMAND_RE = /(^|\s)(?:learnings-identity|lessons-context)(\s|$)/;
+/** True when a CC hook `command` string runs the Hicortex SessionStart hook. */
+function isHicortexSessionStartHook(command) {
+    return typeof command === "string" && exports.SESSION_START_HOOK_COMMAND_RE.test(command);
+}
 async function ask(question) {
     const rl = (0, node_readline_1.createInterface)({ input: process.stdin, output: process.stdout });
     return new Promise((resolve) => {
@@ -130,7 +146,9 @@ async function runUninstall() {
     }
     if (removedCmds > 0)
         console.log(`  ✓ Removed ${removedCmds} legacy CC command${removedCmds > 1 ? "s" : ""} (/learn, /hicortex-activate)`);
-    // 4. Remove SessionStart hook (JSON merge — filter out entries containing "lessons-context")
+    // 4. Remove SessionStart hook (JSON merge — filter out entries containing
+    //    EITHER the canonical "learnings-identity" OR the legacy "lessons-context"
+    //    alias, #264 backcompat: an install may have written either name.)
     try {
         const raw = (0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8");
         const settings = JSON.parse(raw);
@@ -147,7 +165,7 @@ async function runUninstall() {
                         if (typeof h !== "object" || h === null)
                             return false;
                         const hook = h;
-                        return typeof hook.command === "string" && hook.command.includes("lessons-context");
+                        return typeof hook.command === "string" && isHicortexSessionStartHook(hook.command);
                     });
                 }
                 return true;
@@ -155,7 +173,7 @@ async function runUninstall() {
             if (filtered.length < before) {
                 hooks.SessionStart = filtered;
                 (0, node_fs_1.writeFileSync)(CC_SETTINGS, JSON.stringify(settings, null, 2));
-                console.log("  ✓ Removed SessionStart lessons-context hook");
+                console.log("  ✓ Removed SessionStart learnings-identity hook");
             }
         }
     }

package/dist/viz.d.ts

@@ -37,8 +37,16 @@ export declare const VIZ_VENDOR_FILES: ReadonlySet<string>;
  * middleware before this runs). With no token configured, remote requests are
  * REJECTED (not open): the default bind is 0.0.0.0, so "no token = no auth"
  * would expose the whole memory store to the network.
+ *
+ * `authTokenPrevious` (optional, #254) is the prior token kept around during
+ * rotation. Both tokens are accepted; this gives a zero-downtime rotation
+ * window — in-flight clients configured with the old token keep working until
+ * they pick up the new one. BOTH comparisons are constant-time and both are
+ * always evaluated (no short-circuit), so a caller cannot learn WHICH token
+ * matched from the response timing. Absent/empty `authTokenPrevious` behaves
+ * exactly as the single-token middleware always has.
  */
-export declare function createAuthMiddleware(authToken: string | undefined): express.RequestHandler;
+export declare function createAuthMiddleware(authToken: string | undefined, authTokenPrevious?: string): express.RequestHandler;
 /**
  * Resolve the on-disk path of the viz page. Throws (fail explicitly) when the
  * asset is missing — a broken install should surface, not degrade silently.
@@ -52,24 +60,29 @@ export declare function readVizHtml(): string;
  */
 export declare function vizHandler(): express.RequestHandler;
 /**
- * Resolve the on-disk path of the context-layer editor page. Throws (fail
+ * Resolve the on-disk path of the identity-layer editor page. Throws (fail
  * explicitly) when the asset is missing — same contract as resolveVizHtmlPath.
  * assets/ sits next to both dist/ (dist/viz.js → ../assets/) and src/
  * (src/viz.ts → ../assets/ under tsx), so one sibling candidate covers both.
  */
-export declare function resolveContextHtmlPath(): string;
-/** Read the context editor page. Read at request time so a reinstall is live. */
-export declare function readContextHtml(): string;
+export declare function resolveIdentityHtmlPath(): string;
+/** Read the identity editor page. Read at request time so a reinstall is live. */
+export declare function readIdentityHtml(): string;
 /**
- * Express handler for GET /context/ui — the PRIMARY edit surface for the
- * standing context layer. 503 with the usual {error} shape when the asset
- * cannot be read, exactly like vizHandler.
+ * Express handler for GET /identity/ui — the PRIMARY edit surface for the
+ * standing identity layer. 503 with the usual {error} shape when the asset
+ * cannot be read, exactly like vizHandler. Also serves the legacy
+ * /context/ui URL (#264 backcompat).
  */
-export declare function contextUiHandler(): express.RequestHandler;
+export declare function identityUiHandler(): express.RequestHandler;
+/** Backcompat aliases (#264). */
+export declare const resolveContextHtmlPath: typeof resolveIdentityHtmlPath;
+export declare const readContextHtml: typeof readIdentityHtml;
+export declare const contextUiHandler: typeof identityUiHandler;
 /**
  * Resolve the on-disk path of the dashboard page. Throws (fail explicitly)
  * when the asset is missing — same contract as resolveVizHtmlPath and
- * resolveContextHtmlPath. assets/ sits next to both dist/ and src/ (the
+ * resolveIdentityHtmlPath. assets/ sits next to both dist/ and src/ (the
  * sibling layout the other resolvers rely on).
  */
 export declare function resolveDashboardHtmlPath(): string;
@@ -78,7 +91,7 @@ export declare function readDashboardHtml(): string;
 /**
  * Express handler for GET /dashboard — the view-only analytics page (#224).
  * 503 with the usual {error} shape when the asset cannot be read, exactly like
- * vizHandler and contextUiHandler. The page SHELL is public (exempted in
+ * vizHandler and identityUiHandler. The page SHELL is public (exempted in
  * createAuthMiddleware); all data comes from GET /dashboard/data (bearer-only).
  */
 export declare function dashboardHandler(): express.RequestHandler;