@gamaze/hicortex 0.15.2 → 0.16.0

package/dist/retrieval.js

@@ -52,12 +52,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
+exports.SESSION_INTENT_ALPHA = exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
 exports.decayConstantForHalfLife = decayConstantForHalfLife;
 exports.configureDecay = configureDecay;
 exports.configureRecall = configureRecall;
 exports.configureScoring = configureScoring;
 exports.getScoringWeights = getScoringWeights;
+exports.configureSessionIntent = configureSessionIntent;
+exports.getSessionIntent = getSessionIntent;
+exports.blendQueryVector = blendQueryVector;
 exports.findSupersededIds = findSupersededIds;
 exports.l2ToCosine = l2ToCosine;
 exports.effectiveStrength = effectiveStrength;
@@ -65,6 +68,7 @@ exports.computeScore = computeScore;
 exports.retrieve = retrieve;
 exports.searchRecent = searchRecent;
 const storage = __importStar(require("./storage.js"));
+const schema_prototypes_js_1 = require("./schema-prototypes.js");
 /** Default decay half-life (days) at importance 0.5. #192: was 0.0005/h
  *  (~115-day half-life at base 0.5) — aggressive enough to bury the long tail
  *  in ranking. Long-term remembering is the product; time preference stays,
@@ -124,19 +128,45 @@ const SCORING_DEFAULTS = {
     freshnessBoostDays: 7,
     freshnessBoostWeight: 0.15,
     supersededDemotion: 0.5,
+    projectAffinity: 0.15,
+    domainAffinity: 0.15,
+    // #205 defaults: rrfK + rrfCompositeWeight match the pre-#205 hardcoded
+    // values (60 and 0.8) so the no-config path is byte-identical to 0.15.3
+    // except for the FTS per-list weight (1.0 → 0.5) — the one deliberate
+    // nudge toward vector that the recall-sweep eval gates. The eval showed
+    // 0.7 was too timid (Q4 marine contamination persisted) and 0.5 is the
+    // bisection point where BM25F + composite-affinity finally flip the
+    // token-exact marine body match below the same-scope hardware field
+    // (Q4 ON contamination 0.20 → 0.00). 0.5 is still "conservative" — FTS
+    // contributes half its RRF share, enough that pure-keyword queries (the
+    // focused-family "login/CORS/webhook" turns) keep recall@5 = 1.0.
+    rrfK: 60,
+    rrfCompositeWeight: 0.8,
+    rrfFtsWeight: 0.5,
+    rrfVectorWeight: 1.0,
 };
 let scoringWeights = { ...SCORING_DEFAULTS };
 /**
  * Configure scoring weights + ranking knobs from config. Called at boot by the
  * server and the nightly (alongside configureDecay/configureRecall) so
  * retrieval and consolidation rank identically. Invalid/absent values keep the
- * shipped default per key. Returns the resolved set for logging/tests.
+ * shipped default per key. Returns the resolved set for logging/tests. Also
+ * pushes the #205 BM25F field weights into storage (storage.configureBm25Fts)
+ * so searchFts ranks with the same config — BM25F weights live in storage.ts
+ * (next to the FTS column declaration they mirror) but are read here from the
+ * SAME config object for one-place tuning.
  */
 function configureScoring(config) {
     const num = (key, dflt, min, max) => {
         const v = Number(config?.[key]);
         return Number.isFinite(v) && v >= min && v <= max ? v : dflt;
     };
+    // #205 BM25F weights use a [0, ∞) range (no upper bound — a field can dominate
+    // if the operator wills it; 0 drops the field entirely). Invalid ⇒ default.
+    const numW = (key, dflt) => {
+        const v = Number(config?.[key]);
+        return Number.isFinite(v) && v >= 0 ? v : dflt;
+    };
     scoringWeights = {
         similarity: num("scoreSimilarityWeight", SCORING_DEFAULTS.similarity, 0, 1),
         strength: num("scoreStrengthWeight", SCORING_DEFAULTS.strength, 0, 1),
@@ -145,13 +175,80 @@ function configureScoring(config) {
         freshnessBoostDays: num("freshnessBoostDays", SCORING_DEFAULTS.freshnessBoostDays, 0, 365),
         freshnessBoostWeight: num("freshnessBoostWeight", SCORING_DEFAULTS.freshnessBoostWeight, 0, 1),
         supersededDemotion: num("supersededDemotion", SCORING_DEFAULTS.supersededDemotion, 0, 1),
+        projectAffinity: num("projectAffinityWeight", SCORING_DEFAULTS.projectAffinity, 0, 1),
+        domainAffinity: num("domainAffinityWeight", SCORING_DEFAULTS.domainAffinity, 0, 1),
+        rrfK: numW("rrfK", SCORING_DEFAULTS.rrfK),
+        rrfCompositeWeight: num("rrfCompositeWeight", SCORING_DEFAULTS.rrfCompositeWeight, 0, 1),
+        rrfFtsWeight: numW("rrfFtsWeight", SCORING_DEFAULTS.rrfFtsWeight),
+        rrfVectorWeight: numW("rrfVectorWeight", SCORING_DEFAULTS.rrfVectorWeight),
     };
+    // #205: push BM25F field weights into storage so searchFts uses them. Same
+    // config object, one tuning surface; storage owns the module-level mirror
+    // next to the FTS column declaration (the positional order matters there).
+    storage.configureBm25Fts({
+        bm25WeightBody: numW("bm25WeightBody", 1.0),
+        bm25WeightProject: numW("bm25WeightProject", 2.0),
+        bm25WeightDomain: numW("bm25WeightDomain", 2.0),
+    });
     return { ...scoringWeights };
 }
 /** Current resolved weights (tests + status output). */
 function getScoringWeights() {
     return { ...scoringWeights };
 }
+// ---------------------------------------------------------------------------
+// Session-intent keying (#192, 0.15.3). ONE config knob:
+//   sessionIntentWeight  0.33  blend weight of the rolling centroid in the
+//                              search vector: query = (1-w)·prompt + w·centroid.
+//                              0 = DISABLED (pure prompt, the kill-switch —
+//                              current behavior). Range [0, 1].
+//
+// The EMA rate α is a shipped constant (SESSION_INTENT_ALPHA, 0.4), not a
+// second knob — owner directive 0.15.3: one knob is enough to tune/disable;
+// exposing α was speculative generality.
+//
+// The centroid itself lives on SessionRecallRegistry; retrieval only needs to
+// ACCEPT a pre-blended query vector (options.queryEmbedding) so the recall
+// closure can do the one-embed-per-recall + blend without retrieve()
+// re-embedding. /search and other unblended callers omit queryEmbedding and
+// get pure-prompt behavior unchanged.
+// ---------------------------------------------------------------------------
+/** EMA rate for the session-intent centroid: centroid_new = (1-α)·old + α·prompt. */
+exports.SESSION_INTENT_ALPHA = 0.4;
+const SESSION_INTENT_DEFAULT_WEIGHT = 0.33;
+let sessionIntentWeight = SESSION_INTENT_DEFAULT_WEIGHT;
+/**
+ * Configure session-intent keying from config. Called at server boot next to
+ * configureScoring (the nightly does no recall, so it does not need this).
+ * Reads only `sessionIntentWeight` ([0,1]; 0 = disabled). Invalid/out-of-range
+ * values keep the shipped default. Returns `{ weight, alpha }` — alpha is the
+ * fixed constant, surfaced so the recall closure passes it to the registry in
+ * one call.
+ */
+function configureSessionIntent(config) {
+    const v = Number(config?.sessionIntentWeight);
+    sessionIntentWeight =
+        Number.isFinite(v) && v >= 0 && v <= 1 ? v : SESSION_INTENT_DEFAULT_WEIGHT;
+    return { weight: sessionIntentWeight, alpha: exports.SESSION_INTENT_ALPHA };
+}
+/** Current resolved session-intent weight + the shipped alpha (closure + tests). */
+function getSessionIntent() {
+    return { weight: sessionIntentWeight, alpha: exports.SESSION_INTENT_ALPHA };
+}
+/**
+ * Blend the prompt embedding with the session-intent centroid for the vector
+ * search: `query = l2Normalize((1-w)·prompt + w·centroid)`. Returns the prompt
+ * UNCHANGED when `centroid` is undefined (first turn — no behavior change) or
+ * `weight` is 0 (the kill-switch — pure prompt). Extracted from the
+ * /recall-index closure (mcp-server.ts) so the exact blend decision is
+ * unit-testable directly, locking the ternary against a refactor without a
+ * closure-integration harness.
+ */
+function blendQueryVector(promptEmb, centroid, weight) {
+    return centroid && weight > 0
+        ? (0, schema_prototypes_js_1.l2Normalize)((0, schema_prototypes_js_1.weightedAdd)(promptEmb, 1 - weight, centroid, weight))
+        : promptEmb;
+}
 /**
  * Ids among `candidateIds` that have been superseded by a later memory — i.e.
  * they are the SOURCE of a `superseded_by` link (stageSupersession links
@@ -176,7 +273,12 @@ function findSupersededIds(db, candidateIds) {
  * these candidates to cosine 0.875, outranking most true vector matches.
  */
 const DEFAULT_GRAPH_DISTANCE = 1.0;
-const RRF_K = 60;
+// RRF_K is no longer a module constant (#205): it lives in scoringWeights.rrfK
+// (default 60, the pre-#205 hardcoded value) and is read at every retrieve()
+// call so config changes apply without a restart. The DEFAULT_RRF_K here is a
+// fallback for reciprocalRankFusion's optional k argument (tests + the rare
+// non-retrieve caller), NOT the production path.
+const DEFAULT_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
@@ -228,10 +330,6 @@ function effectiveStrength(baseStrength, lastAccessed, now, options) {
     const floor = baseStrength * importance * 0.1;
     return floor + (baseStrength - floor) * Math.pow(decayRate, hours);
 }
-/**
- * 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, options) {
     // TRUE cosine similarity (#145). The old `1 − distance` compressed real
     // cosines (cos 0.8 scored 0.37) and the 0-clamp at that scale flattened
@@ -270,6 +368,35 @@ function computeScore(memory, distance, connectionCount, maxConnections, now, op
         const freshness = 1 - ageDays / scoringWeights.freshnessBoostDays;
         score += freshness * scoringWeights.freshnessBoostWeight;
     }
+    // #203 soft affinity (retrieval scoping). Two graded, additive terms — both
+    // ZERO when the scope is absent (byte-identical ranking) and ZERO for a
+    // non-matching memory (never a penalty). Project affinity is a flat boost on
+    // exact project match; domain affinity is max(overlapping tag weight) × the
+    // domain weight. NULL tag weights (not yet computed by the nightly
+    // reconsolidation) count as 0 — we never invent a boost from missing
+    // association strength. Affinity rides the 0.8 composite side only (the RRF
+    // 0.2 side is #205 territory and untouched here).
+    const scope = options?.scope;
+    if (scope) {
+        if (scope.project && memory.project === scope.project) {
+            score += scoringWeights.projectAffinity;
+        }
+        const domains = scope.missionDomains;
+        if (domains && domains.length > 0 && options.tagWeights && options.tagWeights.length > 0) {
+            const domainSet = domains.length === 1 ? null : new Set(domains);
+            let maxWeight = 0;
+            for (const tw of options.tagWeights) {
+                const overlaps = domainSet ? domainSet.has(tw.tag) : tw.tag === domains[0];
+                if (overlaps) {
+                    const w = tw.weight ?? 0;
+                    if (w > maxWeight)
+                        maxWeight = w;
+                }
+            }
+            if (maxWeight > 0)
+                score += maxWeight * scoringWeights.domainAffinity;
+        }
+    }
     // Superseded demotion (#191 Phase B): a memory whose decision was reversed by
     // a later one keeps its content and strength but must not outrank the
     // decision that replaced it. Applied as an explicit multiplier here rather
@@ -325,6 +452,7 @@ function formatResult(memory, score, effStr, connections, provenance) {
         access_count: memory.access_count ?? 0,
         memory_type: memory.memory_type ?? "episode",
         project: memory.project ?? null,
+        source_agent: memory.source_agent ?? null,
         created_at: memory.created_at ?? "",
         connections,
         similarity: provenance ? provenance.similarity : undefined,
@@ -350,12 +478,28 @@ function strengthen(db, memories, now) {
 // ---------------------------------------------------------------------------
 // Reciprocal Rank Fusion
 // ---------------------------------------------------------------------------
-function reciprocalRankFusion(rankedLists, k = RRF_K) {
+/**
+ * Reciprocal Rank Fusion (#205 per-list weights).
+ *
+ * Each list contributes `weight / (k + rank + 1)` per item. The pre-#205 form
+ * (symmetric 1.0 weight on every list) is recovered by omitting `weight`:
+ * `{ ids }` defaults to weight 1.0 — so callers that don't care about per-list
+ * rebalancing (tests, alternative uses) keep working unchanged.
+ *
+ * Per-list weights are the #205 lever for "nudging toward vector": FTS was
+ * winning cross-scope collisions on raw token overlap (marine "battery" beat
+ * hardware "battery" because the marine row had a tighter token match), so the
+ * shipped default drops FTS to 0.5 while vector stays at 1.0 (0.7 was too
+ * timid — Q4 marine contamination persisted; see SCORING_DEFAULTS). The composite
+ * score (which carries the #203 affinity boost) then breaks the tie in scope.
+ */
+function reciprocalRankFusion(rankedLists, k = DEFAULT_RRF_K) {
     const scores = new Map();
-    for (const ranked of rankedLists) {
-        for (let rank = 0; rank < ranked.length; rank++) {
-            const mid = ranked[rank];
-            scores.set(mid, (scores.get(mid) ?? 0) + 1.0 / (k + rank + 1));
+    for (const list of rankedLists) {
+        const w = list.weight ?? 1.0;
+        for (let rank = 0; rank < list.ids.length; rank++) {
+            const mid = list.ids[rank];
+            scores.set(mid, (scores.get(mid) ?? 0) + w / (k + rank + 1));
         }
     }
     return scores;
@@ -363,26 +507,42 @@ function reciprocalRankFusion(rankedLists, k = RRF_K) {
 /**
  * Main retrieval: BM25 + vector search with RRF fusion, graph traversal,
  * and composite scoring. Strengthens accessed memories.
+ *
+ * #203 retrieval scoping: `project` and `missionDomains` are SOFT affinity
+ * terms in computeScore (zero-boost neutral, never a penalty), NOT filters.
+ * `privacy` remains a hard filter (security boundary). `sourceAgent` remains a
+ * hard filter (kept for completeness; no production caller currently passes
+ * it). When neither project nor missionDomains is sent, scoring is byte-
+ * identical to pre-#203 — the kill-switch / no-op guarantee.
  */
 async function retrieve(db, embedFn, query, options) {
     const limit = options?.limit ?? recallDefaults.searchLimit;
     const project = options?.project;
     const privacy = options?.privacy;
     const sourceAgent = options?.sourceAgent;
+    const missionDomains = options?.missionDomains;
     const now = new Date();
-    // 1. Embed
-    const queryEmbedding = await embedFn(query);
+    // #203 affinity scope — passed to computeScore for every candidate. Built
+    // once; absent fields yield no boost (zero-boost neutral).
+    const scope = project || (missionDomains && missionDomains.length > 0)
+        ? { project: project ?? undefined, missionDomains }
+        : undefined;
+    // 1. Embed — or reuse the caller-provided vector (session-intent blend).
+    const queryEmbedding = options?.queryEmbedding ?? (await embedFn(query));
     // 2. Dual retrieval — vector + BM25.
     // #192: sqlite-vec can't push filters into the KNN, so filtered queries must
     // over-fetch — the old flat limit*3 intersected a global top-15 with (for the
     // median project) ~1% of the corpus, starving every filtered query.
-    const filtered = Boolean(project || privacy || sourceAgent);
+    // #203: project is NO LONGER a filter (soft affinity now), so it does not
+    // trigger over-fetch; privacy/sourceAgent still do (they remain hard filters).
+    const filtered = Boolean(privacy || sourceAgent);
     const fetchLimit = filtered ? Math.min(limit * 20, 200) : limit * 3;
     let vecCandidates = storage.vectorSearch(db, queryEmbedding, fetchLimit, []);
     let ftsCandidates = [];
     try {
-        // privacy/sourceAgent/project are all pushed into the FTS SQL.
-        ftsCandidates = storage.searchFts(db, query, fetchLimit, privacy, sourceAgent, project ?? undefined);
+        // privacy/sourceAgent are pushed into the FTS SQL (hard filters). project
+        // is NOT (it is a soft affinity boost in computeScore as of #203).
+        ftsCandidates = storage.searchFts(db, query, fetchLimit, privacy, sourceAgent);
     }
     catch {
         // FTS5 search can fail on special characters; fall back to vector-only
@@ -390,20 +550,25 @@ async function retrieve(db, embedFn, query, options) {
     if (vecCandidates.length === 0 && ftsCandidates.length === 0) {
         return [];
     }
-    // Post-filter vector candidates (sqlite-vec can't filter)
-    if (project) {
-        vecCandidates = vecCandidates.filter((c) => c.project === project);
-    }
+    // Post-filter vector candidates (sqlite-vec can't filter). privacy stays a
+    // hard filter (security boundary); project was removed here (#203 — it is now
+    // scored, not filtered). sourceAgent stays (see options doc).
     if (privacy) {
         vecCandidates = vecCandidates.filter((c) => privacy.includes(c.privacy));
     }
     if (sourceAgent) {
         vecCandidates = vecCandidates.filter((c) => c.source_agent === sourceAgent);
     }
-    // 3. RRF fusion
+    // 3. RRF fusion (#205: per-list weights + config-driven k). The vector list
+    // carries the composite-side affinity in the next step, so we let it dominate
+    // RRF too — the FTS list is down-weighted to break token-collision ties that
+    // the affinity alone cannot reach (marine "battery" vs hardware "battery").
     const vecRanked = vecCandidates.map((c) => c.id);
     const ftsRanked = ftsCandidates.map((c) => c.id);
-    const rrfScores = reciprocalRankFusion([vecRanked, ftsRanked]);
+    const rrfScores = reciprocalRankFusion([
+        { ids: vecRanked, weight: scoringWeights.rrfVectorWeight },
+        { ids: ftsRanked, weight: scoringWeights.rrfFtsWeight },
+    ], scoringWeights.rrfK);
     // Build unified candidate map (with retrieval-channel provenance, #192)
     const candidateMap = new Map();
     for (const c of vecCandidates) {
@@ -427,8 +592,8 @@ async function retrieve(db, embedFn, query, options) {
         const mem = storage.getMemory(db, gid);
         if (!mem)
             continue;
-        if (project && mem.project !== project)
-            continue;
+        // #203: project check removed — project is a soft affinity in computeScore,
+        // not a filter. privacy (security) and sourceAgent stay as hard filters.
         if (privacy && !privacy.includes(mem.privacy))
             continue;
         if (sourceAgent && mem.source_agent !== sourceAgent)
@@ -444,10 +609,19 @@ async function retrieve(db, embedFn, query, options) {
     // One query for the whole candidate set (#191 Phase B): superseded memories
     // are demoted in computeScore rather than strength-penalized.
     const supersededIds = findSupersededIds(db, [...candidateMap.keys()]);
+    // #203: ONE batched load of every candidate's graded domain tags — fed to
+    // computeScore for domain affinity. Only needed when the scope carries
+    // missionDomains; absent otherwise (skips the query entirely on /search and
+    // other unscoped callers — byte-identical to pre-#203).
+    const tagWeightsByMemory = scope?.missionDomains && scope.missionDomains.length > 0
+        ? storage.getMemoryTagsWeightedBatched(db, [...candidateMap.keys()])
+        : undefined;
     for (const [mid, { mem, distance, source }] of candidateMap) {
         const connCount = connectionCounts.get(mid) ?? 0;
         const composite = computeScore(mem, distance, connCount, maxConnections, now, {
             superseded: supersededIds.has(mid),
+            scope,
+            tagWeights: tagWeightsByMemory?.get(mid),
         });
         const effStr = effectiveStrength(mem.base_strength ?? 0.5, mem.last_accessed, now, {
             accessCount: mem.access_count ?? 0,
@@ -455,7 +629,11 @@ async function retrieve(db, embedFn, query, options) {
         });
         const rrf = rrfScores.get(mid) ?? 0;
         const normalizedRrf = maxRrf > 0 ? rrf / maxRrf : 0;
-        const finalScore = composite * 0.8 + normalizedRrf * 0.2;
+        // #205: composite/RRF blend is now config-driven (rrfCompositeWeight, 0.8
+        // default = pre-#205 behavior). The RRF share is the complement so the two
+        // always sum to 1.0 — the knob tunes the BALANCE, not the total.
+        const compositeWeight = scoringWeights.rrfCompositeWeight;
+        const finalScore = composite * compositeWeight + normalizedRrf * (1 - compositeWeight);
         // Measured cosine only for vector-matched candidates; FTS/graph hits carry
         // the neutral placeholder distance, which is not a real similarity.
         const similarity = source === "vector" || source === "both"

package/dist/schema-prototypes.d.ts

@@ -38,6 +38,21 @@ export declare function blobToVec(buf: Buffer): Float32Array;
  * is returned as an all-zero copy rather than dividing by zero.
  */
 export declare function l2Normalize(vec: Float32Array): Float32Array;
+/**
+ * Weighted sum of two vectors into a NEW Float32Array (inputs untouched). The
+ * result is NOT renormalized — callers normalize explicitly via `l2Normalize`
+ * when they need a unit vector (both call sites below do, because embeddings
+ * are L2-normalized and the blend must stay on the unit sphere to keep cosine
+ * meaningful). Throws on a dimension mismatch rather than silently truncating:
+ * the embedding dim is fixed at 384 in practice, so a mismatch signals a
+ * mid-process model swap or a bug, which must surface (CLAUDE.md: fail
+ * explicitly), not get quietly papered over.
+ *
+ * Used by the session-intent centroid EMA and the recall query blend (#192
+ * session-intent keying): `weightedAdd(a, 1-α, b, α)` is the EMA step,
+ * `weightedAdd(prompt, 1-w, centroid, w)` is the blended search vector.
+ */
+export declare function weightedAdd(a: Float32Array, wA: number, b: Float32Array, wB: number): Float32Array;
 /**
  * Association weight of a memory for a tag = cosine(memory embedding, domain
  * prototype). Both inputs are L2-normalized (embedder.ts normalizes memory

package/dist/schema-prototypes.js

@@ -28,6 +28,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PROTOTYPE_MIN_MEMBERS = void 0;
 exports.blobToVec = blobToVec;
 exports.l2Normalize = l2Normalize;
+exports.weightedAdd = weightedAdd;
 exports.tagWeight = tagWeight;
 exports.compartmentSet = compartmentSet;
 exports.derivePrimary = derivePrimary;
@@ -70,6 +71,29 @@ function l2Normalize(vec) {
         out[i] = vec[i] / norm;
     return out;
 }
+/**
+ * Weighted sum of two vectors into a NEW Float32Array (inputs untouched). The
+ * result is NOT renormalized — callers normalize explicitly via `l2Normalize`
+ * when they need a unit vector (both call sites below do, because embeddings
+ * are L2-normalized and the blend must stay on the unit sphere to keep cosine
+ * meaningful). Throws on a dimension mismatch rather than silently truncating:
+ * the embedding dim is fixed at 384 in practice, so a mismatch signals a
+ * mid-process model swap or a bug, which must surface (CLAUDE.md: fail
+ * explicitly), not get quietly papered over.
+ *
+ * Used by the session-intent centroid EMA and the recall query blend (#192
+ * session-intent keying): `weightedAdd(a, 1-α, b, α)` is the EMA step,
+ * `weightedAdd(prompt, 1-w, centroid, w)` is the blended search vector.
+ */
+function weightedAdd(a, wA, b, wB) {
+    if (a.length !== b.length) {
+        throw new Error(`weightedAdd: dimension mismatch (${a.length} vs ${b.length}) — expected equal-length L2-normalized embeddings`);
+    }
+    const out = new Float32Array(a.length);
+    for (let i = 0; i < a.length; i++)
+        out[i] = a[i] * wA + b[i] * wB;
+    return out;
+}
 /**
  * Association weight of a memory for a tag = cosine(memory embedding, domain
  * prototype). Both inputs are L2-normalized (embedder.ts normalizes memory

package/dist/storage.d.ts

@@ -89,6 +89,17 @@ export declare function getMemoryTagsWeighted(db: Database.Database, memoryId: s
     tag: string;
     weight: number | null;
 }>;
+/**
+ * Batched weighted-tag load for a candidate set (#203 domain affinity). ONE
+ * query for the whole set — never call getMemoryTagsWeighted per-candidate in
+ * a ranking loop. Returns a Map keyed by memory_id; memories with no tags are
+ * simply absent from the map (caller treats missing as "no domain boost").
+ * Ordering within each memory mirrors getMemoryTagsWeighted (weight DESC).
+ */
+export declare function getMemoryTagsWeightedBatched(db: Database.Database, memoryIds: string[]): Map<string, Array<{
+    tag: string;
+    weight: number | null;
+}>>;
 /**
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
@@ -106,10 +117,52 @@ export declare function vectorSearch(db: Database.Database, queryEmbedding: Floa
     distance: number;
 }>;
 /**
- * Full-text search using FTS5 BM25 ranking.
- * Returns memories with a rank field (lower is better).
+ * BM25F field weights (config-driven via {@link configureBm25Fts}, called from
+ * retrieval.configureScoring at boot). The order mirrors the FTS5 column
+ * declaration in db.ts (content, project, domain) — `bm25(memories_fts, …)`
+ * takes weights POSITIONALLY, so a new FTS column MUST be added here in the
+ * same position or the weighting silently shifts. Defaults favor scope fields
+ * (project/domain) over body so cross-scope noise that wins on raw token
+ * frequency (the marine "battery" memory on a hardware query) is demoted
+ * without excluding it — the same "graded, never binary" discipline as
+ * computeScore's affinity terms.
+ */
+export interface Bm25Weights {
+    body: number;
+    project: number;
+    domain: number;
+}
+/**
+ * Configure BM25F weights from config. Called by retrieval.configureScoring
+ * (which itself is called at server + nightly boot) so storage and retrieval
+ * rank identically. Invalid/out-of-range values keep the shipped default per
+ * key. Range [0, ∞) — a 0 weight effectively drops that field from the score;
+ * negative values are rejected (BM25F sign semantics break otherwise). Returns
+ * the resolved set for logging/tests.
  */
-export declare function searchFts(db: Database.Database, query: string, limit?: number, privacy?: string[], sourceAgent?: string, project?: string): Array<Memory & {
+export declare function configureBm25Fts(config?: Record<string, unknown> | null): Bm25Weights;
+/** Current resolved weights (tests + status output). */
+export declare function getBm25Weights(): Bm25Weights;
+/**
+ * Full-text search using FTS5 fielded BM25 (BM25F) ranking.
+ * Returns memories with a rank field (lower is better — see sign note below).
+ *
+ * `project` is NOT a filter here (#203): the hard project WHERE from #192 was
+ * removed — project is now a soft affinity boost in retrieval.computeScore AND
+ * a weighted field in BM25F (#205). `privacy` stays a hard filter (security
+ * boundary, not a relevance signal). `sourceAgent` stays a hard filter (kept
+ * for completeness; no production caller of retrieve() currently passes it).
+ *
+ * #205 sign handling: FTS5's `bm25(table, w0, w1, …)` returns a NEGATIVE score
+ * where MORE-negative = better match (it is 1 − the normalized BM25 score,
+ * which is itself positive — the negation is the FTS5 convention so that
+ * `ORDER BY bm25(…)` ASC gives best-first, matching the legacy `ORDER BY
+ * fts.rank` direction). Higher field weight ⇒ that column contributes MORE to
+ * the per-row score ⇒ matches in that field float up. We bind weights
+ * positionally as parameters (NOT string-interpolated) so query-planner
+ * caching is unaffected and the config path is the only editor.
+ */
+export declare function searchFts(db: Database.Database, query: string, limit?: number, privacy?: string[], sourceAgent?: string): Array<Memory & {
     rank: number;
 }>;
 /**

package/dist/storage.js

@@ -15,8 +15,11 @@ exports.deleteMemory = deleteMemory;
 exports.setMemoryTags = setMemoryTags;
 exports.getMemoryTags = getMemoryTags;
 exports.getMemoryTagsWeighted = getMemoryTagsWeighted;
+exports.getMemoryTagsWeightedBatched = getMemoryTagsWeightedBatched;
 exports.getStoredEmbedding = getStoredEmbedding;
 exports.vectorSearch = vectorSearch;
+exports.configureBm25Fts = configureBm25Fts;
+exports.getBm25Weights = getBm25Weights;
 exports.searchFts = searchFts;
 exports.addLink = addLink;
 exports.getLinks = getLinks;
@@ -244,6 +247,33 @@ function getMemoryTagsWeighted(db, memoryId) {
         .all(memoryId);
     return rows;
 }
+/**
+ * Batched weighted-tag load for a candidate set (#203 domain affinity). ONE
+ * query for the whole set — never call getMemoryTagsWeighted per-candidate in
+ * a ranking loop. Returns a Map keyed by memory_id; memories with no tags are
+ * simply absent from the map (caller treats missing as "no domain boost").
+ * Ordering within each memory mirrors getMemoryTagsWeighted (weight DESC).
+ */
+function getMemoryTagsWeightedBatched(db, memoryIds) {
+    const out = new Map();
+    if (memoryIds.length === 0)
+        return out;
+    const placeholders = memoryIds.map(() => "?").join(", ");
+    const rows = db
+        .prepare(`SELECT memory_id, tag, weight FROM memory_tags
+       WHERE memory_id IN (${placeholders})
+       ORDER BY memory_id, (weight IS NULL) ASC, weight DESC, rowid ASC`)
+        .all(...memoryIds);
+    for (const r of rows) {
+        let arr = out.get(r.memory_id);
+        if (!arr) {
+            arr = [];
+            out.set(r.memory_id, arr);
+        }
+        arr.push({ tag: r.tag, weight: r.weight });
+    }
+    return out;
+}
 /**
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
@@ -286,14 +316,56 @@ function vectorSearch(db, queryEmbedding, limit = 10, excludeIds = []) {
     }
     return results;
 }
-// ---------------------------------------------------------------------------
-// FTS5 search
-// ---------------------------------------------------------------------------
+const BM25_DEFAULTS = {
+    body: 1.0,
+    project: 2.0,
+    domain: 2.0,
+};
+let bm25Weights = { ...BM25_DEFAULTS };
 /**
- * Full-text search using FTS5 BM25 ranking.
- * Returns memories with a rank field (lower is better).
+ * Configure BM25F weights from config. Called by retrieval.configureScoring
+ * (which itself is called at server + nightly boot) so storage and retrieval
+ * rank identically. Invalid/out-of-range values keep the shipped default per
+ * key. Range [0, ∞) — a 0 weight effectively drops that field from the score;
+ * negative values are rejected (BM25F sign semantics break otherwise). Returns
+ * the resolved set for logging/tests.
  */
-function searchFts(db, query, limit = 10, privacy, sourceAgent, project) {
+function configureBm25Fts(config) {
+    const num = (key, dflt) => {
+        const v = Number(config?.[key]);
+        return Number.isFinite(v) && v >= 0 ? v : dflt;
+    };
+    bm25Weights = {
+        body: num("bm25WeightBody", BM25_DEFAULTS.body),
+        project: num("bm25WeightProject", BM25_DEFAULTS.project),
+        domain: num("bm25WeightDomain", BM25_DEFAULTS.domain),
+    };
+    return { ...bm25Weights };
+}
+/** Current resolved weights (tests + status output). */
+function getBm25Weights() {
+    return { ...bm25Weights };
+}
+/**
+ * Full-text search using FTS5 fielded BM25 (BM25F) ranking.
+ * Returns memories with a rank field (lower is better — see sign note below).
+ *
+ * `project` is NOT a filter here (#203): the hard project WHERE from #192 was
+ * removed — project is now a soft affinity boost in retrieval.computeScore AND
+ * a weighted field in BM25F (#205). `privacy` stays a hard filter (security
+ * boundary, not a relevance signal). `sourceAgent` stays a hard filter (kept
+ * for completeness; no production caller of retrieve() currently passes it).
+ *
+ * #205 sign handling: FTS5's `bm25(table, w0, w1, …)` returns a NEGATIVE score
+ * where MORE-negative = better match (it is 1 − the normalized BM25 score,
+ * which is itself positive — the negation is the FTS5 convention so that
+ * `ORDER BY bm25(…)` ASC gives best-first, matching the legacy `ORDER BY
+ * fts.rank` direction). Higher field weight ⇒ that column contributes MORE to
+ * the per-row score ⇒ matches in that field float up. We bind weights
+ * positionally as parameters (NOT string-interpolated) so query-planner
+ * caching is unaffected and the config path is the only editor.
+ */
+function searchFts(db, query, limit = 10, privacy, sourceAgent) {
     const conditions = ["memories_fts MATCH ?"];
     const params = [query];
     if (privacy && privacy.length > 0) {
@@ -305,23 +377,27 @@ function searchFts(db, query, limit = 10, privacy, sourceAgent, project) {
         conditions.push("m.source_agent = ?");
         params.push(sourceAgent);
     }
-    // #192: project is pushed into SQL (like privacy/sourceAgent) instead of
-    // being post-filtered by the caller — post-filtering a global top-N against
-    // a small project starves the result set regardless of corpus content.
-    if (project) {
-        conditions.push("m.project = ?");
-        params.push(project);
-    }
     const where = conditions.join(" AND ");
-    params.push(limit);
+    // SQLite binds `?` parameters in LEXICAL SQL order (left-to-right) — the
+    // `bm25(memories_fts, ?, ?, ?)` in the SELECT clause comes BEFORE the WHERE
+    // and LIMIT `?`s, so the weights must be pushed FIRST. Get this order wrong
+    // and FTS5 ends up with a numeric weight as its MATCH expression (parsed as
+    // FTS5 query syntax → "syntax error near '.'" on the decimal point).
+    const boundParams = [
+        bm25Weights.body,
+        bm25Weights.project,
+        bm25Weights.domain,
+        ...params,
+        limit,
+    ];
     const rows = db
-        .prepare(`SELECT m.*, fts.rank
+        .prepare(`SELECT m.*, bm25(memories_fts, ?, ?, ?) AS rank
        FROM memories_fts fts
        JOIN memories m ON m.rowid = fts.rowid
        WHERE ${where}
-       ORDER BY fts.rank
+       ORDER BY rank
        LIMIT ?`)
-        .all(...params);
+        .all(...boundParams);
     return rows.map((r) => {
         const rank = r.rank;
         const mem = rowToMemory(r);