@gamaze/hicortex 0.15.0 → 0.15.2

package/README.md

@@ -56,9 +56,9 @@ The plugin connects to `http://127.0.0.1:8787` by default. For a remote server,
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 20+
 - **Server mode:** LLM required — Ollama 9b+ (recommended), Claude CLI, or API key (Anthropic, OpenAI, etc.). ~500MB disk for database + embedding model.
-- **Client mode:** No local LLM needed. Node.js 18+ and network access to the server are sufficient.
+- **Client mode:** No local LLM needed. Node.js 20+ and network access to the server are sufficient.
 - **OC plugin:** Requires a running Hicortex server. No local LLM, database, or embedder in the plugin itself.
 
 ## What Happens Automatically
@@ -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)
 ```
@@ -209,6 +210,13 @@ 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 |
+| `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) |
+| `scoreRecencyWeight` | Weight of the slow recency curve (default: 0.15) |
+| `freshnessBoostDays` | Fresh-memory window: new memories rank higher for this many days (default: 7) |
+| `freshnessBoostWeight` | Size of the fresh-memory bonus at age 0, fading linearly to 0 at the window edge (default: 0.15; set 0 to disable) |
+| `supersededDemotion` | Score multiplier for a memory a later decision reversed (default: 0.50) |
 | `decayHalfLifeDays` | Memory decay half-life in days at reference importance (default: 365). Larger = slower forgetting; importance, access, and links slow it further |
 | `searchLimit` / `recentLimit` | Default result counts for search (8) and recent (12) |
 | `recentWindowDays` | Candidate window for recent recall (default: 180) |
@@ -221,7 +229,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/consolidate.d.ts

@@ -135,12 +135,9 @@ export declare function classifyRelationship(source: Memory, target: Memory, sim
 export declare const DEFAULT_SUPERSESSION_MIN_SIMILARITY = 0.8;
 /** Default max classify-tier LLM calls (pairs evaluated) spent per nightly run. */
 export declare const DEFAULT_SUPERSESSION_MAX_CALLS = 30;
-/** Default multiplier applied to a superseded memory's base_strength. */
-export declare const DEFAULT_SUPERSESSION_PENALTY = 0.5;
 export interface SupersessionOptions {
     minSimilarity?: number;
     maxCalls?: number;
-    penalty?: number;
 }
 export interface SupersessionStageResult {
     scanned: number;

package/dist/consolidate.js

@@ -38,7 +38,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SUPERSESSION_PENALTY = exports.DEFAULT_SUPERSESSION_MAX_CALLS = exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = void 0;
+exports.DEFAULT_SUPERSESSION_MAX_CALLS = exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = void 0;
 exports.isContradictionCandidate = isContradictionCandidate;
 exports.parseJsonLenient = parseJsonLenient;
 exports.rebuildContentModuleIndex = rebuildContentModuleIndex;
@@ -850,9 +850,7 @@ exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = 0.8;
 /** Default max classify-tier LLM calls (pairs evaluated) spent per nightly run. */
 exports.DEFAULT_SUPERSESSION_MAX_CALLS = 30;
 /** Default multiplier applied to a superseded memory's base_strength. */
-exports.DEFAULT_SUPERSESSION_PENALTY = 0.5;
 /** Floor under which a superseded memory's base_strength never drops. */
-const SUPERSESSION_STRENGTH_FLOOR = 0.1;
 /** Neighbor pool size before shape/older/similarity filtering narrows to top 5. */
 const SUPERSESSION_NEIGHBOR_POOL = 15;
 /** Older-neighbor pairs kept per candidate after filtering. */
@@ -965,7 +963,6 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
     };
     const minSimilarity = validNumber(options.minSimilarity, exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY, (n) => n > 0 && n <= 1);
     const maxCalls = validNumber(options.maxCalls, exports.DEFAULT_SUPERSESSION_MAX_CALLS, (n) => n >= 0);
-    const penalty = validNumber(options.penalty, exports.DEFAULT_SUPERSESSION_PENALTY, (n) => n > 0 && n <= 1);
     const startCursor = (0, state_js_1.loadState)(stateDir).supersessionCursor ?? 0;
     const rows = db
         .prepare(`SELECT rowid AS __rowid, * FROM memories
@@ -1011,9 +1008,13 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
             }
             if (verdict) {
                 const cosine = (0, retrieval_js_1.l2ToCosine)(neighbor.distance);
+                // The link IS the signal (0.15.2): retrieval demotes superseded
+                // memories via an explicit scoring multiplier (supersededDemotion,
+                // retrieval.ts). The old base_strength penalty was retired because it
+                // (a) fought the config-tunable strength weight and (b) leaked into
+                // prune eligibility — a reversed decision must rank lower, not edge
+                // toward deletion.
                 storage.addLink(db, neighbor.id, candidate.id, "superseded_by", cosine);
-                const newStrength = Math.max(SUPERSESSION_STRENGTH_FLOOR, (neighbor.base_strength ?? 0.5) * penalty);
-                storage.updateMemory(db, neighbor.id, { base_strength: newStrength });
                 superseded++;
                 console.log(`[hicortex] Supersession: ${neighbor.id.slice(0, 8)} superseded_by ${candidate.id.slice(0, 8)} (cosine ${cosine.toFixed(3)})`);
             }

package/dist/init.js

@@ -31,6 +31,7 @@ exports.installRecallHooks = installRecallHooks;
 exports.runInit = runInit;
 exports.resolveNightlyHour = resolveNightlyHour;
 const paths_js_1 = require("./paths.js");
+const telemetry_js_1 = require("./telemetry.js");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -40,6 +41,24 @@ const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
 const context_store_js_1 = require("./context-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/** This package's version, for the install lifecycle ping (0.15.2). */
+function pkgVersion() {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/** Read the just-written config so the install ping honours an opt-out. */
+function readHomeConfig(home) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, "config.json"), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
@@ -1296,6 +1315,15 @@ 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');
+    // Install ping (0.15.2) — sent AFTER the disclosure above, opt-out aware, so
+    // the install → first-nightly → retained funnel is measurable. Never blocks:
+    // failures are swallowed inside sendLifecycleEvent.
+    await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
     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 +1489,15 @@ 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');
+    // Install ping (0.15.2) — sent AFTER the disclosure above, opt-out aware, so
+    // the install → first-nightly → retained funnel is measurable. Never blocks:
+    // failures are swallowed inside sendLifecycleEvent.
+    await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
     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/mcp-server.js

@@ -487,8 +487,12 @@ async function startServer(options = {}) {
     // so calibration is a config edit + restart, never a release.
     retrieval.configureDecay({ halfLifeDays: savedConfig?.decayHalfLifeDays });
     const recallCfg = retrieval.configureRecall(savedConfig);
+    const scoringCfg = retrieval.configureScoring(savedConfig);
     console.log(`[hicortex] Recall: k=${recallCfg.searchLimit}/recent=${recallCfg.recentLimit}` +
-        `/window=${recallCfg.recentWindowDays}d/cold=${recallCfg.coldExposureSlots}`);
+        `/window=${recallCfg.recentWindowDays}d/cold=${recallCfg.coldExposureSlots} · ` +
+        `score sim=${scoringCfg.similarity}/str=${scoringCfg.strength}/conn=${scoringCfg.connections}` +
+        `/rec=${scoringCfg.recency}, fresh=${scoringCfg.freshnessBoostWeight}@${scoringCfg.freshnessBoostDays}d, ` +
+        `superseded×${scoringCfg.supersededDemotion}`);
     recallRegistry = new recall_registry_js_1.SessionRecallRegistry({
         reshowTurns: savedConfig?.recallReshowTurns,
     });

package/dist/nightly.js

@@ -214,6 +214,7 @@ async function runNightly(options = {}) {
     // the server's retrieval path (config decayHalfLifeDays, default 365).
     (0, retrieval_js_1.configureDecay)({ halfLifeDays: savedConfig?.decayHalfLifeDays });
     (0, retrieval_js_1.configureRecall)(savedConfig);
+    (0, retrieval_js_1.configureScoring)(savedConfig);
     const modeLabel = captureOnly ? " (capture-only)" : dryRun ? " (dry run)" : "";
     console.log(`[hicortex] Nightly pipeline starting${modeLabel}`);
     if (captureOnly) {
@@ -393,7 +394,6 @@ async function runNightly(options = {}) {
                 }, {
                     minSimilarity: savedConfig?.supersessionMinSimilarity,
                     maxCalls: savedConfig?.supersessionMaxCalls,
-                    penalty: savedConfig?.supersessionPenalty,
                 });
                 console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
                     (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
@@ -423,15 +423,29 @@ 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,
+                event: "nightly",
                 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 +568,15 @@ 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,
+            event: "nightly",
             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/retrieval.d.ts

@@ -2,8 +2,11 @@
  * Retrieval layer with composite scoring, RRF fusion, and graph traversal.
  * Ported from hicortex/retrieval.py — same scoring model and weights.
  *
- * Scoring model:
- *   score = similarity * 0.4 + effective_strength * 0.3 + connection_score * 0.2 + recency * 0.1
+ * Scoring model (weights are config-driven since 0.15.2 — see configureScoring):
+ *   score = similarity * 0.50 + effective_strength * 0.20
+ *         + connection_score * 0.15 + recency * 0.15
+ *         + fresh-memory bonus (≤ 0.15, linear over the first 7 days)
+ *         then × 0.50 if the memory was superseded by a later decision
  *
  * Decay model (B+E+D):
  *   base_decay = derived from decayHalfLifeDays (config; default 365 → ~1-year
@@ -49,6 +52,30 @@ interface RecallDefaults {
  * Returns the resolved values (for logging + tests).
  */
 export declare function configureRecall(config?: Record<string, unknown> | null): RecallDefaults;
+interface ScoringWeights {
+    similarity: number;
+    strength: number;
+    connections: number;
+    recency: number;
+    freshnessBoostDays: number;
+    freshnessBoostWeight: number;
+    supersededDemotion: number;
+}
+/**
+ * Configure scoring weights + ranking knobs from config. Called at boot by the
+ * server and the nightly (alongside configureDecay/configureRecall) so
+ * retrieval and consolidation rank identically. Invalid/absent values keep the
+ * shipped default per key. Returns the resolved set for logging/tests.
+ */
+export declare function configureScoring(config?: Record<string, unknown> | null): ScoringWeights;
+/** Current resolved weights (tests + status output). */
+export declare function getScoringWeights(): ScoringWeights;
+/**
+ * Ids among `candidateIds` that have been superseded by a later memory — i.e.
+ * they are the SOURCE of a `superseded_by` link (stageSupersession links
+ * old → new). One query, not per-candidate.
+ */
+export declare function findSupersededIds(db: Database.Database, candidateIds: string[]): Set<string>;
 /**
  * Convert an L2 distance (as returned by sqlite-vec's vec0 `distance`) to
  * cosine similarity. Valid because our embeddings are L2-normalized
@@ -72,7 +99,9 @@ export declare function effectiveStrength(baseStrength: number, lastAccessed: st
  * Return a composite relevance score in [0, 1] for a candidate memory.
  * Exported for exact-value tests of the similarity component (#145).
  */
-export declare function computeScore(memory: Memory, distance: number, connectionCount: number, maxConnections: number, now: Date): number;
+export declare function computeScore(memory: Memory, distance: number, connectionCount: number, maxConnections: number, now: Date, options?: {
+    superseded?: boolean;
+}): number;
 export interface EmbedFn {
     (text: string): Promise<Float32Array>;
 }

package/dist/retrieval.js

@@ -3,8 +3,11 @@
  * Retrieval layer with composite scoring, RRF fusion, and graph traversal.
  * Ported from hicortex/retrieval.py — same scoring model and weights.
  *
- * Scoring model:
- *   score = similarity * 0.4 + effective_strength * 0.3 + connection_score * 0.2 + recency * 0.1
+ * Scoring model (weights are config-driven since 0.15.2 — see configureScoring):
+ *   score = similarity * 0.50 + effective_strength * 0.20
+ *         + connection_score * 0.15 + recency * 0.15
+ *         + fresh-memory bonus (≤ 0.15, linear over the first 7 days)
+ *         then × 0.50 if the memory was superseded by a later decision
  *
  * Decay model (B+E+D):
  *   base_decay = derived from decayHalfLifeDays (config; default 365 → ~1-year
@@ -53,6 +56,9 @@ exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
 exports.decayConstantForHalfLife = decayConstantForHalfLife;
 exports.configureDecay = configureDecay;
 exports.configureRecall = configureRecall;
+exports.configureScoring = configureScoring;
+exports.getScoringWeights = getScoringWeights;
+exports.findSupersededIds = findSupersededIds;
 exports.l2ToCosine = l2ToCosine;
 exports.effectiveStrength = effectiveStrength;
 exports.computeScore = computeScore;
@@ -110,6 +116,57 @@ function configureRecall(config) {
     };
     return { ...recallDefaults };
 }
+const SCORING_DEFAULTS = {
+    similarity: 0.5,
+    strength: 0.2,
+    connections: 0.15,
+    recency: 0.15,
+    freshnessBoostDays: 7,
+    freshnessBoostWeight: 0.15,
+    supersededDemotion: 0.5,
+};
+let scoringWeights = { ...SCORING_DEFAULTS };
+/**
+ * Configure scoring weights + ranking knobs from config. Called at boot by the
+ * server and the nightly (alongside configureDecay/configureRecall) so
+ * retrieval and consolidation rank identically. Invalid/absent values keep the
+ * shipped default per key. Returns the resolved set for logging/tests.
+ */
+function configureScoring(config) {
+    const num = (key, dflt, min, max) => {
+        const v = Number(config?.[key]);
+        return Number.isFinite(v) && v >= min && v <= max ? v : dflt;
+    };
+    scoringWeights = {
+        similarity: num("scoreSimilarityWeight", SCORING_DEFAULTS.similarity, 0, 1),
+        strength: num("scoreStrengthWeight", SCORING_DEFAULTS.strength, 0, 1),
+        connections: num("scoreConnectionsWeight", SCORING_DEFAULTS.connections, 0, 1),
+        recency: num("scoreRecencyWeight", SCORING_DEFAULTS.recency, 0, 1),
+        freshnessBoostDays: num("freshnessBoostDays", SCORING_DEFAULTS.freshnessBoostDays, 0, 365),
+        freshnessBoostWeight: num("freshnessBoostWeight", SCORING_DEFAULTS.freshnessBoostWeight, 0, 1),
+        supersededDemotion: num("supersededDemotion", SCORING_DEFAULTS.supersededDemotion, 0, 1),
+    };
+    return { ...scoringWeights };
+}
+/** Current resolved weights (tests + status output). */
+function getScoringWeights() {
+    return { ...scoringWeights };
+}
+/**
+ * Ids among `candidateIds` that have been superseded by a later memory — i.e.
+ * they are the SOURCE of a `superseded_by` link (stageSupersession links
+ * old → new). One query, not per-candidate.
+ */
+function findSupersededIds(db, candidateIds) {
+    if (candidateIds.length === 0)
+        return new Set();
+    const placeholders = candidateIds.map(() => "?").join(",");
+    const rows = db
+        .prepare(`SELECT DISTINCT source_id FROM memory_links
+        WHERE relationship = 'superseded_by' AND source_id IN (${placeholders})`)
+        .all(...candidateIds);
+    return new Set(rows.map((r) => r.source_id));
+}
 /**
  * Placeholder L2 distance for candidates that have no measured vector
  * distance (FTS-only hits and graph-discovered neighbors). Chosen so that
@@ -175,7 +232,7 @@ function effectiveStrength(baseStrength, lastAccessed, now, options) {
  * Return a composite relevance score in [0, 1] for a candidate memory.
  * Exported for exact-value tests of the similarity component (#145).
  */
-function computeScore(memory, distance, connectionCount, maxConnections, now) {
+function computeScore(memory, distance, connectionCount, maxConnections, now, options) {
     // TRUE cosine similarity (#145). The old `1 − distance` compressed real
     // cosines (cos 0.8 scored 0.37) and the 0-clamp at that scale flattened
     // everything below cos 0.5 to exactly 0, killing mid-relevance
@@ -193,7 +250,34 @@ function computeScore(memory, distance, connectionCount, maxConnections, now) {
     const connScore = maxConnections > 0 ? connectionCount / maxConnections : 0;
     const hoursSinceCreated = Math.max((now.getTime() - parseTimestamp(memory.created_at).getTime()) / 3_600_000, 0);
     const recency = Math.pow(0.9995, hoursSinceCreated);
-    return similarity * 0.4 + effStrength * 0.3 + connScore * 0.2 + recency * 0.1;
+    const w = scoringWeights;
+    let score = similarity * w.similarity +
+        effStrength * w.strength +
+        connScore * w.connections +
+        recency * w.recency;
+    // Fresh-memory window (#191 Phase B): a memory is born highly available and
+    // settles into the normal ranking over `freshnessBoostDays`. Age is measured
+    // from created_at, which the nightly sets from the session's own date — so a
+    // session captured last night ranks as ~1 day old (not 0), and backfilled
+    // older content correctly gets no boost. The slow
+    // `recency` term above (≈58-day half-life at weight 0.15) could never lift a
+    // day-old memory past a hardened old one — measured case: an exact-match
+    // 1-day-old memory (strength 0.50) lost to an unrelated memory at strength
+    // 0.80. This is an ADDITIVE bonus that decays linearly to zero at the window
+    // edge, so it cannot distort ranking among memories that are all old.
+    const ageDays = hoursSinceCreated / 24;
+    if (memory.created_at && ageDays < scoringWeights.freshnessBoostDays) {
+        const freshness = 1 - ageDays / scoringWeights.freshnessBoostDays;
+        score += freshness * scoringWeights.freshnessBoostWeight;
+    }
+    // Superseded demotion (#191 Phase B): a memory whose decision was reversed by
+    // a later one keeps its content and strength but must not outrank the
+    // decision that replaced it. Applied as an explicit multiplier here rather
+    // than by penalizing base_strength, so ranking weights stay independently
+    // tunable and supersession never nudges a memory toward prune eligibility.
+    if (options?.superseded)
+        score *= scoringWeights.supersededDemotion;
+    return Math.max(0, Math.min(1, score));
 }
 // ---------------------------------------------------------------------------
 // Graph traversal
@@ -357,9 +441,14 @@ async function retrieve(db, embedFn, query, options) {
         : [0]));
     const scored = [];
     const maxRrf = Math.max(...([...rrfScores.values()].length > 0 ? [...rrfScores.values()] : [1]));
+    // One query for the whole candidate set (#191 Phase B): superseded memories
+    // are demoted in computeScore rather than strength-penalized.
+    const supersededIds = findSupersededIds(db, [...candidateMap.keys()]);
     for (const [mid, { mem, distance, source }] of candidateMap) {
         const connCount = connectionCounts.get(mid) ?? 0;
-        const composite = computeScore(mem, distance, connCount, maxConnections, now);
+        const composite = computeScore(mem, distance, connCount, maxConnections, now, {
+            superseded: supersededIds.has(mid),
+        });
         const effStr = effectiveStrength(mem.base_strength ?? 0.5, mem.last_accessed, now, {
             accessCount: mem.access_count ?? 0,
             linkCount: connectionCounts.get(mem.id) ?? 0,
@@ -435,9 +524,12 @@ function searchRecent(db, options) {
         ? [...connectionCounts.values()]
         : [0]));
     const scored = [];
+    const supersededRecent = findSupersededIds(db, candidates.map((c) => c.id));
     for (const mem of candidates) {
         const connCount = connectionCounts.get(mem.id) ?? 0;
-        const score = computeScore(mem, DEFAULT_GRAPH_DISTANCE, connCount, maxConnections, now);
+        const score = computeScore(mem, DEFAULT_GRAPH_DISTANCE, connCount, maxConnections, now, {
+            superseded: supersededRecent.has(mem.id),
+        });
         const effStr = effectiveStrength(mem.base_strength ?? 0.5, mem.last_accessed, now, {
             accessCount: mem.access_count ?? 0,
             linkCount: connectionCounts.get(mem.id) ?? 0,

package/dist/storage.js

@@ -335,6 +335,16 @@ function searchFts(db, query, limit = 10, privacy, sourceAgent, project) {
  * Create a link between two memories.
  */
 function addLink(db, sourceId, targetId, relationship, strength = 0.5) {
+    // Guard: superseded_by is the sole ranking-demotion signal, so never let a
+    // different relationship clobber an existing superseded_by link for the same
+    // pair — INSERT OR REPLACE would otherwise silently remove the demotion.
+    if (relationship !== "superseded_by") {
+        const protectedLink = db
+            .prepare("SELECT 1 FROM memory_links WHERE source_id = ? AND target_id = ? AND relationship = 'superseded_by' LIMIT 1")
+            .get(sourceId, targetId);
+        if (protectedLink)
+            return;
+    }
     db.prepare(`INSERT OR REPLACE INTO memory_links
      (source_id, target_id, relationship, strength, created_at)
      VALUES (?, ?, ?, ?, ?)`).run(sourceId, targetId, relationship, strength, nowIso());

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,33 @@
 /**
  * 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)
+ *   event    — install | nightly | uninstall (which lifecycle moment this is)
+ *
+ * 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 +36,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 +46,25 @@ export interface TelemetryPayload {
     lessons: number;
     sessions: number;
     ok: boolean;
+    /** Payload schema version (2 = adoption fields, 0.15.1). Absent = v1. */
+    pv?: number;
+    /**
+     * Lifecycle event this ping represents (0.15.2). Absent on pre-0.15.2
+     * payloads, which were always nightlies. Active-install counts are derived
+     * from `nightly` events only, so an install/uninstall ping can never look
+     * like activity.
+     */
+    event?: "install" | "nightly" | "uninstall";
+    /**
+     * 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,7 +77,23 @@ 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.
  */
 export declare function sendTelemetry(payload: TelemetryPayload, serverUrl?: string): Promise<void>;
+/**
+ * Send an install/uninstall lifecycle ping (0.15.2). Same anonymous id and
+ * transport as the nightly ping, minus the corpus aggregates (there is nothing
+ * meaningful to count at install time, and at uninstall the numbers are about
+ * to be irrelevant). Fire-and-forget and opt-out-aware like every other ping;
+ * exists so the funnel install → first nightly → retained → uninstall is
+ * measurable instead of inferred.
+ */
+export declare function sendLifecycleEvent(event: "install" | "uninstall", stateDir: string, config: Record<string, unknown> | null, version: string, serverUrl?: string): Promise<void>;

package/dist/telemetry.js

@@ -2,18 +2,33 @@
 /**
  * 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)
+ *   event    — install | nightly | uninstall (which lifecycle moment this is)
+ *
+ * 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 +38,15 @@
  * 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;
+exports.sendLifecycleEvent = sendLifecycleEvent;
 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 +77,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",
@@ -75,3 +107,32 @@ async function sendTelemetry(payload, serverUrl = TELEMETRY_URL) {
         // Silently ignore — telemetry must never affect the nightly result
     }
 }
+/**
+ * Send an install/uninstall lifecycle ping (0.15.2). Same anonymous id and
+ * transport as the nightly ping, minus the corpus aggregates (there is nothing
+ * meaningful to count at install time, and at uninstall the numbers are about
+ * to be irrelevant). Fire-and-forget and opt-out-aware like every other ping;
+ * exists so the funnel install → first nightly → retained → uninstall is
+ * measurable instead of inferred.
+ */
+async function sendLifecycleEvent(event, stateDir, config, version, serverUrl) {
+    if (!isTelemetryEnabled(config))
+        return;
+    try {
+        await sendTelemetry({
+            id: getTelemetryId(stateDir),
+            v: version,
+            pv: exports.TELEMETRY_PAYLOAD_VERSION,
+            event,
+            mode: config?.mode === "client" ? "client" : "server",
+            agent: "unknown",
+            mem: 0,
+            lessons: 0,
+            sessions: 0,
+            ok: true,
+        }, serverUrl);
+    }
+    catch {
+        // Never let a lifecycle ping affect install/uninstall success.
+    }
+}

package/dist/uninstall.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runUninstall = runUninstall;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
+const telemetry_js_1 = require("./telemetry.js");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
@@ -26,6 +27,15 @@ async function ask(question) {
     });
 }
 async function runUninstall() {
+    // Churn signal (0.15.2): ping BEFORE removing anything, while state.json
+    // still holds the anonymous id. Opt-out aware; failures are swallowed.
+    try {
+        const home = (0, paths_js_1.hicortexHome)();
+        const config = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(home, "config.json"), "utf-8"));
+        const version = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, "..", "package.json"), "utf-8")).version;
+        await (0, telemetry_js_1.sendLifecycleEvent)("uninstall", home, config, version);
+    }
+    catch { /* no config/state or unreadable — nothing to report */ }
     console.log("Hicortex — Uninstall CC Integration\n");
     const answer = await ask("This will remove Hicortex from Claude Code. Your memory database is preserved. Continue? [y/N] ");
     if (answer.toLowerCase() !== "y") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "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": {
@@ -49,7 +49,7 @@
     "vitest": "^3.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "license": "PolyForm-Noncommercial-1.0.0",
   "homepage": "https://hicortex.gamaze.com",
@@ -65,7 +65,7 @@
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.28.0",
-    "better-sqlite3": "^11.0.0",
+    "better-sqlite3": "^12.11.1",
     "express": "^4.21.0",
     "sqlite-vec": "^0.1.7"
   }