@gamaze/hicortex 0.15.1 → 0.15.3

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) |
@@ -218,6 +225,7 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `recallMinSimilarity` | Relevance floor for index entries (default: 0.55; text-search matches always pass) |
 | `recallReshowTurns` | Turns before an already-shown memory may reappear in the same session (default: 30) |
 | `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
+| `sessionIntentWeight` | Blend weight of the session-intent rolling centroid in the recall search vector: `query = (1-w)·prompt + w·centroid` (default: 0.33; set 0 to disable — pure-prompt recall, the kill-switch). The first turn of a session searches with pure prompt and seeds the centroid; subsequent turns blend so recall follows the session's intent instead of being query-literal. The EMA rate (0.4) is a shipped constant, not configurable |
 | `dedupMergeThreshold` | Minimum cosine similarity for `hicortex dedup` to cluster memories as near-duplicates (default: 0.92) |
 | `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) |

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/eval/recall-sweep.d.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Recall@k sweep eval for session-intent keying (#192, commit 0867d6c).
+ *
+ * SHIP GATE: does blending the prompt with the per-session EMA centroid
+ * (retrieval.blendQueryVector) improve recall across rephrased turns, AND
+ * what does it COST when a session shifts topics mid-stream? Picks the
+ * default `sessionIntentWeight`.
+ *
+ * Two scenario families, same corpus:
+ *
+ *   FOCUSED — 6 sessions (one per topic), 4 turns each of GENUINE REPHRASES
+ *   of one intent. Tests the UPSIDE: does the centroid pull drifting
+ *   rephrases back on-topic? (recall@5 / p@5 should rise with w.)
+ *
+ *   SHIFT — 5 sessions, each 2 turns on topic A then 2 turns on topic B (a
+ *   clean mid-session topic change). Tests the DOWNSIDE that focused-only
+ *   can't see: a higher weight leaves the centroid partly A right after the
+ *   shift, so the first turn(s) on B may LAG (lower recall@5 for B). The
+ *   load-bearing read-out is post-shift recovery at turn-3 (first B turn)
+ *   and turn-4, plus turns-to-recover.
+ *
+ * Method (both families):
+ *   - Synthetic corpus of 30 memories across 6 well-separated topics (5 each),
+ *     embedded with the REAL bge-small-en-v1.5 model (the production embedder).
+ *   - For each weight w in {0.0, 0.2, 0.4, 0.5, 0.6, 0.8}: fresh
+ *     SessionRecallRegistry per session; per turn, embed the prompt ONCE,
+ *     blend with the live centroid, pass the blended vector to retrieve() via
+ *     queryEmbedding, record recall@5 + p@5 for the turn's CURRENT topic,
+ *     then fold the prompt into the centroid (EMA α=0.4).
+ *
+ * Fairness controls (load-bearing — the eval is useless if these slip):
+ *   - `noStrengthen: true` on every retrieve(): the DB stays STATIC across all
+ *     retrieve calls. Strengthening would mutate effective_strength/access_count
+ *     between runs and contaminate cross-weight comparisons.
+ *   - Uniform memory metadata: every memory has base_strength=0.5, created_at
+ *     ≈ now, access_count=0, and NO links. So effective_strength, recency,
+ *     connections, and the freshness boost are all uniform → the ONLY
+ *     discriminator is vector cosine + RRF rank. That isolates the blend.
+ *   - Cold-exposure slots are a no-op here (all candidates equally cold),
+ *     so the top-k is the plain score order.
+ *   - The centroid update is weight-INDEPENDENT (EMA of prompts at α=0.4), so
+ *     the per-turn centroid is identical across all weights for a given
+ *     session; only the blend differs. Embeddings are precomputed once.
+ *
+ * Metrics (per turn, for the turn's CURRENT topic):
+ *   - recall@5  — did >=1 same-topic memory surface in the top-5? (coarse; the
+ *     requested ship-gate metric — saturates on a small corpus.)
+ *   - p@5       — on-topic count in the top-5 (0..5, finer).
+ *   - recall@1  — was the SINGLE top result on-topic? (finest; focused only.)
+ *
+ * Honest by construction: it prints whatever the numbers are, including
+ * w=0 winning, the blend hurting a focused scenario, or high weights lagging
+ * badly post-shift. Report written to data/eval-recall-sweep/report.md and
+ * printed to stdout.
+ *
+ * Run:  npm run eval:recall-sweep   (==  node dist/eval/recall-sweep.js)
+ */
+export {};