@gamaze/hicortex 0.16.2 → 0.16.3

package/README.md

@@ -212,6 +212,9 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `contextAgents` | Per-agent context modes (0.13): `{ "<id>": "override" \| "global" \| "off" }`. Absent + no `agents/<id>/` dir → every agent gets the global set. Boot-time (restart to apply) — see [Per-agent context](#per-agent-context-013) |
 | `agentName` | This install's per-agent context id sent as `?agent=`. **Unset by default** (CC shares the global context — no `?agent=` sent). Explicit opt-in via `init --agent-name <name>`; `init --agent-name ""` clears it. An empty/whitespace value equals unset |
 | `nightlyHour` | Local hour (0–23) for the nightly job installed by `init` (defaults: client 2, server 3). Applied on fresh installs; existing schedules are never overwritten |
+| `preflightTimeoutMs` | **Client mode only.** Per-attempt timeout for the nightly's server-reachability check before it starts capturing (default: 15000 ms) |
+| `preflightAttempts` | **Client mode only.** Reachability-check retries before the nightly aborts (default: 3; floored at 1). `1` = single try, no retry |
+| `preflightRetryGapMs` | **Client mode only.** Delay between reachability retries (default: 60000 ms). Note: timers don't advance while the machine is asleep, so on a sleeping laptop this gap counts awake-time, not wall-clock |
 | `scoreSimilarityWeight` | Weight of semantic similarity in the ranking score (default: 0.50) |
 | `scoreStrengthWeight` | Weight of effective strength — importance/use/recency of access (default: 0.20) |
 | `scoreConnectionsWeight` | Weight of graph centrality (default: 0.15) |

package/dist/cli.js

@@ -40,7 +40,7 @@ switch (command) {
             agentName = (0, cli_args_js_1.readValueFlag)(process.argv, "--agent-name");
         }
         catch {
-            console.error("[hicortex] init: --agent-name requires a value, e.g. --agent-name lenovo");
+            console.error("[hicortex] init: --agent-name requires a value, e.g. --agent-name my-agent");
             process.exit(1);
         }
         const repairConfig = process.argv.includes("--repair-config");

package/dist/consolidate.js

@@ -832,7 +832,7 @@ function stageHubBoost(db, dryRun) {
 //
 // A later decision/correction can reverse, replace, or invalidate an earlier
 // one — e.g. "chose Ollama for distillation" superseded a month later by
-// "switched distillation to the MBP's 35B model over Tailscale". Left
+// "switched distillation to a local 35B model over a mesh VPN". Left
 // unlinked, retrieval and lesson selection can surface the stale one. This
 // stage links OLD → NEW with relationship `superseded_by` and accelerates the
 // old memory's decay, WITHOUT deleting it (unlike `hicortex dedup`'s merge —

package/dist/nightly.js

@@ -187,6 +187,27 @@ function captureLockWaitMs() {
     const env = Number(process.env.HICORTEX_CAPTURE_LOCK_WAIT_MS);
     return Number.isFinite(env) && env >= 0 ? env : CAPTURE_LOCK_WAIT_MS;
 }
+/**
+ * Read a positive finite number from a nightly config key, falling back to
+ * `def` when the key is absent/invalid. Used by the pre-flight retry knobs
+ * (#163): tuning knobs live in config, never hardcoded (cf. decayHalfLifeDays,
+ * recallMinSimilarity).
+ *
+ * A value that is PRESENT but rejected (non-number, non-finite, or ≤ 0) warns
+ * — e.g. an operator who sets `preflightAttempts: 0` intending "don't retry"
+ * would otherwise silently get the default 3. (Single-try is
+ * `preflightAttempts: 1`, so there's no functional gap — this just makes the
+ * silent coercion visible, consistent with the fail-explicit pattern.)
+ */
+function readPositiveConfig(config, key, def) {
+    const v = config[key];
+    if (v === undefined)
+        return def;
+    if (typeof v === "number" && Number.isFinite(v) && v > 0)
+        return v;
+    console.warn(`[hicortex] config "${key}" = ${String(v)} is not a positive finite number — using default ${def}.`);
+    return def;
+}
 const NIGHTLY_LOG_MAX_BYTES = 1024 * 1024; // 1 MB — years of normal runs
 /**
  * Keep ~/.hicortex/nightly.log bounded. The launchd plist and systemd unit
@@ -489,16 +510,72 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
     const authToken = config.authToken;
     console.log(`[hicortex] Client nightly starting${dryRun ? " (dry run)" : ""}`);
     console.log(`[hicortex] Server: ${serverUrl}`);
-    // Verify server is reachable
-    try {
-        const resp = await fetch(`${serverUrl}/health`, { signal: AbortSignal.timeout(5000) });
-        if (!resp.ok)
-            throw new Error(`HTTP ${resp.status}`);
-        const data = await resp.json();
-        console.log(`[hicortex] Server OK: v${data.version}, ${data.memories} memories`);
+    // Verify server is reachable. Retry so a client waking from sleep (its
+    // network link not yet re-established) or a transient blip doesn't abort
+    // the whole run — the pre-flight only needs the link back, which can take
+    // ~1 min after wake.
+    //
+    // Config-overridable (#163): a wired Pi vs a sleeping laptop want different
+    // values. Defaults: 15s per-attempt timeout, 3 attempts, 60s gap.
+    //
+    // WALL-CLOCK NOTE: setTimeout and AbortSignal.timeout do NOT advance while
+    // macOS is asleep, so the ~2m45s worst case (3×15s + 2×60s) is wall-clock-
+    // optimistic — a sleeping laptop can straddle sleep cycles and the real
+    // elapsed time can exceed it. Not a defect: the capture lock isn't held
+    // during the retry and the cursor design is dup-over-loss, so a late success
+    // is harmless. Just don't treat 2m45s as a hard wall-clock bound.
+    const PREFLIGHT_TIMEOUT_MS = readPositiveConfig(config, "preflightTimeoutMs", 15_000);
+    const PREFLIGHT_ATTEMPTS = Math.max(1, Math.floor(readPositiveConfig(config, "preflightAttempts", 3)));
+    const PREFLIGHT_RETRY_GAP_MS = readPositiveConfig(config, "preflightRetryGapMs", 60_000);
+    let reachable = false;
+    for (let attempt = 1; attempt <= PREFLIGHT_ATTEMPTS; attempt++) {
+        try {
+            const resp = await fetch(`${serverUrl}/health`, { signal: AbortSignal.timeout(PREFLIGHT_TIMEOUT_MS) });
+            if (!resp.ok)
+                throw new Error(`HTTP ${resp.status}`);
+            const data = await resp.json();
+            console.log(`[hicortex] Server OK: v${data.version}, ${data.memories} memories`);
+            reachable = true;
+            break;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (attempt < PREFLIGHT_ATTEMPTS) {
+                console.error(`[hicortex] Server unreachable at ${serverUrl} (attempt ${attempt}/${PREFLIGHT_ATTEMPTS}): ${msg} — retrying in ${PREFLIGHT_RETRY_GAP_MS / 1000}s`);
+                await new Promise((r) => setTimeout(r, PREFLIGHT_RETRY_GAP_MS));
+            }
+            else {
+                console.error(`[hicortex] Server unreachable at ${serverUrl} after ${PREFLIGHT_ATTEMPTS} attempts: ${msg}`);
+            }
+        }
     }
-    catch (err) {
-        console.error(`[hicortex] Server unreachable at ${serverUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    if (!reachable) {
+        // The abort was invisible for weeks once: a plain `return` let the oneshot
+        // exit 0, so systemd/launchd recorded success and the capture gap went
+        // unnoticed. Exit non-zero so `systemctl --user status` / launchd show the
+        // unit failed (safe — this is a timer-driven oneshot with no Restart=, so
+        // no loop), and fire the telemetry ping (ok=false) so the abort is
+        // distinguishable from "powered off / uninstalled" in the activity aggregate.
+        process.exitCode = 1;
+        if (!dryRun && (0, telemetry_js_1.isTelemetryEnabled)(config)) {
+            await (0, telemetry_js_1.sendTelemetry)({
+                id: (0, telemetry_js_1.getTelemetryId)(stateDir),
+                v: VERSION,
+                pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
+                event: "nightly",
+                mode: "client",
+                // `agent` deliberately OMITTED: no transcripts have been read at
+                // pre-flight, so the type is genuinely unknown. The admin summary
+                // buckets a missing agent as "?" (distinct from cc/pi/oc/mixed) —
+                // sending "cc" here would miscount an aborting Hermes/OC-only client
+                // as a cc install. The success-path ping sends the real type once
+                // session sources are known.
+                mem: 0,
+                lessons: 0,
+                sessions: 0,
+                ok: false,
+            });
+        }
         console.error(`[hicortex] Aborting. Will retry next run.`);
         return; // Don't update last-run so we retry
     }

package/dist/pi-transcript-reader.d.ts

@@ -19,7 +19,7 @@
  *     --home-alice-projects-myagent--/
  *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
  *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
- *     --home-agents-Development-MAIC--/
+ *     --home-user-projects-ExampleApp--/
  *       ...
  *
  * The encoded-cwd uses double-dash separators: /home/alice/projects/myagent

package/dist/pi-transcript-reader.js

@@ -20,7 +20,7 @@
  *     --home-alice-projects-myagent--/
  *       2026-04-10T18-37-44-615Z_<uuid>.jsonl
  *       2026-04-11T07-51-28-282Z_<uuid>.jsonl
- *     --home-agents-Development-MAIC--/
+ *     --home-user-projects-ExampleApp--/
  *       ...
  *
  * The encoded-cwd uses double-dash separators: /home/alice/projects/myagent

package/dist/recall-index.d.ts

@@ -75,8 +75,8 @@ export declare function formatIndexLine(r: MemorySearchResult & {
  * NOTE: FTS hits BYPASS the similarity floor, so raising the floor shifts
  * weight toward FTS-sourced entries. In practice FTS is currently inert on
  * real prompts — eval #3 had 0 FTS rows / 2,208 (2,203 vector + 5 graph), and
- * a 12-prompt live bedrock sample returned 96/96 vector — so the floor change
- * is safe as measured. But FTS quality is unmeasured; if FTS starts firing
+ * a relevance sample returned 96/96 vector — so the floor change is safe as
+ * measured. But FTS quality is unmeasured; if FTS starts firing
  * (e.g. as #205's fielded-BM25 retune beds in), give it its own eval.
  */
 export declare function passesRelevanceGate(r: MemorySearchResult, minSimilarity: number): boolean;

package/dist/recall-index.js

@@ -129,8 +129,8 @@ function formatIndexLine(r, maxLen = DEFAULT_TITLE_CHARS) {
  * NOTE: FTS hits BYPASS the similarity floor, so raising the floor shifts
  * weight toward FTS-sourced entries. In practice FTS is currently inert on
  * real prompts — eval #3 had 0 FTS rows / 2,208 (2,203 vector + 5 graph), and
- * a 12-prompt live bedrock sample returned 96/96 vector — so the floor change
- * is safe as measured. But FTS quality is unmeasured; if FTS starts firing
+ * a relevance sample returned 96/96 vector — so the floor change is safe as
+ * measured. But FTS quality is unmeasured; if FTS starts firing
  * (e.g. as #205's fielded-BM25 retune beds in), give it its own eval.
  */
 function passesRelevanceGate(r, minSimilarity) {

package/dist/redact.d.ts

@@ -5,8 +5,8 @@
  * Why this exists:
  *   - Session transcripts contain tool output: file reads, command output,
  *     env var dumps. These regularly contain API keys, tokens, and paths.
- *   - The distillation LLM is often remote (e.g., Ollama on MBP via
- *     Tailscale). Secrets in the transcript travel over the network.
+ *   - The distillation LLM is often remote (e.g., a mesh VPN link to a
+ *     GPU box). Secrets in the transcript travel over the network.
  *   - Even if the LLM correctly classifies the memory as SENSITIVE, the
  *     secret is already stored and searchable via hicortex_search.
  *   - Redaction runs BEFORE the LLM sees the text, eliminating the risk.

package/dist/redact.js

@@ -6,8 +6,8 @@
  * Why this exists:
  *   - Session transcripts contain tool output: file reads, command output,
  *     env var dumps. These regularly contain API keys, tokens, and paths.
- *   - The distillation LLM is often remote (e.g., Ollama on MBP via
- *     Tailscale). Secrets in the transcript travel over the network.
+ *   - The distillation LLM is often remote (e.g., a mesh VPN link to a
+ *     GPU box). Secrets in the transcript travel over the network.
  *   - Even if the LLM correctly classifies the memory as SENSITIVE, the
  *     secret is already stored and searchable via hicortex_search.
  *   - Redaction runs BEFORE the LLM sees the text, eliminating the risk.

package/dist/telemetry.d.ts

@@ -6,7 +6,11 @@
  *   v        — package version
  *   pv       — payload schema version
  *   mode     — server or client
- *   agent    — cc, pi, oc, or mixed (detected from session sources)
+ *   agent    — cc, pi, oc, or mixed (detected from session sources); OMITTED
+ *              when the agent type is genuinely unknown (pre-flight abort — no
+ *              transcripts read yet). The admin summary buckets a missing agent
+ *              as "?", distinct from any real type, so an aborting Hermes/OC
+ *              client is never miscounted as "cc".
  *   mem      — total memory count
  *   lessons  — total lesson count
  *   sessions — sessions distilled this run
@@ -41,7 +45,14 @@ export interface TelemetryPayload {
     id: string;
     v: string;
     mode: string;
-    agent: string;
+    /**
+     * Agent type detected from session sources (cc/pi/oc/mixed). OMITTED when
+     * unknown — currently only the pre-flight abort path, where no transcripts
+     * have been read yet (sending "cc" there mislabelled aborting Hermes/OC
+     * clients in the admin aggregate). The admin summary buckets a missing agent
+     * as "?", which is the honest signal.
+     */
+    agent?: string;
     mem: number;
     lessons: number;
     sessions: number;

package/dist/telemetry.js

@@ -7,7 +7,11 @@
  *   v        — package version
  *   pv       — payload schema version
  *   mode     — server or client
- *   agent    — cc, pi, oc, or mixed (detected from session sources)
+ *   agent    — cc, pi, oc, or mixed (detected from session sources); OMITTED
+ *              when the agent type is genuinely unknown (pre-flight abort — no
+ *              transcripts read yet). The admin summary buckets a missing agent
+ *              as "?", distinct from any real type, so an aborting Hermes/OC
+ *              client is never miscounted as "cc".
  *   mem      — total memory count
  *   lessons  — total lesson count
  *   sessions — sessions distilled this run

package/dist/types.d.ts

@@ -54,7 +54,7 @@ export interface MemorySearchResult {
     access_count: number;
     memory_type: string;
     project: string | null;
-    /** Origin agent (e.g. "hermes/atlas", "cc/mbp5") — surfaced in the recall
+    /** Origin agent (e.g. "hermes/profile-name", "cc/machine-name") — surfaced in the recall
      *  one-liner so agents can calibrate trust (#202 provenance). Optional on the
      *  result type (matches how `domain` is threaded) to avoid breaking fixtures. */
     source_agent?: string | null;
@@ -260,6 +260,28 @@ export interface HicortexConfig {
      * near its lower tail). See domains.example.json for a worked example.
      */
     weakPrimaryFloor?: number;
+    /**
+     * Per-attempt timeout (ms) for the CLIENT nightly's pre-flight GET /health
+     * check before capturing (#163). Default 15000. Overridable per machine —
+     * a wired Pi vs a sleeping laptop want different values. See runClientNightly
+     * in nightly.ts. No effect in server mode (server capture is localhost).
+     */
+    preflightTimeoutMs?: number;
+    /**
+     * Max attempts for the client nightly's pre-flight /health retry loop (#163).
+     * Default 3. Attempts are spaced preflightRetryGapMs apart; on exhaustion the
+     * run aborts with a non-zero exit code and an ok=false telemetry ping so the
+     * failure is visible to systemd/launchd and the activity aggregate.
+     */
+    preflightAttempts?: number;
+    /**
+     * Gap (ms) between pre-flight /health attempts in the client nightly (#163).
+     * Default 60000. Wall-clock-optimistic on a sleeping laptop — setTimeout does
+     * NOT advance while macOS is asleep, so real elapsed time can exceed the
+     * nominal worst case. Not a defect (capture lock isn't held; cursor design is
+     * dup-over-loss); just don't treat the nominal sum as a hard bound.
+     */
+    preflightRetryGapMs?: number;
 }
 /** A config-owned life-sphere domain (see HicortexConfig.domains). */
 export interface DomainDef {

package/hermes-plugin/hicortex/config.py

@@ -27,7 +27,7 @@ CONFIG_SCHEMA: list[dict[str, Any]] = [
         "description": (
             "URL of the Hicortex memory server. On the server host use "
             "http://localhost:8787; on other machines use the server's "
-            "Tailscale hostname, e.g. http://memory-server:8787."
+            "private hostname, e.g. http://memory-server:8787."
         ),
         "default": "http://localhost:8787",
         "required": True,

package/hermes-plugin/hicortex/provider.py

@@ -210,7 +210,8 @@ class HicortexProvider(MemoryProvider):
             self._recall_limit = 5
         self._privacy = cfg.get("privacy_filter", "WORK,PERSONAL")
         # #203 scope: declared knowledge domains for this role-bound agent
-        # (e.g. Lenny → Health). Soft affinity boost on recall; never excludes.
+        # (e.g. a health-focused agent → Health). Soft affinity boost on
+        # recall; never excludes.
         _md_raw = cfg.get("mission_domains") or ""
         self._mission_domains = [d.strip() for d in _md_raw.split(",") if d.strip()]
         self._agent_name = _resolve_agent_name(cfg)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "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": {