@gamaze/hicortex 0.19.1 → 0.19.2

package/dist/learnings-identity.d.ts

@@ -63,18 +63,25 @@ export declare function resolveConfig(): ResolvedConfig | null;
  */
 export declare function titleCaseSection(name: string): string;
 /**
- * Stable section ordering: `user` first, then `rules` (the seeded primary
- * sections, spec §8), then every other section alphabetically. Server-side
- * enumeration order (readdirSync) is FS-dependent, so we sort here for a
- * deterministic injection block. Exported for reuse by the OC plugin.
+ * Stable section ordering for the rendered `## Identity` block: the #313
+ * precedence contract — `agent_identity` (the agent's own self + role
+ * conduct) first, then `user` (the principal), then `rules` (fleet-wide house
+ * rules), then every other section alphabetically. The list is imported from
+ * identity-store (SECTION_PRECEDENCE) so the server's SERVED order and every
+ * client's RENDERED order are the same definition — they cannot drift.
+ * Server-side enumeration order (readdirSync) is FS-dependent, so we sort
+ * here for a deterministic injection block. Exported for reuse by the OC
+ * plugin; the Python Hermes plugin mirrors this helper — keep them in sync.
  */
 export declare function orderSectionNames(names: string[]): string[];
 /**
  * Render the `## Identity` block from a resolved section map, or null when there
  * is nothing to inject (no sections, or every section blank after trimming).
  * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
- * both harnesses emit an identical block. Sections are ordered (user, rules,
- * then alphabetical) and rendered under title-cased `###` headings.
+ * both harnesses emit an identical block. Sections are ordered (agent_identity,
+ * user, rules, then alphabetical) and rendered under `###` headings labeled by
+ * the #313 scope map (SECTION_LABELS: "Agent identity" / "User" / "Global
+ * rules"); unknown section names fall back to title-case.
  */
 export declare function renderIdentityBlock(sections: Record<string, string>): string | null;
 /**
@@ -116,10 +123,12 @@ export interface IdentityToolResult {
  *     `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>`
+ *  2. `serveIdentityBody` — the ONE composition helper (REST uses it too):
+ *     injects the synthetic product-owned `memory` section (WARNING-1: the
+ *     REST route + SessionStart hook inject it; the tool did not,
+ *     contradicting its "same data" docs) and applies the SECTION_PRECEDENCE
+ *     wire order.
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Label>`
  *     markdown the hook injects.
  *
  * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the

package/dist/learnings-identity.js

@@ -39,7 +39,6 @@ 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");
@@ -152,22 +151,29 @@ function titleCaseSection(name) {
         .join(" ");
 }
 /**
- * Stable section ordering: `user` first, then `rules` (the seeded primary
- * sections, spec §8), then every other section alphabetically. Server-side
- * enumeration order (readdirSync) is FS-dependent, so we sort here for a
- * deterministic injection block. Exported for reuse by the OC plugin.
+ * Stable section ordering for the rendered `## Identity` block: the #313
+ * precedence contract — `agent_identity` (the agent's own self + role
+ * conduct) first, then `user` (the principal), then `rules` (fleet-wide house
+ * rules), then every other section alphabetically. The list is imported from
+ * identity-store (SECTION_PRECEDENCE) so the server's SERVED order and every
+ * client's RENDERED order are the same definition — they cannot drift.
+ * Server-side enumeration order (readdirSync) is FS-dependent, so we sort
+ * here for a deterministic injection block. Exported for reuse by the OC
+ * plugin; the Python Hermes plugin mirrors this helper — keep them in sync.
  */
 function orderSectionNames(names) {
-    const primaries = ["user", "rules"].filter((p) => names.includes(p));
-    const rest = names.filter((n) => n !== "user" && n !== "rules").sort();
+    const primaries = identity_store_js_1.SECTION_PRECEDENCE.filter((p) => names.includes(p));
+    const rest = names.filter((n) => !identity_store_js_1.SECTION_PRECEDENCE.includes(n)).sort();
     return [...primaries, ...rest];
 }
 /**
  * Render the `## Identity` block from a resolved section map, or null when there
  * is nothing to inject (no sections, or every section blank after trimming).
  * Pure — no gating, no I/O. Shared verbatim by the CC hook and the OC plugin so
- * both harnesses emit an identical block. Sections are ordered (user, rules,
- * then alphabetical) and rendered under title-cased `###` headings.
+ * both harnesses emit an identical block. Sections are ordered (agent_identity,
+ * user, rules, then alphabetical) and rendered under `###` headings labeled by
+ * the #313 scope map (SECTION_LABELS: "Agent identity" / "User" / "Global
+ * rules"); unknown section names fall back to title-case.
  */
 function renderIdentityBlock(sections) {
     if (!sections || typeof sections !== "object" || Array.isArray(sections))
@@ -178,7 +184,11 @@ function renderIdentityBlock(sections) {
         const body = sections[name];
         if (typeof body !== "string" || body.trim() === "")
             continue;
-        bodyParts.push(`### ${titleCaseSection(name)}`, "", body.trim());
+        // Own-property lookup (CR-A): "constructor" is allowlist-VALID, and a
+        // plain SECTION_LABELS[name] would resolve through the Object.prototype
+        // chain and render the inherited function's source as the heading.
+        const label = Object.hasOwn(identity_store_js_1.SECTION_LABELS, name) ? identity_store_js_1.SECTION_LABELS[name] : titleCaseSection(name);
+        bodyParts.push(`### ${label}`, "", body.trim());
     }
     if (bodyParts.length === 0)
         return null;
@@ -195,10 +205,12 @@ function renderIdentityBlock(sections) {
  *     `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>`
+ *  2. `serveIdentityBody` — the ONE composition helper (REST uses it too):
+ *     injects the synthetic product-owned `memory` section (WARNING-1: the
+ *     REST route + SessionStart hook inject it; the tool did not,
+ *     contradicting its "same data" docs) and applies the SECTION_PRECEDENCE
+ *     wire order.
+ *  3. optional `name` filter, then `renderIdentityBlock` for the `### <Label>`
  *     markdown the hook injects.
  *
  * Pure: no I/O of its own (the only I/O is `handleIdentityGet` reading the
@@ -209,7 +221,10 @@ function buildIdentityToolResult(identityDir, identityClients, identityAgents, o
     // 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);
+    // WARNING-1: inject the synthetic `memory` section exactly like REST + the
+    // SessionStart hook — via the ONE composition helper (serveIdentityBody,
+    // #313 CR3) so the tool's served order is the routes' served order.
+    const r = (0, identity_store_js_1.serveIdentityBody)((0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, query, identityAgents), opts.memoryInstructionsEnabled);
     if (r.status !== 200) {
         const errBody = r.body;
         return {
@@ -217,10 +232,6 @@ function buildIdentityToolResult(identityDir, identityClients, identityAgents, o
             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] } : {})

package/dist/mcp-server.js

@@ -309,7 +309,7 @@ function createMcpServer() {
             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.
+            // handleIdentityGet → serveIdentityBody → renderIdentityBlock.
             const result = (0, learnings_identity_js_1.buildIdentityToolResult)(identityDir, identityClients, identityAgents, {
                 name,
                 agent,
@@ -975,14 +975,11 @@ async function startServer(options = {}) {
     const identityDir = (0, node_path_1.join)(stateDir, "identity");
     app.get("/identity", (req, res) => {
         try {
-            const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents);
-            // #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);
-            }
+            // serveIdentityBody (#192 + #313): the ONE composition — synthetic
+            // product-owned `memory` section, then the SECTION_PRECEDENCE wire
+            // order. Shared with GET /context and the MCP hicortex_identity tool so
+            // every surface serves byte-identical ordering.
+            const r = (0, identity_store_js_1.serveIdentityBody)((0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents), memoryInstructionsEnabled);
             res.status(r.status).json(r.body);
         }
         catch (err) {
@@ -1013,10 +1010,9 @@ async function startServer(options = {}) {
     // difference in behaviour, only the URL.
     app.get("/context", (req, res) => {
         try {
-            const r = (0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents);
-            if (r.status === 200) {
-                (0, memory_instructions_js_1.injectMemorySection)(r.body, memoryInstructionsEnabled);
-            }
+            // Same serveIdentityBody composition as GET /identity — the alias
+            // serves byte-equal behaviour by construction.
+            const r = (0, identity_store_js_1.serveIdentityBody)((0, identity_store_js_1.handleIdentityGet)(identityDir, identityClients, req.query, identityAgents), memoryInstructionsEnabled);
             res.status(r.status).json(r.body);
         }
         catch (err) {

package/dist/prompts.js

@@ -130,6 +130,8 @@ EXTRACT into this markdown format:
 
 ### Project State Changes
 - [D] [SUBJECT]: [what changed], [from → to] (${date})
+  (Durable shifts only — the model/tool/approach the project now uses. A
+   status flip or counter change is NEVER-RECORD ephemera, not a state change)
 
 ### Key Entities & Relationships
 - [K] [entity A] → [relationship] → [entity B] (${date})
@@ -179,6 +181,23 @@ label, a sentiment ("Strong Negative"), or "User rejected…" is unfindable —
 matches every emotionally-similar prompt and no topically-relevant one. Front-load
 the subject; put reaction, intensity and reasoning AFTER it.
 
+NEVER-RECORD — ephemera gate (critical):
+Every candidate must pass one test: will it still be TRUE and still MATTER in 3 months?
+Content whose entire value is a state that expires is NEVER recorded —
+do not score it lower and write it anyway: OMIT it. A closed category of never-record ephemera:
+- issue/PR/epic/merge status: "PR #173 merged", "Epic 2 CLOSED — all children merged"
+- version/deploy/test-count statistics: "v0.16.0 deployed to rc dist-tag",
+  "Test suite grew 616→749", "Main branch updated to <sha>"
+- session bookkeeping/outcomes: "Session closure: nothing remains to do",
+  todo deferrals ("parked until next week"), sync/replay states
+- transient readings/snapshots: "disk usage snapshot: 84% at 14:20",
+  "uptime counter passed 40 days"
+The durable part of the same event may still qualify — the CHOICE a change
+embodies ("standardize on model X", user-confirmed) is [D], a configuration
+that holds going forward is [K]; the version bump, merge, or count itself never is.
+If EVERY item in the transcript is never-record ephemera, output ONLY:
+"NO_EXTRACT" — zero memories is the correct result for a pure-status segment.
+
 RULES:
 - Extract MAX 20 items total (quality over quantity)
 - Use EXACT names/versions/paths/numbers as they appear in the transcript —
@@ -187,7 +206,8 @@ RULES:
 - Each must be useful if recalled in a future session
 - Skip: routine code edits, standard tool usage, trivial fixes
 - Include: architectural decisions, debugging breakthroughs, user preferences,
-  tool configurations, API discoveries, project milestones
+  tool configurations, API discoveries, durable project milestones (a status
+  flip — shipped/merged/closed — is NEVER-RECORD ephemera, not a milestone)
 - PRIORITIZE Corrections & Rejections — these are high-value signals for learning
   what the user does NOT want. Even a single "no" or style correction is worth extracting.
 - Strong language or profanity from the user is a high-intensity signal — it indicates

package/dist/types.d.ts

@@ -399,6 +399,20 @@ export interface HicortexConfig {
      * leaner system prompts.
      */
     lessonsLimit?: number;
+    /**
+     * Default project name for the OpenClaw plugin (#316, Hermes `default_project`
+     * parity): sent as the `project` fallback on /recall-index, the pre-0.14
+     * /search fallback, and the search/recent/ingest tools whenever the gateway
+     * supplies no project. Absent ⇒ no scope sent.
+     */
+    defaultProject?: string;
+    /**
+     * Max memories per recall on the OpenClaw plugin's legacy /search fallback
+     * (pre-0.14 servers, #316). Default 8. Does NOT size the pushed
+     * /recall-index — that is server config (`recallMaxItems`); the server
+     * accepts no client limit.
+     */
+    recallLimit?: number;
     /**
      * Soft cap on the memory corpus (default 10000). When the corpus exceeds this,
      * the nightly's capacity-eviction stage (#245) removes the lowest-

package/hermes-plugin/hicortex/provider.py

@@ -123,22 +123,38 @@ def _title_case_section(name: str) -> str:
     return " ".join(w[:1].upper() + w[1:] for w in words)
 
 
+# #313 scope labels — mirror of the TS ``SECTION_LABELS`` in
+# identity-store.ts (keep in sync). "Global rules" marks the section as
+# fleet-wide; unknown section names fall back to title-case.
+_SECTION_LABELS = {
+    "agent_identity": "Agent identity",
+    "user": "User",
+    "rules": "Global rules",
+}
+
+
 def _order_section_names(names: Iterable[str]) -> List[str]:
-    """Stable ordering: user, rules, then the rest alphabetically."""
+    """Stable ordering — the #313 precedence contract, mirroring the TS
+    ``SECTION_PRECEDENCE`` (keep in sync): ``agent_identity`` (the agent's own
+    self + role conduct, per-agent only) first, then ``user`` (the principal),
+    then ``rules`` (fleet-wide house rules), then the rest alphabetically."""
     names = list(names)
-    primaries = [p for p in ("user", "rules") if p in names]
-    rest = sorted(n for n in names if n not in ("user", "rules"))
+    primaries = [p for p in ("agent_identity", "user", "rules") if p in names]
+    rest = sorted(n for n in names if n not in ("agent_identity", "user", "rules"))
     return primaries + rest
 
 
 def _render_context_block(sections: Dict[str, Any]) -> str:
-    """Render the ``## Identity`` block, or "" when every section is blank."""
+    """Render the ``## Identity`` block, or "" when every section is blank.
+    Headings use the #313 scope labels (``_SECTION_LABELS``); unknown sections
+    fall back to title-case."""
     body_parts: List[str] = []
     for name in _order_section_names(sections.keys()):
         body = sections.get(name)
         if not isinstance(body, str) or not body.strip():
             continue
-        body_parts.extend([f"### {_title_case_section(name)}", "", body.strip()])
+        label = _SECTION_LABELS.get(name) or _title_case_section(name)
+        body_parts.extend([f"### {label}", "", body.strip()])
     if not body_parts:
         return ""
     return "\n".join(["## Identity", "", *body_parts])

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hicortex",
   "name": "Hicortex — Long-term Memory That Learns",
   "description": "Your agents remember past decisions, avoid repeated mistakes, and get smarter every day. Nightly reflection generates actionable lessons that automatically update agent behavior.",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "kind": "lifecycle",
   "skills": ["./skills/hicortex-memory"],
   "configSchema": {
@@ -17,9 +17,14 @@
         "type": "string",
         "description": "Bearer token for the Hicortex server. Localhost bypasses auth automatically. Required for remote servers — use the authToken from ~/.hicortex/config.json on the server."
       },
-      "licenseKey": {
+      "defaultProject": {
         "type": "string",
-        "description": "Hicortex license key (hctx-...). Leave empty for free tier (250 memory cap)."
+        "description": "Optional default project name scoping recall, search, and ingest when the gateway supplies no project (Hermes default_project parity)."
+      },
+      "recallLimit": {
+        "type": "number",
+        "default": 8,
+        "description": "Max memories per recall on the pre-0.14 /search fallback (default 8). The pushed recall index is sized by SERVER config (recallMaxItems) — the server accepts no client limit."
       }
     },
     "required": []
@@ -34,10 +39,13 @@
       "sensitive": true,
       "placeholder": "Required for remote servers"
     },
-    "licenseKey": {
-      "label": "License Key",
-      "placeholder": "hctx-... (optional, free tier without key)",
-      "sensitive": true
+    "defaultProject": {
+      "label": "Default Project",
+      "placeholder": "Optional — scopes recall/ingest when the gateway sends no project"
+    },
+    "recallLimit": {
+      "label": "Recall Limit",
+      "placeholder": "8"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.19.1",
+  "version": "0.19.2",
   "description": "Persistent agent identity for AI agents \u2014 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": {