@gamaze/hicortex 0.14.4 → 0.15.1

package/dist/telemetry-cli.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * `hicortex telemetry` — transparency surface for anonymous usage telemetry.
+ *
+ * Read-only BY DESIGN (owner decision 30.07.2026). It shows the exact payload
+ * and both documented ways to switch telemetry off, but it does not flip the
+ * switch itself: the `telemetry` key is deliberately NOT scaffolded into
+ * config.json, and opting out is a deliberate edit the operator makes. Turning
+ * it off must stay completely possible and completely documented — just not a
+ * one-keystroke default-path action.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTelemetryCommand = runTelemetryCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const paths_js_1 = require("./paths.js");
+const telemetry_js_1 = require("./telemetry.js");
+function readConfig(home) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, "config.json"), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function printHowToDisable(home) {
+    console.log("To turn it off (either one works, both are permanent):");
+    console.log(`  1. add  "telemetry": false  to ${(0, node_path_1.join)(home, "config.json")}`);
+    console.log("  2. or set  HICORTEX_TELEMETRY=off  in the environment");
+}
+function runTelemetryCommand(args) {
+    const home = (0, paths_js_1.hicortexHome)();
+    const sub = args[0] ?? "status";
+    if (sub === "on" || sub === "off") {
+        // Intentionally not a write command — see the module docstring.
+        console.log(`[hicortex] telemetry is not toggled by this command; it reports state only.`);
+        printHowToDisable(home);
+        return;
+    }
+    if (sub !== "status") {
+        console.error(`[hicortex] telemetry: unknown subcommand '${sub}' (only 'status' is supported)`);
+        process.exit(1);
+    }
+    const config = readConfig(home);
+    const reason = (0, telemetry_js_1.telemetryDisabledReason)(config);
+    const mode = config?.mode === "client" ? "client" : "server";
+    console.log("Hicortex telemetry");
+    console.log("──────────────────────────────────────────");
+    if (reason) {
+        console.log(`Status:    DISABLED (via ${reason === "env" ? "HICORTEX_TELEMETRY env var" : 'config.json "telemetry": false'})`);
+        console.log("Nothing is sent. Remove that setting to re-enable.");
+        return;
+    }
+    console.log("Status:    ENABLED (anonymous, aggregate only) — the default");
+    console.log(`Endpoint:  ${telemetry_js_1.TELEMETRY_URL}`);
+    console.log("When:      once at the end of each full nightly run");
+    console.log("");
+    console.log("Exactly what is sent (counts from this install; values vary per run):");
+    const example = {
+        id: (0, telemetry_js_1.getTelemetryId)(home),
+        v: "<package version>",
+        pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
+        mode,
+        agent: "<cc|hermes|pi|oc|mixed>",
+        mem: "<total memories>",
+        lessons: "<total lessons>",
+        sessions: "<sessions captured this run>",
+        ok: "<nightly succeeded>",
+    };
+    if (mode === "server") {
+        example.shown = "<sum of shown_count>";
+        example.uses = "<sum of access_count>";
+        example.cold = "<memories never shown or used>";
+    }
+    console.log(JSON.stringify(example, null, 2));
+    console.log("");
+    console.log("NOT sent: memory content, prompts, file paths, project names,");
+    console.log("hostnames, tokens, or IP addresses (the server stores no IPs).");
+    console.log("Every install sends the same fields — nothing marks yours as special.");
+    console.log("");
+    printHowToDisable(home);
+}

package/dist/telemetry.d.ts

@@ -1,18 +1,32 @@
 /**
  * Anonymous telemetry — sends aggregate stats after each nightly run.
  *
- * What's sent (8 fields, all aggregate):
+ * What's sent (all aggregate, payload version 2 since 0.15.1):
  *   id       — random UUID, generated once on first run, stored in state.json
  *   v        — package version
+ *   pv       — payload schema version
  *   mode     — server or client
  *   agent    — cc, pi, oc, or mixed (detected from session sources)
  *   mem      — total memory count
  *   lessons  — total lesson count
  *   sessions — sessions distilled this run
  *   ok       — nightly succeeded (true/false)
+ *   shown    — sum of shown_count (server mode only)
+ *   uses     — sum of access_count (server mode only)
+ *   cold     — memories never shown and never used (server mode only)
+ *
+ * Every install sends the SAME fields — nothing marks an install as special
+ * (a rare label would be a fingerprint, i.e. no longer anonymous). Excluding
+ * the maintainer's own installs from adoption stats is an analysis-side
+ * concern, done by anonymous id at the admin endpoint.
  *
  * What's NOT sent:
- *   No personal data, no session content, no file paths, no IPs stored.
+ *   No personal data, no session content, no file paths, no project names,
+ *   no hostnames, no tokens. The server stores no IPs.
+ *
+ * Inspect / control:
+ *   `hicortex telemetry` prints the exact payload shape and current state;
+ *   `hicortex telemetry off` / `on` flips it.
  *
  * Opt-out:
  *   Set "telemetry": false in ~/.hicortex/config.json
@@ -21,6 +35,7 @@
  * The ping is fire-and-forget with a 5s timeout. If it fails, nothing
  * happens — the nightly result is unaffected.
  */
+export declare const TELEMETRY_URL = "https://hicortex.gamaze.com/api/telemetry";
 export interface TelemetryPayload {
     id: string;
     v: string;
@@ -30,6 +45,18 @@ export interface TelemetryPayload {
     lessons: number;
     sessions: number;
     ok: boolean;
+    /** Payload schema version (2 = adoption fields, 0.15.1). Absent = v1. */
+    pv?: number;
+    /**
+     * Adoption aggregates (server mode only — a client install has no DB).
+     * `shown`/`uses` are corpus-wide sums of shown_count/access_count; their
+     * ratio (uses per showing) is the recall-quality signal. `cold` counts
+     * memories never shown AND never used. Aggregate counts only — no content,
+     * no ids, nothing per-memory.
+     */
+    shown?: number;
+    uses?: number;
+    cold?: number;
 }
 /**
  * Check if telemetry is enabled. Disabled by:
@@ -42,6 +69,13 @@ export declare function isTelemetryEnabled(config: Record<string, unknown> | nul
  * Generated once, stored in state.json, never linked to any personal info.
  */
 export declare function getTelemetryId(stateDir: string): string;
+/** Payload schema version sent by this release. */
+export declare const TELEMETRY_PAYLOAD_VERSION = 2;
+/**
+ * Why telemetry is off, or null when it is on. Exposed so `hicortex telemetry`
+ * can tell the operator WHICH switch is in effect (config vs env).
+ */
+export declare function telemetryDisabledReason(config: Record<string, unknown> | null): "config" | "env" | null;
 /**
  * Send anonymous telemetry. Fire-and-forget — failures are silently ignored.
  */

package/dist/telemetry.js

@@ -2,18 +2,32 @@
 /**
  * Anonymous telemetry — sends aggregate stats after each nightly run.
  *
- * What's sent (8 fields, all aggregate):
+ * What's sent (all aggregate, payload version 2 since 0.15.1):
  *   id       — random UUID, generated once on first run, stored in state.json
  *   v        — package version
+ *   pv       — payload schema version
  *   mode     — server or client
  *   agent    — cc, pi, oc, or mixed (detected from session sources)
  *   mem      — total memory count
  *   lessons  — total lesson count
  *   sessions — sessions distilled this run
  *   ok       — nightly succeeded (true/false)
+ *   shown    — sum of shown_count (server mode only)
+ *   uses     — sum of access_count (server mode only)
+ *   cold     — memories never shown and never used (server mode only)
+ *
+ * Every install sends the SAME fields — nothing marks an install as special
+ * (a rare label would be a fingerprint, i.e. no longer anonymous). Excluding
+ * the maintainer's own installs from adoption stats is an analysis-side
+ * concern, done by anonymous id at the admin endpoint.
  *
  * What's NOT sent:
- *   No personal data, no session content, no file paths, no IPs stored.
+ *   No personal data, no session content, no file paths, no project names,
+ *   no hostnames, no tokens. The server stores no IPs.
+ *
+ * Inspect / control:
+ *   `hicortex telemetry` prints the exact payload shape and current state;
+ *   `hicortex telemetry off` / `on` flips it.
  *
  * Opt-out:
  *   Set "telemetry": false in ~/.hicortex/config.json
@@ -23,12 +37,14 @@
  * happens — the nightly result is unaffected.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TELEMETRY_PAYLOAD_VERSION = exports.TELEMETRY_URL = void 0;
 exports.isTelemetryEnabled = isTelemetryEnabled;
 exports.getTelemetryId = getTelemetryId;
+exports.telemetryDisabledReason = telemetryDisabledReason;
 exports.sendTelemetry = sendTelemetry;
 const node_crypto_1 = require("node:crypto");
 const state_js_1 = require("./state.js");
-const TELEMETRY_URL = "https://hicortex.gamaze.com/api/telemetry";
+exports.TELEMETRY_URL = "https://hicortex.gamaze.com/api/telemetry";
 /**
  * Check if telemetry is enabled. Disabled by:
  *   - config.telemetry === false
@@ -59,10 +75,24 @@ function getTelemetryId(stateDir) {
     }, stateDir);
     return id;
 }
+/** Payload schema version sent by this release. */
+exports.TELEMETRY_PAYLOAD_VERSION = 2;
+/**
+ * Why telemetry is off, or null when it is on. Exposed so `hicortex telemetry`
+ * can tell the operator WHICH switch is in effect (config vs env).
+ */
+function telemetryDisabledReason(config) {
+    const env = process.env.HICORTEX_TELEMETRY?.toLowerCase();
+    if (env === "off" || env === "false" || env === "0")
+        return "env";
+    if (config?.telemetry === false)
+        return "config";
+    return null;
+}
 /**
  * Send anonymous telemetry. Fire-and-forget — failures are silently ignored.
  */
-async function sendTelemetry(payload, serverUrl = TELEMETRY_URL) {
+async function sendTelemetry(payload, serverUrl = exports.TELEMETRY_URL) {
     try {
         await fetch(serverUrl, {
             method: "POST",

package/dist/types.d.ts

@@ -108,6 +108,21 @@ export interface ConsolidationReport {
             heuristic_fallback?: number;
             failed: number;
         };
+        /** Supersession detection (#191 Phase B) — runs after linking, before decay/prune. */
+        supersession?: {
+            /** Decision/correction-shaped candidates examined this run. */
+            scanned: number;
+            /** Older-neighbor pairs actually sent to the classify-tier LLM. */
+            evaluated: number;
+            /** Pairs the LLM judged superseded — a `superseded_by` link was created. */
+            superseded: number;
+            /** Pairs skipped on a parse/infra error (retried naturally next night). */
+            skipped_infra: number;
+            /** Pairs skipped because a superseded_by link already existed (either direction). */
+            skipped_idempotent: number;
+            /** supersessionCursor after this run (unchanged in dry-run). */
+            cursor: number;
+        };
         decay_prune?: {
             candidates: number;
             pruned: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.14.4",
+  "version": "0.15.1",
   "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": {
@@ -37,6 +37,7 @@
     "build": "rm -rf dist && tsc",
     "test": "vitest run",
     "test:watch": "vitest",
+    "eval": "node dist/eval/run-eval.js",
     "prepack": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true",
     "prepublishOnly": "npm run build && rm -rf ./hermes-plugin && mkdir -p ./hermes-plugin && cp -r ../../hermes-plugin/hicortex ./hermes-plugin/ && find ./hermes-plugin -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true"
   },