@gamaze/hicortex 0.17.5 → 0.18.0

package/dist/{lessons-context.d.ts → learnings-identity.d.ts}

@@ -1,32 +1,37 @@
 /**
- * lessons-context — query-time context injection for the CC SessionStart hook.
+ * learnings-identity — query-time identity + lessons injection for the CC
+ * SessionStart hook. (Canonical command name `learnings-identity` since #264;
+ * the legacy `lessons-context` subcommand is kept as a backcompat alias via
+ * resolveCommandAlias so existing installed hooks keep working. Fetches the
+ * identity layer + the lessons block.)
  *
  * Replaces file-based injection (injectLessons / injectLessonsFromServer).
  * Reads ~/.hicortex/config.json to find the server URL, then fetches TWO
  * endpoints concurrently and prints a compact Markdown block to stdout so CC
  * picks it up as session context:
  *
- *   GET /context  → the standing context layer (user info + rules; 0.12).
- *                   Injected as a `## Context` block ONLY when this harness
- *                   ("cc") is in the server-resolved `clients` list (self-gate).
+ *   GET /identity → the standing identity layer (user info + rules; 0.12,
+ *                   renamed from /context in 0.18 #264). Injected as a
+ *                   `## Identity` block ONLY when this harness ("cc") is in
+ *                   the server-resolved `clients` list (self-gate).
  *   GET /lessons  → episodic memory lessons + memory index, rendered as the
  *                   existing `## Hicortex Memory` block.
  *
  * The two fetches run in Promise.all, each with its OWN 3 s timeout and
- * INDEPENDENT fail-soft: a /context failure must never cost the lessons block,
- * and vice versa. Sequential fetches would double worst-case SessionStart
- * latency (~6 s) — see spec §7.
+ * INDEPENDENT fail-soft: an /identity failure must never cost the lessons
+ * block, and vice versa. Sequential fetches would double worst-case
+ * SessionStart latency (~6 s) — see spec §7.
  *
  * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
  * parse error) results in silent exit-0. A broken hook must never block a
- * CC session, and a broken /context fetch must never blank the whole output.
+ * CC session, and a broken /identity fetch must never blank the whole output.
  */
 /**
- * The GET /context response shape, shared by the CC hook and the OC plugin so
+ * The GET /identity response shape, shared by the CC hook and the OC plugin so
  * their gating cannot drift. `agent`/`mode` are echoed by a 0.13 server whenever
  * `?agent=` was sent (in EVERY mode); a pre-0.13 server omits them.
  */
-export interface ContextResponse {
+export interface IdentityResponse {
     sections?: Record<string, string>;
     updated_at?: string;
     clients?: string[];
@@ -37,7 +42,7 @@ export interface ResolvedConfig {
     serverUrl: string;
     authToken: string | undefined;
     home: string;
-    /** Per-agent context id sent as ?agent= (0.13); null → global (no param). */
+    /** Per-agent identity id sent as ?agent= (0.13); null → global (no param). */
     agentName: string | null;
     /** Max lessons to inject (config.lessonsLimit, default 10). */
     lessonsLimit?: number;
@@ -52,7 +57,7 @@ export declare function resolveConfig(): ResolvedConfig | null;
 /**
  * Title-case a section name for its heading: split on `-`/`_`, capitalize each
  * word ("user" → "User", "my_notes" → "My Notes").
- * Exported so the OC plugin (index.ts) renders the `## Context` block
+ * Exported so the OC plugin (index.ts) renders the `## Identity` block
  * identically to the CC hook rather than duplicating the logic.
  */
 export declare function titleCaseSection(name: string): string;
@@ -64,15 +69,15 @@ export declare function titleCaseSection(name: string): string;
  */
 export declare function orderSectionNames(names: string[]): string[];
 /**
- * Render the `## Context` block from a resolved section map, or null when there
+ * Render the `## Identity` block from a resolved section map, or null when there
  * is nothing to inject (no sections, or every section blank after trimming).
  * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
  * both harnesses emit an identical block. Sections are ordered (user, rules,
  * then alphabetical) and rendered under title-cased `###` headings.
  */
-export declare function renderContextBlock(sections: Record<string, string>): string | null;
+export declare function renderIdentityBlock(sections: Record<string, string>): string | null;
 /**
- * Gate a GET /context response and render the `## Context` block, or null when
+ * Gate a GET /identity response and render the `## Identity` block, or null when
  * nothing should be injected: `harness` not in the server-resolved `clients`,
  * an empty/blank section set, or — when `requireAgentEcho` — a response that
  * does not echo `agent`. The SINGLE gate used by both CC and OC so the two can
@@ -81,22 +86,28 @@ export declare function renderContextBlock(sections: Record<string, string>): st
  *
  * `requireAgentEcho` is the old-server guard, and it is the CALLER's decision:
  *   - OC passes `agentId !== null` — when it actually sent an id, a 0.12 server
- *     that ignores `?agent=` (200 global, no echo) must NOT leak global context
+ *     that ignores `?agent=` (200 global, no echo) must NOT leak global identity
  *     into every persona; on a bare fetch (no id) the guard is off (amendment
  *     A2).
  *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
  *     client auto-upgrades via npx BEFORE the server does, so during the upgrade
  *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
  *     global IS the operator's intended state there, and a guard would instead
- *     blank ALL context for every CC session in that window.
+ *     blank ALL identity for every CC session in that window.
  */
-export declare function gateAndRenderContext(data: ContextResponse, harness: string, opts: {
+export declare function gateAndRenderIdentity(data: IdentityResponse, harness: string, opts: {
     requireAgentEcho: boolean;
 }): string | null;
 /**
- * Fetch context + lessons concurrently and return the combined Markdown block,
+ * Fetch identity + lessons concurrently and return the combined Markdown block,
  * or null when neither yields anything (nothing to inject; caller prints
- * nothing and exits 0). The `## Context` block is prepended before the existing
+ * nothing and exits 0). The `## Identity` block is prepended before the existing
  * `## Hicortex Memory` block.
  */
-export declare function fetchLessonsContext(): Promise<string | null>;
+export declare function fetchLessonsIdentity(): Promise<string | null>;
+/** Backcompat alias (#264). */
+export declare const fetchLessonsContext: typeof fetchLessonsIdentity;
+/** Backcompat aliases (#264) for the renamed symbols. */
+export declare const renderContextBlock: typeof renderIdentityBlock;
+export declare const gateAndRenderContext: typeof gateAndRenderIdentity;
+export type ContextResponse = IdentityResponse;

package/dist/{lessons-context.js → learnings-identity.js}

@@ -1,43 +1,49 @@
 "use strict";
 /**
- * lessons-context — query-time context injection for the CC SessionStart hook.
+ * learnings-identity — query-time identity + lessons injection for the CC
+ * SessionStart hook. (Canonical command name `learnings-identity` since #264;
+ * the legacy `lessons-context` subcommand is kept as a backcompat alias via
+ * resolveCommandAlias so existing installed hooks keep working. Fetches the
+ * identity layer + the lessons block.)
  *
  * Replaces file-based injection (injectLessons / injectLessonsFromServer).
  * Reads ~/.hicortex/config.json to find the server URL, then fetches TWO
  * endpoints concurrently and prints a compact Markdown block to stdout so CC
  * picks it up as session context:
  *
- *   GET /context  → the standing context layer (user info + rules; 0.12).
- *                   Injected as a `## Context` block ONLY when this harness
- *                   ("cc") is in the server-resolved `clients` list (self-gate).
+ *   GET /identity → the standing identity layer (user info + rules; 0.12,
+ *                   renamed from /context in 0.18 #264). Injected as a
+ *                   `## Identity` block ONLY when this harness ("cc") is in
+ *                   the server-resolved `clients` list (self-gate).
  *   GET /lessons  → episodic memory lessons + memory index, rendered as the
  *                   existing `## Hicortex Memory` block.
  *
  * The two fetches run in Promise.all, each with its OWN 3 s timeout and
- * INDEPENDENT fail-soft: a /context failure must never cost the lessons block,
- * and vice versa. Sequential fetches would double worst-case SessionStart
- * latency (~6 s) — see spec §7.
+ * INDEPENDENT fail-soft: an /identity failure must never cost the lessons
+ * block, and vice versa. Sequential fetches would double worst-case
+ * SessionStart latency (~6 s) — see spec §7.
  *
  * Fail-soft by design: ANY failure (missing config, network error, non-2xx,
  * parse error) results in silent exit-0. A broken hook must never block a
- * CC session, and a broken /context fetch must never blank the whole output.
+ * CC session, and a broken /identity fetch must never blank the whole output.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.gateAndRenderContext = exports.renderContextBlock = exports.fetchLessonsContext = void 0;
 exports.resolveConfig = resolveConfig;
 exports.titleCaseSection = titleCaseSection;
 exports.orderSectionNames = orderSectionNames;
-exports.renderContextBlock = renderContextBlock;
-exports.gateAndRenderContext = gateAndRenderContext;
-exports.fetchLessonsContext = fetchLessonsContext;
+exports.renderIdentityBlock = renderIdentityBlock;
+exports.gateAndRenderIdentity = gateAndRenderIdentity;
+exports.fetchLessonsIdentity = fetchLessonsIdentity;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const context_store_js_1 = require("./context-store.js");
+const identity_store_js_1 = require("./identity-store.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
 const paths_js_1 = require("./paths.js");
 const DEFAULT_PORT = 8787;
-/** Harness name this hook injects for — used to self-gate on GET /context `clients`. */
+/** Harness name this hook injects for — used to self-gate on GET /identity `clients`. */
 const THIS_HARNESS = "cc";
 /**
  * Read ~/.hicortex/config.json and resolve the server URL + auth token, or
@@ -58,12 +64,12 @@ function resolveConfig() {
     const serverUrl = config.mode === "client" && typeof config.serverUrl === "string"
         ? config.serverUrl.replace(/\/+$/, "")
         : `http://127.0.0.1:${config.port ?? DEFAULT_PORT}`;
-    // Per-agent context id (0.13) via the shared resolver, so the id sent here
+    // Per-agent identity id (0.13) via the shared resolver, so the id sent here
     // always matches what `hicortex status` reports. No configured agentName →
     // agentId null → NO ?agent= (bare fetch): CC's default is the shared global
-    // context. A configured agentName that sanitizes to null → agentId null too
+    // identity. A configured agentName that sanitizes to null → agentId null too
     // (NO ?agent=), never a 400 that the fail-soft hook would silently swallow.
-    const agentName = (0, context_store_js_1.resolveAgentIdentity)(config).agentId;
+    const agentName = (0, identity_store_js_1.resolveAgentIdentity)(config).agentId;
     return {
         serverUrl,
         authToken: config.authToken,
@@ -133,7 +139,7 @@ async function fetchLessonsBlock(cfg) {
 /**
  * Title-case a section name for its heading: split on `-`/`_`, capitalize each
  * word ("user" → "User", "my_notes" → "My Notes").
- * Exported so the OC plugin (index.ts) renders the `## Context` block
+ * Exported so the OC plugin (index.ts) renders the `## Identity` block
  * identically to the CC hook rather than duplicating the logic.
  */
 function titleCaseSection(name) {
@@ -155,13 +161,13 @@ function orderSectionNames(names) {
     return [...primaries, ...rest];
 }
 /**
- * Render the `## Context` block from a resolved section map, or null when there
+ * Render the `## Identity` block from a resolved section map, or null when there
  * is nothing to inject (no sections, or every section blank after trimming).
  * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
  * both harnesses emit an identical block. Sections are ordered (user, rules,
  * then alphabetical) and rendered under title-cased `###` headings.
  */
-function renderContextBlock(sections) {
+function renderIdentityBlock(sections) {
     if (!sections || typeof sections !== "object" || Array.isArray(sections))
         return null;
     const names = orderSectionNames(Object.keys(sections));
@@ -174,10 +180,10 @@ function renderContextBlock(sections) {
     }
     if (bodyParts.length === 0)
         return null;
-    return ["## Context", "", ...bodyParts].join("\n");
+    return ["## Identity", "", ...bodyParts].join("\n");
 }
 /**
- * Gate a GET /context response and render the `## Context` block, or null when
+ * Gate a GET /identity response and render the `## Identity` block, or null when
  * nothing should be injected: `harness` not in the server-resolved `clients`,
  * an empty/blank section set, or — when `requireAgentEcho` — a response that
  * does not echo `agent`. The SINGLE gate used by both CC and OC so the two can
@@ -186,16 +192,16 @@ function renderContextBlock(sections) {
  *
  * `requireAgentEcho` is the old-server guard, and it is the CALLER's decision:
  *   - OC passes `agentId !== null` — when it actually sent an id, a 0.12 server
- *     that ignores `?agent=` (200 global, no echo) must NOT leak global context
+ *     that ignores `?agent=` (200 global, no echo) must NOT leak global identity
  *     into every persona; on a bare fetch (no id) the guard is off (amendment
  *     A2).
  *   - CC passes `false` ALWAYS and deliberately (see the call site): a thin CC
  *     client auto-upgrades via npx BEFORE the server does, so during the upgrade
  *     window it talks to a 0.12 server that cannot hold ANY per-agent config —
  *     global IS the operator's intended state there, and a guard would instead
- *     blank ALL context for every CC session in that window.
+ *     blank ALL identity for every CC session in that window.
  */
-function gateAndRenderContext(data, harness, opts) {
+function gateAndRenderIdentity(data, harness, opts) {
     if (!data || typeof data !== "object")
         return null;
     const clients = Array.isArray(data.clients) ? data.clients : [];
@@ -203,21 +209,21 @@ function gateAndRenderContext(data, harness, opts) {
         return null;
     if (opts.requireAgentEcho && typeof data.agent !== "string")
         return null;
-    return renderContextBlock(data.sections ?? {});
+    return renderIdentityBlock(data.sections ?? {});
 }
 /**
- * Fetch /context and build the `## Context` block, or null when nothing should
+ * Fetch /identity and build the `## Identity` block, or null when nothing should
  * be injected: non-2xx, this harness not in `clients`, no sections, or all
  * sections empty. Throws propagate to the caller's fail-soft catch.
  */
-async function fetchContextBlock(cfg) {
+async function fetchIdentityBlock(cfg) {
     // Send ?agent= only when we have a valid id; the server does the merge and
     // returns the resolved sections, so the hook stays dumb (no client-side mode
     // logic). A null id (CC's default: no configured agentName, or a configured
-    // value that sanitizes to nothing) → bare /context → the shared global set.
+    // value that sanitizes to nothing) → bare /identity → the shared global set.
     const url = cfg.agentName
-        ? `${cfg.serverUrl}/context?agent=${encodeURIComponent(cfg.agentName)}`
-        : `${cfg.serverUrl}/context`;
+        ? `${cfg.serverUrl}/identity?agent=${encodeURIComponent(cfg.agentName)}`
+        : `${cfg.serverUrl}/identity`;
     const resp = await fetch(url, {
         headers: authHeaders(cfg.authToken),
         signal: AbortSignal.timeout(3000),
@@ -227,30 +233,35 @@ async function fetchContextBlock(cfg) {
     const data = await resp.json();
     // CC deliberately passes requireAgentEcho: false (NOT the OC/Hermes old-server
     // guard). A thin CC client auto-upgrades via npx BEFORE the server does, so
-    // mid-upgrade it may hit a 0.12 server that returns global context with no
+    // mid-upgrade it may hit a 0.12 server that returns global identity with no
     // `agent` echo — and a 0.12 server cannot hold per-agent config, so global is
-    // the intended state. Guarding here would blank ALL CC context in that window.
-    return gateAndRenderContext(data, THIS_HARNESS, { requireAgentEcho: false });
+    // the intended state. Guarding here would blank ALL CC identity in that window.
+    return gateAndRenderIdentity(data, THIS_HARNESS, { requireAgentEcho: false });
 }
 /**
- * Fetch context + lessons concurrently and return the combined Markdown block,
+ * Fetch identity + lessons concurrently and return the combined Markdown block,
  * or null when neither yields anything (nothing to inject; caller prints
- * nothing and exits 0). The `## Context` block is prepended before the existing
+ * nothing and exits 0). The `## Identity` block is prepended before the existing
  * `## Hicortex Memory` block.
  */
-async function fetchLessonsContext() {
+async function fetchLessonsIdentity() {
     const cfg = resolveConfig();
     if (!cfg)
         return null;
     // Independent fail-soft: each branch degrades to null without affecting the
     // other. Promise.all runs them concurrently — each carries its own 3 s
     // timeout, so worst-case latency stays ~3 s, not ~6 s (spec §7).
-    const [contextBlock, lessonsBlock] = await Promise.all([
-        fetchContextBlock(cfg).catch(() => null),
+    const [identityBlock, lessonsBlock] = await Promise.all([
+        fetchIdentityBlock(cfg).catch(() => null),
         fetchLessonsBlock(cfg).catch(() => null),
     ]);
-    const blocks = [contextBlock, lessonsBlock].filter((b) => b !== null && b !== "");
+    const blocks = [identityBlock, lessonsBlock].filter((b) => b !== null && b !== "");
     if (blocks.length === 0)
         return null;
     return blocks.join("\n\n");
 }
+/** Backcompat alias (#264). */
+exports.fetchLessonsContext = fetchLessonsIdentity;
+/** Backcompat aliases (#264) for the renamed symbols. */
+exports.renderContextBlock = renderIdentityBlock;
+exports.gateAndRenderContext = gateAndRenderIdentity;

package/dist/mcp-server.d.ts

@@ -10,9 +10,11 @@
  *   GET  /sse        — SSE stream for MCP clients
  *   POST /messages   — message endpoint for MCP clients
  */
+import type { MemorySearchResult } from "./types.js";
 export declare function startServer(options?: {
     port?: number;
     host?: string;
     dbPath?: string;
     licenseKey?: string;
 }): Promise<void>;
+export declare function formatResults(results: MemorySearchResult[]): string;