@gamaze/hicortex 0.10.1 → 0.11.0

package/dist/db.js

@@ -250,6 +250,76 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 5,
+        name: "rescale_link_strength_to_cosine",
+        up: (db) => {
+            // memory_links.strength was stored on an accidental 1−L2 scale
+            // (consolidate.ts computed similarity as `1 − distance`, where distance
+            // is sqlite-vec's L2 distance). Embeddings are L2-normalized, so the
+            // true cosine is 1 − d²/2; with old = 1 − d this rewrites to
+            //   cosine = 1 − (1 − old)² / 2.
+            // LLM-classified links also stored the candidate similarity as
+            // strength, so the rewrite applies to ALL rows. Guarded to strengths in
+            // (0, 1] — the only range the old formula could have written above the
+            // link threshold (values are 0.55–0.8 in practice); anything outside is
+            // left untouched. The rewrite is NOT self-idempotent: it must run
+            // exactly once, which the schema_version gate in migrate() guarantees
+            // (up() and the version-row insert share one transaction).
+            db.exec(`
+        UPDATE memory_links
+        SET strength = 1.0 - ((1.0 - strength) * (1.0 - strength)) / 2.0
+        WHERE strength > 0 AND strength <= 1
+      `);
+        },
+    },
+    {
+        version: 6,
+        name: "add_memory_tags",
+        up: (db) => {
+            // Multi-tag classification (feat/memory-tags). `memories.domain` keeps its
+            // meaning as the PRIMARY tag; this sidecar table carries the full label
+            // set (including the primary). Sidecar (not a virtual-table column) per
+            // the migration rules above. FK → memories(id); deletes cascade in code
+            // (storage.deleteMemory) since foreign_keys pragma is on but existing rows
+            // predate the constraint. Idempotent: IF NOT EXISTS on table + index.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS memory_tags (
+          memory_id TEXT NOT NULL,
+          tag TEXT NOT NULL,
+          PRIMARY KEY (memory_id, tag),
+          FOREIGN KEY (memory_id) REFERENCES memories(id)
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_tags_tag ON memory_tags(tag)");
+        },
+    },
+    {
+        version: 7,
+        name: "graded_tag_weights",
+        up: (db) => {
+            // Graded schema membership (spec 2026-07-07): every tag assignment gets a
+            // derived association weight = cosine(memory embedding, domain prototype).
+            // NULL until the first prototype/weight computation runs (nightly stage or
+            // classification-time write). Guarded with hasColumn for idempotency
+            // across partially-migrated databases.
+            if (!hasColumn(db, "memory_tags", "weight")) {
+                db.exec("ALTER TABLE memory_tags ADD COLUMN weight REAL");
+            }
+            // Domain prototypes: L2-normalized centroid of member embeddings (or the
+            // embedded config description as a cold-start seed when member_count < 5).
+            // Sidecar table, NOT a vec0 virtual table — prototypes are point-read by
+            // name, never KNN-searched (see the virtual-table rule above).
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS domain_prototypes (
+          domain TEXT PRIMARY KEY,
+          embedding BLOB,
+          member_count INTEGER,
+          updated_at TIMESTAMP
+        )
+      `);
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/domain-classify.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Content-based memory MULTI-TAG classification (feat/memory-tags).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The nightly's legacy `stageDomainCuration` groups PROJECTS into domains and
+ * assigns every memory its project's domain. For an owner whose "projects" are
+ * often AGENT names (lenny, nano, ...), one agent produces memories spanning
+ * many life areas, so life-memories get smeared under the agent. This module
+ * classifies a single memory into life-spheres by its CONTENT, drawn from a
+ * user-curated vocabulary in ~/.hicortex/config.json (`domains`).
+ *
+ * GRADED SCHEMA TAGS (spec 2026-07-07, supersedes the LLM-picked primary from
+ * PR #152/#153): a memory genuinely spans spheres — "set up bedrock for the
+ * agent fleet" is both Hardware AND Ventures. The classifier now returns ONLY
+ * the discrete part:
+ *   - `tags`: 0..N vocabulary names that genuinely apply, MOST-RELEVANT FIRST
+ *     (the order is used solely as an exact-weight tiebreak downstream).
+ * The PRIMARY (memories.domain) is NO LONGER requested from the LLM — audits
+ * proved LLM primaries a coin-flip on overlapping spheres. It is DERIVED
+ * deterministically (argmax association weight + compartment override) in
+ * schema-prototypes.ts / storage.setMemoryTags.
+ *
+ * NO-FIT = EMPTY TAG SET (owner amendment 07.07): "Unsorted" is a non-tag —
+ * there is NO fallback category in the vocabulary and no configured domain is
+ * ever auto-assigned on a no-fit. A genuine no-fit is the distinct result
+ * `{tags: []}`; the CALLER then derives a weak primary from prototype cosines
+ * (>= the weakPrimaryFloor) or, below the floor, applies accelerated decay
+ * (see nofit.ts). If a user still configures a domain named "Unsorted", it is
+ * just a normal domain with no special semantics.
+ *
+ * The `project` name is passed to the classifier as a HINT (content wins;
+ * project only breaks ties). This rescues terse technical memories from
+ * projects like raider/hiops/catalyst whose content alone reads as ambiguous.
+ *
+ * The classifier makes ONE constrained LLM call per memory (via the classify
+ * tier — classifyModel/classifyBaseUrl when configured, else the reflect
+ * tier), validates every returned name against the configured vocabulary
+ * (case-insensitive), and retries once on an invalid/unparseable reply.
+ *
+ * ROBUSTNESS (folds in issue #150):
+ *   - Successful classification with no genuine fit → {tags: []} (no-fit).
+ *   - LLM/endpoint ERROR (throws after the retry) → returns NULL. The caller
+ *     leaves the memory unclassified and retries it on a later run. Infra
+ *     errors must NOT be filed anywhere (that mis-labels good memories).
+ *
+ * SCOPE: sphere-level tags only. Sub-labels within a sphere are a future phase.
+ *
+ * Example owner vocabulary (documented, NOT hardcoded — lives in config.json):
+ *   Work, Ventures, Hardware, Finances, Property, Vehicles, Boating, Health,
+ *   Family, People, Travel
+ */
+import type { LlmClient } from "./llm.js";
+import type { DomainDef } from "./types.js";
+export type { DomainDef };
+/** Max characters of memory content fed to the classifier prompt. */
+export declare const CLASSIFY_CONTENT_MAX_CHARS = 1500;
+/**
+ * Parse and validate the `domains` field from a raw config.json object.
+ * Returns a clean DomainDef[] (name + description both non-empty strings) or
+ * null when the field is absent or malformed — null means "content
+ * classification is NOT active; keep the legacy project-grouping path".
+ *
+ * A present-but-empty array is treated as null (nothing to classify into).
+ */
+export declare function parseConfigDomains(config: Record<string, unknown> | null | undefined): DomainDef[] | null;
+/**
+ * Stable cache-invalidation key for a configured domain set: sha256 of the
+ * sorted, lowercased domain names. Changing the list (add/remove/rename)
+ * changes the hash and triggers a re-file of affected rows.
+ */
+export declare function domainSetHash(domains: DomainDef[]): string;
+/**
+ * Match an LLM reply against the configured domain set (case-insensitive).
+ * Returns the CANONICAL name from the config (preserving its casing) or null.
+ *
+ * Tolerates common LLM decorations: surrounding quotes, a trailing period,
+ * a leading "Domain:" label, and markdown emphasis. The match is exact on the
+ * normalized token — we do NOT substring-match, to avoid "People" matching
+ * inside "Peoples' court" style noise.
+ */
+export declare function matchDomain(reply: string, domains: DomainDef[]): string | null;
+/**
+ * Result of a successful multi-tag classification.
+ *   - `tags`: 0..N vocabulary names that genuinely apply, MOST-RELEVANT FIRST
+ *     (LLM order — used downstream only as an exact-weight tiebreak), deduped,
+ *     all members of the configured vocabulary.
+ *   - An EMPTY array is a distinct, VALID result: genuine no-fit (owner
+ *     amendment 07.07 — no fallback category). Callers route it through the
+ *     weak-primary / no-association-decay path (nofit.ts). It is NOT the same
+ *     as null (null = infra error → skip and retry later).
+ *
+ * There is deliberately NO `primary` field (graded-schema spec 2026-07-07):
+ * the primary is derived from association weights, never from the LLM.
+ */
+export interface TagResult {
+    tags: string[];
+}
+/**
+ * Build the constrained multi-tag classification prompt.
+ *
+ * Includes: the vocabulary (names + descriptions), the (truncated) memory
+ * content, and the source `project` name as a HINT. The model is instructed to
+ * apply EVERY genuinely-applicable tag (with an explicit multi-tag emphasis —
+ * things the owner builds usually carry both the venture/project domain AND
+ * the life topic they touch) and reply with ONLY a `{"tags": [...]}` object,
+ * most-relevant first. No primary, no weights, no ranks — the LLM decides
+ * only DISCRETE membership; all gradation is derived from embeddings.
+ *
+ * The emphasis sentence is GENERIC by design: concrete pairings (which venture
+ * touches which topic) must come from the configured domain DESCRIPTIONS, not
+ * from hardcoded examples in the product prompt.
+ *
+ * The project hint is deliberately weak ("content wins, project only breaks
+ * ties") — it rescues terse technical memories whose content alone reads as
+ * ambiguous, without letting the project name override clear content signals.
+ */
+export declare function buildClassifyPrompt(content: string, project: string | null | undefined, domains: DomainDef[]): string;
+/**
+ * Parse the model reply into a validated, ORDERED {tags} against the
+ * vocabulary.
+ *
+ * Return values (three distinct outcomes):
+ *   - {tags: [...]} — >= 1 valid vocabulary tag (canonical-cased, ordered).
+ *   - {tags: []}    — the model EXPLICITLY replied with an empty tags array:
+ *     genuine no-fit (owner amendment 07.07). NOT retried by the caller.
+ *   - null          — unparseable reply, missing/non-array `tags`, or a
+ *     NON-EMPTY tags array in which no name matched the vocabulary (invalid
+ *     names are dropped — an all-invalid reply is a bad reply, not a no-fit).
+ *     The caller retries once.
+ *
+ * Accepts a JSON object with `tags`, tolerating code-fence wrapping and
+ * surrounding prose. The legacy `{"primary": ..., "tags": [...]}` shape is
+ * ACCEPTED for tolerance (older models / cached prompts may still emit it) but
+ * `primary` is IGNORED — nothing is derived from it (graded-schema spec: the
+ * primary comes from weights, never the LLM). Every tag name is matched
+ * case-insensitively via matchDomain; invalid names are dropped; duplicates
+ * are removed keeping the first (most-relevant) occurrence.
+ */
+export declare function parseTagReply(reply: string, domains: DomainDef[]): TagResult | null;
+/**
+ * Multi-tag classify one memory's content against the configured vocabulary.
+ *
+ * Uses the classify tier (`completeClassify` → classifyBaseUrl/classifyModel
+ * when configured, else the reflect tier) — the caller is responsible for
+ * having pre-flighted that endpoint via resolveClassifyProbeTarget (strict:
+ * skip classification entirely if it is unreachable).
+ *
+ * Behaviour:
+ *   - Valid JSON reply with ≥1 vocabulary tag → {tags} (ordered,
+ *     most-relevant first).
+ *   - Valid reply with an EXPLICIT empty tags array → {tags: []} (genuine
+ *     no-fit — owner amendment 07.07: no fallback category is ever assigned;
+ *     the caller routes empty tag sets through nofit.ts).
+ *   - Unparseable / no-valid-tag reply → retry ONCE, then treat as a genuine
+ *     no-fit: {tags: []} (the model responded twice but produced nothing
+ *     usable — the embedding-side weak-primary/decay path takes over).
+ *   - LLM THROWS after the retry → return NULL (infra error; caller aborts this
+ *     memory for a later retry — never filed anywhere, closes #150).
+ *
+ * @returns {tags} on success (all members of the vocabulary; empty = no-fit),
+ *          or null on infra error.
+ */
+export declare function classifyMemoryTags(content: string, project: string | null | undefined, domains: DomainDef[], llm: LlmClient): Promise<TagResult | null>;

package/dist/domain-classify.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * Content-based memory MULTI-TAG classification (feat/memory-tags).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The nightly's legacy `stageDomainCuration` groups PROJECTS into domains and
+ * assigns every memory its project's domain. For an owner whose "projects" are
+ * often AGENT names (lenny, nano, ...), one agent produces memories spanning
+ * many life areas, so life-memories get smeared under the agent. This module
+ * classifies a single memory into life-spheres by its CONTENT, drawn from a
+ * user-curated vocabulary in ~/.hicortex/config.json (`domains`).
+ *
+ * GRADED SCHEMA TAGS (spec 2026-07-07, supersedes the LLM-picked primary from
+ * PR #152/#153): a memory genuinely spans spheres — "set up bedrock for the
+ * agent fleet" is both Hardware AND Ventures. The classifier now returns ONLY
+ * the discrete part:
+ *   - `tags`: 0..N vocabulary names that genuinely apply, MOST-RELEVANT FIRST
+ *     (the order is used solely as an exact-weight tiebreak downstream).
+ * The PRIMARY (memories.domain) is NO LONGER requested from the LLM — audits
+ * proved LLM primaries a coin-flip on overlapping spheres. It is DERIVED
+ * deterministically (argmax association weight + compartment override) in
+ * schema-prototypes.ts / storage.setMemoryTags.
+ *
+ * NO-FIT = EMPTY TAG SET (owner amendment 07.07): "Unsorted" is a non-tag —
+ * there is NO fallback category in the vocabulary and no configured domain is
+ * ever auto-assigned on a no-fit. A genuine no-fit is the distinct result
+ * `{tags: []}`; the CALLER then derives a weak primary from prototype cosines
+ * (>= the weakPrimaryFloor) or, below the floor, applies accelerated decay
+ * (see nofit.ts). If a user still configures a domain named "Unsorted", it is
+ * just a normal domain with no special semantics.
+ *
+ * The `project` name is passed to the classifier as a HINT (content wins;
+ * project only breaks ties). This rescues terse technical memories from
+ * projects like raider/hiops/catalyst whose content alone reads as ambiguous.
+ *
+ * The classifier makes ONE constrained LLM call per memory (via the classify
+ * tier — classifyModel/classifyBaseUrl when configured, else the reflect
+ * tier), validates every returned name against the configured vocabulary
+ * (case-insensitive), and retries once on an invalid/unparseable reply.
+ *
+ * ROBUSTNESS (folds in issue #150):
+ *   - Successful classification with no genuine fit → {tags: []} (no-fit).
+ *   - LLM/endpoint ERROR (throws after the retry) → returns NULL. The caller
+ *     leaves the memory unclassified and retries it on a later run. Infra
+ *     errors must NOT be filed anywhere (that mis-labels good memories).
+ *
+ * SCOPE: sphere-level tags only. Sub-labels within a sphere are a future phase.
+ *
+ * Example owner vocabulary (documented, NOT hardcoded — lives in config.json):
+ *   Work, Ventures, Hardware, Finances, Property, Vehicles, Boating, Health,
+ *   Family, People, Travel
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLASSIFY_CONTENT_MAX_CHARS = void 0;
+exports.parseConfigDomains = parseConfigDomains;
+exports.domainSetHash = domainSetHash;
+exports.matchDomain = matchDomain;
+exports.buildClassifyPrompt = buildClassifyPrompt;
+exports.parseTagReply = parseTagReply;
+exports.classifyMemoryTags = classifyMemoryTags;
+const node_crypto_1 = require("node:crypto");
+/** Max characters of memory content fed to the classifier prompt. */
+exports.CLASSIFY_CONTENT_MAX_CHARS = 1500;
+/**
+ * Parse and validate the `domains` field from a raw config.json object.
+ * Returns a clean DomainDef[] (name + description both non-empty strings) or
+ * null when the field is absent or malformed — null means "content
+ * classification is NOT active; keep the legacy project-grouping path".
+ *
+ * A present-but-empty array is treated as null (nothing to classify into).
+ */
+function parseConfigDomains(config) {
+    const raw = config?.domains;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "object" || item === null)
+            continue;
+        const d = item;
+        const name = typeof d.name === "string" ? d.name.trim() : "";
+        const description = typeof d.description === "string" ? d.description.trim() : "";
+        if (!name)
+            continue;
+        const def = { name, description };
+        // Compartment policy passthrough (graded-schema spec): a domain flagged
+        // `compartment: true` becomes the primary whenever tagged.
+        if (d.compartment === true)
+            def.compartment = true;
+        out.push(def);
+    }
+    return out.length > 0 ? out : null;
+}
+/**
+ * Stable cache-invalidation key for a configured domain set: sha256 of the
+ * sorted, lowercased domain names. Changing the list (add/remove/rename)
+ * changes the hash and triggers a re-file of affected rows.
+ */
+function domainSetHash(domains) {
+    const names = domains.map((d) => d.name.trim().toLowerCase()).sort();
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(names)).digest("hex");
+}
+/**
+ * Match an LLM reply against the configured domain set (case-insensitive).
+ * Returns the CANONICAL name from the config (preserving its casing) or null.
+ *
+ * Tolerates common LLM decorations: surrounding quotes, a trailing period,
+ * a leading "Domain:" label, and markdown emphasis. The match is exact on the
+ * normalized token — we do NOT substring-match, to avoid "People" matching
+ * inside "Peoples' court" style noise.
+ */
+function matchDomain(reply, domains) {
+    if (!reply)
+        return null;
+    let cleaned = reply.trim();
+    // Take the first non-empty line — models sometimes add a justification below.
+    const firstLine = cleaned.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0);
+    if (firstLine)
+        cleaned = firstLine;
+    // Strip a leading label like "Domain:" / "Answer:".
+    cleaned = cleaned.replace(/^(domain|answer|category|sphere)\s*[:\-]\s*/i, "");
+    // Strip markdown emphasis, surrounding quotes/backticks, trailing punctuation.
+    cleaned = cleaned
+        .replace(/^[*_`"'\s]+/, "")
+        .replace(/[*_`"'.\s]+$/, "")
+        .trim();
+    const norm = cleaned.toLowerCase();
+    for (const d of domains) {
+        if (d.name.trim().toLowerCase() === norm)
+            return d.name;
+    }
+    return null;
+}
+/**
+ * Build the constrained multi-tag classification prompt.
+ *
+ * Includes: the vocabulary (names + descriptions), the (truncated) memory
+ * content, and the source `project` name as a HINT. The model is instructed to
+ * apply EVERY genuinely-applicable tag (with an explicit multi-tag emphasis —
+ * things the owner builds usually carry both the venture/project domain AND
+ * the life topic they touch) and reply with ONLY a `{"tags": [...]}` object,
+ * most-relevant first. No primary, no weights, no ranks — the LLM decides
+ * only DISCRETE membership; all gradation is derived from embeddings.
+ *
+ * The emphasis sentence is GENERIC by design: concrete pairings (which venture
+ * touches which topic) must come from the configured domain DESCRIPTIONS, not
+ * from hardcoded examples in the product prompt.
+ *
+ * The project hint is deliberately weak ("content wins, project only breaks
+ * ties") — it rescues terse technical memories whose content alone reads as
+ * ambiguous, without letting the project name override clear content signals.
+ */
+function buildClassifyPrompt(content, project, domains) {
+    const list = domains.map((d) => `- ${d.name}: ${d.description}`).join("\n");
+    const truncated = content.length > exports.CLASSIFY_CONTENT_MAX_CHARS
+        ? content.slice(0, exports.CLASSIFY_CONTENT_MAX_CHARS) + "…"
+        : content;
+    const projectHint = project && project.trim()
+        ? `Source project: ${project.trim()} — a useful signal, but classify by ` +
+            `content; content wins, the project only breaks ties.\n\n`
+        : "";
+    return (`You are tagging a single memory with life-sphere domains.\n\n` +
+        `DOMAINS (name: description):\n${list}\n\n` +
+        projectHint +
+        `MEMORY:\n${truncated}\n\n` +
+        `Apply EVERY domain that genuinely applies — memories often span several. ` +
+        `Memories about things the owner builds or runs usually carry BOTH the ` +
+        `venture/project domain AND the life topic they touch. ` +
+        `List 1-4 domains, most relevant first. ` +
+        `If none genuinely fits, reply {"tags": []}.\n` +
+        `Reply with ONLY a JSON object, no prose:\n` +
+        `{"tags": ["<most relevant domain>", "<next domain>", ...]}\n` +
+        `Every name MUST come from the list above.`);
+}
+/**
+ * Parse the model reply into a validated, ORDERED {tags} against the
+ * vocabulary.
+ *
+ * Return values (three distinct outcomes):
+ *   - {tags: [...]} — >= 1 valid vocabulary tag (canonical-cased, ordered).
+ *   - {tags: []}    — the model EXPLICITLY replied with an empty tags array:
+ *     genuine no-fit (owner amendment 07.07). NOT retried by the caller.
+ *   - null          — unparseable reply, missing/non-array `tags`, or a
+ *     NON-EMPTY tags array in which no name matched the vocabulary (invalid
+ *     names are dropped — an all-invalid reply is a bad reply, not a no-fit).
+ *     The caller retries once.
+ *
+ * Accepts a JSON object with `tags`, tolerating code-fence wrapping and
+ * surrounding prose. The legacy `{"primary": ..., "tags": [...]}` shape is
+ * ACCEPTED for tolerance (older models / cached prompts may still emit it) but
+ * `primary` is IGNORED — nothing is derived from it (graded-schema spec: the
+ * primary comes from weights, never the LLM). Every tag name is matched
+ * case-insensitively via matchDomain; invalid names are dropped; duplicates
+ * are removed keeping the first (most-relevant) occurrence.
+ */
+function parseTagReply(reply, domains) {
+    if (!reply)
+        return null;
+    // Extract the first {...} block (tolerates ```json fences and stray prose).
+    const start = reply.indexOf("{");
+    const end = reply.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(reply.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== "object" || obj === null)
+        return null;
+    const o = obj;
+    // `tags` must be an ARRAY — a missing or malformed field is an invalid
+    // reply (null → retry), NOT a no-fit.
+    if (!Array.isArray(o.tags))
+        return null;
+    const rawTags = o.tags;
+    // Explicit empty array = genuine no-fit — a distinct, valid result.
+    if (rawTags.length === 0)
+        return { tags: [] };
+    // Collect valid tags (canonical-cased, deduped, ORDER-PRESERVING — the LLM's
+    // most-relevant-first order is the downstream exact-weight tiebreak).
+    const seen = new Set();
+    const tags = [];
+    for (const t of rawTags) {
+        if (typeof t !== "string")
+            continue;
+        const matched = matchDomain(t, domains);
+        if (matched && !seen.has(matched)) {
+            seen.add(matched);
+            tags.push(matched);
+        }
+    }
+    // Legacy `primary` field: tolerated in the shape, derives NOTHING.
+    // A non-empty raw array with ZERO vocabulary matches is an invalid reply.
+    if (tags.length === 0)
+        return null;
+    return { tags };
+}
+/**
+ * Multi-tag classify one memory's content against the configured vocabulary.
+ *
+ * Uses the classify tier (`completeClassify` → classifyBaseUrl/classifyModel
+ * when configured, else the reflect tier) — the caller is responsible for
+ * having pre-flighted that endpoint via resolveClassifyProbeTarget (strict:
+ * skip classification entirely if it is unreachable).
+ *
+ * Behaviour:
+ *   - Valid JSON reply with ≥1 vocabulary tag → {tags} (ordered,
+ *     most-relevant first).
+ *   - Valid reply with an EXPLICIT empty tags array → {tags: []} (genuine
+ *     no-fit — owner amendment 07.07: no fallback category is ever assigned;
+ *     the caller routes empty tag sets through nofit.ts).
+ *   - Unparseable / no-valid-tag reply → retry ONCE, then treat as a genuine
+ *     no-fit: {tags: []} (the model responded twice but produced nothing
+ *     usable — the embedding-side weak-primary/decay path takes over).
+ *   - LLM THROWS after the retry → return NULL (infra error; caller aborts this
+ *     memory for a later retry — never filed anywhere, closes #150).
+ *
+ * @returns {tags} on success (all members of the vocabulary; empty = no-fit),
+ *          or null on infra error.
+ */
+async function classifyMemoryTags(content, project, domains, llm) {
+    if (domains.length === 0)
+        return { tags: [] };
+    const prompt = buildClassifyPrompt(content, project, domains);
+    let threw = false;
+    // Two attempts: one call, one retry on a throw OR an unparseable reply.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let raw;
+        try {
+            // ~64 tokens covers a short JSON object with a handful of tags.
+            raw = await llm.completeClassify(prompt, 64);
+            threw = false;
+        }
+        catch (err) {
+            threw = true;
+            if (attempt === 0)
+                continue; // retry once
+            console.warn(`[hicortex] tag classify LLM error: ${err instanceof Error ? err.message : String(err)} — aborting this memory (will retry)`);
+            return null; // infra error → abort untouched (never filed, never decayed)
+        }
+        const parsed = parseTagReply(raw, domains);
+        if (parsed)
+            return parsed;
+        if (attempt === 0) {
+            console.warn(`[hicortex] tag classify: unparseable reply "${raw.slice(0, 60)}" — retrying once`);
+        }
+    }
+    // Two successful calls, neither parseable → treated as a genuine no-fit
+    // (empty tag set). (If the second attempt THREW we returned null above;
+    // reaching here means the model responded but produced no valid vocabulary
+    // tag.) The weak-primary floor guards against mis-decaying a good memory:
+    // if it genuinely associates with a domain, the embedding argmax tags it.
+    if (threw)
+        return null;
+    return { tags: [] };
+}

package/dist/extensions.d.ts

@@ -46,6 +46,11 @@ export interface SelectableLesson {
     access_count?: number;
     id?: string;
     memory_type?: string;
+    /**
+     * Life-sphere domain (content-based classification). Present on Memory rows.
+     * Used by the same-domain affinity boost when the context carries a `domain`.
+     */
+    domain?: string | null;
 }
 export interface LessonSelectorContext {
     /** Maximum number of lessons to return. Caller decides this from features.lessonsLimit(). */
@@ -58,6 +63,13 @@ export interface LessonSelectorContext {
     currentTask?: string;
     /** MODULE_INDEX for domain-aware lesson selection (same-domain projects score 0.5). */
     moduleIndex?: ModuleIndex;
+    /**
+     * Current life-sphere domain, if known (content-based classification). When
+     * set, lessons in the SAME domain get the same-domain affinity boost directly
+     * off `lesson.domain` — the content-mode analogue of the project-grouping
+     * moduleIndex boost.
+     */
+    domain?: string | null;
 }
 export interface LessonSelector {
     /**

package/dist/graph.d.ts

@@ -51,4 +51,60 @@ export interface GraphNeighbor {
     project: string | null;
 }
 export declare function getNeighbors(db: Database.Database, memoryId: string, limit?: number, relationship?: string): GraphNeighbor[];
+export declare const EXPORT_DEFAULT_LIMIT = 5000;
+export declare const EXPORT_MAX_LIMIT = 10000;
+export interface VizNode {
+    id: string;
+    label: string;
+    content: string;
+    memory_type: string | null;
+    domain: string | null;
+    tags: string[];
+    tagWeights: number[];
+    project: string | null;
+    strength: number;
+    linkCount: number;
+    isHub: boolean;
+    created_at: string | null;
+}
+export interface VizEdge {
+    source: string;
+    target: string;
+    relationship: string;
+    strength: number;
+}
+export interface VizGraph {
+    nodes: VizNode[];
+    edges: VizEdge[];
+    domains: string[];
+    types: string[];
+    meta: {
+        total: number;
+        shown: number;
+        edgeCount: number;
+    };
+}
+export interface ExportGraphOptions {
+    domain?: string;
+    type?: string;
+    /**
+     * "Everything touching X" (graded-schema spec): keep only nodes CARRYING the
+     * tag, any weight. A node with no memory_tags rows counts as carrying its
+     * `domain` (mirrors the payload's tags fallback). Unlike `domain`, which
+     * matches only the derived primary.
+     */
+    tag?: string;
+    minStrength?: number;
+    limit?: number;
+}
+/**
+ * Assemble the full node/edge payload for the /viz page.
+ *
+ * Nodes are ranked by effective (decayed) strength and capped at `limit`.
+ * Edges include only links where BOTH endpoints made the cut.
+ * Link counts come from one aggregate query over memory_links (no per-row
+ * queries) and feed both the effectiveStrength hardening term and the
+ * per-node linkCount field.
+ */
+export declare function exportGraph(db: Database.Database, options?: ExportGraphOptions): VizGraph;
 export declare function shortestPath(db: Database.Database, fromId: string, toId: string, maxDepth?: number): string[] | null;