@gamaze/hicortex 0.18.0 → 0.18.1

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/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");
@@ -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;

package/dist/mcp-server.js

@@ -73,6 +73,7 @@ const recall_index_js_1 = require("./recall-index.js");
 const type_labels_js_1 = require("./type-labels.js");
 const health_js_1 = require("./health.js");
 const seed_lesson_js_1 = require("./seed-lesson.js");
+const learnings_identity_js_1 = require("./learnings-identity.js");
 const distiller_js_1 = require("./distiller.js");
 const dedup_js_1 = require("./dedup.js");
 const redact_js_1 = require("./redact.js");
@@ -260,23 +261,56 @@ function createMcpServer() {
             return { content: [{ type: "text", text: `Delete failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
         }
     });
-    // -- hicortex_lessons --
-    server.tool("hicortex_lessons", "Get actionable lessons learned from past sessions. Auto-generated insights about mistakes to avoid.", {
-        days: zod_1.z.coerce.number().optional().describe("Look back N days (default 7)"),
-        project: zod_1.z.string().optional().describe("Filter by project name"),
-    }, async ({ days, project }) => {
+    // -- hicortex_learnings (canonical) + hicortex_lessons (alias) --
+    const learningsHandler = async ({ days, project }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
         try {
             const lessons = storage.getLessons(db, days ?? 7, project);
             if (lessons.length === 0) {
-                return { content: [{ type: "text", text: "No lessons found for the specified period." }] };
+                return { content: [{ type: "text", text: "No Learnings found for the specified period." }] };
             }
             const text = lessons.map((l) => `- ${l.content.slice(0, 500)}`).join("\n");
             return { content: [{ type: "text", text }] };
         }
         catch (err) {
-            return { content: [{ type: "text", text: `Lessons fetch failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+            return { content: [{ type: "text", text: `Learnings fetch failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        }
+    };
+    const learningsSchema = {
+        days: zod_1.z.coerce.number().optional().describe("Look back N days (default 7)"),
+        project: zod_1.z.string().optional().describe("Filter by project name"),
+    };
+    server.tool("hicortex_learnings", "Get actionable Learnings from past sessions. Auto-generated insights about mistakes to avoid.", learningsSchema, learningsHandler);
+    server.tool("hicortex_lessons", "Get actionable Learnings from past sessions. (Alias for hicortex_learnings.)", learningsSchema, learningsHandler);
+    // -- hicortex_identity --
+    // Standing identity layer on-demand (the same data GET /identity returns and
+    // the SessionStart hook injects). Lets an agent re-read its identity after
+    // context compaction, or look up one named section, mid-session. Renders the
+    // same `### <Title>` section markdown the hook injects (shared pipeline in
+    // learnings-identity.ts → buildIdentityToolResult) so the agent sees one
+    // consistent shape. The handler is a thin wrapper over that pure function;
+    // tests exercise it directly (no MCP SDK plumbing re-implemented).
+    server.tool("hicortex_identity", "Fetch your standing identity — the hand-edited 'who you are + how you work' layer (personality, rules, preferences). Returns all sections or a specific one. Use this to re-read your identity after context compaction or to look up a specific rule. On multi-agent installs, pass `agent` to fetch a specific agent's scoped identity; omit for the global identity.", {
+        name: zod_1.z.string().optional().describe("Fetch a specific identity section by name (e.g. 'rules'). Omit for all sections."),
+        agent: zod_1.z.string().optional().describe("Fetch a specific agent's identity scope (for per-agent installs). Omit for global."),
+    }, async ({ name, agent }) => {
+        if (!db)
+            return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
+        try {
+            const identityDir = (0, node_path_1.join)(stateDir, "identity");
+            // Single pipeline shared with REST /identity + the SessionStart hook
+            // (#264 CRITICAL + WARNING-1 + WARNING-2). The pure function owns
+            // handleIdentityGet → injectMemorySection → renderIdentityBlock.
+            const result = (0, learnings_identity_js_1.buildIdentityToolResult)(identityDir, identityClients, identityAgents, {
+                name,
+                agent,
+                memoryInstructionsEnabled,
+            });
+            return { content: [{ type: "text", text: result.text }], isError: result.isError };
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `Identity fetch failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
         }
     });
     // -- hicortex_index --
@@ -606,8 +640,11 @@ async function startServer(options = {}) {
             llmLabel: llmConfig ? `${llmConfig.provider}/${llmConfig.model}` : "not configured",
         }));
     });
-    // REST /lessons — return lessons + memory index for client CLAUDE.md injection
-    app.get("/lessons", (_req, res) => {
+    // REST /learnings (canonical, #264) + /lessons (alias) — return lessons +
+    // memory index for client CLAUDE.md injection. Both routes share ONE handler
+    // so the alias can never drift from the canonical shape. The legacy name is
+    // kept indefinitely (existing SessionStart hooks literally fetch /lessons).
+    const learningsIndexHandler = (_req, res) => {
         if (!db) {
             res.status(503).json({ error: "Server not initialized" });
             return;
@@ -639,9 +676,11 @@ async function startServer(options = {}) {
             });
         }
         catch (err) {
-            (0, health_js_1.logAndSendInternalError)(res, "lessons", err);
+            (0, health_js_1.logAndSendInternalError)(res, "learnings", err);
         }
-    });
+    };
+    app.get("/learnings", learningsIndexHandler);
+    app.get("/lessons", learningsIndexHandler); // #264 backcompat alias
     // REST /ingest — accept pre-distilled memories from remote clients
     app.post("/ingest", async (req, res) => {
         if (!db) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Persistent agent identity for AI agents — a hand-edited identity layer, nightly-distilled experience, and lessons injected every session, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {