@gamaze/hicortex 0.14.3 → 0.14.4

package/dist/mcp-server.js

@@ -65,6 +65,7 @@ const viz_js_1 = require("./viz.js");
 const context_store_js_1 = require("./context-store.js");
 const retrieval = __importStar(require("./retrieval.js"));
 const recall_registry_js_1 = require("./recall-registry.js");
+const memory_instructions_js_1 = require("./memory-instructions.js");
 const recall_index_js_1 = require("./recall-index.js");
 const seed_lesson_js_1 = require("./seed-lesson.js");
 const distiller_js_1 = require("./distiller.js");
@@ -90,6 +91,8 @@ let contextAgents = {};
 // Pushed-recall dedup registry (#192) + options; configured at boot.
 let recallRegistry = new recall_registry_js_1.SessionRecallRegistry();
 let recallIndexOptions = {};
+// Product-owned memory instructions (#192): on unless config says false.
+let memoryInstructionsEnabled = true;
 // Cache detectChunkSize results keyed by "<provider>/<model>@<baseUrl>" so we
 // probe each endpoint once per server boot rather than once per /distill request.
 const chunkSizeCache = new Map();
@@ -493,6 +496,7 @@ async function startServer(options = {}) {
         maxItems: savedConfig?.recallMaxItems,
         minPromptLength: savedConfig?.recallMinPromptChars,
     };
+    memoryInstructionsEnabled = savedConfig?.memoryInstructions !== false;
     if (resolvedAgents.dropped.length > 0) {
         console.warn(`[hicortex] Ignoring invalid contextAgents entries: ${resolvedAgents.dropped.join(", ")} ` +
             `(keys must match ^[a-z0-9][a-z0-9_-]*$; modes must be override|global|off)`);
@@ -727,6 +731,13 @@ async function startServer(options = {}) {
     app.get("/context", (req, res) => {
         try {
             const r = (0, context_store_js_1.handleContextGet)((0, node_path_1.join)(stateDir, "context"), contextClients, req.query, contextAgents);
+            // #192: product-owned memory instructions ride as a synthetic read-only
+            // `memory` section (config memoryInstructions !== false; agent mode
+            // "off" respected inside the helper). Every harness renders it via the
+            // shared section renderer — zero client changes.
+            if (r.status === 200) {
+                (0, memory_instructions_js_1.injectMemorySection)(r.body, memoryInstructionsEnabled);
+            }
             res.status(r.status).json(r.body);
         }
         catch (err) {
@@ -735,6 +746,12 @@ async function startServer(options = {}) {
     });
     app.put("/context", (req, res) => {
         try {
+            // Reserved product section: never writable, loud error (no silent skip).
+            const putSections = req.body?.sections;
+            if (putSections && Object.keys(putSections).some((n) => (0, memory_instructions_js_1.isReservedSectionName)(n))) {
+                res.status(400).json({ error: `Section name '${memory_instructions_js_1.MEMORY_SECTION_NAME}' is reserved for the product-owned memory instructions (config memoryInstructions to disable them)` });
+                return;
+            }
             const r = (0, context_store_js_1.handleContextPut)((0, node_path_1.join)(stateDir, "context"), req.body, req.query, contextAgents);
             if (r.warn)
                 console.warn(`[hicortex] ${r.warn}`);

package/dist/memory-instructions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Product-owned memory instructions (#192, owner decision 28.07.2026).
+ *
+ * The instructions for HOW agents use Hicortex are shipped BY the product,
+ * versioned with the server, and injected as a synthetic read-only `memory`
+ * section in the GET /context response. Rationale ("enforced, built-in"):
+ *   - Harness personas (SOUL.md etc.) carry ZERO hicortex content — mechanics
+ *     described there rot silently when the product changes (field evidence:
+ *     stale "captured via hooks" sentences; an agent shell-spelunking its own
+ *     plugin infrastructure when told "the plugin was updated").
+ *   - User context files (user.md / rules.md) stay purely personal — norms the
+ *     product depends on must not live in user-editable files (same principle
+ *     as the built-in citation norm, 0.14.1).
+ *   - Because every harness already renders `## Context` sections through the
+ *     shared gate/render path, a synthetic section ships fleet-wide with zero
+ *     client changes — including plugins that predate this feature.
+ *
+ * The section name is RESERVED: PUT /context rejects it, and the synthetic
+ * text overrides any user file of the same name (enforced means enforced).
+ * Off-switch: config `memoryInstructions: false`.
+ */
+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;
+/** 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;
+/**
+ * Inject the synthetic section into a successful GET /context body.
+ * Pure: returns the same body object with sections.memory set. Skips agent
+ * mode "off" (operator explicitly silenced context for that agent) and
+ * non-object bodies (error shapes). Overrides a user file named memory.md.
+ */
+export declare function injectMemorySection<T extends {
+    sections?: Record<string, string>;
+    mode?: string;
+}>(body: T, enabled: boolean): T;

package/dist/memory-instructions.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Product-owned memory instructions (#192, owner decision 28.07.2026).
+ *
+ * The instructions for HOW agents use Hicortex are shipped BY the product,
+ * versioned with the server, and injected as a synthetic read-only `memory`
+ * section in the GET /context response. Rationale ("enforced, built-in"):
+ *   - Harness personas (SOUL.md etc.) carry ZERO hicortex content — mechanics
+ *     described there rot silently when the product changes (field evidence:
+ *     stale "captured via hooks" sentences; an agent shell-spelunking its own
+ *     plugin infrastructure when told "the plugin was updated").
+ *   - User context files (user.md / rules.md) stay purely personal — norms the
+ *     product depends on must not live in user-editable files (same principle
+ *     as the built-in citation norm, 0.14.1).
+ *   - Because every harness already renders `## Context` sections through the
+ *     shared gate/render path, a synthetic section ships fleet-wide with zero
+ *     client changes — including plugins that predate this feature.
+ *
+ * The section name is RESERVED: PUT /context rejects it, and the synthetic
+ * text overrides any user file of the same name (enforced means enforced).
+ * Off-switch: config `memoryInstructions: false`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_SECTION_NAME = void 0;
+exports.renderMemoryInstructions = renderMemoryInstructions;
+exports.isReservedSectionName = isReservedSectionName;
+exports.injectMemorySection = injectMemorySection;
+exports.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. */
+function renderMemoryInstructions() {
+    return [
+        "Your long-term memory is Hicortex — shared across all agents and sessions.",
+        "- A `## Memory recall (auto)` index may arrive with prompts: it is a MENU, not content. Fetch a full memory with `hicortex_get(id)` only when the entry is relevant to your current task.",
+        "- Recall before assuming: `hicortex_search` for prior decisions/facts/preferences, `hicortex_recent` to catch up on a project.",
+        "- Cite any memory you rely on (id, date); on conflicts, newer memories supersede older.",
+        "- Capture is automatic (nightly). Do not manually ingest routine content — `hicortex_ingest` is for explicitly requested learnings only.",
+        "- Never inspect, test, or modify memory/plugin/gateway infrastructure (configs, services, tokens). If a memory tool seems missing or broken, say so and stop.",
+    ].join("\n");
+}
+/** True for the reserved product section name (case-insensitive guard —
+ *  section names are lowercase by allowlist, but be safe). */
+function isReservedSectionName(name) {
+    return typeof name === "string" && name.trim().toLowerCase() === exports.MEMORY_SECTION_NAME;
+}
+/**
+ * Inject the synthetic section into a successful GET /context body.
+ * Pure: returns the same body object with sections.memory set. Skips agent
+ * mode "off" (operator explicitly silenced context for that agent) and
+ * non-object bodies (error shapes). Overrides a user file named memory.md.
+ */
+function injectMemorySection(body, enabled) {
+    if (!enabled)
+        return body;
+    if (!body || typeof body !== "object")
+        return body;
+    if (body.mode === "off")
+        return body;
+    if (!body.sections || typeof body.sections !== "object")
+        return body;
+    body.sections[exports.MEMORY_SECTION_NAME] = renderMemoryInstructions();
+    return body;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "description": "Self-learning memory for AI agents — experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {