@gamaze/hicortex 0.15.1 → 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
@@ -210,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) |

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");
@@ -1301,6 +1320,10 @@ async function runInit(options = {}) {
     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) {
@@ -1471,6 +1494,10 @@ async function runClientInit(serverUrl, agentName) {
     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)` : ""));
@@ -436,6 +436,7 @@ async function runNightly(options = {}) {
                 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),
@@ -568,6 +569,7 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
             id: (0, telemetry_js_1.getTelemetryId)(stateDir),
             v: VERSION,
             pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
+            event: "nightly",
             mode: "client",
             agent: agentType,
             mem: memoriesIngested,

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.d.ts

@@ -14,6 +14,7 @@
  *   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
@@ -47,6 +48,13 @@ export interface TelemetryPayload {
     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
@@ -80,3 +88,12 @@ export declare function telemetryDisabledReason(config: Record<string, unknown>
  * 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

@@ -15,6 +15,7 @@
  *   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
@@ -42,6 +43,7 @@ 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");
 exports.TELEMETRY_URL = "https://hicortex.gamaze.com/api/telemetry";
@@ -105,3 +107,32 @@ async function sendTelemetry(payload, serverUrl = exports.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.1",
+  "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"
   }