@gamaze/hicortex 0.17.6 → 0.18.1

package/dist/{context-store.js → identity-store.js}

@@ -1,16 +1,17 @@
 "use strict";
 /**
- * Context layer (L2) — file-backed storage (0.12.0, spec 2026-07-12).
+ * Identity layer — file-backed storage (formerly "Context Layer" / L2; 0.12.0,
+ * spec 2026-07-12; renamed 0.18 #264).
  *
- * The context layer is hand-edited Markdown ("who you are + how to work") stored
- * as plain files in `<hicortex-home>/context/*.md` — one file per section, one
+ * The identity layer is hand-edited Markdown ("who you are + how to work") stored
+ * as plain files in `<hicortex-home>/identity/*.md` — one file per section, one
  * Web UI tab. It lives OUTSIDE the memories table: never distilled, scored,
  * decayed, or pruned. As plain files this guarantee is structural — no code in
  * consolidate.ts / distiller.ts references this directory.
  *
  * This module is pure file-layer logic (no express) so it is unit-testable and
  * reusable by the CLI. The daemon resolves `<hicortex-home>` exactly as it
- * resolves the DB dir (dirname of the resolved DB path) and passes the context
+ * resolves the DB dir (dirname of the resolved DB path) and passes the identity
  * dir in — nothing here hardcodes `~`.
  *
  * Security contract (spec §1): client-supplied section names are NEVER joined
@@ -18,23 +19,35 @@
  * itself appends `.md`. Reads skip symlinks (lstat, not stat). Writes validate
  * ALL names before touching the disk (atomic request semantics), go via
  * temp-file-then-rename, and keep a one-generation `<name>.md.bak` undo.
+ *
+ * Backcompat (#264): the pre-rename directory was `<hicortex-home>/context/`.
+ * `migrateIdentityDir` renames it to `identity/` on the next init/nightly run
+ * when the old dir exists and the new does not. When BOTH exist (partial
+ * migration, a disk-full renameSync failure, or an operator re-creating
+ * `context/`), reads ADDITIVELY MERGE: per-section `identity/` wins, and
+ * legacy-only sections are included so nothing is lost — at both the global
+ * and the per-agent (`agents/<id>/`) level.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_CONTEXT_CLIENTS = exports.CONTEXT_SIZE_WARN_BYTES = exports.isValidAgentId = exports.AGENTS_DIR = exports.InvalidSectionNameError = exports.SECTION_NAME_MAX = exports.SECTION_NAME_RE = void 0;
+exports.KNOWN_CONTEXT_CLIENTS = exports.KNOWN_IDENTITY_CLIENTS = exports.CONTEXT_SIZE_WARN_BYTES = exports.IDENTITY_SIZE_WARN_BYTES = exports.isValidAgentId = exports.AGENTS_DIR = exports.InvalidSectionNameError = exports.SECTION_NAME_MAX = exports.SECTION_NAME_RE = void 0;
 exports.isValidSectionName = isValidSectionName;
 exports.sanitizeAgentId = sanitizeAgentId;
 exports.resolveAgentIdentity = resolveAgentIdentity;
-exports.resolveContextAgents = resolveContextAgents;
+exports.resolveIdentityAgents = resolveIdentityAgents;
+exports.migrateIdentityDir = migrateIdentityDir;
 exports.readSections = readSections;
+exports.readSectionsWithFallback = readSectionsWithFallback;
 exports.writeSections = writeSections;
 exports.totalBytes = totalBytes;
-exports.resolveContextClients = resolveContextClients;
+exports.resolveIdentityClients = resolveIdentityClients;
+exports.resolveIdentityClientsConfig = resolveIdentityClientsConfig;
+exports.resolveIdentityAgentsConfig = resolveIdentityAgentsConfig;
 exports.agentDirState = agentDirState;
 exports.resolveAgentMode = resolveAgentMode;
 exports.listAgents = listAgents;
 exports.readResolvedSections = readResolvedSections;
-exports.handleContextGet = handleContextGet;
-exports.handleContextPut = handleContextPut;
+exports.handleIdentityGet = handleIdentityGet;
+exports.handleIdentityPut = handleIdentityPut;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_crypto_1 = require("node:crypto");
@@ -64,11 +77,11 @@ class InvalidSectionNameError extends Error {
     }
 }
 exports.InvalidSectionNameError = InvalidSectionNameError;
-/** Reserved subdir under <context>/ holding per-agent sections. NOT a section. */
+/** Reserved subdir under <identity>/ holding per-agent sections. NOT a section. */
 exports.AGENTS_DIR = "agents";
 /**
  * Agent ids share the section-name allowlist: they are joined into a filesystem
- * path (`context/agents/<id>`), so this is the same security contract, not just
+ * path (`identity/agents/<id>`), so this is the same security contract, not just
  * hygiene.
  */
 exports.isValidAgentId = isValidSectionName;
@@ -101,9 +114,9 @@ function sanitizeAgentId(raw) {
  *  - absent, or empty/whitespace-only → null id, "unset". Empty string == unset
  *    everywhere (this is the value `init --agent-name ""` writes-then-clears to
  *    opt back out): CC's default is NO `?agent=`, so all CC boxes for one user
- *    share the global context — one user = one identity across machines.
+ *    share the global identity — one user = one identity across machines.
  * There is NO hostname fallback: a hostname-derived default would silently give
- * every machine its own context, the opposite of the shared-identity default.
+ * every machine its own identity, the opposite of the shared-identity default.
  */
 function resolveAgentIdentity(config) {
     const value = config.agentName;
@@ -117,12 +130,16 @@ function resolveAgentIdentity(config) {
     return { agentId: null, source: "unset" };
 }
 /**
- * Normalize the raw `contextAgents` config value into a map of valid agent id →
+ * Normalize the raw `identityAgents` config value into a map of valid agent id →
  * mode. An entry is kept only when its key passes isValidAgentId AND its value
  * is one of the three modes; everything else is dropped and its key collected
- * for a one-time boot warning (mirrors resolveContextClients).
+ * for a one-time boot warning (mirrors resolveIdentityClients).
+ *
+ * Backcompat (#264): the pre-rename key was `contextAgents`. Callers that want
+ * to honour it should pass the already-resolved value here (see
+ * `resolveIdentityConfig` in mcp-server.ts which reads new + old).
  */
-function resolveContextAgents(raw) {
+function resolveIdentityAgents(raw) {
     const agents = {};
     const dropped = [];
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
@@ -137,8 +154,39 @@ function resolveContextAgents(raw) {
     }
     return { agents, dropped };
 }
+// ---------------------------------------------------------------------------
+// Directory migration (backcompat — pre-rename was <home>/context/, #264)
+// ---------------------------------------------------------------------------
+/**
+ * Rename `<home>/context/` → `<home>/identity/` when the legacy dir exists and
+ * the new dir does not. Idempotent + safe: when both exist (a partial
+ * migration, or the operator created both) NOTHING is renamed — the caller
+ * falls back to a legacy read instead. Returns a description of what happened
+ * for a one-time boot log.
+ *
+ * Called from init and nightly so the migration lands on the next run of either
+ * command an existing install hits.
+ */
+function migrateIdentityDir(home) {
+    const from = (0, node_path_1.join)(home, "context");
+    const to = (0, node_path_1.join)(home, "identity");
+    if (!(0, node_fs_1.existsSync)(from))
+        return { renamed: false, from, to, reason: "no legacy context/ dir" };
+    if ((0, node_fs_1.existsSync)(to))
+        return { renamed: false, from, to, reason: "identity/ already exists — leaving context/ in place (reads additively merge identity/ over legacy context/ per-section)" };
+    try {
+        (0, node_fs_1.renameSync)(from, to);
+        return { renamed: true, from, to };
+    }
+    catch (err) {
+        // A failed rename is non-fatal: the legacy dir is still readable via the
+        // fallback in readSectionsWithFallback, so log + continue rather than
+        // blocking the boot.
+        return { renamed: false, from, to, reason: `rename failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 /**
- * Enumerate the context dir and return the served sections. Only regular files
+ * Enumerate the identity dir and return the served sections. Only regular files
  * whose basename (sans `.md`) passes the allowlist are included; symlinks are
  * skipped (lstat). `<name>.md.bak` and temp files never match the `*.md` filter.
  *
@@ -195,6 +243,42 @@ function readSections(dir) {
     const updatedAt = Object.keys(sections).length > 0 ? new Date(latestMtimeMs).toISOString() : null;
     return { sections, updatedAt, mtimes };
 }
+/**
+ * Merge two ReadResults into an additive union: a section present in BOTH is
+ * taken from `primary` (it wins per-section); sections present ONLY in
+ * `secondary` are included so nothing is lost. `updatedAt` is recomputed across
+ * the files that won the merge. Pure helper.
+ */
+function mergeSections(primary, secondary) {
+    const sections = { ...secondary.sections, ...primary.sections };
+    const mtimes = {};
+    let latestMtimeMs = 0;
+    for (const name of Object.keys(sections)) {
+        const mt = name in primary.mtimes ? primary.mtimes[name] : secondary.mtimes[name];
+        if (mt !== undefined)
+            mtimes[name] = mt;
+        if (mt && mt > latestMtimeMs)
+            latestMtimeMs = mt;
+    }
+    const updatedAt = Object.keys(sections).length > 0 ? new Date(latestMtimeMs).toISOString() : null;
+    return { sections, updatedAt, mtimes };
+}
+/**
+ * Read the identity dir, additively merging the legacy `context/` sibling so
+ * nothing is lost when both dirs exist (post-#264 safety net for a partial/no
+ * migration: a disk-full renameSync failure, or an operator re-creating
+ * `context/`). Per-section, `identity/` wins; legacy-only sections are included
+ * (union). Pure function over the two dirs — used by the GET handler.
+ */
+function readSectionsWithFallback(identityDir) {
+    const primary = readSections(identityDir);
+    const legacy = readSections((0, node_path_1.join)(identityDir, "..", "context"));
+    if (Object.keys(legacy.sections).length === 0)
+        return primary;
+    if (Object.keys(primary.sections).length === 0)
+        return legacy;
+    return mergeSections(primary, legacy);
+}
 // ---------------------------------------------------------------------------
 // Write
 // ---------------------------------------------------------------------------
@@ -297,26 +381,30 @@ function totalBytes(sections) {
     return total;
 }
 /** Warn threshold: this layer bypasses token budgeting and injects every session. */
-exports.CONTEXT_SIZE_WARN_BYTES = 16_384;
+exports.IDENTITY_SIZE_WARN_BYTES = 16_384;
+/** Backcompat alias for the pre-rename name (#264). */
+exports.CONTEXT_SIZE_WARN_BYTES = exports.IDENTITY_SIZE_WARN_BYTES;
 // ---------------------------------------------------------------------------
-// Config — contextClients normalization
+// Config — identityClients normalization
 // ---------------------------------------------------------------------------
-/** Harness names that may inject the context layer. */
-exports.KNOWN_CONTEXT_CLIENTS = ["cc", "hermes", "oc"];
+/** Harness names that may inject the identity layer. */
+exports.KNOWN_IDENTITY_CLIENTS = ["cc", "hermes", "oc"];
+/** Backcompat alias for the pre-rename name (#264). */
+exports.KNOWN_CONTEXT_CLIENTS = exports.KNOWN_IDENTITY_CLIENTS;
 /**
- * Normalize the raw `contextClients` config value (spec §2):
+ * Normalize the raw `identityClients` config value (spec §2):
  *  - `"all"` (any case)      → ["cc","hermes","oc"]
  *  - array                   → lowercase, keep known names (de-duped), collect dropped unknowns
  *  - missing / non-array-non-"all" → default ["cc"]
- * The resolved list is echoed by GET /context as `clients` so each harness's
+ * The resolved list is echoed by GET /identity as `clients` so each harness's
  * hook can self-gate without its own config.
  */
-function resolveContextClients(raw) {
+function resolveIdentityClients(raw) {
     if (typeof raw === "string" && raw.toLowerCase() === "all") {
-        return { clients: [...exports.KNOWN_CONTEXT_CLIENTS], dropped: [] };
+        return { clients: [...exports.KNOWN_IDENTITY_CLIENTS], dropped: [] };
     }
     if (Array.isArray(raw)) {
-        const known = new Set(exports.KNOWN_CONTEXT_CLIENTS);
+        const known = new Set(exports.KNOWN_IDENTITY_CLIENTS);
         const clients = [];
         const dropped = [];
         for (const item of raw) {
@@ -329,7 +417,7 @@ function resolveContextClients(raw) {
             // the natural form of the documented "all" value, so ["all"] must mean
             // all, not an empty list.
             if (lower === "all") {
-                for (const k of exports.KNOWN_CONTEXT_CLIENTS)
+                for (const k of exports.KNOWN_IDENTITY_CLIENTS)
                     if (!clients.includes(k))
                         clients.push(k);
                 continue;
@@ -346,14 +434,44 @@ function resolveContextClients(raw) {
     }
     return { clients: ["cc"], dropped: [] };
 }
+/**
+ * Read the identity-clients config value from a raw config object, honouring
+ * the new key (`identityClients`) and falling back to the legacy
+ * `contextClients` (#264) with a one-time deprecation signal. Returns the
+ * resolved clients, dropped unknowns, and whether the value came from the
+ * legacy key.
+ */
+function resolveIdentityClientsConfig(config) {
+    if (config && "identityClients" in config) {
+        return { ...resolveIdentityClients(config.identityClients), legacy: false };
+    }
+    if (config && "contextClients" in config) {
+        return { ...resolveIdentityClients(config.contextClients), legacy: true };
+    }
+    return { ...resolveIdentityClients(undefined), legacy: false };
+}
+/**
+ * Read the identity-agents config value from a raw config object, honouring
+ * the new key (`identityAgents`) and falling back to the legacy
+ * `contextAgents` (#264) with a one-time deprecation signal.
+ */
+function resolveIdentityAgentsConfig(config) {
+    if (config && "identityAgents" in config) {
+        return { ...resolveIdentityAgents(config.identityAgents), legacy: false };
+    }
+    if (config && "contextAgents" in config) {
+        return { ...resolveIdentityAgents(config.contextAgents), legacy: true };
+    }
+    return { ...resolveIdentityAgents(undefined), legacy: false };
+}
 // ---------------------------------------------------------------------------
 // Per-agent resolution (0.13)
 // ---------------------------------------------------------------------------
 /**
- * Classify the on-disk state of `context/agents/<id>`, hardened against a
+ * Classify the on-disk state of `identity/agents/<id>`, hardened against a
  * symlink planted at EITHER the `agents` ROOT or the `<id>` leaf — lstat/readdir
  * follow a symlinked intermediate path component, so checking only the leaf
- * would let a symlinked root escape the context root entirely. BOTH must be
+ * would let a symlinked root escape the identity root entirely. BOTH must be
  * real, non-symlink directories.
  *  - "absent" — the root or the leaf does not exist (fresh install / no dir for
  *    this agent). A normal, safe "no agent sections" case.
@@ -364,8 +482,8 @@ function resolveContextClients(raw) {
  * rethrow (a permissions fault must never masquerade as "empty", matching
  * readSections). The single source of truth for the four call sites below.
  */
-function agentDirState(contextDir, agentId) {
-    const root = (0, node_path_1.join)(contextDir, exports.AGENTS_DIR);
+function agentDirState(identityDir, agentId) {
+    const root = (0, node_path_1.join)(identityDir, exports.AGENTS_DIR);
     let rootSt;
     try {
         rootSt = (0, node_fs_1.lstatSync)(root);
@@ -393,27 +511,53 @@ function agentDirState(contextDir, agentId) {
 /**
  * Resolve the mode for a request `?agent=<id>` (spec §3):
  *  1. config entry present → that mode;
- *  2. else `context/agents/<id>/` present as a REAL directory (root + leaf both
+ *  2. else `identity/agents/<id>/` present as a REAL directory (root + leaf both
  *     real, non-symlink) → "override" (dropping in a dir is intent, no config);
  *  3. else → "global".
  * A symlinked/non-dir root or leaf never counts as "present" (agentDirState).
  */
-function resolveAgentMode(contextDir, agentId, contextAgents) {
-    const configured = contextAgents[agentId];
+function resolveAgentMode(identityDir, agentId, identityAgents) {
+    const configured = identityAgents[agentId];
     if (configured)
         return configured;
-    return agentDirState(contextDir, agentId) === "real" ? "override" : "global";
+    // Presence of EITHER the identity agent dir OR the legacy `context/agents/<id>/`
+    // dir counts as intent to override (post-#264 both-dirs edge case: a partial
+    // migration must not silently demote a legacy agent to "global" and lose its
+    // per-agent sections).
+    if (agentDirState(identityDir, agentId) === "real")
+        return "override";
+    const legacyDir = (0, node_path_1.join)(identityDir, "..", "context");
+    if (agentDirState(legacyDir, agentId) === "real")
+        return "override";
+    return "global";
+}
+/**
+ * Read one agent's sections from BOTH the identity agent dir and the legacy
+ * `context/agents/<id>/` dir, additively merged (identity wins per-section;
+ * legacy-only sections are included so nothing is lost in the both-dirs edge
+ * case). A symlinked/non-dir leaf contributes nothing (agentDirState guard).
+ */
+function readAgentSectionsWithFallback(identityDir, agentId) {
+    const primaryDir = (0, node_path_1.join)(identityDir, exports.AGENTS_DIR, agentId);
+    const primary = agentDirState(identityDir, agentId) === "real" ? readSections(primaryDir) : { sections: {}, updatedAt: null, mtimes: {} };
+    const legacyDir = (0, node_path_1.join)(identityDir, "..", "context");
+    const legacy = agentDirState(legacyDir, agentId) === "real" ? readSections((0, node_path_1.join)(legacyDir, exports.AGENTS_DIR, agentId)) : { sections: {}, updatedAt: null, mtimes: {} };
+    if (Object.keys(legacy.sections).length === 0)
+        return primary;
+    if (Object.keys(primary.sections).length === 0)
+        return legacy;
+    return mergeSections(primary, legacy);
 }
 /**
  * Enumerate the agents the UI selector should offer: the union of allowlisted
- * REAL directories under `context/agents/` and every configured `contextAgents`
+ * REAL directories under `identity/agents/` and every configured `identityAgents`
  * key, each mapped to its resolved mode (config wins over presence). A missing
  * agents dir (fresh install) yields the config keys only; a symlinked/non-dir
  * agents root is treated as "no dirs" (config keys only).
  */
-function listAgents(contextDir, contextAgents) {
+function listAgents(identityDir, identityAgents) {
     const result = {};
-    const agentsRoot = (0, node_path_1.join)(contextDir, exports.AGENTS_DIR);
+    const agentsRoot = (0, node_path_1.join)(identityDir, exports.AGENTS_DIR);
     // Guard the root itself before readdir would follow a symlinked root.
     let rootReal = false;
     try {
@@ -430,14 +574,14 @@ function listAgents(contextDir, contextAgents) {
                 continue;
             // Real leaf confirmed by the shared guard → its mode is config-or-override
             // (config wins over presence); no second lstat via resolveAgentMode.
-            if (agentDirState(contextDir, entry) === "real") {
-                result[entry] = contextAgents[entry] ?? "override";
+            if (agentDirState(identityDir, entry) === "real") {
+                result[entry] = identityAgents[entry] ?? "override";
             }
         }
     }
-    for (const id of Object.keys(contextAgents)) {
+    for (const id of Object.keys(identityAgents)) {
         if (!(id in result))
-            result[id] = contextAgents[id];
+            result[id] = identityAgents[id];
     }
     return result;
 }
@@ -449,25 +593,22 @@ function listAgents(contextDir, contextAgents) {
  * reading (A1): a symlinked or non-directory `agents/<id>` contributes NO agent
  * sections regardless of how override was selected (config or presence).
  */
-function readResolvedSections(contextDir, agentId, contextAgents) {
+function readResolvedSections(identityDir, agentId, identityAgents) {
     if (agentId === null) {
-        const g = readSections(contextDir);
+        const g = readSectionsWithFallback(identityDir);
         return { sections: g.sections, updatedAt: g.updatedAt };
     }
-    const mode = resolveAgentMode(contextDir, agentId, contextAgents);
+    const mode = resolveAgentMode(identityDir, agentId, identityAgents);
     if (mode === "off") {
         return { sections: {}, updatedAt: null, agent: agentId, mode };
     }
-    const global = readSections(contextDir);
+    const global = readSectionsWithFallback(identityDir);
     if (mode === "global") {
         return { sections: global.sections, updatedAt: global.updatedAt, agent: agentId, mode };
     }
-    // override — read the agent dir, but only if root + leaf are real dirs
-    // (agentDirState closes the config-forced-override + symlinked-root holes).
-    let agentRead = { sections: {}, updatedAt: null, mtimes: {} };
-    if (agentDirState(contextDir, agentId) === "real") {
-        agentRead = readSections((0, node_path_1.join)(contextDir, exports.AGENTS_DIR, agentId));
-    }
+    // override — read the agent dir (identity + legacy fallback merged so the
+    // both-dirs edge case doesn't lose legacy-only agent sections).
+    const agentRead = readAgentSectionsWithFallback(identityDir, agentId);
     const sections = { ...global.sections, ...agentRead.sections };
     const origins = {};
     let latestMtimeMs = 0;
@@ -482,7 +623,7 @@ function readResolvedSections(contextDir, agentId, contextAgents) {
     return { sections, updatedAt, agent: agentId, mode, origins };
 }
 // ---------------------------------------------------------------------------
-// HTTP-shape handlers (real logic behind GET/PUT /context)
+// HTTP-shape handlers (real logic behind GET/PUT /identity)
 // ---------------------------------------------------------------------------
 //
 // These are the actual request handlers, expressed as pure functions over
@@ -506,18 +647,18 @@ function extractAgentParam(query) {
     return { agentId: raw };
 }
 /**
- * GET /context. Stale-client tripwire first: recall moved to /recent, so
+ * GET /identity. Stale-client tripwire first: recall moved to /recent, so
  * project/limit/privacy on this route mean a legacy recall caller — return a
- * loud 400 rather than silently degrading to an empty context-layer response.
- * (A bare GET /context with no params is the legitimate context-layer read and
+ * loud 400 rather than silently degrading to an empty identity-layer response.
+ * (A bare GET /identity with no params is the legitimate identity-layer read and
  * is served normally — the two are indistinguishable at the wire, so a
  * paramless legacy caller is covered by the migration docs, not this guard.)
  */
-function handleContextGet(contextDir, clients, query, contextAgents = {}) {
+function handleIdentityGet(identityDir, clients, query, identityAgents = {}) {
     if (RECALL_PARAMS.some((p) => p in query)) {
         return {
             status: 400,
-            body: { error: "recall moved to /recent — GET /context now serves the standing context layer (0.12)" },
+            body: { error: "recall moved to /recent — GET /identity now serves the standing identity layer (0.12)" },
         };
     }
     const { agentId, error } = extractAgentParam(query);
@@ -526,13 +667,13 @@ function handleContextGet(contextDir, clients, query, contextAgents = {}) {
     // No agent → the plain global read plus the additive `agents` map the UI
     // selector needs (backward compatible: existing callers ignore unknown keys).
     if (agentId === null) {
-        const { sections, updatedAt } = readSections(contextDir);
+        const { sections, updatedAt } = readSectionsWithFallback(identityDir);
         return {
             status: 200,
-            body: { sections, updated_at: updatedAt, clients, agents: listAgents(contextDir, contextAgents) },
+            body: { sections, updated_at: updatedAt, clients, agents: listAgents(identityDir, identityAgents) },
         };
     }
-    const resolved = readResolvedSections(contextDir, agentId, contextAgents);
+    const resolved = readResolvedSections(identityDir, agentId, identityAgents);
     const body = {
         sections: resolved.sections,
         updated_at: resolved.updatedAt,
@@ -545,11 +686,11 @@ function handleContextGet(contextDir, clients, query, contextAgents = {}) {
     return { status: 200, body };
 }
 /**
- * PUT /context. Validates the body shape and section content types, then
+ * PUT /identity. Validates the body shape and section content types, then
  * delegates to writeSections (which owns the name allowlist + atomicity +
  * symlink safety). Throws are left to the adapter to turn into a 500.
  */
-function handleContextPut(contextDir, body, query = {}, contextAgents = {}) {
+function handleIdentityPut(identityDir, body, query = {}, identityAgents = {}) {
     const { agentId, error } = extractAgentParam(query);
     if (error)
         return { status: 400, body: { error } };
@@ -562,23 +703,23 @@ function handleContextPut(contextDir, body, query = {}, contextAgents = {}) {
             return { status: 400, body: { error: `Section '${name}' content must be a string` } };
         }
     }
-    const targetDir = agentId === null ? contextDir : (0, node_path_1.join)(contextDir, exports.AGENTS_DIR, agentId);
+    const targetDir = agentId === null ? identityDir : (0, node_path_1.join)(identityDir, exports.AGENTS_DIR, agentId);
     if (agentId !== null) {
         // A1 write-path guard: never write through a symlinked/non-dir root or leaf
         // (agentDirState checks both). "absent" is fine — writeSections creates it.
-        if (agentDirState(contextDir, agentId) === "unsafe") {
-            return { status: 400, body: { error: "agent context path exists but is not a directory" } };
+        if (agentDirState(identityDir, agentId) === "unsafe") {
+            return { status: 400, body: { error: "agent identity path exists but is not a directory" } };
         }
         // Black-hole guard: if config FORCES off/global for this agent, sections
         // written under agents/<id>/ could never be served (resolution ignores the
         // dir). Reject loudly rather than accept a write that silently vanishes.
         // No config entry → writing creates the dir ⇒ override ⇒ served (allowed).
-        const configMode = contextAgents[agentId];
+        const configMode = identityAgents[agentId];
         if (configMode === "off" || configMode === "global") {
             return {
                 status: 409,
                 body: {
-                    error: `config contextAgents['${agentId}']='${configMode}' — sections written here would never be served; ` +
+                    error: `config identityAgents['${agentId}']='${configMode}' — sections written here would never be served; ` +
                         `set it to 'override' (or remove the entry) first`,
                 },
             };
@@ -599,10 +740,10 @@ function handleContextPut(contextDir, body, query = {}, contextAgents = {}) {
             throw err; // real I/O fault → adapter returns 500
         }
     }
-    const resolved = readResolvedSections(contextDir, agentId, contextAgents);
+    const resolved = readResolvedSections(identityDir, agentId, identityAgents);
     const bytes = totalBytes(resolved.sections);
-    const warn = bytes > exports.CONTEXT_SIZE_WARN_BYTES
-        ? `Context layer total size ${bytes} bytes exceeds ${exports.CONTEXT_SIZE_WARN_BYTES} — injected into every session; consider trimming.`
+    const warn = bytes > exports.IDENTITY_SIZE_WARN_BYTES
+        ? `Identity layer total size ${bytes} bytes exceeds ${exports.IDENTITY_SIZE_WARN_BYTES} — injected into every session; consider trimming.`
         : undefined;
     const respBody = { ok: true, updated_at: resolved.updatedAt };
     if (agentId !== null) {

package/dist/index.d.ts

@@ -9,13 +9,13 @@
  * Run server:   `npx @gamaze/hicortex init`
  *
  * Responsibilities (recall-only adapter, like the Hermes plugin):
- *   - before_agent_start  → GET /context + GET /lessons + POST /recall-index
- *     (fail-soft, 3s timeout each, concurrent) → inject context. In OpenClaw
- *     every inbound message spawns an embedded run, so this hook fires PER
- *     TURN with the current prompt and session id — it is the per-turn
+ *   - before_agent_start  → GET /identity + GET /lessons + POST /recall-index
+ *     (fail-soft, 3s timeout each, concurrent) → inject identity + lessons. In
+ *     OpenClaw every inbound message spawns an embedded run, so this hook fires
+ *     PER TURN with the current prompt and session id — it is the per-turn
  *     /recall-index surface, not just session start.
  *   - after_compaction / before_reset → POST /recall-index {reset:true}
- *     (context rebuilt → the server's per-session shown-set is stale)
+ *     (context window rebuilt → the server's per-session shown-set is stale)
  *   - Tools               → HTTP proxies to /search, /memory, /recent, /ingest, /lessons
  *
  * CAPTURE IS NOT THIS PLUGIN'S JOB. OpenClaw persists sessions at
@@ -23,6 +23,13 @@
  * machine's Hicortex nightly reads them via oc-transcript-reader.ts —
  * canonical nightly-from-logs, same as CC JSONL and Hermes state.db.
  */
+import type { MemorySearchResult } from "./types.js";
+export declare function formatToolResults(results: MemorySearchResult[]): {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+};
 declare const _default: {
     id: string;
     name: string;