@gamaze/hicortex 0.12.1 → 0.13.0

package/dist/status.d.ts

@@ -1,4 +1,13 @@
 /**
  * Hicortex status — show current configuration and stats.
  */
+/**
+ * The value shown after "Agent name:" in `hicortex status` (#179, A3). Reports
+ * EXACTLY what the CC hook resolves (shared `resolveAgentIdentity`), so the
+ * operator never keys `contextAgents`/`agents/<id>/` on an id the install does
+ * not actually send. Unset → the install sends no `?agent=` and shares the
+ * global context (CC default). A configured-but-unsanitizable value is called
+ * out as invalid (the hook sends none) rather than silently accepted.
+ */
+export declare function statusAgentLine(config: Record<string, unknown>): string;
 export declare function runStatus(): Promise<void>;

package/dist/status.js

@@ -3,6 +3,7 @@
  * Hicortex status — show current configuration and stats.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusAgentLine = statusAgentLine;
 exports.runStatus = runStatus;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -12,9 +13,29 @@ const node_child_process_1 = require("node:child_process");
 const db_js_1 = require("./db.js");
 const features_js_1 = require("./features.js");
 const state_js_1 = require("./state.js");
+const context_store_js_1 = require("./context-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
+/**
+ * The value shown after "Agent name:" in `hicortex status` (#179, A3). Reports
+ * EXACTLY what the CC hook resolves (shared `resolveAgentIdentity`), so the
+ * operator never keys `contextAgents`/`agents/<id>/` on an id the install does
+ * not actually send. Unset → the install sends no `?agent=` and shares the
+ * global context (CC default). A configured-but-unsanitizable value is called
+ * out as invalid (the hook sends none) rather than silently accepted.
+ */
+function statusAgentLine(config) {
+    const id = (0, context_store_js_1.resolveAgentIdentity)(config);
+    switch (id.source) {
+        case "configured":
+            return id.agentId;
+        case "invalid-config":
+            return `(invalid configured value "${id.rawConfigured}" — fix config.agentName; hook sends none)`;
+        default: // unset
+            return "(not set — global context)";
+    }
+}
 async function runStatus() {
     console.log("Hicortex Status");
     console.log("─".repeat(40));
@@ -42,11 +63,12 @@ async function runStatus() {
     let licenseKey = "";
     let savedAuthToken = "";
     let isClientMode = false;
+    let parsedConfig = {};
     try {
-        const config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
-        licenseKey = config.licenseKey ?? "";
-        savedAuthToken = config.authToken ?? "";
-        isClientMode = config.mode === "client";
+        parsedConfig = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+        licenseKey = parsedConfig.licenseKey ?? "";
+        savedAuthToken = parsedConfig.authToken ?? "";
+        isClientMode = parsedConfig.mode === "client";
     }
     catch { /* no config */ }
     const validated = (0, features_js_1.getValidatedLicense)();
@@ -65,6 +87,9 @@ async function runStatus() {
     else if (!isClientMode && !savedAuthToken) {
         console.log(`Auth token:   not configured (run: npx @gamaze/hicortex init)`);
     }
+    // Per-agent context id (#179) — the id this install sends as ?agent= and the
+    // key operators use for contextAgents / agents/<id>/ dirs.
+    console.log(`Agent name:   ${statusAgentLine(parsedConfig)}`);
     console.log();
     // Adapters
     console.log("Adapters:");

package/hermes-plugin/hicortex/README.md

@@ -14,11 +14,24 @@ Gives [Hermes](https://github.com/nousresearch/hermes-agent) agents self-learnin
 |---|---|---|
 | `prefetch(query)` | recall relevant memories before each turn | `GET /search` |
 | `queue_prefetch(query)` | background recall for the next turn | `GET /search` |
-| `system_prompt_block()` | inject distilled lessons + memory index | `GET /lessons` |
+| `system_prompt_block()` | inject per-agent standing context + distilled lessons + memory index | `GET /context`, `GET /lessons` |
 | `get_tool_schemas()` | exposes the 8 unified tools | see tool table below |
 
 That's the whole surface. No `sync_turn`, no compaction/session-end capture — those are intentionally absent.
 
+### Per-agent standing context (0.13)
+
+`system_prompt_block()` also injects the hand-edited **standing context layer** (`## Context`, above the lessons block) — "who you are + how to work", distinct from episodic memory. The server resolves it **per agent**: this profile's own sections override the global set (`override`), or it can be `global` or `off`. See the main repo's `/context` layer docs.
+
+The plugin sends its **profile name** as `?agent=`, resolved in this order:
+
+1. `agent_name` in the plugin config (explicit override);
+2. the `HERMES_PROFILE` environment variable;
+3. a `HERMES_HOME` ending in `profiles/<name>` (the per-profile install path);
+4. none → the global context (backward compatible).
+
+Leave `agent_name` blank to auto-derive (2–4). Context injection needs a Hicortex server **≥ 0.13**; against an older server the plugin detects the missing per-agent support and injects no context (lessons are unaffected). Context and lessons fail soft independently — a context failure never costs the lessons block.
+
 ### Tools (unified 8)
 
 | Tool | REST call | Description |
@@ -57,7 +70,7 @@ hermes memory setup   # select "hicortex", enter the server URL/token when promp
 
 Run it once per profile if you use Hermes profiles. Hermes allows **one** external memory provider at a time, so disable Honcho (or any other) first, then restart the gateway.
 
-Config fields (`hicortex_url`, `default_project`, `recall_limit`, `privacy_filter`) can also be written to `$HERMES_HOME/plugins/hicortex/config.json` directly. The auth token is a **secret** — set it via env, not the JSON file:
+Config fields (`hicortex_url`, `default_project`, `recall_limit`, `privacy_filter`, `agent_name`) can also be written to `$HERMES_HOME/plugins/hicortex/config.json` directly. `agent_name` pins the per-agent context id for this profile (leave blank to auto-derive — see [Per-agent standing context](#per-agent-standing-context-013)). The auth token is a **secret** — set it via env, not the JSON file:
 
 ```bash
 export HICORTEX_AUTH_TOKEN=hctx-default-token   # or your custom token

package/hermes-plugin/hicortex/client.py

@@ -96,6 +96,13 @@ class HicortexClient:
     def lessons(self) -> dict[str, Any]:
         return self._get("/lessons")
 
+    def context(self, agent: Optional[str] = None) -> dict[str, Any]:
+        """Standing context layer (L2). When ``agent`` is set, the server
+        resolves the per-agent scope and echoes ``agent``/``mode`` (0.13); a
+        pre-0.13 server ignores the param and returns the global set with no
+        echo — the caller uses that echo as an old-server guard."""
+        return self._get("/context", {"agent": agent})
+
     def index(self) -> dict[str, Any]:
         return self._get("/index")
 

package/hermes-plugin/hicortex/config.py

@@ -57,6 +57,16 @@ CONFIG_SCHEMA: list[dict[str, Any]] = [
         "default": "WORK,PERSONAL",
         "required": False,
     },
+    {
+        "key": "agent_name",
+        "label": "Agent name (per-agent context)",
+        "description": (
+            "Identity sent as ?agent= when fetching the standing context layer, "
+            "so this profile gets its own context (0.13). Leave blank to "
+            "auto-derive from the running profile (HERMES_PROFILE / HERMES_HOME)."
+        ),
+        "required": False,
+    },
     # NOTE: recall-only plugin — no capture config. Capture is handled by the
     # nightly server-side reader of each agent's session store.
 ]

package/hermes-plugin/hicortex/plugin.yaml

@@ -1,6 +1,6 @@
 name: hicortex
-version: 0.5.0
-description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Injects fresh lessons each turn and exposes the full 8-tool memory surface (search, recent, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only."
+version: 0.6.0
+description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Injects fresh lessons each turn plus a per-agent standing context block, and exposes the full 8-tool memory surface (search, recent, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only."
 pip_dependencies: []
 hooks: []
 requires_env:

package/hermes-plugin/hicortex/provider.py

@@ -16,8 +16,11 @@ from __future__ import annotations
 import hashlib
 import json
 import logging
+import os
+import re
 import threading
-from typing import Any, Dict, List, Optional
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, Iterable, List, Optional
 
 from agent.memory_provider import MemoryProvider
 
@@ -28,6 +31,89 @@ logger = logging.getLogger(__name__)
 
 _INJECT_CONTENT_CAP = 500
 
+# Agent ids are joined into a filesystem path server-side, so they share the
+# section-name allowlist. \Z (NOT $) anchors the END OF STRING: Python's $ also
+# matches just before a trailing "\n", so "nano\n" would pass and go out as
+# agent=nano%0A → a 400 the fail-soft path silently swallows.
+_AGENT_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*\Z")
+
+
+def _valid_agent_id(name: Optional[str]) -> bool:
+    return bool(name) and len(name) <= 64 and bool(_AGENT_ID_RE.match(name))
+
+
+def _sanitize_agent_id(raw: Optional[str]) -> Optional[str]:
+    """Sanitize a raw identity (profile name / env value) into a valid agent id,
+    or None when nothing valid remains — mirrors the TS ``sanitizeAgentId``
+    EXACTLY so a profile resolves to the SAME id on both harnesses (a mismatch
+    would make one honor the persona firewall and the other leak global context
+    into an ``off``/``override`` persona): lowercase → collapse invalid runs to
+    "-" → strip leading -/_ → truncate 64 → validate. "Lenny" → "lenny";
+    "MacBook-Pro.local" → "macbook-pro-local"; all-symbols → None."""
+    if not isinstance(raw, str):
+        return None
+    cleaned = re.sub(r"[^a-z0-9_-]+", "-", raw.lower())
+    cleaned = re.sub(r"^[-_]+", "", cleaned)[:64]
+    return cleaned if _valid_agent_id(cleaned) else None
+
+
+def _profile_from_home(home: str) -> Optional[str]:
+    """Parse a Hermes profile name from a ``HERMES_HOME`` ending in
+    ``…/profiles/<name>``; None when the path is not profile-shaped."""
+    home = (home or "").strip().rstrip("/")
+    if not home:
+        return None
+    parent, name = os.path.split(home)
+    return name if name and os.path.basename(parent) == "profiles" else None
+
+
+def _resolve_agent_name(cfg: Dict[str, Any]) -> Optional[str]:
+    """Resolve the per-agent context id (0.13), in priority order:
+      1. config ``agent_name`` (explicit override);
+      2. ``HERMES_PROFILE`` env;
+      3. parse ``HERMES_HOME`` when it ends ``profiles/<name>``;
+      4. None → bare fetch → the global set.
+    Each source is stripped then SANITIZED (not rejected) so "Lenny" → "lenny"
+    matches the TS contract; a source that sanitizes to None yields None (bare
+    fetch), never a fall-through to another identity."""
+    configured = (cfg.get("agent_name") or "").strip()
+    if configured:
+        return _sanitize_agent_id(configured)
+    prof = (os.environ.get("HERMES_PROFILE") or "").strip()
+    if prof:
+        return _sanitize_agent_id(prof)
+    parsed = _profile_from_home(os.environ.get("HERMES_HOME") or "")
+    if parsed:
+        return _sanitize_agent_id(parsed)
+    return None
+
+
+def _title_case_section(name: str) -> str:
+    """"user" → "User", "my_notes" → "My Notes" (mirrors the CC/OC helper)."""
+    words = [w for w in re.split(r"[-_]+", name) if w]
+    return " ".join(w[:1].upper() + w[1:] for w in words)
+
+
+def _order_section_names(names: Iterable[str]) -> List[str]:
+    """Stable ordering: user, 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"))
+    return primaries + rest
+
+
+def _render_context_block(sections: Dict[str, Any]) -> str:
+    """Render the ``## Context`` block, or "" when every section is blank."""
+    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()])
+    if not body_parts:
+        return ""
+    return "\n".join(["## Context", "", *body_parts])
+
 
 class HicortexProvider(MemoryProvider):
     """Hicortex long-term memory backend for Hermes (recall-only)."""
@@ -37,6 +123,7 @@ class HicortexProvider(MemoryProvider):
         self._project: Optional[str] = None
         self._recall_limit: int = 5
         self._privacy: Optional[str] = "WORK,PERSONAL"
+        self._agent_name: Optional[str] = None
         self._prefetch_cache: Dict[str, str] = {}
         self._bg_threads: List[threading.Thread] = []
 
@@ -81,6 +168,7 @@ class HicortexProvider(MemoryProvider):
         except (TypeError, ValueError):
             self._recall_limit = 5
         self._privacy = cfg.get("privacy_filter", "WORK,PERSONAL")
+        self._agent_name = _resolve_agent_name(cfg)
         try:
             self._client = self._build_client()
         except Exception as e:
@@ -142,6 +230,51 @@ class HicortexProvider(MemoryProvider):
         client = self._client_or_none()
         if client is None:
             return ""
+        # Standing context (L2, 0.13) is prepended ABOVE the lessons block. The
+        # two fetches run CONCURRENTLY (matching the TS Promise.all paths): run
+        # serially, a blackholed server would stall the turn for up to 2× the
+        # client timeout. Each block fails soft independently — a context failure
+        # must never cost the lessons block, and vice versa.
+        with ThreadPoolExecutor(max_workers=2) as executor:
+            f_context = executor.submit(self._context_block, client)
+            f_lessons = executor.submit(self._lessons_block, client)
+            blocks = [f_context.result(), f_lessons.result()]
+        return "\n\n".join(b for b in blocks if b)
+
+    def _context_block(self, client: HicortexClient) -> str:
+        """Fetch the standing context layer and render a ``## Context`` block,
+        or "" when nothing should be injected. Gates (ALL): "hermes" in the
+        server-resolved ``clients``; when an agent id was SENT, the response
+        echoes ``agent`` (old-server guard — a pre-0.13 server ignores ?agent=
+        and returns global with no echo; injecting would push global context
+        into every persona; the check is skipped on a bare fetch); and the
+        resolved section set is non-empty (mode "off" → {}).
+
+        Reference implementation for the gate: TS ``gateAndRenderContext`` in
+        ``packages/hicortex/src/lessons-context.ts`` (keep the two in sync).
+
+        The ENTIRE path — fetch, parse, gate, render — is inside the try: a
+        malformed ``clients`` value (e.g. an int from a proxy error page) would
+        otherwise raise during the ``in`` check, escape, and cost the lessons
+        block too (mirrors the TS ``.catch(() => null)`` totality)."""
+        try:
+            data = client.context(agent=self._agent_name)
+            if not isinstance(data, dict):
+                return ""
+            clients = data.get("clients") or []
+            if "hermes" not in clients:
+                return ""
+            if self._agent_name is not None and not isinstance(data.get("agent"), str):
+                return ""
+            sections = data.get("sections") or {}
+            if not isinstance(sections, dict):
+                return ""
+            return _render_context_block(sections)
+        except Exception as e:
+            logger.debug("hicortex context injection failed: %s", e)
+            return ""
+
+    def _lessons_block(self, client: HicortexClient) -> str:
         try:
             data = client.lessons()
         except Exception as e:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Self-learning memory for AI agents \u2014 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": {