@gamaze/hicortex 0.18.0 → 0.18.2

package/README.md

@@ -118,17 +118,18 @@ The run is resumable — interrupt it any time and it continues where it stopped
 
 ## Agent Tools (MCP)
 
-9 tools available via MCP:
+10 canonical tools available via MCP (plus `hicortex_lessons` as a backcompat alias of `hicortex_learnings`):
 
 - **hicortex_search** — Semantic search across all stored memories
 - **hicortex_get** — Fetch one memory's full content by id (0.14) — the lazy-load counterpart of the recall index; fetching marks the memory as used
 - **hicortex_recent** — Get recent decisions and project state (queryless recall; renamed in 0.12)
 - **hicortex_ingest** — Store a memory directly
-- **hicortex_lessons** — Get actionable lessons from reflection
+- **hicortex_learnings** — Get actionable Learnings from reflection (`hicortex_lessons` is kept as a backcompat alias)
 - **hicortex_index** — Get the knowledge domain index (what topics are stored)
 - **hicortex_graph** — Graph traversal: neighbors, hubs, shortest paths
 - **hicortex_update** — Fix incorrect memories (re-embeds on content change)
 - **hicortex_delete** — Remove memories with cascade cleanup
+- **hicortex_identity** — Fetch your standing identity layer on demand (all sections, or one by name; pass `agent` on multi-agent installs to scope to a specific agent)
 
 Explicit learnings: call `hicortex_ingest` directly (capture is otherwise automatic, nightly).
 
@@ -271,7 +272,7 @@ Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze
 | `/recent` | GET | Yes | Recent memories, queryless recall (renamed from `/context` in 0.12) |
 | `/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) |
+| `/learnings` | GET | Yes | Learnings + memory index (used by CC SessionStart hook). `/lessons` is a backcompat alias for the same handler |
 | `/ingest` | POST | Yes | Legacy: accept a single pre-distilled memory from older clients |
 | `/sse` | GET | Yes | MCP SSE stream for agent connections |
 | `/messages` | POST | Yes | MCP message endpoint |

package/assets/dashboard.html

@@ -238,10 +238,15 @@ 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.
+// #264 final: the data blob carries the CANONICAL human-term keys
+// (knowledge/experience/decisions/learnings). Legacy raw keys are also mapped
+// so a snapshot taken mid-migrate renders correctly. Unknown keys pass through.
 const TYPE_LABELS = {
+  knowledge: "Knowledge",
+  experience: "Experience",
+  decisions: "Decisions",
+  learnings: "Learnings",
+  // Legacy raw enum (same types, renamed).
   fact: "Knowledge",
   episode: "Experience",
   decision: "Decisions",

package/assets/viz.html

@@ -389,10 +389,16 @@
   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.
+  // #264 final: node data carries the CANONICAL human-term values
+  // (knowledge/experience/decisions/learnings). Legacy raw values are also
+  // mapped so a mid-migrate snapshot renders correctly. Unknown values pass
+  // through unchanged.
   var TYPE_LABELS = {
+    knowledge: "Knowledge",
+    experience: "Experience",
+    decisions: "Decisions",
+    learnings: "Learnings",
+    // Legacy raw enum (same types, renamed).
     fact: "Knowledge",
     episode: "Experience",
     decision: "Decisions",

package/dist/consolidate.js

@@ -418,7 +418,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
             const severity = String(lo.severity ?? "important");
             const confidence = String(lo.confidence ?? "medium");
             const sourcePattern = String(lo.source_pattern ?? "");
-            // No `## Lesson:` prefix: memory_type='lesson' carries the type, and the
+            // No `## Lesson:` prefix: memory_type='learnings' carries the type, and the
             // text is the topic-first first line (display reads the first line, not a
             // header parse — see learnings-identity.ts / index.ts).
             let content = `${lessonText}\n\n`;
@@ -443,7 +443,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                 // the accidental 1−L2 scale and required cosine > 0.98 — the check
                 // effectively never fired. See isContradictionCandidate.
                 const similarLessons = storage.vectorSearch(db, embedding, 3)
-                    .filter((n) => isContradictionCandidate(n.distance) && n.memory_type === "lesson");
+                    .filter((n) => isContradictionCandidate(n.distance) && n.memory_type === "learnings");
                 let contradicted = false;
                 if (similarLessons.length > 0 && budget.use("contradiction_check")) {
                     const existingText = similarLessons[0].content.slice(0, 300);
@@ -470,7 +470,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                     storage.insertMemory(db, content, embedding, {
                         sourceAgent: "hicortex/reflection",
                         project,
-                        memoryType: "lesson",
+                        memoryType: "learnings",
                         baseStrength: baseStrength[severity] ?? 0.8,
                     });
                     generated++;
@@ -509,7 +509,7 @@ function rebuildContentModuleIndex(db, domains, stateDir) {
         .all();
     const lessonRows = db
         .prepare(`SELECT domain, COUNT(*) AS cnt FROM memories
-       WHERE domain IS NOT NULL AND memory_type = 'lesson' GROUP BY domain`)
+       WHERE domain IS NOT NULL AND memory_type = 'learnings' GROUP BY domain`)
         .all();
     const memByDomain = new Map(memRows.map((r) => [r.domain, r.cnt]));
     const lessonByDomain = new Map(lessonRows.map((r) => [r.domain, r.cnt]));
@@ -637,7 +637,7 @@ async function stageDomainCuration(db, llm, budget, dryRun, stateDir) {
     }
     const lessonRows = db
         .prepare(`SELECT project, COUNT(*) as cnt FROM memories
-       WHERE project IS NOT NULL AND memory_type = 'lesson'
+       WHERE project IS NOT NULL AND memory_type = 'learnings'
        GROUP BY project`)
         .all();
     const lessonsByProject = new Map(lessonRows.map((r) => [r.project, r.cnt]));
@@ -997,7 +997,7 @@ const SUPERSESSION_BATCH_SIZE = 500;
  * events, not mutable state, so there is nothing to supersede.
  */
 function isSupersedableShape(mem) {
-    return (mem.memory_type === "decision" ||
+    return (mem.memory_type === "decisions" ||
         mem.content.includes("[Decisions Made]") ||
         mem.content.includes("[Corrections & Rejections]") ||
         mem.content.includes("[Facts Learned]") ||
@@ -1117,7 +1117,7 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
     // in lockstep (an inline SQL copy, so drift here silently narrows scope).
     `SELECT rowid AS __rowid, * FROM memories
        WHERE rowid > ?
-         AND (memory_type = 'decision'
+         AND (memory_type = 'decisions'
               OR content LIKE '%[Decisions Made]%'
               OR content LIKE '%[Corrections & Rejections]%'
               OR content LIKE '%[Facts Learned]%'

package/dist/dashboard.js

@@ -53,7 +53,7 @@ function countBy(db, col) {
 function computeDashboardMetrics(db) {
     const mem = db.prepare("SELECT COUNT(*) AS c FROM memories").get().c;
     const lesson = db
-        .prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'lesson'")
+        .prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'learnings'")
         .get().c;
     const link = db.prepare("SELECT COUNT(*) AS c FROM memory_links").get().c;
     const adoptionRow = db
@@ -228,7 +228,7 @@ function backfillSnapshots(db) {
             const dayRows = byDay.get(d);
             for (const r of dayRows) {
                 mem++;
-                if (r.memory_type === "lesson")
+                if (r.memory_type === "learnings")
                     lesson++;
                 byType[r.memory_type] = (byType[r.memory_type] ?? 0) + 1;
                 const domKey = r.domain ?? "(unscoped)";
@@ -380,7 +380,7 @@ function handleDashboardData(db, query, config) {
     const lessonRows = db
         .prepare(`SELECT id, content, created_at
          FROM memories
-        WHERE memory_type = 'lesson' AND created_at BETWEEN ? AND ?
+        WHERE memory_type = 'learnings' AND created_at BETWEEN ? AND ?
         ORDER BY created_at ASC`)
         .all(dayStart, dayEnd);
     // Stage outcomes for the day: dedup merges + supersession links that day.

package/dist/db.js

@@ -105,7 +105,7 @@ CREATE TABLE IF NOT EXISTS memories (
     source_session TEXT,
     project TEXT,
     privacy TEXT DEFAULT 'WORK',
-    memory_type TEXT DEFAULT 'episode',
+    memory_type TEXT DEFAULT 'experience',
     updated_at TIMESTAMP
 );
 
@@ -488,6 +488,29 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 13,
+        name: "memory_type_unified_terminology",
+        up: (db) => {
+            // #264 final step: rename the memory_type COLUMN VALUES from the raw
+            // internal enum (fact/episode/decision/lesson) to the unified human
+            // terms (knowledge/experience/decisions/learnings). The column itself,
+            // its default, and every SQL query/filter were updated in the same
+            // change; this migration converts existing rows in place. Idempotent:
+            // re-running against an already-migrated DB matches 0 rows per clause.
+            // The CREATE TABLE default is now 'experience' (was 'episode'); legacy
+            // rows with the old default value are rewritten here.
+            //
+            // Ordering is irrelevant (each clause keys on a distinct old value) and
+            // no clause can fire on another clause's output (the new values are
+            // disjoint from the old). The transaction wrapper in migrate() makes the
+            // whole migration atomic.
+            db.exec("UPDATE memories SET memory_type = 'knowledge'  WHERE memory_type = 'fact'");
+            db.exec("UPDATE memories SET memory_type = 'experience' WHERE memory_type = 'episode'");
+            db.exec("UPDATE memories SET memory_type = 'decisions'  WHERE memory_type = 'decision'");
+            db.exec("UPDATE memories SET memory_type = 'learnings'  WHERE memory_type = 'lesson'");
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/distiller.d.ts

@@ -64,13 +64,13 @@ export declare function distillSession(llm: LlmClient, conversation: string, pro
 export declare function hasMinimalSubstance(entry: string): boolean;
 /**
  * A parsed distillation entry: the stored content (type tag STRIPPED) plus the
- * classified memory_type. `memoryType` is one of "episode" | "fact" |
- * "decision" — the three distillation-time types. "lesson" is deliberately
- * absent: lessons are the reflection stage's product, never distillation's
- * (#216). A missing/unknown tag defaults to "episode" so older distiller
+ * classified memory_type. `memoryType` is one of "experience" | "knowledge" |
+ * "decisions" — the three distillation-time types. "learnings" is deliberately
+ * absent: learnings are the reflection stage's product, never distillation's
+ * (#216). A missing/unknown tag defaults to "experience" so older distiller
  * output (pre-#216, no tag) stays backward-compatible.
  */
 export interface DistilledEntry {
     content: string;
-    memoryType: "episode" | "fact" | "decision";
+    memoryType: "experience" | "knowledge" | "decisions";
 }

package/dist/distiller.js

@@ -267,7 +267,7 @@ async function distillSession(llm, conversation, projectName, date, chunkSizeCha
             for (const entry of entries) {
                 // Deduplicate by normalized content (type tag does not participate —
                 // two chunks extracting the same fact should collapse regardless of
-                // whether one tagged it [F] and the other [E]).
+                // whether one tagged it [K] and the other [E]).
                 const key = entry.content.toLowerCase().replace(/\s+/g, " ").slice(0, 100);
                 if (!seen.has(key)) {
                     seen.add(key);
@@ -325,7 +325,7 @@ async function distillChunk(llm, transcript, projectName, date) {
     // sometimes ignore constraints (cf. the prior max-15-bullet failure). Count
     // entries that still look actor-led or bracket-led so a format regression
     // shows in nightly logs, not months later in the next eval. Non-blocking.
-    // Note: the type tag ([E]/[F]/[D]) is already stripped by the parser, so a
+    // Note: the type tag ([E]/[K]/[D]) is already stripped by the parser, so a
     // leading bracket here means a payload-bracket or a category-first regression.
     const offTopic = parsed.filter((e) => /^\s*(user|ai|the user|assistant)\b/i.test(e.content) || /^\s*\[/.test(e.content)).length;
     if (parsed.length > 0 && offTopic > 0) {
@@ -426,21 +426,31 @@ function hasMinimalSubstance(entry) {
 }
 /**
  * Map a single-letter type tag to the stored memory_type. Unknown/absent →
- * episode (the pre-#216 default). `[L]` is explicitly rejected → episode: the
- * distiller must NEVER emit lessons (that's the reflection stage's job), so a
- * model that emits `[L]` is wrong and we do not propagate it as a lesson.
+ * experience (the pre-#216 default). `[L]` is explicitly rejected →
+ * experience: the distiller must NEVER emit learnings (that's the reflection
+ * stage's job), so a model that emits `[L]` is wrong and we do not propagate
+ * it as a learning.
+ *
+ * The single-letter tags ([E]/[K]/[D]) are unchanged from the raw-enum era —
+ * the model is taught these as "EXPERIENCE/KNOWLEDGE/DECISIONS" concepts in prompts.ts
+ * (ordinary English the model understands), and only the resulting STORED
+ * value changed in #264 (episode→experience, fact→knowledge, decision→
+ * decisions). The tag letters stay stable so neither the prompt nor the
+ * parser needs to change; only this mapping table moves.
  */
 function typeFromTag(letter) {
     switch (letter) {
-        case "F":
+        case "K":
+        case "k":
+        case "F": // legacy tag (was Fact)
         case "f":
-            return "fact";
+            return "knowledge";
         case "D":
         case "d":
-            return "decision";
-        // E, e, L, l (rejected), undefined, or anything else → episode.
+            return "decisions";
+        // E, e, L, l (rejected), undefined, or anything else → experience.
         default:
-            return "episode";
+            return "experience";
     }
 }
 /**
@@ -448,7 +458,7 @@ function typeFromTag(letter) {
  * Each bullet becomes a separate memory. The leading `[E]`/`[F]`/`[D]` type
  * tag is extracted (→ memoryType), stripped from the stored content, and
  * passed to `insertMemory` via the `memoryType` option (#216). Bullets with
- * no tag default to "episode" (backward compatible with pre-#216 distiller
+ * no tag default to "experience" (backward compatible with pre-#216 distiller
  * output that never carried a tag).
  */
 function parseDistilledEntries(markdown) {
@@ -472,15 +482,15 @@ function parseDistilledEntries(markdown) {
             // Extract an optional leading single-letter type tag: "[E]", "[F]",
             // "[D]" (case-insensitive). The tag must be the very first token of the
             // bullet — a bracket that appears later is payload, not a type tag.
-            const tagMatch = body.match(/^\[([EFDefdLl])\]\s*/);
+            const tagMatch = body.match(/^\[([EFDKefdklL])\]\s*/);
             if (tagMatch) {
                 const memoryType = typeFromTag(tagMatch[1].toUpperCase());
                 entries.push({ content: body.slice(tagMatch[0].length), memoryType });
             }
             else {
-                // No tag → episode (pre-#216 distiller output, or a model that
+                // No tag → experience (pre-#216 distiller output, or a model that
                 // skipped the tag). Keep the content verbatim.
-                entries.push({ content: body, memoryType: "episode" });
+                entries.push({ content: body, memoryType: "experience" });
             }
         }
     }

package/dist/eval/recall-sweep.js

@@ -431,7 +431,7 @@ async function buildCorpusDb(dbPath) {
         const vec = await (0, embedder_js_1.embed)(mem.text);
         const id = storage.insertMemory(db, mem.text, vec, {
             sourceAgent: "eval-corpus",
-            memoryType: "episode",
+            memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
         });
         idToTopic.set(id, mem.topic);
@@ -455,7 +455,7 @@ async function buildScopeDb(dbPath) {
         const vec = await (0, embedder_js_1.embed)(mem.text);
         const id = storage.insertMemory(db, mem.text, vec, {
             sourceAgent: "eval-scope",
-            memoryType: "episode",
+            memoryType: "experience",
             baseStrength: 0.5, // uniform — strength is NOT a discriminator here
             project: mem.project, // #203 scope label
         });

package/dist/eval/reflection-census.js

@@ -11,11 +11,11 @@ exports.runReflectionCensus = runReflectionCensus;
 function runReflectionCensus(db) {
     const lessonsByDate = db
         .prepare(`SELECT date(created_at) AS date, COUNT(*) AS count
-       FROM memories WHERE memory_type = 'lesson'
+       FROM memories WHERE memory_type = 'learnings'
        GROUP BY date ORDER BY date`)
         .all();
-    const totalLessons = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'lesson'").get().c;
-    const totalEpisodes = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'episode'").get().c;
+    const totalLessons = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'learnings'").get().c;
+    const totalEpisodes = db.prepare("SELECT COUNT(*) AS c FROM memories WHERE memory_type = 'experience'").get().c;
     return {
         lessonsByDate,
         totalLessons,

package/dist/index.js

@@ -150,7 +150,7 @@ async function fetchOcIdentityBlock(agentId) {
     return (0, learnings_identity_js_1.gateAndRenderIdentity)(data, THIS_HARNESS, { requireAgentEcho: agentId !== null });
 }
 /**
- * Fetch /lessons and build the `## Hicortex Lessons` block, or null on any
+ * Fetch /lessons and build the `## Hicortex Learnings` block, or null on any
  * failure or when no lessons survive selection. Preserves the pre-0.13 lesson
  * output; the caller prepends the `## Identity` block and adds separators.
  */
@@ -177,8 +177,8 @@ async function buildLessonsBlock(project) {
         const meta = [severityMatch?.[1], typeMatch?.[1]].filter(Boolean).join(", ");
         return `- ${title}${meta ? ` (${meta})` : ""}`;
     });
-    return (`## Hicortex Lessons (auto-injected from long-term memory)\n` +
-        `These are actionable lessons learned from past sessions:\n\n` +
+    return (`## Hicortex Learnings (auto-injected from long-term memory)\n` +
+        `These are actionable Learnings from past sessions:\n\n` +
         formatted.join("\n"));
 }
 // ---------------------------------------------------------------------------
@@ -354,7 +354,7 @@ exports.default = {
                 const agentId = (0, identity_store_js_1.sanitizeAgentId)(ctx?.agentId ?? "");
                 // Fetch all three concurrently with INDEPENDENT fail-soft: no block
                 // may ever cost another. Order in the injected output: `## Identity`
-                // (standing identity, 0.13) → `## Hicortex Lessons` → the per-turn
+                // (standing identity, 0.13) → `## Hicortex Learnings` → the per-turn
                 // `## Memory recall (auto)` index (#193, closest to the prompt).
                 const [identityBlock, lessonsBlock, recallBlock] = await Promise.all([
                     fetchOcIdentityBlock(agentId).catch(() => null),
@@ -481,7 +481,7 @@ exports.default = {
         }), { name: "hicortex_recent" });
         api.registerTool((_ctx) => ({
             name: "hicortex_ingest",
-            description: "Store a new memory in long-term storage. Use for important facts, decisions, or lessons.",
+            description: "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings.",
             parameters: {
                 type: "object",
                 properties: {
@@ -489,8 +489,8 @@ exports.default = {
                     project: { type: "string", description: "Project this memory belongs to" },
                     memory_type: {
                         type: "string",
-                        enum: ["episode", "lesson", "fact", "decision"],
-                        description: "Type of memory (default: episode)",
+                        enum: ["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"],
+                        description: "Type of memory (default: Experience). Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term).",
                     },
                 },
                 required: ["content"],
@@ -501,7 +501,7 @@ exports.default = {
                         content: args.content,
                         source_agent: `openclaw/${context?.agentId ?? "manual"}`,
                         project: args.project,
-                        memory_type: args.memory_type ?? "episode",
+                        memory_type: args.memory_type ? (0, type_labels_js_1.normalizeMemoryType)(args.memory_type) : "experience",
                     }, 15000);
                     if (!result.ok) {
                         return { error: `Ingest failed: ${result.data?.error ?? `HTTP ${result.status}`}` };
@@ -516,7 +516,7 @@ exports.default = {
         }), { name: "hicortex_ingest" });
         api.registerTool((_ctx) => ({
             name: "hicortex_lessons",
-            description: "Get actionable lessons learned from past sessions. Auto-generated insights about mistakes to avoid.",
+            description: "Get actionable Learnings distilled from past sessions. Auto-generated insights about mistakes to avoid.",
             parameters: {
                 type: "object",
                 properties: {
@@ -530,7 +530,7 @@ exports.default = {
                         return { error: `Lessons fetch failed: ${describeGetFailure(status, "/lessons")}` };
                     const lessons = data.lessons ?? [];
                     if (lessons.length === 0) {
-                        return { content: [{ type: "text", text: "No lessons found." }] };
+                        return { content: [{ type: "text", text: "No Learnings found." }] };
                     }
                     const text = lessons.map((l) => `- ${l.content.slice(0, 500)}`).join("\n");
                     return { content: [{ type: "text", text }] };
@@ -612,8 +612,8 @@ exports.default = {
                     project: { type: "string", description: "New project name" },
                     memory_type: {
                         type: "string",
-                        enum: ["episode", "lesson", "fact", "decision"],
-                        description: "New memory type",
+                        enum: ["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"],
+                        description: "New memory type. Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term).",
                     },
                 },
                 required: ["id"],
@@ -624,7 +624,7 @@ exports.default = {
                         id: args.id,
                         content: args.content,
                         project: args.project,
-                        memory_type: args.memory_type,
+                        memory_type: args.memory_type ? (0, type_labels_js_1.normalizeMemoryType)(args.memory_type) : undefined,
                     }, 15000);
                     if (result.status === 404) {
                         return { error: `Memory not found: ${args.id}` };

package/dist/learnings-identity.d.ts

@@ -26,6 +26,7 @@
  * parse error) results in silent exit-0. A broken hook must never block a
  * CC session, and a broken /identity fetch must never blank the whole output.
  */
+import { type AgentMode } from "./identity-store.js";
 /**
  * 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
@@ -95,6 +96,41 @@ export declare function renderIdentityBlock(sections: Record<string, string>): s
  *     global IS the operator's intended state there, and a guard would instead
  *     blank ALL identity for every CC session in that window.
  */
+/**
+ * Result of `buildIdentityToolResult` — the MCP tool handler maps this to its
+ * `{content:[{type:"text",text}],isError?}` shape. Pure value: no MCP SDK
+ * types leak here so the function is unit-testable with no harness.
+ */
+export interface IdentityToolResult {
+    text: string;
+    isError?: boolean;
+}
+/**
+ * Build the `hicortex_identity` MCP tool result from the SAME pure pipeline the
+ * REST `GET /identity` route and the SessionStart hook use (#264 CRITICAL fix:
+ * previously the tool was a closure inside `createMcpServer()` that tests
+ * re-implemented locally, so the production path was never exercised).
+ *
+ * Pipeline (kept identical to REST + hook by CONSTRUCTION, not by mirroring):
+ *  1. `handleIdentityGet` — the real GET /identity handler, with the optional
+ *     `agent` param forwarded so per-agent installs resolve the right scope
+ *     (WARNING-2: previously the tool always passed `{}` → global, so an agent
+ *     with an override saw the wrong identity).
+ *  2. `injectMemorySection` — the synthetic product-owned `memory` section
+ *     (WARNING-1: the REST route + SessionStart hook inject it; the tool did
+ *     not, contradicting its "same data" docs).
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Title>`
+ *     markdown the hook injects.
+ *
+ * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the
+ * identity dir, which is the same I/O the REST route does). Takes the resolved
+ * `identityClients` / `identityAgents` the daemon already holds at boot.
+ */
+export declare function buildIdentityToolResult(identityDir: string, identityClients: string[], identityAgents: Record<string, AgentMode>, opts: {
+    name?: string;
+    agent?: string;
+    memoryInstructionsEnabled: boolean;
+}): IdentityToolResult;
 export declare function gateAndRenderIdentity(data: IdentityResponse, harness: string, opts: {
     requireAgentEcho: boolean;
 }): string | null;

package/dist/learnings-identity.js

@@ -33,11 +33,13 @@ exports.resolveConfig = resolveConfig;
 exports.titleCaseSection = titleCaseSection;
 exports.orderSectionNames = orderSectionNames;
 exports.renderIdentityBlock = renderIdentityBlock;
+exports.buildIdentityToolResult = buildIdentityToolResult;
 exports.gateAndRenderIdentity = gateAndRenderIdentity;
 exports.fetchLessonsIdentity = fetchLessonsIdentity;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const identity_store_js_1 = require("./identity-store.js");
+const memory_instructions_js_1 = require("./memory-instructions.js");
 const features_js_1 = require("./features.js");
 const extensions_js_1 = require("./extensions.js");
 const state_js_1 = require("./state.js");
@@ -115,7 +117,7 @@ async function fetchLessonsBlock(cfg) {
     parts.push("BEFORE making decisions, search memory: `hicortex_search` for prior decisions on the same topic.");
     parts.push("Use `hicortex_recent` at session start for recent project state.");
     if (lessonLines.length > 0) {
-        parts.push("", "### Lessons (updated nightly)");
+        parts.push("", "### Learnings (updated nightly)");
         parts.push(...lessonLines);
     }
     const { index } = data;
@@ -123,16 +125,16 @@ async function fetchLessonsBlock(cfg) {
         parts.push("", "### Memory Index");
         for (const domain of moduleIndex.domains) {
             const kwStr = domain.keywords.length > 0 ? `: ${domain.keywords.join(", ")}` : "";
-            parts.push(`${domain.name} (${domain.memoryCount} memories, ${domain.lessonCount} lessons)${kwStr}`);
+            parts.push(`${domain.name} (${domain.memoryCount} memories, ${domain.lessonCount} Learnings)${kwStr}`);
             if (domain.projects.length > 0)
                 parts.push(`  ${domain.projects.join(" | ")}`);
         }
-        parts.push(`${index.total} memories, ${index.lessonCount} lessons, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
+        parts.push(`${index.total} memories, ${index.lessonCount} Learnings, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
     }
     else if (index.projects.length > 0) {
         parts.push("", "### Memory Index");
         parts.push(index.projects.map(p => `${p.name}: ${p.count}`).join(" | "));
-        parts.push(`${index.total} memories, ${index.lessonCount} lessons, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
+        parts.push(`${index.total} memories, ${index.lessonCount} Learnings, ${index.sourceCount} agents. Search with \`hicortex_search\`.`);
     }
     return parts.join("\n");
 }
@@ -183,24 +185,55 @@ function renderIdentityBlock(sections) {
     return ["## Identity", "", ...bodyParts].join("\n");
 }
 /**
- * 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
- * never drift (the Python Hermes plugin `provider.py::_context_block` mirrors
- * this logic — keep them in sync).
+ * Build the `hicortex_identity` MCP tool result from the SAME pure pipeline the
+ * REST `GET /identity` route and the SessionStart hook use (#264 CRITICAL fix:
+ * previously the tool was a closure inside `createMcpServer()` that tests
+ * re-implemented locally, so the production path was never exercised).
  *
- * `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 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 identity for every CC session in that window.
+ * Pipeline (kept identical to REST + hook by CONSTRUCTION, not by mirroring):
+ *  1. `handleIdentityGet` — the real GET /identity handler, with the optional
+ *     `agent` param forwarded so per-agent installs resolve the right scope
+ *     (WARNING-2: previously the tool always passed `{}` → global, so an agent
+ *     with an override saw the wrong identity).
+ *  2. `injectMemorySection` — the synthetic product-owned `memory` section
+ *     (WARNING-1: the REST route + SessionStart hook inject it; the tool did
+ *     not, contradicting its "same data" docs).
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Title>`
+ *     markdown the hook injects.
+ *
+ * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the
+ * identity dir, which is the same I/O the REST route does). Takes the resolved
+ * `identityClients` / `identityAgents` the daemon already holds at boot.
  */
+function buildIdentityToolResult(identityDir, identityClients, identityAgents, opts) {
+    // WARNING-2: forward `agent` so per-agent installs resolve the right scope.
+    // An invalid id makes handleIdentityGet return a 400 → surfaced as isError.
+    const query = opts.agent ? { agent: opts.agent } : {};
+    const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, query, identityAgents);
+    if (r.status !== 200) {
+        const errBody = r.body;
+        return {
+            text: `Identity fetch failed: ${JSON.stringify(errBody.error ?? r.body)}`,
+            isError: true,
+        };
+    }
+    // WARNING-1: inject the synthetic `memory` section exactly like REST + the
+    // SessionStart hook. `injectMemorySection` is a no-op when disabled or when
+    // agent mode === "off".
+    (0, memory_instructions_js_1.injectMemorySection)(r.body, opts.memoryInstructionsEnabled);
+    const sections = r.body.sections ?? {};
+    const filtered = opts.name
+        ? (sections[opts.name] !== undefined ? { [opts.name]: sections[opts.name] } : {})
+        : sections;
+    const block = renderIdentityBlock(filtered);
+    if (block === null) {
+        const text = opts.name
+            ? `No identity section named '${opts.name}'.`
+            : "No identity sections configured.";
+        return { text };
+    }
+    return { text: block };
+}
 function gateAndRenderIdentity(data, harness, opts) {
     if (!data || typeof data !== "object")
         return null;