@gamaze/hicortex 0.15.0 → 0.15.1

package/README.md

@@ -164,6 +164,7 @@ npx @gamaze/hicortex context edit <name>       # Edit a context section in $EDIT
 npx @gamaze/hicortex context show --agent <id> # Show a specific agent's resolved context (0.13)
 npx @gamaze/hicortex init --agent-name <name>  # Opt in to a per-agent context id (default: unset — shared global context)
 npx @gamaze/hicortex init --agent-name ""      # Clear it back to global context
+npx @gamaze/hicortex telemetry                 # Show exactly what anonymous telemetry sends
 npx @gamaze/hicortex status                    # Show config, DB stats
 npx @gamaze/hicortex uninstall                 # Remove CC integration (keeps DB)
 ```
@@ -221,7 +222,7 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `supersessionMinSimilarity` | Minimum cosine similarity for a nightly supersession candidate pair (default: 0.80) |
 | `supersessionMaxCalls` | Max classify-tier LLM calls the nightly's supersession stage spends per run (default: 30) |
 | `supersessionPenalty` | Multiplier applied to a superseded memory's `base_strength` (default: 0.5) |
-| `telemetry` | Anonymous usage telemetry, `false` to opt out |
+| `telemetry` | Anonymous usage telemetry. **On by default and not written into config by `init`** — add `"telemetry": false` yourself (or set `HICORTEX_TELEMETRY=off`) to opt out. Inspect exactly what is sent with `hicortex telemetry` |
 
 Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze.com/docs/configuration.html)
 

package/dist/cli.js

@@ -185,6 +185,17 @@ switch (command) {
         });
         break;
     }
+    case "telemetry": {
+        // Transparency surface: reports what anonymous telemetry sends. Read-only
+        // by design — opting out is a deliberate config/env edit (0.15.1).
+        import("./telemetry-cli.js").then(({ runTelemetryCommand }) => {
+            runTelemetryCommand(process.argv.slice(3));
+        }).catch((err) => {
+            console.error("[hicortex] telemetry command failed:", err instanceof Error ? err.message : err);
+            process.exit(1);
+        });
+        break;
+    }
     case "status":
         import("./status.js").then(({ runStatus }) => {
             runStatus().catch((err) => {
@@ -246,6 +257,7 @@ Commands:
   lessons-context Fetch lessons and print Markdown to stdout (CC SessionStart hook)
   recall-hook    Pushed recall index for the current prompt (CC UserPromptSubmit/SessionStart hook)
   context         Standing context layer (show|edit) against the configured server
+  telemetry       Show exactly what anonymous telemetry sends (read-only)
   status          Show current configuration and stats
   uninstall       Remove CC integration (preserves DB)
 

package/dist/init.js

@@ -1296,6 +1296,11 @@ async function runInit(options = {}) {
         console.log(`  ✓ Removed old static lessons block from ${claudeMdPath} — lessons now injected at session start`);
     }
     console.log("\n✓ Hicortex setup complete!\n");
+    // Telemetry disclosure at install time (informed consent, best practice):
+    // opt-out telemetry is only acceptable if the user is TOLD about it.
+    console.log("Anonymous usage telemetry (aggregate counts only, no content) is on by default —");
+    console.log("see exactly what is sent with `hicortex telemetry`; to opt out, add");
+    console.log('"telemetry": false to ~/.hicortex/config.json or set HICORTEX_TELEMETRY=off.\n');
     console.log("Next steps:");
     console.log("  1. Restart Claude Code to pick up the new MCP server and SessionStart hook");
     if (d.hermesFound) {
@@ -1461,6 +1466,11 @@ async function runClientInit(serverUrl, agentName) {
         setupHermes(serverUrl, authToken);
     }
     console.log("\n✓ Hicortex client setup complete!\n");
+    // Telemetry disclosure at install time (informed consent, best practice):
+    // opt-out telemetry is only acceptable if the user is TOLD about it.
+    console.log("Anonymous usage telemetry (aggregate counts only, no content) is on by default —");
+    console.log("see exactly what is sent with `hicortex telemetry`; to opt out, add");
+    console.log('"telemetry": false to ~/.hicortex/config.json or set HICORTEX_TELEMETRY=off.\n');
     console.log("How it works:");
     console.log("  • MCP tools (search, context, ingest) talk to the remote server");
     console.log("  • Nightly pipeline denoises CC transcripts, POSTs to server for distillation");

package/dist/nightly.js

@@ -423,15 +423,28 @@ async function runNightly(options = {}) {
                 ocBatches.length > 0 && "oc",
             ].filter(Boolean);
             const agentType = kinds.length > 1 ? "mixed" : (kinds[0] ?? "cc");
+            // Adoption aggregates (0.15.1): corpus-wide exposure vs use. uses/shown
+            // is the recall-quality signal; cold is the never-touched share.
+            const adoption = db
+                .prepare(`SELECT COALESCE(SUM(shown_count), 0) AS shown,
+                  COALESCE(SUM(access_count), 0) AS uses,
+                  SUM(CASE WHEN COALESCE(shown_count, 0) = 0
+                            AND COALESCE(access_count, 0) = 0 THEN 1 ELSE 0 END) AS cold
+             FROM memories`)
+                .get();
             await (0, telemetry_js_1.sendTelemetry)({
                 id: (0, telemetry_js_1.getTelemetryId)(stateDir),
                 v: VERSION,
+                pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
                 mode: "server",
                 agent: agentType,
                 mem: storage.countMemories(db),
                 lessons: storage.getLessons(db, 365).length,
                 sessions: batches.length,
                 ok: !hadTransientFailure,
+                shown: adoption.shown,
+                uses: adoption.uses,
+                cold: adoption.cold,
             });
         }
     }
@@ -554,12 +567,14 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
         await (0, telemetry_js_1.sendTelemetry)({
             id: (0, telemetry_js_1.getTelemetryId)(stateDir),
             v: VERSION,
+            pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
             mode: "client",
             agent: agentType,
             mem: memoriesIngested,
             lessons: 0, // client doesn't have direct DB access
             sessions: batches.length,
             ok: !hadTransientFailure,
+            // No adoption fields: a client install has no local DB to aggregate.
         });
     }
 }

package/dist/telemetry-cli.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `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.
+ */
+export declare function runTelemetryCommand(args: string[]): void;

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/package.json

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