@gamaze/hicortex 0.23.2 → 0.24.0

package/dist/nightly.js

@@ -77,6 +77,8 @@ const state_js_1 = require("./state.js");
 const identity_store_js_1 = require("./identity-store.js");
 const capture_cursors_js_1 = require("./capture-cursors.js");
 const capture_js_1 = require("./capture.js");
+const distill_queue_js_1 = require("./distill-queue.js");
+const token_budget_js_1 = require("./token-budget.js");
 const run_deadline_js_1 = require("./run-deadline.js");
 const dashboard_js_1 = require("./dashboard.js");
 const recall_precision_js_1 = require("./recall-precision.js");
@@ -224,6 +226,43 @@ function makeRemotePost(serverUrl, authToken, deadline) {
         return normalizePostResult(resp);
     };
 }
+/**
+ * #529: the REAL yield-signal probe (the drain's is injected so the stage is
+ * unit-testable without HTTP). GETs the configured URL with a short timeout
+ * and classifies: busy = 2xx AND (a JSON body with a truthy `busy` field OR
+ * the plain body "busy"); a non-2xx answer means the endpoint ANSWERED and is
+ * simply not reporting busy → idle; a network error/timeout → unreachable
+ * (the drain proceeds fail-open and warns once). The URL lives in the nightly
+ * (not distill-queue.ts) so the drain module stays fetch-free.
+ */
+function makeDrainYieldProbe() {
+    return async (url) => {
+        try {
+            const resp = await fetch(url, {
+                signal: AbortSignal.timeout(calibration_js_1.DRAIN_YIELD_PROBE_TIMEOUT_MS),
+            });
+            if (!resp.ok)
+                return "idle";
+            const body = (await resp.text()).trim();
+            try {
+                const parsed = JSON.parse(body);
+                if (typeof parsed === "object" &&
+                    parsed !== null &&
+                    "busy" in parsed &&
+                    Boolean(parsed.busy)) {
+                    return "busy";
+                }
+            }
+            catch {
+                // Not JSON — the plain-body form below is the whole remaining check.
+            }
+            return body.toLowerCase() === "busy" ? "busy" : "idle";
+        }
+        catch {
+            return "unreachable";
+        }
+    };
+}
 /**
  * Per-POST timeout: 20 min (synchronous distillation of a large segment can
  * take minutes), clamped to the run deadline's remaining time when one is in
@@ -244,6 +283,9 @@ async function normalizePostResult(resp) {
             status: 201,
             distilled: data.distilled ?? 0,
             dropped: data.dropped ?? [],
+            // #529: a queue-mode server confirms durable storage, not distillation
+            // — the client only swaps its log line on this flag.
+            queued: data.queued === true,
             ...(usage ? { usage } : {}),
         };
     }
@@ -665,6 +707,51 @@ async function runNightly(options = {}) {
                 }
             }
         } // end capture block (consolidateOnly else)
+        // Step 2.5 (#529): drain the distill inbox — distill everything the
+        // daemon queued since the last run, BEFORE consolidation so drained
+        // memories are scored/linked/reflected in the SAME run. Full AND
+        // consolidate-only runs drain (the same gate as consolidation — hosted
+        // tenants deliver through their daemon too); capture-only/watchdog and
+        // dry-run never do (compute stays scheduled; capture-only keeps its
+        // no-LLM contract). All LLM goes through the one LlmClient (ladder,
+        // breaker, single-flight, dispatcher); token gate + run deadline are
+        // checked between items; the optional yield signal (drainYieldUrl) waits
+        // out interactive use of the endpoint. Runs even when capture above was
+        // skipped (lock wait / consolidate-only) — the inbox is independent of
+        // this machine's capture.
+        if (!dryRun && !captureOnly) {
+            const drainReport = await (0, distill_queue_js_1.drainDistillQueue)(db, {
+                llm,
+                llmConfig,
+                embed: embedder_js_1.embed,
+                budgetExceeded: () => (0, token_budget_js_1.isTokenBudgetExceeded)(stateDir),
+                deadline,
+                yieldUrl: (0, config_read_js_1.readStringConfig)(savedConfig ?? {}, "drainYieldUrl") ?? undefined,
+                probeBusy: makeDrainYieldProbe(),
+            });
+            // #5 metering, same as the daemon's sync path: record tokens against
+            // the monthly budget (incl. a failed item's partial usage) and fold
+            // them into the snapshot's distill share so new_this_run.tokens stays
+            // the run's TRUE total.
+            if (drainReport.usage.total > 0) {
+                (0, token_budget_js_1.recordDistillUsage)(stateDir, drainReport.usage);
+                distillUsage = distillUsage
+                    ? {
+                        prompt: distillUsage.prompt + drainReport.usage.prompt,
+                        completion: distillUsage.completion + drainReport.usage.completion,
+                        total: distillUsage.total + drainReport.usage.total,
+                    }
+                    : drainReport.usage;
+            }
+            if (drainReport.outcome !== "empty" && drainReport.outcome !== "completed") {
+                // A non-clean drain is a health signal, not a run failure: processed
+                // items are durable and the rest retries next scheduled run. Make it
+                // visible next to the capture-complete line so the queue-depth/age
+                // warning in status has a log-side counterpart.
+                console.warn(`[hicortex] Distill drain ${drainReport.outcome}: ` +
+                    `${drainReport.processed} processed, ${drainReport.remaining} still queued`);
+            }
+        }
         // Step 3: Consolidation — skipped in capture-only mode, dry-run, or no LLM.
         // Runs even if capture had transient failures (opens DB directly, independent
         // of the HTTP capture path). Full nightly only — capture-only runs are

package/dist/nofit.d.ts

@@ -1,6 +1,6 @@
 /**
  * No-fit lifecycle — weak-primary floor + no-association decay
- * (owner amendment 07.07 to specs/2026-07-07-graded-schema-memory-tags.md).
+ * (owner amendment 07.07).
  *
  * THE MODEL
  * ---------

package/dist/nofit.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * No-fit lifecycle — weak-primary floor + no-association decay
- * (owner amendment 07.07 to specs/2026-07-07-graded-schema-memory-tags.md).
+ * (owner amendment 07.07).
  *
  * THE MODEL
  * ---------

package/dist/schema-prototypes.d.ts

@@ -1,6 +1,6 @@
 /**
  * Graded schema membership — domain prototypes + per-tag association weights
- * (spec: specs/2026-07-07-graded-schema-memory-tags.md).
+ *.
  *
  * MODEL (cognitive grounding → mechanism)
  * ---------------------------------------

package/dist/schema-prototypes.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Graded schema membership — domain prototypes + per-tag association weights
- * (spec: specs/2026-07-07-graded-schema-memory-tags.md).
+ *.
  *
  * MODEL (cognitive grounding → mechanism)
  * ---------------------------------------

package/dist/status.d.ts

@@ -18,4 +18,15 @@ export declare function statusAgentLine(config: Record<string, unknown>): string
  * the full status printer. Unknown keys pass through verbatim (forward-compat).
  */
 export declare function formatTypeBreakdown(byType: Record<string, number>): string;
+/**
+ * The distill-inbox lines for `hicortex status` (#529). Pure on the
+ * {@link readQueueStats} shape so the rendering (incl. the 24 h stale-item
+ * warning, DRAIN_QUEUE_WARN_AGE_HOURS) is unit-testable without the full
+ * status printer. An empty inbox prints nothing — depth 0 is the healthy
+ * steady state, not worth a line.
+ */
+export declare function formatDistillQueueLines(stats: {
+    depth: number;
+    oldest_age_hours: number | null;
+}): string[];
 export declare function runStatus(): Promise<void>;

package/dist/status.js

@@ -5,6 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.statusAgentLine = statusAgentLine;
 exports.formatTypeBreakdown = formatTypeBreakdown;
+exports.formatDistillQueueLines = formatDistillQueueLines;
 exports.runStatus = runStatus;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -16,6 +17,8 @@ const features_js_1 = require("./features.js");
 const state_js_1 = require("./state.js");
 const identity_store_js_1 = require("./identity-store.js");
 const type_labels_js_1 = require("./type-labels.js");
+const distill_queue_js_1 = require("./distill-queue.js");
+const calibration_js_1 = require("./calibration.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");
@@ -50,6 +53,24 @@ function formatTypeBreakdown(byType) {
         .map(([k, v]) => `${(0, type_labels_js_1.labelForType)(k)}=${v}`)
         .join(", ");
 }
+/**
+ * The distill-inbox lines for `hicortex status` (#529). Pure on the
+ * {@link readQueueStats} shape so the rendering (incl. the 24 h stale-item
+ * warning, DRAIN_QUEUE_WARN_AGE_HOURS) is unit-testable without the full
+ * status printer. An empty inbox prints nothing — depth 0 is the healthy
+ * steady state, not worth a line.
+ */
+function formatDistillQueueLines(stats) {
+    if (stats.depth === 0)
+        return [];
+    const age = stats.oldest_age_hours ?? 0;
+    const lines = [`Distill queue: ${stats.depth} pending (oldest ${age.toFixed(1)}h)`];
+    if (age >= calibration_js_1.DRAIN_QUEUE_WARN_AGE_HOURS) {
+        lines.push(`  ⚠ Distill inbox oldest item is ${age.toFixed(1)}h old (>${calibration_js_1.DRAIN_QUEUE_WARN_AGE_HOURS}h) — ` +
+            `check the drain outcome in the last nightly log`);
+    }
+    return lines;
+}
 async function runStatus() {
     console.log("Hicortex Status");
     console.log("─".repeat(40));
@@ -66,6 +87,10 @@ async function runStatus() {
             console.log(`Memories:     ${stats.memories} (${typeStr || "none"})`);
             console.log(`Links:        ${stats.links}`);
             console.log(`DB size:      ${(stats.db_size_bytes / 1024).toFixed(1)} KB`);
+            // #529: inbox visibility — depth + oldest-item age, warn above 24 h.
+            for (const line of formatDistillQueueLines((0, distill_queue_js_1.readQueueStats)(db))) {
+                console.log(line);
+            }
             // 0.21 migration detection (#425): pre-0.21 stores have inflated importance
             // scores (median ~0.80 vs the honest ~0.40). If the live median is high,
             // recommend the one-shot rescore.

package/dist/types.d.ts

@@ -642,6 +642,26 @@ export interface HicortexConfig {
      * probe per window. Nightly runs are single-shot and never cache.
      */
     llmProbeTtlMs?: number;
+    /**
+     * #529 kill switch for the durable distill inbox. Default TRUE (queue
+     * mode): POST /distill stores the redacted segment durably and answers the
+     * SAME 201 shape with zeroed counts + `queued: true` — no LLM call — and
+     * the nightly's drain stage distills the inbox before consolidation, so
+     * all distill LLM traffic happens inside the scheduled runs. `false`
+     * restores synchronous distill-on-POST byte-for-byte (every delivery
+     * lands in the sync flow). Read through readStrictBoolean — a non-boolean
+     * value is ignored (warned), never coerced.
+     */
+    distillQueue?: boolean;
+    /**
+     * #529 optional interactive-yield signal: a URL the drain polls BETWEEN
+     * items. A 2xx answer whose body is JSON with a truthy `busy` field — or
+     * the plain text `busy` — makes the drain wait and re-check (bounded by
+     * the run deadline and a per-item cap); unset or unreachable proceeds
+     * fail-open (one warn per run). Seam only for now — the drain side ships
+     * with this contract, endpoints can adopt it whenever.
+     */
+    drainYieldUrl?: string;
     /**
      * Max lessons injected into an agent's session-start context (default 10).
      * Lessons are ranked per-session by project/domain affinity + recency +

package/hermes-plugin/hicortex/README.md

@@ -2,11 +2,18 @@
 
 > **Install:** `hermes plugins install gamaze-labs/hicortex-hermes-plugin` → `hermes memory setup hicortex` → restart your gateway.
 >
-> The [gamaze-labs/hicortex-hermes-plugin](https://github.com/gamaze-labs/hicortex-hermes-plugin) repo is a **generated read-only mirror** of `hermes-plugin/hicortex/` in the main Hicortex repo — do not open PRs there. Requires a running [Hicortex server](https://hicortex.gamaze.com/docs/installation.html) (local or remote) for recall; capture of Hermes sessions is handled by the server machine's nightly job.
+> The [gamaze-labs/hicortex-hermes-plugin](https://github.com/gamaze-labs/hicortex-hermes-plugin) repo is a **generated read-only mirror** of `hermes-plugin/hicortex/` in the main Hicortex repo — do not open PRs there. Requires a running [Hicortex server](https://hicortex.gamaze.com/docs/installation.html) (local or remote) for recall; capture of Hermes sessions is the nightly job's, not this plugin's (see [Data flow](#data-flow)).
 
-Gives [Hermes](https://github.com/nousresearch/hermes-agent) agents self-learning memory backed by a [Hicortex](https://hicortex.gamaze.com/) server: their experience is distilled into lessons overnight, and they wake up wiser. **Recall-only:** the plugin retrieves relevant memories on every turn and injects distilled lessons into the system prompt. It has **no local LLM, no capture, no cron** — it is a thin recall shim.
+Gives [Hermes](https://github.com/nousresearch/hermes-agent) agents self-learning memory backed by a [Hicortex](https://hicortex.gamaze.com/) server: their experience is distilled into lessons overnight, and they wake up wiser. **Recall-only:** each turn the plugin sends the user's message to the configured server and injects the returned recall index, plus distilled lessons into the system prompt. It has **no local LLM, no capture, no cron** — it is a thin recall shim.
 
-**Capture happens centrally.** A nightly reader on the Hicortex server distills each agent's own session store (Hermes keeps full history in `~/.hermes/profiles/<agent>/state.db`), so nothing needs to be captured in real time. See `specs/2026-07-01-memory-capture-architecture.md` in the main repo.
+## Data flow
+
+Both directions of the wire, stated plainly:
+
+- **Recall — every turn.** Each user message is sent to your configured Hicortex server for recall (`POST /recall-index`, or `GET /search` on pre-0.14 servers), and session distillation runs on the server. The server therefore sees prompt text as it arrives — point `hicortex_url` at a server you trust (default `http://localhost:8787`).
+- **Capture — nightly.** Session logs are read locally from each machine's own Hermes store (Hermes keeps full history in `~/.hermes/profiles/<agent>/state.db`); the nightly ships only denoised text to the server, and the server stores distilled memories — raw session logs stay on the capturing machine. Nothing is captured in real time.
+
+The plugin warns once at startup when `hicortex_url` is plain `http://` on a non-loopback host while an auth token is set — credentials and prompts then cross the network in cleartext. Use `https://`, or keep the server on a trusted private network (plain http over a private/overlay network is a legitimate setup; the warning is advisory, not a rejection). The HTTP client also strips the `Authorization` header on any redirect that leaves the original host.
 
 ## How it works
 
@@ -26,9 +33,9 @@ Instead of injecting full memory content every turn, `prefetch` sends the user's
 
 ### 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.
+`system_prompt_block()` also injects the hand-edited **standing context layer** (`## Identity`, 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.
 
-> **Note (#264 rename):** the server-side layer was renamed Context → Identity in 0.18. The `/context` endpoint remains as an alias so this plugin keeps working unchanged; the heading is still rendered as `## Context` here and will switch to `## Identity` in a follow-up plugin release. No action needed.
+> **Note (#264 rename):** the server-side layer was renamed Context → Identity in 0.18. The `/context` endpoint remains as an alias so this plugin keeps working unchanged, and the injected heading renders as `## Identity`. No action needed.
 
 The plugin sends its **profile name** as `?agent=`, resolved in this order:
 
@@ -91,7 +98,7 @@ Env overrides: `HICORTEX_URL`, `HICORTEX_AUTH_TOKEN`.
 ## Topology
 
 - **Server host:** runs Hicortex. Set `hicortex_url: http://localhost:8787` (localhost bypasses auth).
-- **Other Hermes boxes:** set `hicortex_url` to the server's hostname (e.g. `http://memory-server:8787`) and `HICORTEX_AUTH_TOKEN` to the server's token. Each box recalls from the same shared brain.
+- **Other Hermes boxes:** set `hicortex_url` to the server's hostname (e.g. `http://memory-server:8787`) and `HICORTEX_AUTH_TOKEN` to the server's token. Each box recalls from the same shared brain — and every user message travels to that server each turn (see [Data flow](#data-flow)). Over plain `http://` the token and prompts cross the network in cleartext (one startup warning); prefer `https://` or a trusted private network.
 
 ## Notes
 

package/hermes-plugin/hicortex/__init__.py

@@ -16,3 +16,10 @@ from agent.memory_provider import MemoryProvider  # noqa: F401  (loader scans fo
 from .provider import HicortexProvider
 
 __all__ = ["HicortexProvider"]
+
+
+def register(ctx) -> None:
+    """Hermes plugin entry point (memory-provider guide convention): hand this
+    provider to the host. Complements the direct import path — the loader
+    scans for ``MemoryProvider`` subclasses either way."""
+    ctx.register_memory_provider(HicortexProvider())

package/hermes-plugin/hicortex/client.py

@@ -6,10 +6,55 @@ Stdlib-only (no pip dependencies) so the plugin installs with zero friction.
 from __future__ import annotations
 
 import json
+import logging
 import urllib.error
 import urllib.parse
 import urllib.request
-from typing import Any, Optional
+from typing import Any, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# One-shot-per-process guard for the cleartext-transport warning. Clients are
+# rebuilt per provider/config read; warning per construction would spam the
+# gateway log on every rebuild.
+_cleartext_warned = False
+
+
+def _origin(url: str) -> Tuple[Optional[str], Optional[int]]:
+    """(host, port) origin of a URL, default-port-normalized (http→80,
+    https→443) and lower-cased — the identity a redirect must preserve for the
+    Authorization header to be safe to keep. Unparseable URLs never compare
+    equal, so they fail CLOSED (token stripped)."""
+    try:
+        parsed = urllib.parse.urlparse(url)
+        port = parsed.port or (443 if parsed.scheme == "https" else 80)
+        return (parsed.hostname or "").lower(), port
+    except ValueError:
+        return (url, None)
+
+
+class _AuthStrippingRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Strip ``Authorization`` on any redirect that leaves the original origin.
+
+    urllib's default redirect handler forwards the request's headers to the
+    redirect target (only content headers — length/type/encoding — are
+    dropped), so a cross-host 302 hands the bearer token to whoever answers
+    the redirect. Same-origin redirects (path changes, trailing-slash fixes)
+    keep authenticating as before."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        new_req = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new_req is not None and _origin(req.full_url) != _origin(newurl):
+            # Request headers are Capitalized by add_header ("Authorization").
+            new_req.headers.pop("Authorization", None)
+            new_req.unredirected_hdrs.pop("Authorization", None)
+        return new_req
+
+
+# Shared opener: urllib's defaults plus the auth-stripping redirect handler.
+# `urlopen` cannot be used for this — it goes through the process-global
+# default opener, which we must not reconfigure from inside a plugin.
+_OPENER = urllib.request.build_opener(_AuthStrippingRedirectHandler)
 
 
 class HicortexClient:
@@ -31,6 +76,23 @@ class HicortexClient:
             if host in ("127.0.0.1", "localhost", "::1", "::ffff:127.0.0.1")
             else auth_token
         )
+        # Cleartext transport warning (catalog review 130093): a plain http://
+        # URL to a non-loopback host while a token is set means the token AND
+        # every prompt sent for recall cross the network unencrypted. WARN,
+        # never reject — plain http on a trusted private network (overlay
+        # networks, private overlay meshes) is a legitimate setup.
+        if self.auth_token and urllib.parse.urlparse(self.base_url).scheme != "https":
+            global _cleartext_warned
+            if not _cleartext_warned:
+                _cleartext_warned = True
+                logger.warning(
+                    "hicortex: %s uses plain http:// on a non-loopback host "
+                    "while an auth token is set — the token and every prompt "
+                    "sent for recall cross the network in cleartext. Use "
+                    "https://, or keep the server on a trusted private "
+                    "network. (This warning fires once per process.)",
+                    self.base_url,
+                )
         self.timeout = timeout
 
     def _headers(self) -> dict[str, str]:
@@ -69,7 +131,7 @@ class HicortexClient:
         errors converted to statuses (never raised)."""
         req = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
         try:
-            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as resp:
+            with _OPENER.open(req, timeout=timeout or self.timeout) as resp:
                 return resp.status, json.loads(resp.read().decode("utf-8"))
         except urllib.error.HTTPError as e:
             return e.code, self._parse_http_error(e)

package/hermes-plugin/hicortex/plugin.yaml

@@ -1,5 +1,5 @@
 name: hicortex
-version: 0.7.8
+version: 0.7.10
 description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Pushes a compact per-turn recall index (lazy-loaded with hicortex_get), injects fresh lessons plus a per-agent standing context block, and exposes the full 9-tool memory surface (search, get, recent, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only. AFTER INSTALL: run `hermes memory setup`, select hicortex, enter the server URL + token (see the token env var description for where to find it)."
 pip_dependencies: []
 hooks: []

package/hermes-plugin/hicortex/provider.py

@@ -26,7 +26,7 @@ Recall:   prefetch()          -> POST /recall-index (pushed recall index, 0.14
 
 Capture is NOT the plugin's job. A nightly reader on the Hicortex server
 distills each agent's own session store (Hermes: ~/.hermes/profiles/<agent>/
-state.db) centrally — see specs/2026-07-01-memory-capture-architecture.md. This
+state.db) centrally. This
 plugin has no local LLM, no spool, no timer, and no capture path.
 """
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "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, Pi, and opencode.",
   "main": "dist/index.js",
   "bin": {

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.gamaze-labs/hicortex",
   "title": "Hicortex \u2014 AI Fleet Memory",
   "description": "Shared fleet memory for AI agents: nightly self-correction, recall every prompt (supported agents).",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@gamaze/hicortex",
-      "version": "0.23.2",
+      "version": "0.24.0",
       "transport": {
         "type": "stdio",
         "command": "npx",