@gamaze/hicortex 0.20.4 → 0.20.5

package/dist/index.js

@@ -1038,7 +1038,7 @@ exports.default = {
         // -----------------------------------------------------------------------
         api.registerTool((_ctx) => ({
             name: "hicortex_search",
-            description: "Search long-term memory using semantic similarity. Returns the most relevant memories from past sessions.",
+            description: "Search shared long-term memory (all agents, all sessions). CALL THIS BEFORE assuming, guessing, or asking the user about anything that may have come up before: prior decisions, preferences, project facts, people, hardware, past incidents. If you are about to write 'I don't have information about…', search first.",
             parameters: {
                 type: "object",
                 properties: {
@@ -1068,7 +1068,7 @@ exports.default = {
         }), { name: "hicortex_search" });
         api.registerTool((_ctx) => ({
             name: "hicortex_get",
-            description: "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so fetch entries that could change your action — not every shown one. When the memory shapes your answer, cite it as given in the response — mark a fetched memory `FETCHED` and a one-line entry cited unread `SNIPPET`; don't pass SNIPPET off as established.",
+            description: "Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so fetch entries that could change your action — not every shown one. When the memory shapes your answer, cite it to the user (id + date + origin agent) — mark a fetched memory `FETCHED` and a one-line entry cited unread `SNIPPET`; don't pass SNIPPET off as established.",
             parameters: {
                 type: "object",
                 properties: {
@@ -1101,7 +1101,7 @@ exports.default = {
         }), { name: "hicortex_get" });
         api.registerTool((_ctx) => ({
             name: "hicortex_recent",
-            description: "Get recent memories, optionally filtered by project. Queryless recall of the latest memories by project, ranked by importance. Useful to catch up on what happened recently.",
+            description: "Get recent memories, optionally filtered by project. CALL THIS AT THE START of substantive work on a project to catch up on its latest state — cheaper than asking the user what happened.",
             parameters: {
                 type: "object",
                 properties: {
@@ -1130,7 +1130,7 @@ exports.default = {
         }), { name: "hicortex_recent" });
         api.registerTool((_ctx) => ({
             name: "hicortex_ingest",
-            description: "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings.",
+            description: "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings. Capture is automatic (nightly) — use this ONLY for explicitly requested learnings, never routine content.",
             parameters: {
                 type: "object",
                 properties: {
@@ -1165,7 +1165,7 @@ exports.default = {
         }), { name: "hicortex_ingest" });
         api.registerTool((_ctx) => ({
             name: "hicortex_lessons",
-            description: "Get actionable Learnings distilled from past sessions. Auto-generated insights about mistakes to avoid.",
+            description: "Get actionable Learnings — auto-generated insights about mistakes to avoid. CALL THIS before retrying an approach that failed before, or when picking up work where past problems may have been recorded.",
             parameters: {
                 type: "object",
                 properties: {
@@ -1191,7 +1191,7 @@ exports.default = {
         }), { name: "hicortex_lessons" });
         api.registerTool((_ctx) => ({
             name: "hicortex_index",
-            description: "Get the knowledge domain index — shows what topics and projects are stored in memory, grouped by domain.",
+            description: "Get the knowledge domain index — shows what topics and projects are stored in memory, grouped by domain. Call before a broad search to see which knowledge domains exist, or when unsure what the memory covers.",
             parameters: {
                 type: "object",
                 properties: {},
@@ -1210,7 +1210,7 @@ exports.default = {
         }), { name: "hicortex_index" });
         api.registerTool((_ctx) => ({
             name: "hicortex_graph",
-            description: "Query the memory knowledge graph — find connected memories, hub nodes, or paths between memories.",
+            description: "Query the memory knowledge graph — find connected memories, hub nodes, or paths between memories. Use it to explore memories connected to one you just fetched, or to find hub memories in a domain.",
             parameters: {
                 type: "object",
                 properties: {

package/dist/init.d.ts

@@ -7,13 +7,16 @@
  *   3. OC plugin installed (~/.openclaw/openclaw.json)
  *   4. CC MCP already registered (~/.claude/settings.json)
  *   5. Hermes present (~/.hermes) / Pi present (~/.pi/agent) /
- *      opencode present (~/.config/opencode or ~/.local/share/opencode)
+ *      opencode present (~/.config/opencode or ~/.local/share/opencode) /
+ *      Claude Desktop present (macOS ~/Library/Application Support/Claude,
+ *      Windows %APPDATA%\Claude)
  *   6. Existing DB (~/.hicortex/ or ~/.openclaw/data/)
  *
  * Actions:
  *   - Install persistent daemon (launchd/systemd)
  *   - Register MCP server in CC settings
  *   - Install CC SessionStart hook for query-time lessons
+ *   - Offer the Claude Desktop stdio MCP entry (opt-in, #381)
  *   - Strip old static CLAUDE.md learnings block if present
  *   - Remove legacy pre-0.10 CC commands (/learn, /hicortex-activate) if present
  */

package/dist/init.js

@@ -8,13 +8,16 @@
  *   3. OC plugin installed (~/.openclaw/openclaw.json)
  *   4. CC MCP already registered (~/.claude/settings.json)
  *   5. Hermes present (~/.hermes) / Pi present (~/.pi/agent) /
- *      opencode present (~/.config/opencode or ~/.local/share/opencode)
+ *      opencode present (~/.config/opencode or ~/.local/share/opencode) /
+ *      Claude Desktop present (macOS ~/Library/Application Support/Claude,
+ *      Windows %APPDATA%\Claude)
  *   6. Existing DB (~/.hicortex/ or ~/.openclaw/data/)
  *
  * Actions:
  *   - Install persistent daemon (launchd/systemd)
  *   - Register MCP server in CC settings
  *   - Install CC SessionStart hook for query-time lessons
+ *   - Offer the Claude Desktop stdio MCP entry (opt-in, #381)
  *   - Strip old static CLAUDE.md learnings block if present
  *   - Remove legacy pre-0.10 CC commands (/learn, /hicortex-activate) if present
  */
@@ -59,6 +62,7 @@ const node_child_process_1 = require("node:child_process");
 const node_readline_1 = require("node:readline");
 const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
+const claude_desktop_js_1 = require("./claude-desktop.js");
 const config_read_js_1 = require("./config-read.js");
 const identity_store_js_1 = require("./identity-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
@@ -99,6 +103,7 @@ async function detect() {
         hermesFound: false,
         piFound: false,
         opencodeFound: false,
+        desktopFound: false,
         existingDb: false,
     };
     // Check local server. /health/detail carries the diagnostics (memories,
@@ -143,6 +148,15 @@ async function detect() {
     // Check opencode (~/.config/opencode or ~/.local/share/opencode — its
     // global plugins dir / session store; it auto-loads ~/.config/opencode/plugins/)
     result.opencodeFound = (0, node_fs_1.existsSync)(OPENCODE_CONFIG_DIR) || (0, node_fs_1.existsSync)(OPENCODE_DATA_DIR);
+    // Check Claude Desktop (#381 — macOS ~/Library/Application Support/Claude,
+    // Windows %APPDATA%\Claude; Linux has no Desktop build → null → skip
+    // silently). Detection is the DIRECTORY: the config file may not exist
+    // yet, and creating it fresh is exactly what the Desktop setup step does.
+    const desktopDir = (0, claude_desktop_js_1.desktopConfigDir)();
+    if (desktopDir && (0, node_fs_1.existsSync)(desktopDir)) {
+        result.desktopFound = true;
+        result.desktopDir = desktopDir;
+    }
     // Check OC plugin
     try {
         const raw = (0, node_fs_1.readFileSync)(OC_CONFIG, "utf-8");
@@ -399,6 +413,84 @@ function setupOpencode() {
     console.log("  → Restart opencode sessions to load the plugin (recall, identity, lessons, 9 tools)");
 }
 // ---------------------------------------------------------------------------
+// Claude Desktop setup
+// ---------------------------------------------------------------------------
+/**
+ * Offer to add the Hicortex stdio MCP entry to Claude Desktop's
+ * claude_desktop_config.json (#381) — Desktop's only stdio MCP route, and a
+ * file owned by ANOTHER app, which is why this step is OPT-IN (default No,
+ * its own prompt after the batch actions) while the other harness setups
+ * just run. The write itself is merge-safe + atomic + backed up (see
+ * claude-desktop.ts); a malformed existing config is refused UNTOUCHED with
+ * the hand-fix snippet printed. The entry is the `hicortex mcp` bridge with
+ * an ABSOLUTE npx path (GUI apps don't inherit the shell PATH — a bare
+ * "npx" is the #1 Desktop failure mode); remote targets carry the server
+ * URL + token in env, loopback needs none (the bridge autostarts the daemon
+ * and loopback bypasses auth). Never throws — every failure path is a
+ * printed warning and init continues. No-ops when Desktop is not installed.
+ */
+async function setupClaudeDesktop(serverUrl, authToken) {
+    const dir = (0, claude_desktop_js_1.desktopConfigDir)();
+    if (!dir || !(0, node_fs_1.existsSync)(dir))
+        return; // no Claude Desktop on this machine
+    // Same non-interactive guard as persistLlmConfig: a piped/scripted init
+    // must not auto-apply an opt-in choice — a readline EOF would read as "".
+    if (!process.stdin.isTTY) {
+        console.log("  ⚠ Non-interactive stdin — Claude Desktop setup skipped; re-run `hicortex init` interactively to add it.");
+        return;
+    }
+    const answer = (await ask("Add the Hicortex MCP server to Claude Desktop? [y/N] ")).toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+        console.log("  → Claude Desktop left unchanged");
+        return;
+    }
+    const configPath = (0, node_path_1.join)(dir, "claude_desktop_config.json");
+    // Absolute npx, rejecting npm's ephemeral /_npx/ cache (#176). Null → we
+    // cannot write a WORKING entry, so we print it and write nothing.
+    const npxPath = (0, claude_desktop_js_1.resolveDesktopNpxPath)();
+    if (!npxPath) {
+        console.log("  ⚠ Could not locate a durable npx on this machine — nothing written.");
+        printDesktopManualEntry(configPath, "<path-to-npx>", serverUrl, authToken);
+        return;
+    }
+    // Remote targets carry the connection in env; loopback needs none.
+    const env = (0, claude_desktop_js_1.isLocalServerUrl)(serverUrl)
+        ? undefined
+        : { HICORTEX_SERVER_URL: serverUrl, ...(authToken ? { HICORTEX_AUTH_TOKEN: authToken } : {}) };
+    // getPackageSpec() reads the config.json this run has already written (or
+    // an earlier run's), so the Desktop entry honours updateChannel exactly
+    // like the daemon/timer ExecStart does.
+    const entry = (0, claude_desktop_js_1.buildDesktopServerEntry)(npxPath, getPackageSpec(), env);
+    const result = (0, claude_desktop_js_1.writeDesktopServerConfig)(configPath, entry);
+    if (result.status === "written") {
+        console.log(`  ✓ Added the Hicortex MCP server to Claude Desktop (${configPath})`);
+        if (result.backupPath) {
+            console.log(`    Backup of the previous config: ${result.backupPath}`);
+        }
+        console.log("  → Fully quit and restart Claude Desktop to load it (Cmd+Q on macOS).");
+    }
+    else if (result.status === "refused") {
+        console.log(`  ✗ ${result.reason}`);
+        printDesktopManualEntry(configPath, npxPath, serverUrl, authToken);
+    }
+    else {
+        console.log(`  ⚠ Claude Desktop config write failed: ${result.reason} — nothing was changed.`);
+    }
+}
+/**
+ * The hand-fix snippet for the two paths where init writes nothing (no
+ * durable npx found / existing config refused): the ready-to-paste entry and
+ * the file it goes in, so the user can finish by hand in one paste.
+ */
+function printDesktopManualEntry(configPath, command, serverUrl, authToken) {
+    const env = (0, claude_desktop_js_1.isLocalServerUrl)(serverUrl)
+        ? undefined
+        : { HICORTEX_SERVER_URL: serverUrl, ...(authToken ? { HICORTEX_AUTH_TOKEN: authToken } : {}) };
+    const entry = (0, claude_desktop_js_1.buildDesktopServerEntry)(command, getPackageSpec(), env);
+    console.log(`    Add it by hand in ${configPath}, under "mcpServers":`);
+    console.log(`    "hicortex": ${JSON.stringify(entry)}`);
+}
+// ---------------------------------------------------------------------------
 // Hermes setup
 // ---------------------------------------------------------------------------
 /**
@@ -1662,6 +1754,8 @@ async function runInit(options = {}) {
         console.log(`  • Pi found at ${PI_AGENT_DIR}`);
     if (d.opencodeFound)
         console.log(`  • opencode found at ${OPENCODE_CONFIG_DIR}`);
+    if (d.desktopFound)
+        console.log(`  • Claude Desktop found at ${d.desktopDir}`);
     if (d.ccMcpRegistered)
         console.log("  • CC MCP already registered");
     if (d.existingDb)
@@ -1822,6 +1916,10 @@ async function runInit(options = {}) {
     if (d.opencodeFound) {
         setupOpencode();
     }
+    // Offer the Claude Desktop MCP entry (opt-in — Desktop's config file
+    // belongs to another app, so it gets its own prompt after the batch
+    // actions above). No-ops when Desktop is not installed.
+    await setupClaudeDesktop(serverUrl, authToken);
     // Install CC SessionStart hook for query-time lesson injection.
     // Lessons are now fetched live at session start — no static CLAUDE.md block needed.
     installSessionStartHook();
@@ -2014,6 +2112,10 @@ async function runClientInit(serverUrl, agentName) {
         console.log("\nopencode detected — installing plugin...");
         setupOpencode();
     }
+    // Step 8d: Offer the Claude Desktop MCP entry (opt-in; no-ops when Desktop
+    // is not installed). The client config was written in Step 3, so the
+    // entry's package spec already honours updateChannel.
+    await setupClaudeDesktop(serverUrl, authToken);
     console.log("\n✓ Hicortex client setup complete!\n");
     // Telemetry disclosure at install time (informed consent, best practice):
     // opt-out telemetry is only acceptable if the user is TOLD about it.

package/dist/llm.d.ts

@@ -23,6 +23,10 @@ export interface LlmConfig {
     provider: string;
     /** Max output tokens for all phases (one model). Default 8192. */
     maxTokens?: number;
+    /** Max output tokens for the CLASSIFY tier only — the short JSON-verdict
+     *  calls (correction/supersession verdicts, rewrite contracts, type + tag
+     *  classification). Default 1024. See HicortexConfig.classifyMaxTokens (#391). */
+    classifyMaxTokens?: number;
     /** Toggle thinking on the openai-compat path for all phases. Absent = no kwarg sent.
      *  LOCAL-endpoint only (ollama / mlx-lm gateway); see HicortexConfig.enableThinking. */
     enableThinking?: boolean;
@@ -82,18 +86,19 @@ export declare function resolveExplicitLlmConfig(overrides?: {
 export declare const resolveLlmConfigForCC: typeof resolveExplicitLlmConfig;
 /**
  * Validate + copy the tuning keys (#220: maxTokens + enableThinking + numCtx +
- * ollama flush) from the saved disk config onto a runtime LlmConfig. Called by
- * BOTH LlmConfig construction sites — the daemon in mcp-server.ts (runs
- * distill) AND resolveSavedLlmConfig below (the nightly runs reflect +
- * classify) — so every process honors the keys, and a future site calling this
- * inherits them by construction.
+ * ollama flush; #391: classifyMaxTokens) from the saved disk config onto a
+ * runtime LlmConfig. Called by BOTH LlmConfig construction sites — the daemon
+ * in mcp-server.ts (runs distill) AND resolveSavedLlmConfig below (the nightly
+ * runs reflect + classify) — so every process honors the keys, and a future
+ * site calling this inherits them by construction.
  *
- * All keys are optional; absent = call-site defaults (maxTokens 8192, numCtx
- * 8192, thinking kwarg omitted, flush off). Wrong-typed values warn and are
- * dropped (readPositiveConfig / readStrictBoolean / readNonNegativeConfig) —
- * notably a JSON slip `"enableThinking": "false"` (string) is rejected rather
- * than coerced to truthy thinking-on, which would silently invert the fix this
- * key exists to apply.
+ * All keys are optional; absent = call-site defaults (maxTokens 8192,
+ * classifyMaxTokens 1024, numCtx 8192, thinking kwarg omitted, flush off).
+ * Wrong-typed values warn and are dropped (readPositiveConfig /
+ * readStrictBoolean / readNonNegativeConfig) — notably a JSON slip
+ * `"enableThinking": "false"` (string) is rejected rather than coerced to
+ * truthy thinking-on, which would silently invert the fix this key exists to
+ * apply.
  */
 export declare function applyTierTuningOverlay(llmConfig: LlmConfig, savedConfig: Record<string, unknown> | null | undefined): void;
 /**
@@ -213,8 +218,9 @@ export declare class LlmClient {
      */
     completeDistill(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**
-     * Classification-tier completion (memory tag classification). One model
-     * serves all phases (#231) — thin wrapper kept for call-site readability.
+     * Classification-tier completion (verdicts + tag/type classification). One
+     * model serves all phases (#231) — thin wrapper kept for call-site
+     * readability, but the tier keeps its OWN output ceiling (#391).
      */
     completeClassify(prompt: string, maxTokens?: number): Promise<LlmResult>;
     /**

package/dist/llm.js

@@ -87,18 +87,19 @@ function resolveExplicitLlmConfig(overrides) {
 exports.resolveLlmConfigForCC = resolveExplicitLlmConfig;
 /**
  * Validate + copy the tuning keys (#220: maxTokens + enableThinking + numCtx +
- * ollama flush) from the saved disk config onto a runtime LlmConfig. Called by
- * BOTH LlmConfig construction sites — the daemon in mcp-server.ts (runs
- * distill) AND resolveSavedLlmConfig below (the nightly runs reflect +
- * classify) — so every process honors the keys, and a future site calling this
- * inherits them by construction.
+ * ollama flush; #391: classifyMaxTokens) from the saved disk config onto a
+ * runtime LlmConfig. Called by BOTH LlmConfig construction sites — the daemon
+ * in mcp-server.ts (runs distill) AND resolveSavedLlmConfig below (the nightly
+ * runs reflect + classify) — so every process honors the keys, and a future
+ * site calling this inherits them by construction.
  *
- * All keys are optional; absent = call-site defaults (maxTokens 8192, numCtx
- * 8192, thinking kwarg omitted, flush off). Wrong-typed values warn and are
- * dropped (readPositiveConfig / readStrictBoolean / readNonNegativeConfig) —
- * notably a JSON slip `"enableThinking": "false"` (string) is rejected rather
- * than coerced to truthy thinking-on, which would silently invert the fix this
- * key exists to apply.
+ * All keys are optional; absent = call-site defaults (maxTokens 8192,
+ * classifyMaxTokens 1024, numCtx 8192, thinking kwarg omitted, flush off).
+ * Wrong-typed values warn and are dropped (readPositiveConfig /
+ * readStrictBoolean / readNonNegativeConfig) — notably a JSON slip
+ * `"enableThinking": "false"` (string) is rejected rather than coerced to
+ * truthy thinking-on, which would silently invert the fix this key exists to
+ * apply.
  */
 function applyTierTuningOverlay(llmConfig, savedConfig) {
     if (!savedConfig)
@@ -106,6 +107,9 @@ function applyTierTuningOverlay(llmConfig, savedConfig) {
     if (savedConfig.maxTokens !== undefined) {
         llmConfig.maxTokens = (0, config_read_js_1.readPositiveConfig)(savedConfig, "maxTokens", 8192);
     }
+    if (savedConfig.classifyMaxTokens !== undefined) {
+        llmConfig.classifyMaxTokens = (0, config_read_js_1.readPositiveConfig)(savedConfig, "classifyMaxTokens", 1024);
+    }
     const thinking = (0, config_read_js_1.readStrictBoolean)(savedConfig, "enableThinking");
     if (thinking !== undefined) {
         llmConfig.enableThinking = thinking;
@@ -437,11 +441,18 @@ class LlmClient {
         return this.complete(this.config.model, prompt, tokens, this.config.timeoutMs ?? 900_000);
     }
     /**
-     * Classification-tier completion (memory tag classification). One model
-     * serves all phases (#231) — thin wrapper kept for call-site readability.
+     * Classification-tier completion (verdicts + tag/type classification). One
+     * model serves all phases (#231) — thin wrapper kept for call-site
+     * readability, but the tier keeps its OWN output ceiling (#391).
      */
     async completeClassify(prompt, maxTokens) {
-        const tokens = maxTokens ?? this.config.maxTokens ?? 8192;
+        // #391: classify-tier ceiling — the call sites' old hardcoded caps
+        // (64/32/20, tuned for a local non-reasoning model) starved reasoning
+        // models whose internal thinking consumed the whole budget, leaving
+        // verdicts empty. Deliberately NOT this.config.maxTokens: that knob
+        // governs the heavy phases; this tier has its own (a ceiling, not a
+        // target — generation still stops at the model's natural end).
+        const tokens = maxTokens ?? this.config.classifyMaxTokens ?? 1024;
         return this.complete(this.config.model, prompt, tokens, this.config.timeoutMs ?? 900_000);
     }
     /**

package/dist/mcp-server.d.ts

@@ -11,6 +11,7 @@
  *   POST /messages   — message endpoint for MCP clients
  */
 import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { MemorySearchResult } from "./types.js";
 /**
  * Resolve the /distill probe gate (#337): true when the endpoint recently
@@ -28,6 +29,11 @@ export declare function resolveDistillProbeGate(llm: {
     baseUrl: string;
     probeTtlMs?: number;
 }): Promise<boolean>;
+/**
+ * Build the McpServer with all Hicortex tools, one per /sse connection.
+ * Exported for tests (protocol-level initialize-result checks, #383).
+ */
+export declare function createMcpServer(): McpServer;
 /**
  * Resolve the request body-size limit in MB (#7, #328 item 2b). Pure —
  * exported for tests. Precedence: HICORTEX_DISTILL_BODY_LIMIT_MB env >

package/dist/mcp-server.js

@@ -49,6 +49,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveDistillProbeGate = resolveDistillProbeGate;
+exports.createMcpServer = createMcpServer;
 exports.resolveBodyLimitMb = resolveBodyLimitMb;
 exports.makeBodyLimitErrorHandler = makeBodyLimitErrorHandler;
 exports.makeContentLengthGate = makeContentLengthGate;
@@ -84,6 +85,7 @@ 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 reconsolidation_js_1 = require("./reconsolidation.js");
 const redact_js_1 = require("./redact.js");
 const init_js_1 = require("./init.js");
 // ---------------------------------------------------------------------------
@@ -163,11 +165,18 @@ catch { /* fallback */ }
 // ---------------------------------------------------------------------------
 // MCP Server setup
 // ---------------------------------------------------------------------------
+/**
+ * Build the McpServer with all Hicortex tools, one per /sse connection.
+ * Exported for tests (protocol-level initialize-result checks, #383).
+ */
 function createMcpServer() {
-    const server = new mcp_js_1.McpServer({
-        name: "hicortex",
-        version: VERSION,
-    });
+    // #383: the initialize-result instructions are the only product-owned
+    // guidance passive MCP clients (e.g. Claude Desktop — no hooks, no injected
+    // sections) ever see: the MCP-native SessionStart. Same off-switch as the
+    // identity `memory` section (config `memoryInstructions: false`); the
+    // module var is read at call time, so per-connection construction
+    // preserves the boot-time gate.
+    const server = new mcp_js_1.McpServer({ name: "hicortex", version: VERSION }, { instructions: (0, memory_instructions_js_1.resolveMcpInstructions)(memoryInstructionsEnabled) });
     // -- hicortex_search --
     server.tool("hicortex_search", "Search shared long-term memory (all agents, all sessions). CALL THIS BEFORE assuming, guessing, or asking the user about anything that may have come up before: prior decisions, preferences, project facts, people, hardware, past incidents. If you are about to write 'I don't have information about…', search first.", {
         query: zod_1.z.string().describe("Search query text"),
@@ -218,14 +227,30 @@ function createMcpServer() {
         }
     });
     // -- hicortex_ingest --
-    server.tool("hicortex_ingest", "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings.", {
+    server.tool("hicortex_ingest", "Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings. Capture is automatic (nightly) — use this ONLY for explicitly requested learnings, never routine content.", {
         content: zod_1.z.string().describe("Memory content to store"),
         project: zod_1.z.string().optional().describe("Project this memory belongs to"),
         memory_type: zod_1.z.enum(["knowledge", "experience", "decisions", "learnings", "fact", "episode", "decision", "lesson"]).optional().describe("Type of memory (default: Experience). Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term)."),
-    }, async ({ content, project, memory_type }) => {
+        corrects: zod_1.z.string().optional().describe("ID (8-char prefix or full UUID) of an existing memory this one CORRECTS — records a corrected_by link and retracts the old memory (deterministic, no LLM). Mutually exclusive with supersedes."),
+        supersedes: zod_1.z.string().optional().describe("ID (8-char prefix or full UUID) of an existing memory this one SUPERSEDES — records a superseded_by link and marks the old memory superseded (deterministic, no LLM). Mutually exclusive with corrects."),
+    }, async ({ content, project, memory_type, corrects, supersedes }) => {
         if (!db)
             return { content: [{ type: "text", text: "Hicortex not initialized" }], isError: true };
         try {
+            // #384 explicit mark — validated BEFORE storing (an unknown/ambiguous
+            // target fails the whole call; nothing is written).
+            if (corrects !== undefined && supersedes !== undefined) {
+                return { content: [{ type: "text", text: "Provide at most one of 'corrects' or 'supersedes'" }], isError: true };
+            }
+            const rawMark = corrects !== undefined ? corrects : supersedes;
+            let explicitMark;
+            if (rawMark !== undefined) {
+                explicitMark = { kind: corrects !== undefined ? "corrects" : "supersedes", target: rawMark };
+                const check = (0, reconsolidation_js_1.checkExplicitMarkTarget)(db, explicitMark);
+                if (!check.ok) {
+                    return { content: [{ type: "text", text: `Ingest failed: ${check.error}` }], isError: true };
+                }
+            }
             const embedding = await (0, embedder_js_1.embed)(content);
             const id = storage.insertMemory(db, content, embedding, {
                 sourceAgent: "claude-code/manual",
@@ -233,7 +258,9 @@ function createMcpServer() {
                 // Normalize legacy raw enum to the canonical term the DB stores.
                 memoryType: memory_type ? (0, type_labels_js_1.normalizeMemoryType)(memory_type) : "experience",
             });
-            return { content: [{ type: "text", text: `Memory stored (id: ${id.slice(0, 8)})` }] };
+            if (explicitMark)
+                (0, reconsolidation_js_1.applyExplicitMark)(db, id, explicitMark);
+            return { content: [{ type: "text", text: `Memory stored (id: ${id.slice(0, 8)})${explicitMark ? ` — marked as ${explicitMark.kind === "corrects" ? "correcting" : "superseding"} ${explicitMark.target}` : ""}` }] };
         }
         catch (err) {
             return { content: [{ type: "text", text: `Ingest failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
@@ -253,6 +280,12 @@ function createMcpServer() {
             const fullId = resolveMemoryId(db, id);
             if (!fullId)
                 return { content: [{ type: "text", text: `Memory not found: ${id}` }], isError: true };
+            // #384: absorbed memories are invisible evidence — an update would
+            // re-embed and resurrect them. Refuse; roll back the rewrite first.
+            const target = storage.getMemory(db, fullId);
+            if (target?.status === "absorbed") {
+                return { content: [{ type: "text", text: `Memory ${fullId.slice(0, 8)} is absorbed (folded into a corrected memory) — roll back the absorbing rewrite first (hicortex history --rollback)` }], isError: true };
+            }
             const fields = {};
             if (content !== undefined)
                 fields.content = content;
@@ -318,8 +351,8 @@ function createMcpServer() {
         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);
+    server.tool("hicortex_learnings", "Get actionable Learnings — auto-generated insights about mistakes to avoid. CALL THIS before retrying an approach that failed before, or when picking up work where past problems may have been recorded.", learningsSchema, learningsHandler);
+    server.tool("hicortex_lessons", "Get actionable Learnings from past sessions — call it before retrying an approach that failed before. (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
@@ -351,7 +384,7 @@ function createMcpServer() {
         }
     });
     // -- hicortex_index --
-    server.tool("hicortex_index", "Get the knowledge domain index — shows what topics and projects are stored in memory, grouped by domain.", {}, async () => {
+    server.tool("hicortex_index", "Get the knowledge domain index — shows what topics and projects are stored in memory, grouped by domain. Call before a broad search to see which knowledge domains exist, or when unsure what the memory covers.", {}, async () => {
         const state = (0, state_js_1.loadState)(stateDir);
         const moduleIndex = state.moduleIndex;
         if (moduleIndex && moduleIndex.domains.length > 0) {
@@ -378,7 +411,7 @@ function createMcpServer() {
         return { content: [{ type: "text", text }] };
     });
     // -- hicortex_graph --
-    server.tool("hicortex_graph", "Query the memory knowledge graph — find connected memories, hub nodes, or paths between memories.", {
+    server.tool("hicortex_graph", "Query the memory knowledge graph — find connected memories, hub nodes, or paths between memories. Use it to explore memories connected to one you just fetched, or to find hub memories in a domain.", {
         operation: zod_1.z.enum(["neighbors", "hubs", "path"]).describe("Graph operation to perform"),
         id: zod_1.z.string().optional().describe("Memory ID (required for neighbors and path operations)"),
         target_id: zod_1.z.string().optional().describe("Target memory ID (required for path operation)"),
@@ -885,7 +918,7 @@ async function startServer(options = {}) {
             res.status(503).json({ error: "Server not initialized" });
             return;
         }
-        const { content, source_agent, source_agent_id, source_domain, project, memory_type, privacy, source_session, session_date } = req.body ?? {};
+        const { content, source_agent, source_agent_id, source_domain, project, memory_type, privacy, source_session, session_date, corrects, supersedes } = req.body ?? {};
         if (!content || typeof content !== "string") {
             res.status(400).json({ error: "Missing or invalid 'content' field" });
             return;
@@ -899,6 +932,28 @@ async function startServer(options = {}) {
         // canonical term the DB stores (knowledge/experience/decisions/learnings).
         // Canonical values pass through unchanged.
         const normalizedType = memory_type ? (0, type_labels_js_1.normalizeMemoryType)(memory_type) : memory_type;
+        // #384 explicit write-time marking: `corrects` XOR `supersedes`, a single
+        // memory id reference. Validated BEFORE anything is written — an unknown
+        // or ambiguous target fails the WHOLE request (nothing is stored with a
+        // half-applied mark). Deterministic link + status, zero LLM.
+        if (corrects !== undefined && supersedes !== undefined) {
+            res.status(400).json({ error: "Provide at most one of 'corrects' or 'supersedes'" });
+            return;
+        }
+        let explicitMark;
+        const rawMarkValue = corrects !== undefined ? corrects : supersedes;
+        if (rawMarkValue !== undefined) {
+            if (typeof rawMarkValue !== "string" || !rawMarkValue) {
+                res.status(400).json({ error: `'${corrects !== undefined ? "corrects" : "supersedes"}' must be a memory id (8-char prefix or full UUID)` });
+                return;
+            }
+            explicitMark = { kind: corrects !== undefined ? "corrects" : "supersedes", target: rawMarkValue };
+            const check = (0, reconsolidation_js_1.checkExplicitMarkTarget)(db, explicitMark);
+            if (!check.ok) {
+                res.status(check.httpStatus).json({ error: check.error });
+                return;
+            }
+        }
         // Dedup by source_session (idempotent — skip if already ingested)
         if (source_session) {
             const existing = db.prepare("SELECT COUNT(*) as cnt FROM memories WHERE source_session = ?").get(source_session);
@@ -922,7 +977,13 @@ async function startServer(options = {}) {
                 privacy: typeof privacy === "string" ? privacy : null,
                 createdAt: session_date ? new Date(session_date).toISOString() : undefined,
             });
-            res.status(201).json({ id, message: "Memory ingested" });
+            if (explicitMark)
+                (0, reconsolidation_js_1.applyExplicitMark)(db, id, explicitMark);
+            res.status(201).json({
+                id,
+                message: "Memory ingested",
+                ...(explicitMark ? { marked: explicitMark.kind } : {}),
+            });
         }
         catch (err) {
             res.status(500).json({ error: "Ingestion failed" });
@@ -1337,6 +1398,16 @@ async function startServer(options = {}) {
             res.status(404).json({ error: `Memory not found: ${id}` });
             return;
         }
+        // #384: an absorbed memory is invisible evidence — updating its content
+        // would re-embed and resurrect a row the store deliberately folded into a
+        // corrected target. Roll back the absorbing rewrite first.
+        const target = storage.getMemory(db, fullId);
+        if (target?.status === "absorbed") {
+            res.status(409).json({
+                error: `Memory ${fullId.slice(0, 8)} is absorbed (folded into a corrected memory) — roll back the absorbing rewrite first (hicortex history --rollback)`,
+            });
+            return;
+        }
         const fields = {};
         if (content !== undefined)
             fields.content = content;

package/dist/mcp-stdio.js

@@ -261,7 +261,12 @@ async function runMcpStdio(options = {}) {
     }
     // Downstream: a low-level Server over stdio advertising exactly what the
     // daemon offers (tools). Ping is auto-answered by the Protocol base.
-    const server = new index_js_1.Server({ name: "hicortex", version: VERSION }, { capabilities: { tools: {} } });
+    // #383: forward the DAEMON's initialize-result instructions verbatim — the
+    // daemon owns the text and the memoryInstructions gate, so the two surfaces
+    // cannot diverge and no config read is duplicated in the bridge (a
+    // pre-#383 remote daemon simply has none to forward; undefined omits the
+    // field from the bridge's own initialize result).
+    const server = new index_js_1.Server({ name: "hicortex", version: VERSION }, { capabilities: { tools: {} }, instructions: client.getInstructions() });
     // The proxy core — the SDK's documented proxy pattern. Forward the two
     // tools requests and pass extra.signal through so a downstream
     // notifications/cancelled aborts the upstream call (which emits the

package/dist/memory-instructions.d.ts

@@ -18,11 +18,29 @@
  * The section name is RESERVED: PUT /identity rejects it, and the synthetic
  * text overrides any user file of the same name (enforced means enforced).
  * Off-switch: config `memoryInstructions: false`.
+ *
+ * Since #383 the file is also the source for the MCP standing instructions
+ * (the initialize-result `instructions` field) — the same policy, shaped for
+ * passive MCP clients, behind the same off-switch.
  */
 export declare const MEMORY_SECTION_NAME = "memory";
 /** The product-authored instruction text. Keep compact (~120 tokens): it is
  *  injected once per session into every agent on the fleet. */
 export declare function renderMemoryInstructions(): string;
+/** The MCP-client-shaped sibling (#383): standing instructions for the MCP
+ *  `instructions` field in the initialize result — the MCP-native
+ *  SessionStart. Passive MCP clients (Claude Desktop etc.) run no hooks and
+ *  see no injected sections, so this field is the ONLY product-owned
+ *  guidance their model ever receives; the 2026-09-10 field test showed the
+ *  memory going entirely unused without it. Compact by construction (same
+ *  ~120-token budget as the identity sibling) and shares the two policy
+ *  sentences verbatim — one source, two surfaces. Drops the hook-only
+ *  surfaces (the `## Memory recall (auto)` index) those clients never see. */
+export declare function renderMcpInstructions(): string;
+/** The config gate as a pure function (#383): enabled → the rendered text,
+ *  disabled → undefined (the SDK omits the field from the initialize result,
+ *  so `memoryInstructions: false` silences BOTH surfaces with one switch). */
+export declare function resolveMcpInstructions(enabled: boolean): string | undefined;
 /** True for the reserved product section name (case-insensitive guard —
  *  section names are lowercase by allowlist, but be safe). */
 export declare function isReservedSectionName(name: unknown): boolean;