@gamaze/hicortex 0.15.3 → 0.16.0

package/dist/retrieval.d.ts

@@ -60,12 +60,28 @@ interface ScoringWeights {
     freshnessBoostDays: number;
     freshnessBoostWeight: number;
     supersededDemotion: number;
+    /** #203 soft affinity boost on exact project match. */
+    projectAffinity: number;
+    /** #203 soft affinity boost multiplier on max overlapping domain-tag weight. */
+    domainAffinity: number;
+    /** #205 RRF k parameter (1/(k+rank+1)). Larger ⇒ shallower rank curve. */
+    rrfK: number;
+    /** #205 composite-score share of the final blend (RRF gets the remainder). */
+    rrfCompositeWeight: number;
+    /** #205 per-list RRF weight for the FTS list (BM25-driven candidates). */
+    rrfFtsWeight: number;
+    /** #205 per-list RRF weight for the vector list (KNN-driven candidates). */
+    rrfVectorWeight: number;
 }
 /**
  * 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.
  */
 export declare function configureScoring(config?: Record<string, unknown> | null): ScoringWeights;
 /** Current resolved weights (tests + status output). */
@@ -127,9 +143,31 @@ export declare function effectiveStrength(baseStrength: number, lastAccessed: st
 /**
  * Return a composite relevance score in [0, 1] for a candidate memory.
  * Exported for exact-value tests of the similarity component (#145).
+ *
+ * #203 soft affinity (options.scope + options.tagWeights): two additive,
+ * graded, zero-boost-neutral terms — project affinity (exact project match)
+ * and domain affinity (max overlapping memory_tags.weight × scope). Both are
+ * 0 when the scope is absent (byte-identical to pre-#203) and NEVER negative
+ * (a foreign memory adds 0, never a penalty — penalties re-introduce
+ * soft-exclusion). See `AffinityScope`.
  */
+export interface AffinityScope {
+    /** Exact-match project from the client (CC/OC cwd-derived; /search project). */
+    project?: string | null;
+    /** Hermes mission domains declared in plugin config. Drawn from the same
+     *  vocabulary as memory_tags (config `domains`). */
+    missionDomains?: string[];
+}
 export declare function computeScore(memory: Memory, distance: number, connectionCount: number, maxConnections: number, now: Date, options?: {
     superseded?: boolean;
+    /** #203: when present, project/domain affinity boosts are applied. */
+    scope?: AffinityScope;
+    /** Candidate's graded domain tags (memory_tags rows). Loaded batched for
+     *  the whole candidate set in retrieve(); used for domain affinity. */
+    tagWeights?: Array<{
+        tag: string;
+        weight: number | null;
+    }>;
 }): number;
 export interface EmbedFn {
     (text: string): Promise<Float32Array>;
@@ -137,12 +175,25 @@ export interface EmbedFn {
 /**
  * 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.
  */
 export declare function retrieve(db: Database.Database, embedFn: EmbedFn, query: string, options?: {
     limit?: number;
+    /** #203: soft project affinity (exact match boost in computeScore).
+     *  Formerly a hard WHERE filter (#192); softening removes cross-scope
+     *  starvation without excluding anything. */
     project?: string | null;
     privacy?: string[];
     sourceAgent?: string;
+    /** #203: Hermes mission domains (declared in plugin config). Soft domain
+     *  affinity in computeScore via max overlapping memory_tags.weight. */
+    missionDomains?: string[];
     /** #192: skip access strengthening — for pushed recall (/recall-index),
      *  where appearing in results must not count as use. */
     noStrengthen?: boolean;

package/dist/retrieval.js

@@ -128,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),
@@ -149,7 +175,21 @@ 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). */
@@ -233,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
@@ -285,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
@@ -327,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
@@ -382,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,
@@ -407,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;
@@ -420,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();
+    // #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
@@ -447,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) {
@@ -484,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)
@@ -501,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,
@@ -512,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/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);

package/dist/types.d.ts

@@ -40,6 +40,10 @@ export interface MemorySearchResult {
     access_count: number;
     memory_type: string;
     project: string | null;
+    /** Origin agent (e.g. "hermes/atlas", "cc/mbp5") — surfaced in the recall
+     *  one-liner so agents can calibrate trust (#202 provenance). Optional on the
+     *  result type (matches how `domain` is threaded) to avoid breaking fixtures. */
+    source_agent?: string | null;
     created_at: string;
     connections: number;
     /** True cosine similarity to the query for vector-matched candidates; null

package/dist/uninstall.js

@@ -101,14 +101,28 @@ async function runUninstall() {
         }
         catch { /* no settings */ }
     }
-    // 3. Remove CC custom commands
+    // 3. Remove CC custom commands — only files we actually wrote. `learn.md` is
+    // a generic name a user may own; guard on the "hicortex" marker the installer
+    // always embedded, so uninstall never deletes an unrelated user command.
+    let removedCmds = 0;
     for (const cmd of ["learn.md", "hicortex-activate.md"]) {
         const cmdPath = (0, node_path_1.join)(CC_COMMANDS_DIR, cmd);
-        if ((0, node_fs_1.existsSync)(cmdPath)) {
-            (0, node_fs_1.unlinkSync)(cmdPath);
+        if (!(0, node_fs_1.existsSync)(cmdPath))
+            continue;
+        try {
+            if (!(0, node_fs_1.readFileSync)(cmdPath, "utf-8").toLowerCase().includes("hicortex")) {
+                console.log(`  ⚠ Skipping ${cmd} — not a Hicortex file, left untouched`);
+                continue;
+            }
+        }
+        catch {
+            continue;
         }
+        (0, node_fs_1.unlinkSync)(cmdPath);
+        removedCmds++;
     }
-    console.log("  ✓ Removed /learn and /hicortex-activate commands");
+    if (removedCmds > 0)
+        console.log(`  ✓ Removed ${removedCmds} legacy CC command${removedCmds > 1 ? "s" : ""} (/learn, /hicortex-activate)`);
     // 4. Remove SessionStart hook (JSON merge — filter out entries containing "lessons-context")
     try {
         const raw = (0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8");