@gamaze/hicortex 0.10.1 → 0.11.0

package/dist/schema-prototypes.js

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOTYPE_MIN_MEMBERS = void 0;
+exports.blobToVec = blobToVec;
+exports.l2Normalize = l2Normalize;
+exports.tagWeight = tagWeight;
+exports.compartmentSet = compartmentSet;
+exports.derivePrimary = derivePrimary;
+exports.loadDomainPrototypes = loadDomainPrototypes;
+exports.computeDomainPrototypes = computeDomainPrototypes;
+exports.computeTagWeights = computeTagWeights;
+exports.bestPrototypeMatch = bestPrototypeMatch;
+exports.recomputeAllTagWeights = recomputeAllTagWeights;
+exports.refreshPrimaries = refreshPrimaries;
+/**
+ * Below this member count a domain's prototype is seeded from its config
+ * description instead of the member centroid (cold start / thin domains).
+ */
+exports.PROTOTYPE_MIN_MEMBERS = 5;
+// ---------------------------------------------------------------------------
+// Vector helpers (local — this module must not import storage.ts, which
+// imports derivePrimary from here; keep the dependency one-way)
+// ---------------------------------------------------------------------------
+/** Deserialize a BLOB column into a Float32Array (same layout as sqlite-vec). */
+function blobToVec(buf) {
+    return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
+/** Serialize a Float32Array to a BLOB (same layout as storage.embedToBlob). */
+function vecToBlob(vec) {
+    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+/**
+ * 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.
+ */
+function l2Normalize(vec) {
+    let sumSq = 0;
+    for (let i = 0; i < vec.length; i++)
+        sumSq += vec[i] * vec[i];
+    const norm = Math.sqrt(sumSq);
+    const out = new Float32Array(vec.length);
+    if (norm === 0)
+        return out;
+    for (let i = 0; i < vec.length; i++)
+        out[i] = vec[i] / norm;
+    return out;
+}
+/**
+ * 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.
+ */
+function tagWeight(memoryEmbedding, prototype) {
+    const n = Math.min(memoryEmbedding.length, prototype.length);
+    let dot = 0;
+    for (let i = 0; i < n; i++)
+        dot += memoryEmbedding[i] * prototype[i];
+    return dot;
+}
+/** The configured compartment domain names (DomainDef.compartment === true). */
+function compartmentSet(domains) {
+    return new Set(domains.filter((d) => d.compartment === true).map((d) => d.name));
+}
+/**
+ * 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.
+ */
+function derivePrimary(tags, compartments) {
+    if (tags.length === 0) {
+        throw new Error("derivePrimary: empty tag set (callers must pass >= 1 tag)");
+    }
+    for (const t of tags) {
+        if (compartments.has(t.tag))
+            return t.tag;
+    }
+    let best = tags[0];
+    let bestWeight = best.weight ?? Number.NEGATIVE_INFINITY;
+    for (let i = 1; i < tags.length; i++) {
+        const w = tags[i].weight ?? Number.NEGATIVE_INFINITY;
+        if (w > bestWeight) {
+            best = tags[i];
+            bestWeight = w;
+        }
+    }
+    return best.tag;
+}
+/** Read a single memory's stored embedding (point lookup on memory_vectors). */
+function getMemoryEmbedding(db, memoryId) {
+    const row = db
+        .prepare("SELECT embedding FROM memory_vectors WHERE id = ?")
+        .get(memoryId);
+    if (!row?.embedding)
+        return null;
+    return blobToVec(row.embedding);
+}
+/** Load all stored prototypes into a name → vector map. */
+function loadDomainPrototypes(db) {
+    const rows = db
+        .prepare("SELECT domain, embedding FROM domain_prototypes")
+        .all();
+    const map = new Map();
+    for (const r of rows) {
+        if (r.embedding)
+            map.set(r.domain, blobToVec(r.embedding));
+    }
+    return map;
+}
+/**
+ * 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).
+ */
+async function computeDomainPrototypes(db, domains, getEmbedFn) {
+    const memberStmt = db.prepare("SELECT memory_id FROM memory_tags WHERE tag = ?");
+    const upsert = db.prepare(`INSERT OR REPLACE INTO domain_prototypes (domain, embedding, member_count, updated_at)
+     VALUES (?, ?, ?, ?)`);
+    const prototypes = new Map();
+    const stats = [];
+    for (const d of domains) {
+        const memberIds = memberStmt.all(d.name)
+            .map((r) => r.memory_id);
+        // Collect member embeddings (a tag row without a vector is skipped — it
+        // cannot contribute to a centroid and would poison the mean with zeros).
+        const embeddings = [];
+        for (const id of memberIds) {
+            const emb = getMemoryEmbedding(db, id);
+            if (emb)
+                embeddings.push(emb);
+        }
+        const memberCount = embeddings.length;
+        let prototype;
+        let seeded = false;
+        if (memberCount >= exports.PROTOTYPE_MIN_MEMBERS) {
+            const dim = embeddings[0].length;
+            const mean = new Float32Array(dim);
+            for (const emb of embeddings) {
+                for (let i = 0; i < dim; i++)
+                    mean[i] += emb[i];
+            }
+            for (let i = 0; i < dim; i++)
+                mean[i] /= memberCount;
+            prototype = l2Normalize(mean);
+        }
+        else {
+            // Cold start / thin domain → description seed.
+            const embedFn = await getEmbedFn();
+            prototype = l2Normalize(await embedFn(`${d.name}: ${d.description}`));
+            seeded = true;
+        }
+        upsert.run(d.name, vecToBlob(prototype), memberCount, new Date().toISOString());
+        prototypes.set(d.name, prototype);
+        stats.push({ domain: d.name, memberCount, seeded });
+    }
+    return { prototypes, stats };
+}
+// ---------------------------------------------------------------------------
+// Weight computation
+// ---------------------------------------------------------------------------
+/**
+ * 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).
+ */
+function computeTagWeights(db, memoryId, tags, prototypes) {
+    const emb = getMemoryEmbedding(db, memoryId);
+    const out = {};
+    for (const tag of tags) {
+        const proto = prototypes.get(tag);
+        out[tag] = emb && proto ? tagWeight(emb, proto) : null;
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+function bestPrototypeMatch(db, memoryId, domains, prototypes) {
+    const emb = getMemoryEmbedding(db, memoryId);
+    if (!emb)
+        return null;
+    let best = null;
+    for (const d of domains) {
+        const proto = prototypes.get(d.name);
+        if (!proto)
+            continue;
+        const w = tagWeight(emb, proto);
+        if (best === null || w > best.weight) {
+            best = { domain: d.name, weight: w };
+        }
+    }
+    return best;
+}
+/**
+ * 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).
+ */
+function recomputeAllTagWeights(db, prototypes) {
+    const rows = db
+        .prepare("SELECT memory_id, tag FROM memory_tags ORDER BY memory_id")
+        .all();
+    const update = db.prepare("UPDATE memory_tags SET weight = ? WHERE memory_id = ? AND tag = ?");
+    let updated = 0;
+    let nulled = 0;
+    const tx = db.transaction(() => {
+        let currentId = null;
+        let currentEmb = null;
+        for (const row of rows) {
+            if (row.memory_id !== currentId) {
+                currentId = row.memory_id;
+                currentEmb = getMemoryEmbedding(db, row.memory_id);
+            }
+            const proto = prototypes.get(row.tag);
+            if (currentEmb && proto) {
+                update.run(tagWeight(currentEmb, proto), row.memory_id, row.tag);
+                updated++;
+            }
+            else {
+                update.run(null, row.memory_id, row.tag);
+                nulled++;
+            }
+        }
+    });
+    tx();
+    return { updated, nulled };
+}
+/**
+ * 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).
+ */
+function refreshPrimaries(db, domains) {
+    const compartments = compartmentSet(domains);
+    const rows = db
+        .prepare(`SELECT mt.memory_id, mt.tag, mt.weight, m.domain
+       FROM memory_tags mt JOIN memories m ON m.id = mt.memory_id
+       ORDER BY mt.memory_id, mt.rowid`)
+        .all();
+    // Group per memory, preserving rowid (LLM) order within each group.
+    const byMemory = new Map();
+    for (const r of rows) {
+        let entry = byMemory.get(r.memory_id);
+        if (!entry) {
+            entry = { tags: [], domain: r.domain };
+            byMemory.set(r.memory_id, entry);
+        }
+        entry.tags.push({ tag: r.tag, weight: r.weight });
+    }
+    const update = db.prepare("UPDATE memories SET domain = ? WHERE id = ?");
+    let updated = 0;
+    const tx = db.transaction(() => {
+        for (const [memoryId, entry] of byMemory) {
+            const primary = derivePrimary(entry.tags, compartments);
+            if (primary !== entry.domain) {
+                update.run(primary, memoryId);
+                updated++;
+            }
+        }
+    });
+    tx();
+    return { examined: byMemory.size, updated };
+}

package/dist/state.d.ts

@@ -37,6 +37,19 @@ export interface HicortexState {
     telemetryId?: string;
     /** Cached MODULE_INDEX from domain curation (generated during consolidation). */
     moduleIndex?: ModuleIndex;
+    /**
+     * Resume cursor for `hicortex relink` — highest memories.rowid whose batch
+     * has been fully committed. Absent/0 = never run (or reset). Cleared is not
+     * required on completion; a finished run simply leaves the cursor at the
+     * max rowid processed.
+     */
+    relinkCursor?: number;
+    /**
+     * Resume cursor for `hicortex classify-domains` — highest memories.rowid
+     * whose batch has been fully committed. Absent/0 = never run (or reset).
+     * Same discipline as relinkCursor.
+     */
+    domainCursor?: number;
 }
 /**
  * Load the state file. Returns an empty state if the file is missing
@@ -66,3 +79,22 @@ export declare function updateState(updater: (state: HicortexState) => HicortexS
  * Returns true if migration ran, false if state.json already existed.
  */
 export declare function migrateLegacyState(stateDir?: string): boolean;
+export interface LastNightlyInfo {
+    /** Raw timestamp string as stored. */
+    timestamp: string;
+    /** True when the stored value is not a parseable date. */
+    invalid: boolean;
+    ageHours?: number;
+    /** Human age, e.g. "just now", "5h ago", "2d ago". */
+    ageStr?: string;
+    /** True when older than the missed-a-night threshold (30h). */
+    stale?: boolean;
+}
+/**
+ * Last nightly run for status display, shared by `hicortex status` and
+ * `hicortex nightly --status`. Read-only: prefers state.json but falls
+ * back to the pre-migration nightly-last-run.txt so upgraded installs
+ * report correctly before their first nightly performs the migration.
+ * Returns null when no run has ever been recorded.
+ */
+export declare function describeLastNightly(stateDir?: string): LastNightlyInfo | null;

package/dist/state.js

@@ -22,6 +22,7 @@ exports.loadState = loadState;
 exports.saveState = saveState;
 exports.updateState = updateState;
 exports.migrateLegacyState = migrateLegacyState;
+exports.describeLastNightly = describeLastNightly;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -141,6 +142,34 @@ function migrateLegacyState(stateDir = HICORTEX_HOME) {
     }
     return false;
 }
+const STALE_THRESHOLD_HOURS = 30;
+/**
+ * Last nightly run for status display, shared by `hicortex status` and
+ * `hicortex nightly --status`. Read-only: prefers state.json but falls
+ * back to the pre-migration nightly-last-run.txt so upgraded installs
+ * report correctly before their first nightly performs the migration.
+ * Returns null when no run has ever been recorded.
+ */
+function describeLastNightly(stateDir = HICORTEX_HOME) {
+    const ts = loadState(stateDir).lastNightly ??
+        readLegacyText(stateDir, "nightly-last-run.txt");
+    if (!ts)
+        return null;
+    const d = new Date(ts);
+    if (isNaN(d.getTime()))
+        return { timestamp: ts, invalid: true };
+    const ageHours = Math.round((Date.now() - d.getTime()) / (60 * 60 * 1000));
+    const ageStr = ageHours < 1 ? "just now" :
+        ageHours < 24 ? `${ageHours}h ago` :
+            `${Math.round(ageHours / 24)}d ago`;
+    return {
+        timestamp: ts,
+        invalid: false,
+        ageHours,
+        ageStr,
+        stale: ageHours > STALE_THRESHOLD_HOURS,
+    };
+}
 function readLegacyText(stateDir, name) {
     try {
         const raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(stateDir, name), "utf-8").trim();

package/dist/status.js

@@ -10,6 +10,7 @@ const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
 const db_js_1 = require("./db.js");
 const features_js_1 = require("./features.js");
+const state_js_1 = require("./state.js");
 const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
@@ -129,27 +130,19 @@ async function runStatus() {
         }
     }
     // Last nightly run
-    const lastRunPath = (0, node_path_1.join)(HICORTEX_HOME, "nightly-last-run.txt");
-    try {
-        const ts = (0, node_fs_1.readFileSync)(lastRunPath, "utf-8").trim();
-        const lastRun = new Date(ts);
-        if (isNaN(lastRun.getTime())) {
-            console.log(`  Last run:   ${ts} (invalid timestamp)`);
-        }
-        else {
-            const STALE_THRESHOLD_HOURS = 30;
-            const ageHours = Math.round((Date.now() - lastRun.getTime()) / (60 * 60 * 1000));
-            const ageStr = ageHours < 1 ? "just now" : ageHours < 24 ? `${ageHours}h ago` : `${Math.round(ageHours / 24)}d ago`;
-            console.log(`  Last run:   ${ts} (${ageStr})`);
-            // Show staleness warning if missed a night
-            if (ageHours > STALE_THRESHOLD_HOURS) {
-                console.log(`  ⚠ Nightly pipeline hasn't run in ${ageHours}h. Check: hicortex nightly --dry-run`);
-            }
-        }
-    }
-    catch {
+    const lastRun = (0, state_js_1.describeLastNightly)();
+    if (!lastRun) {
         console.log("  Last run:   never (run: hicortex nightly)");
     }
+    else if (lastRun.invalid) {
+        console.log(`  Last run:   ${lastRun.timestamp} (invalid timestamp)`);
+    }
+    else {
+        console.log(`  Last run:   ${lastRun.timestamp} (${lastRun.ageStr})`);
+        if (lastRun.stale) {
+            console.log(`  ⚠ Nightly pipeline hasn't run in ${lastRun.ageHours}h. Check: hicortex nightly --dry-run`);
+        }
+    }
     // Distillation stats (if DB exists)
     if (dbExists) {
         const TOP_SOURCES_LIMIT = 5;

package/dist/storage.d.ts

@@ -31,9 +31,52 @@ export declare function updateMemory(db: Database.Database, memoryId: string, fi
  */
 export declare function strengthenMemory(db: Database.Database, memoryId: string, nowIsoStr: string): void;
 /**
- * Delete a memory, its vector, and all its links.
+ * Delete a memory, its vector, its tags, and all its links.
  */
 export declare function deleteMemory(db: Database.Database, memoryId: string): void;
+/** Options for setMemoryTags (graded-schema spec 2026-07-07). */
+export interface SetMemoryTagsOptions {
+    /**
+     * Per-tag association weights (cosine vs the domain prototype), computed by
+     * schema-prototypes.computeTagWeights. A missing/null entry stores NULL
+     * (repaired by the next nightly recompute).
+     */
+    weights?: Record<string, number | null>;
+    /**
+     * Compartment domain names (DomainDef.compartment === true): a tagged
+     * compartment domain becomes the primary regardless of weights.
+     */
+    compartments?: Set<string>;
+}
+/**
+ * Set a memory's classification tags (graded schema model).
+ *
+ * `tags` is the ORDERED tag set from the classifier (most-relevant first —
+ * the order is persisted via insertion/rowid order and breaks exact-weight
+ * ties). The `memory_tags` sidecar rows for this memory are REPLACED; each
+ * row stores its association weight (NULL when not yet computed).
+ *
+ * The PRIMARY (memories.domain) is DERIVED here — never passed in by the LLM:
+ * compartment override first, else argmax weight, else first tag (all-null
+ * weights). The whole update is one transaction so domain, tag set, and
+ * weights never diverge.
+ *
+ * @returns the derived primary written to memories.domain
+ */
+export declare function setMemoryTags(db: Database.Database, memoryId: string, tags: string[], options?: SetMemoryTagsOptions): string;
+/**
+ * Get a memory's tag set (the full multi-label set, including the primary).
+ * Returns tags sorted alphabetically for stable output; empty array if none.
+ */
+export declare function getMemoryTags(db: Database.Database, memoryId: string): string[];
+/**
+ * Get a memory's tags WITH weights, ordered by weight descending (NULL
+ * weights last, in insertion/relevance order). Empty array if none.
+ */
+export declare function getMemoryTagsWeighted(db: Database.Database, memoryId: string): Array<{
+    tag: string;
+    weight: number | null;
+}>;
 /**
  * Find similar memories by vector distance. Returns memories with distance field.
  */

package/dist/storage.js

@@ -10,6 +10,9 @@ exports.getMemory = getMemory;
 exports.updateMemory = updateMemory;
 exports.strengthenMemory = strengthenMemory;
 exports.deleteMemory = deleteMemory;
+exports.setMemoryTags = setMemoryTags;
+exports.getMemoryTags = getMemoryTags;
+exports.getMemoryTagsWeighted = getMemoryTagsWeighted;
 exports.vectorSearch = vectorSearch;
 exports.searchFts = searchFts;
 exports.addLink = addLink;
@@ -24,6 +27,7 @@ exports.getPruneCandidates = getPruneCandidates;
 exports.getAllLinkCounts = getAllLinkCounts;
 exports.getUnscoredMemories = getUnscoredMemories;
 const node_crypto_1 = require("node:crypto");
+const schema_prototypes_js_1 = require("./schema-prototypes.js");
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -127,13 +131,78 @@ function strengthenMemory(db, memoryId, nowIsoStr) {
      WHERE id = ?`).run(nowIsoStr, memoryId);
 }
 /**
- * Delete a memory, its vector, and all its links.
+ * Delete a memory, its vector, its tags, and all its links.
  */
 function deleteMemory(db, memoryId) {
     db.prepare("DELETE FROM memory_links WHERE source_id = ? OR target_id = ?").run(memoryId, memoryId);
+    db.prepare("DELETE FROM memory_tags WHERE memory_id = ?").run(memoryId);
     db.prepare("DELETE FROM memory_vectors WHERE id = ?").run(memoryId);
     db.prepare("DELETE FROM memories WHERE id = ?").run(memoryId);
 }
+/**
+ * Set a memory's classification tags (graded schema model).
+ *
+ * `tags` is the ORDERED tag set from the classifier (most-relevant first —
+ * the order is persisted via insertion/rowid order and breaks exact-weight
+ * ties). The `memory_tags` sidecar rows for this memory are REPLACED; each
+ * row stores its association weight (NULL when not yet computed).
+ *
+ * The PRIMARY (memories.domain) is DERIVED here — never passed in by the LLM:
+ * compartment override first, else argmax weight, else first tag (all-null
+ * weights). The whole update is one transaction so domain, tag set, and
+ * weights never diverge.
+ *
+ * @returns the derived primary written to memories.domain
+ */
+function setMemoryTags(db, memoryId, tags, options = {}) {
+    // Dedup preserving first (most-relevant) occurrence; defensive — the
+    // classifier already dedups.
+    const unique = Array.from(new Set(tags));
+    if (unique.length === 0) {
+        throw new Error("setMemoryTags: empty tag set (callers must pass >= 1 tag)");
+    }
+    const weighted = unique.map((tag) => ({
+        tag,
+        weight: options.weights?.[tag] ?? null,
+    }));
+    const primary = (0, schema_prototypes_js_1.derivePrimary)(weighted, options.compartments ?? new Set());
+    const setDomain = db.prepare("UPDATE memories SET domain = ? WHERE id = ?");
+    const clearTags = db.prepare("DELETE FROM memory_tags WHERE memory_id = ?");
+    const insertTag = db.prepare("INSERT OR IGNORE INTO memory_tags (memory_id, tag, weight) VALUES (?, ?, ?)");
+    const tx = db.transaction(() => {
+        setDomain.run(primary, memoryId);
+        clearTags.run(memoryId);
+        // Insert in LLM order — rowid order IS the persisted relevance order.
+        // schema-prototypes.ts refreshPrimaries depends on this (ORDER BY mt.rowid
+        // as the argmax tiebreak): any future bulk writer of memory_tags MUST
+        // insert most-relevant-first or tiebreak ordering silently corrupts.
+        for (const w of weighted)
+            insertTag.run(memoryId, w.tag, w.weight);
+    });
+    tx();
+    return primary;
+}
+/**
+ * Get a memory's tag set (the full multi-label set, including the primary).
+ * Returns tags sorted alphabetically for stable output; empty array if none.
+ */
+function getMemoryTags(db, memoryId) {
+    const rows = db
+        .prepare("SELECT tag FROM memory_tags WHERE memory_id = ? ORDER BY tag")
+        .all(memoryId);
+    return rows.map((r) => r.tag);
+}
+/**
+ * Get a memory's tags WITH weights, ordered by weight descending (NULL
+ * weights last, in insertion/relevance order). Empty array if none.
+ */
+function getMemoryTagsWeighted(db, memoryId) {
+    const rows = db
+        .prepare(`SELECT tag, weight FROM memory_tags WHERE memory_id = ?
+       ORDER BY (weight IS NULL) ASC, weight DESC, rowid ASC`)
+        .all(memoryId);
+    return rows;
+}
 // ---------------------------------------------------------------------------
 // Vector search
 // ---------------------------------------------------------------------------