@gamaze/hicortex 0.10.1 → 0.11.1

package/dist/prompts.js

@@ -8,7 +8,6 @@ exports.importanceScoring = importanceScoring;
 exports.reflection = reflection;
 exports.distillation = distillation;
 exports.domainCuration = domainCuration;
-exports.edgeClassification = edgeClassification;
 /**
  * Importance scoring prompt. Takes a {memories_block} with indexed memories.
  */
@@ -170,31 +169,8 @@ Rules:
 
 Respond with ONLY a JSON array. No explanations.`;
 }
-/**
- * Edge classification prompt. Presents memory pairs and asks the LLM to
- * choose the most specific relationship type for each.
- */
-function edgeClassification(pairsBlock) {
-    return `You are a memory graph analyst. Classify the relationship between each memory pair.
-
-VALID RELATIONSHIP TYPES:
-- derives: A lesson or fact was derived from episodes (lesson ← episode)
-- updates: A newer memory updates/replaces an older one on the same topic
-- extends: Memory adds detail to another within the same project
-- relates_to: Generic association (use ONLY when no specific type fits)
-- CONTRADICTS: Memories give opposite advice or conflicting information
-- SUPERSEDES: One memory fully replaces another (stronger than "updates")
-- DEPENDS_ON: One memory's validity requires the other (prerequisite)
-- CAUSED_BY: One event/decision directly caused the other
-- VALIDATES: One memory confirms or provides evidence for the other
-
-Choose the MOST SPECIFIC type. Prefer specific types over "relates_to".
-
-MEMORY PAIRS:
-${pairsBlock}
-
-Respond with ONLY a JSON array of relationship type strings, one per pair, in order.
-Example for 3 pairs: ["CAUSED_BY", "extends", "VALIDATES"]
-
-No explanations. Just the JSON array.`;
-}
+// edgeClassification prompt REMOVED (2026-07). LLM edge classification is
+// retired: the 672-link audit found the LLM-classified UPPERCASE relationship
+// types near-useless (CONTRADICTS 4% acceptable). Linking is now heuristic-only
+// (extends/relates_to) in consolidate.ts. A classification prompt may return
+// only when a future classifier passes the audit harness at >= 70% acceptable.

package/dist/relink.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `hicortex relink` — deliberate, resumable link-discovery pass over the
+ * ENTIRE memories corpus (issue #143).
+ *
+ * The nightly's stageLinks only processes memories that are new since the
+ * last consolidation, so everything ingested before the TS linking stage
+ * (e.g. a migrated corpus) has never been through link discovery. This
+ * command back-fills the graph by reusing the exact same discovery +
+ * classification machinery (discoverLinkCandidates / classifyLinkCandidates
+ * from consolidate.ts) — no new linking logic.
+ *
+ * Classification is HEURISTIC-ONLY (2026-07). LLM edge classification was
+ * retired after the 672-link audit (see consolidate.ts Stage 3 header) found
+ * the LLM-classified UPPERCASE types near-useless. relink therefore never needs
+ * an LLM; the old `--no-llm`, `--max-llm-calls`, and `--llm-base-url/--llm-model`
+ * flags are gone. The classifyLinkCandidates call is retained (shared with the
+ * nightly) but takes no live LLM.
+ *
+ * Design:
+ *   - Scope: all memories ordered by rowid, processed in batches (default 200).
+ *   - Resumable: `relinkCursor` (last fully-committed rowid) is persisted in
+ *     state.json after each batch. Interruption never loses more than the
+ *     current batch. `--reset` restarts from rowid 0.
+ *   - Candidates: reuses the STORED embedding from memory_vectors (no
+ *     re-embedding); falls back to embedding the content only when a vector
+ *     row is missing. Same rules as the nightly: top-10 neighbors, cosine
+ *     above CONSOLIDATE_LINK_THRESHOLD (CROSS_PROJECT_LINK_THRESHOLD for
+ *     cross-project pairs), capped at CONSOLIDATE_LINK_TOP_K.
+ *   - Pair dedup: a candidate is skipped when a link already exists in EITHER
+ *     direction (memory_links PK is directional, so reverse duplicates must
+ *     be filtered here). Existing pairs are loaded once at start and the set
+ *     is maintained as links are added during the run.
+ *   - Classification: heuristic `extends`/`relates_to` only (classifyRelationship).
+ *   - `--dry-run`: full discovery, zero writes, cursor untouched. Would-be
+ *     links are reported with a breakdown by heuristic type.
+ *
+ * Server-mode only: relink needs the local DB. Client installs must run it
+ * on the server machine.
+ */
+import type Database from "better-sqlite3";
+import type { EmbedFn } from "./retrieval.js";
+export interface RelinkOptions {
+    /** Full discovery + would-be counts, zero writes, cursor untouched. */
+    dryRun?: boolean;
+    /** Memories per batch (default 200). Cursor advances per committed batch. */
+    batchSize?: number;
+    /** Ignore the saved cursor and restart from rowid 0. */
+    reset?: boolean;
+    /** DB path override (tests). Defaults to resolveDbPath(). */
+    dbPath?: string;
+    /** State dir override (tests). Defaults to ~/.hicortex. */
+    stateDir?: string;
+    /**
+     * Fallback embedder for memories missing a memory_vectors row (tests).
+     * Defaults to the local ONNX embedder, loaded lazily on first miss.
+     */
+    embedFn?: EmbedFn;
+}
+export interface RelinkReport {
+    dryRun: boolean;
+    /** Memories examined in this invocation. */
+    scanned: number;
+    /** Candidate pairs above the similarity threshold (before dedup). */
+    candidatesFound: number;
+    /** Candidates skipped: link existed in either direction BEFORE this run. */
+    skippedExisting: number;
+    /** Candidates skipped: pair already handled earlier in this run (a pair is
+     *  discovered from both sides — the reverse discovery is not a new link). */
+    skippedDuplicate: number;
+    /** Links created (or, in dry-run, links that would be created). */
+    linksCreated: number;
+    /** Candidates classified by an LLM. Always 0 — LLM classification retired. */
+    llmClassified: number;
+    /** Candidates classified by the heuristic (always all of them now). */
+    heuristicFallback: number;
+    /** Final relationship-type breakdown of created (or would-be) links. */
+    byType: Record<string, number>;
+    /** Memories whose discovery failed (missing vector AND embed failure). */
+    failed: number;
+    /** Batches processed. */
+    batches: number;
+    /** Cursor after this run (unchanged in dry-run). */
+    cursor: number;
+    /** Why the run ended. Only "complete" now (the LLM budget path is retired). */
+    stoppedReason: "complete";
+}
+/**
+ * Read the stored embedding for a memory from memory_vectors.
+ * Returns null when the row is missing (caller falls back to re-embedding).
+ */
+export declare function getStoredEmbedding(db: Database.Database, memoryId: string): Float32Array | null;
+/**
+ * Run the relink pass. Returns a structured report.
+ * Throws on unrecoverable errors (client mode, DB write failure) — the cursor
+ * always reflects the last committed batch.
+ *
+ * Classification is heuristic-only (LLM edge classification retired 2026-07),
+ * so relink never contacts an LLM.
+ */
+export declare function runRelink(options?: RelinkOptions): Promise<RelinkReport>;

package/dist/relink.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * `hicortex relink` — deliberate, resumable link-discovery pass over the
+ * ENTIRE memories corpus (issue #143).
+ *
+ * The nightly's stageLinks only processes memories that are new since the
+ * last consolidation, so everything ingested before the TS linking stage
+ * (e.g. a migrated corpus) has never been through link discovery. This
+ * command back-fills the graph by reusing the exact same discovery +
+ * classification machinery (discoverLinkCandidates / classifyLinkCandidates
+ * from consolidate.ts) — no new linking logic.
+ *
+ * Classification is HEURISTIC-ONLY (2026-07). LLM edge classification was
+ * retired after the 672-link audit (see consolidate.ts Stage 3 header) found
+ * the LLM-classified UPPERCASE types near-useless. relink therefore never needs
+ * an LLM; the old `--no-llm`, `--max-llm-calls`, and `--llm-base-url/--llm-model`
+ * flags are gone. The classifyLinkCandidates call is retained (shared with the
+ * nightly) but takes no live LLM.
+ *
+ * Design:
+ *   - Scope: all memories ordered by rowid, processed in batches (default 200).
+ *   - Resumable: `relinkCursor` (last fully-committed rowid) is persisted in
+ *     state.json after each batch. Interruption never loses more than the
+ *     current batch. `--reset` restarts from rowid 0.
+ *   - Candidates: reuses the STORED embedding from memory_vectors (no
+ *     re-embedding); falls back to embedding the content only when a vector
+ *     row is missing. Same rules as the nightly: top-10 neighbors, cosine
+ *     above CONSOLIDATE_LINK_THRESHOLD (CROSS_PROJECT_LINK_THRESHOLD for
+ *     cross-project pairs), capped at CONSOLIDATE_LINK_TOP_K.
+ *   - Pair dedup: a candidate is skipped when a link already exists in EITHER
+ *     direction (memory_links PK is directional, so reverse duplicates must
+ *     be filtered here). Existing pairs are loaded once at start and the set
+ *     is maintained as links are added during the run.
+ *   - Classification: heuristic `extends`/`relates_to` only (classifyRelationship).
+ *   - `--dry-run`: full discovery, zero writes, cursor untouched. Would-be
+ *     links are reported with a breakdown by heuristic type.
+ *
+ * Server-mode only: relink needs the local DB. Client installs must run it
+ * on the server machine.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStoredEmbedding = getStoredEmbedding;
+exports.runRelink = runRelink;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const db_js_1 = require("./db.js");
+const storage = __importStar(require("./storage.js"));
+const consolidate_js_1 = require("./consolidate.js");
+const state_js_1 = require("./state.js");
+const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
+function readConfig(stateDir) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(stateDir, "config.json"), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Canonical unordered key for a memory pair — direction-insensitive dedup. */
+function pairKey(a, b) {
+    return a < b ? `${a}|${b}` : `${b}|${a}`;
+}
+/** Load every existing link as an unordered pair set (both directions collapse). */
+function loadExistingPairs(db) {
+    const rows = db
+        .prepare("SELECT source_id, target_id FROM memory_links")
+        .all();
+    const pairs = new Set();
+    for (const row of rows)
+        pairs.add(pairKey(row.source_id, row.target_id));
+    return pairs;
+}
+/**
+ * Read the stored embedding for a memory from memory_vectors.
+ * Returns null when the row is missing (caller falls back to re-embedding).
+ */
+function getStoredEmbedding(db, memoryId) {
+    const row = db
+        .prepare("SELECT embedding FROM memory_vectors WHERE id = ?")
+        .get(memoryId);
+    if (!row?.embedding)
+        return null;
+    const buf = row.embedding;
+    return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
+/**
+ * Run the relink pass. Returns a structured report.
+ * Throws on unrecoverable errors (client mode, DB write failure) — the cursor
+ * always reflects the last committed batch.
+ *
+ * Classification is heuristic-only (LLM edge classification retired 2026-07),
+ * so relink never contacts an LLM.
+ */
+async function runRelink(options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const batchSize = options.batchSize ?? 200;
+    const stateDir = options.stateDir ?? HICORTEX_HOME;
+    if (!Number.isInteger(batchSize) || batchSize < 1) {
+        throw new Error(`[hicortex] relink: invalid --batch value: ${options.batchSize}`);
+    }
+    // Server-mode only — client installs have no local DB.
+    const config = readConfig(stateDir);
+    if (config?.mode === "client") {
+        throw new Error("[hicortex] relink is server-mode only (it needs the local DB). " +
+            `This machine is a client of ${config.serverUrl ?? "a remote server"} — run relink on the server.`);
+    }
+    // Classification is heuristic-only — no LLM client, no budget cap.
+    const budget = new consolidate_js_1.BudgetTracker(Number.MAX_SAFE_INTEGER);
+    const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
+    const db = (0, db_js_1.initDb)(dbPath);
+    const report = {
+        dryRun,
+        scanned: 0,
+        candidatesFound: 0,
+        skippedExisting: 0,
+        skippedDuplicate: 0,
+        linksCreated: 0,
+        llmClassified: 0,
+        heuristicFallback: 0,
+        byType: {},
+        failed: 0,
+        batches: 0,
+        cursor: 0,
+        stoppedReason: "complete",
+    };
+    try {
+        const totalMemories = storage.countMemories(db);
+        let cursor = options.reset ? 0 : ((0, state_js_1.loadState)(stateDir).relinkCursor ?? 0);
+        report.cursor = cursor;
+        console.log(`[hicortex] relink starting (${dryRun ? "dry-run" : "heuristic"}): ${totalMemories} memories, ` +
+            `batch ${batchSize}, cursor ${cursor}${options.reset ? " (reset)" : ""}`);
+        // Load all existing links once as an unordered pair set (471 rows on the
+        // live corpus — trivial). `seenPairs` additionally accumulates pairs
+        // handled during this run so re-runs AND within-run reverse candidates
+        // never create duplicate edges.
+        const preExistingPairs = loadExistingPairs(db);
+        const seenPairs = new Set(preExistingPairs);
+        const batchStmt = db.prepare("SELECT rowid AS __rowid, * FROM memories WHERE rowid > ? ORDER BY rowid ASC LIMIT ?");
+        // Lazy fallback embedder — only loaded if a memory_vectors row is missing.
+        let embedFn = options.embedFn ?? null;
+        const getEmbedFn = async () => {
+            if (!embedFn) {
+                const { embed } = await import("./embedder.js");
+                embedFn = embed;
+            }
+            return embedFn;
+        };
+        for (;;) {
+            const rows = batchStmt.all(cursor, batchSize);
+            if (rows.length === 0)
+                break;
+            const lastRowid = rows[rows.length - 1].__rowid;
+            // Phase A: discovery — reuse stored embeddings, same candidate rules
+            // as the nightly (discoverLinkCandidates).
+            const candidates = [];
+            let batchSkippedExisting = 0;
+            let batchSkippedDuplicate = 0;
+            for (const row of rows) {
+                const { __rowid: _ignored, ...memRow } = row;
+                const mem = memRow;
+                try {
+                    let embedding = getStoredEmbedding(db, mem.id);
+                    if (!embedding) {
+                        embedding = await (await getEmbedFn())(mem.content);
+                    }
+                    for (const cand of (0, consolidate_js_1.discoverLinkCandidates)(db, mem, embedding)) {
+                        report.candidatesFound++;
+                        const key = pairKey(cand.source.id, cand.target.id);
+                        if (seenPairs.has(key)) {
+                            if (preExistingPairs.has(key))
+                                batchSkippedExisting++;
+                            else
+                                batchSkippedDuplicate++;
+                            continue;
+                        }
+                        // Reserve the pair immediately so the reverse direction later in
+                        // this run (or this batch) is deduped too.
+                        seenPairs.add(key);
+                        candidates.push(cand);
+                    }
+                }
+                catch {
+                    report.failed++;
+                }
+            }
+            report.skippedExisting += batchSkippedExisting;
+            report.skippedDuplicate += batchSkippedDuplicate;
+            // Phase B: classification — shared heuristic-only path (LLM retired).
+            // classifyLinkCandidates ignores the null LLM/budget and returns each
+            // candidate's heuristic type (extends/relates_to).
+            const classified = await (0, consolidate_js_1.classifyLinkCandidates)(candidates, null, budget);
+            const types = classified.types;
+            report.llmClassified += classified.llmClassified; // always 0
+            report.heuristicFallback += classified.heuristicFallback;
+            // Phase C: store — one transaction per batch, then persist the cursor.
+            // A crash between commit and cursor save is safe: the re-run re-scans
+            // the batch but the pair dedup (loaded from the DB) skips every link.
+            if (!dryRun) {
+                const tx = db.transaction(() => {
+                    for (let i = 0; i < candidates.length; i++) {
+                        const c = candidates[i];
+                        storage.addLink(db, c.source.id, c.target.id, types[i], c.similarity);
+                    }
+                });
+                tx();
+                (0, state_js_1.updateState)((s) => {
+                    s.relinkCursor = lastRowid;
+                }, stateDir);
+                report.cursor = lastRowid;
+            }
+            for (const t of types)
+                report.byType[t] = (report.byType[t] ?? 0) + 1;
+            report.linksCreated += candidates.length;
+            report.scanned += rows.length;
+            report.batches++;
+            cursor = lastRowid;
+            console.log(`[hicortex]   batch ${report.batches}: scanned ${rows.length}, ` +
+                `candidates ${candidates.length + batchSkippedExisting + batchSkippedDuplicate}, ` +
+                `skipped ${batchSkippedExisting} already-linked + ${batchSkippedDuplicate} duplicate, ` +
+                `${dryRun ? "would create" : "created"} ${candidates.length} ` +
+                `(cursor ${lastRowid}, ${report.scanned} scanned this run)`);
+        }
+        // Final summary
+        const typeBreakdown = Object.entries(report.byType)
+            .sort((a, b) => b[1] - a[1])
+            .map(([t, n]) => `${t}=${n}`)
+            .join(", ") || "none";
+        console.log(`[hicortex] relink complete` +
+            `${dryRun ? " (dry-run, nothing written)" : ""}: ` +
+            `${report.scanned} memories scanned, ${report.candidatesFound} candidates, ` +
+            `${report.skippedExisting} already linked, ${report.skippedDuplicate} reverse-duplicates, ` +
+            `${report.linksCreated} links ${dryRun ? "would be created" : "created"} ` +
+            `(heuristic ${report.heuristicFallback})`);
+        console.log(`[hicortex]   by type: ${typeBreakdown}`);
+        if (report.failed > 0) {
+            console.warn(`[hicortex]   ${report.failed} memories failed discovery (see errors above)`);
+        }
+        return report;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/retrieval.d.ts

@@ -14,7 +14,17 @@
  *   effective = floor + (base - floor) * decay_rate^hours
  */
 import type Database from "better-sqlite3";
-import type { MemorySearchResult } from "./types.js";
+import type { Memory, MemorySearchResult } from "./types.js";
+/**
+ * Convert an L2 distance (as returned by sqlite-vec's vec0 `distance`) to
+ * cosine similarity. Valid because our embeddings are L2-normalized
+ * (embedder.ts, `normalize: true`): for unit vectors, d² = 2 − 2·cos,
+ * hence cos = 1 − d²/2. Exact anchors: d=0 → 1, d=√2 → 0, d=2 → −1.
+ *
+ * Lives here (the dependency-root of the scoring code) and is re-exported
+ * by consolidate.ts so pre-#145 importers keep working.
+ */
+export declare function l2ToCosine(distance: number): number;
 /**
  * Compute decayed strength with adaptive decay (B+E+D model).
  * Exported for use by consolidation decay/prune stage.
@@ -24,6 +34,11 @@ export declare function effectiveStrength(baseStrength: number, lastAccessed: st
     accessCount?: number;
     linkCount?: number;
 }): number;
+/**
+ * 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 interface EmbedFn {
     (text: string): Promise<Float32Array>;
 }

package/dist/retrieval.js

@@ -48,13 +48,35 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.l2ToCosine = l2ToCosine;
 exports.effectiveStrength = effectiveStrength;
+exports.computeScore = computeScore;
 exports.retrieve = retrieve;
 exports.searchContext = searchContext;
 const storage = __importStar(require("./storage.js"));
 const BASE_DECAY = 0.0005;
-const DEFAULT_GRAPH_DISTANCE = 0.5;
+/**
+ * Placeholder L2 distance for candidates that have no measured vector
+ * distance (FTS-only hits and graph-discovered neighbors). Chosen so that
+ * l2ToCosine(1.0) = 0.5 — a neutral mid-scale similarity. Before the #145
+ * fix the value was 0.5 on the accidental 1−L2 scale, which also yielded
+ * similarity 0.5; keeping 0.5 under the corrected formula would have jumped
+ * these candidates to cosine 0.875, outranking most true vector matches.
+ */
+const DEFAULT_GRAPH_DISTANCE = 1.0;
 const RRF_K = 60;
+/**
+ * Convert an L2 distance (as returned by sqlite-vec's vec0 `distance`) to
+ * cosine similarity. Valid because our embeddings are L2-normalized
+ * (embedder.ts, `normalize: true`): for unit vectors, d² = 2 − 2·cos,
+ * hence cos = 1 − d²/2. Exact anchors: d=0 → 1, d=√2 → 0, d=2 → −1.
+ *
+ * Lives here (the dependency-root of the scoring code) and is re-exported
+ * by consolidate.ts so pre-#145 importers keep working.
+ */
+function l2ToCosine(distance) {
+    return 1 - (distance * distance) / 2;
+}
 // ---------------------------------------------------------------------------
 // Timestamp parsing
 // ---------------------------------------------------------------------------
@@ -96,9 +118,19 @@ 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) {
-    const similarity = Math.max(0, 1.0 - distance);
+    // 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
+    // discrimination. The clamp stays at 0 — a negative cosine means truly
+    // unrelated — but now at the correct scale. NOTE: the similarity values
+    // roughly DOUBLE for related content on the new scale; the blend weights
+    // below are deliberately unchanged in this pass so the before/after
+    // retrieval comparison is measured, not guessed. Rebalancing the weights
+    // is a data-driven follow-up if the eval shows it is needed.
+    const similarity = Math.max(0, l2ToCosine(distance));
     const effStrength = effectiveStrength(memory.base_strength ?? 0.5, memory.last_accessed, now, {
         accessCount: memory.access_count ?? 0,
         linkCount: connectionCount,

package/dist/schema-prototypes.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Graded schema membership — domain prototypes + per-tag association weights
+ * (spec: specs/2026-07-07-graded-schema-memory-tags.md).
+ *
+ * MODEL (cognitive grounding → mechanism)
+ * ---------------------------------------
+ * A configured domain is a SCHEMA with graded membership (Rosch prototypes):
+ *   - prototype(domain) = L2-normalized mean of the embeddings of memories
+ *     whose tag set includes the domain. Cold start / thin domains
+ *     (member_count < PROTOTYPE_MIN_MEMBERS) seed the prototype from the
+ *     embedding of the domain's config description instead.
+ *   - weight(memory, tag) = cosine(memory embedding, prototype(tag)). Both
+ *     vectors are L2-normalized, so cosine reduces to a dot product.
+ *   - PRIMARY (memories.domain) = argmax-weight tag, overridden by any tagged
+ *     domain flagged `compartment: true` (deliberate compartmentalization —
+ *     the owner's Work firewall). Fully mechanical, no LLM.
+ *
+ * The LLM decides ONLY the discrete part (which schemas apply — see
+ * domain-classify.ts); ALL gradation is derived from embeddings here.
+ * Prototypes + weights are recomputed each nightly, so categories drift with
+ * the data ("reconsolidation") without any re-classification runs.
+ *
+ * Persistence: `domain_prototypes(domain, embedding, member_count, updated_at)`
+ * and `memory_tags.weight` (both migration v7).
+ */
+import type Database from "better-sqlite3";
+import type { DomainDef } from "./types.js";
+import type { EmbedFn } from "./retrieval.js";
+/**
+ * Below this member count a domain's prototype is seeded from its config
+ * description instead of the member centroid (cold start / thin domains).
+ */
+export declare const PROTOTYPE_MIN_MEMBERS = 5;
+/** Deserialize a BLOB column into a Float32Array (same layout as sqlite-vec). */
+export declare function blobToVec(buf: Buffer): Float32Array;
+/**
+ * L2-normalize a vector IN A COPY. A zero vector (norm 0 — e.g. test fixtures)
+ * is returned as an all-zero copy rather than dividing by zero.
+ */
+export declare function l2Normalize(vec: Float32Array): Float32Array;
+/**
+ * Association weight of a memory for a tag = cosine(memory embedding, domain
+ * prototype). Both inputs are L2-normalized (embedder.ts normalizes memory
+ * embeddings; computeDomainPrototypes normalizes prototypes), so cosine is
+ * exactly the dot product.
+ */
+export declare function tagWeight(memoryEmbedding: Float32Array, prototype: Float32Array): number;
+/** One tag with its association weight (null = never computed / no prototype). */
+export interface WeightedTag {
+    tag: string;
+    weight: number | null;
+}
+/** The configured compartment domain names (DomainDef.compartment === true). */
+export declare function compartmentSet(domains: DomainDef[]): Set<string>;
+/**
+ * Derive the PRIMARY tag (memories.domain) from a weighted tag set.
+ *
+ * Rules (deterministic, no LLM):
+ *   1. Any tagged compartment domain wins — first one in array order if the
+ *      (unusual) case of several arises.
+ *   2. Else the argmax-weight tag. `tags` MUST be in LLM most-relevant-first
+ *      order: ties (and all-null weights) resolve to the EARLIEST array
+ *      position — strict `>` comparison keeps the first maximum.
+ *   3. A null weight loses to any numeric weight (treated as -Infinity).
+ *
+ * Throws on an empty tag set — callers guarantee >= 1 tag (an empty tag set
+ * from the classifier is a NO-FIT and must be routed through nofit.ts, never
+ * here); an empty set reaching this function is a programming error.
+ */
+export declare function derivePrimary(tags: WeightedTag[], compartments: Set<string>): string;
+export interface PrototypeStat {
+    domain: string;
+    memberCount: number;
+    /** true = description seed (member_count < PROTOTYPE_MIN_MEMBERS). */
+    seeded: boolean;
+}
+/** Load all stored prototypes into a name → vector map. */
+export declare function loadDomainPrototypes(db: Database.Database): Map<string, Float32Array>;
+/**
+ * Compute + persist the prototype of every configured domain.
+ *
+ * Per domain: mean of the embeddings of memories whose memory_tags include the
+ * domain, L2-normalized. When member_count < PROTOTYPE_MIN_MEMBERS the
+ * prototype is instead the embedding of `"<Name>: <description>"` (the same
+ * "name: description" line the classifier prompt shows) — this seeds cold
+ * starts and keeps thin domains from collapsing onto 1-2 outliers.
+ *
+ * `getEmbedFn` is LAZY (a function returning a promise of the embedder) so the
+ * ~130 MB ONNX embedder is loaded ONLY when at least one domain actually needs
+ * a description seed — same pattern as relink.ts's lazy fallback embedder.
+ *
+ * Returns the fresh prototype map (for immediate classification-time weights)
+ * plus per-domain stats. Rows in domain_prototypes are REPLACED per domain;
+ * domains removed from the config keep a stale row until the next config-set
+ * change (harmless — nothing reads prototypes outside the configured set).
+ */
+export declare function computeDomainPrototypes(db: Database.Database, domains: DomainDef[], getEmbedFn: () => Promise<EmbedFn>): Promise<{
+    prototypes: Map<string, Float32Array>;
+    stats: PrototypeStat[];
+}>;
+/**
+ * Compute the per-tag weights for ONE memory from the current prototypes
+ * (classification-time path: newly tagged memories get weights immediately).
+ * A missing memory vector or missing prototype yields null (stored as NULL;
+ * repaired by the next nightly recompute).
+ */
+export declare function computeTagWeights(db: Database.Database, memoryId: string, tags: string[], prototypes: Map<string, Float32Array>): Record<string, number | null>;
+/**
+ * Best prototype match for one memory across ALL configured domains:
+ * argmax of cosine(memory embedding, prototype(domain)).
+ *
+ * Used by the no-fit path (nofit.ts, owner amendment 07.07): when the LLM
+ * says no domain fits, the memory can still earn a WEAK primary from pure
+ * embedding association — provided the best cosine clears the configured
+ * weakPrimaryFloor (the caller checks the floor; this function just reports
+ * the argmax).
+ *
+ * Returns null when the memory has no stored vector or no configured domain
+ * has a prototype (nothing to associate against). Ties resolve to the FIRST
+ * domain in config order (strict `>` comparison), mirroring derivePrimary.
+ */
+export declare function bestPrototypeMatch(db: Database.Database, memoryId: string, domains: DomainDef[], prototypes: Map<string, Float32Array>): {
+    domain: string;
+    weight: number;
+} | null;
+/**
+ * One pass over ALL memory_tags rows: weight = cosine(memory embedding,
+ * prototype(tag)). Rows whose memory has no stored vector, or whose tag has no
+ * prototype (out-of-vocabulary leftovers), are set to NULL. Cheap: one point
+ * lookup per distinct memory + one dot product per tag row (3–5k on the
+ * production corpus).
+ */
+export declare function recomputeAllTagWeights(db: Database.Database, prototypes: Map<string, Float32Array>): {
+    updated: number;
+    nulled: number;
+};
+/**
+ * Re-derive the PRIMARY (memories.domain) of every tagged memory from its
+ * current tag weights: compartment override first, else argmax weight, LLM
+ * order (memory_tags insertion order = rowid, written most-relevant-first by
+ * storage.setMemoryTags) breaking exact-weight ties.
+ *
+ * Memories with NO memory_tags rows are untouched (e.g. infra-skipped rows
+ * awaiting classification — issue #150 discipline).
+ */
+export declare function refreshPrimaries(db: Database.Database, domains: DomainDef[]): {
+    examined: number;
+    updated: number;
+};