@seanhogg/builderforce-memory 2026.6.27 → 2026.6.28

package/dist/retrieval/fusion.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Rank fusion + diversity reranking.
+ *
+ *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
+ *     rankings into one list without needing the two score scales to be
+ *     commensurable — it fuses on RANK, not raw score. This is the standard,
+ *     parameter-light way to combine hybrid retrieval signals.
+ *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
+ *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ *
+ * Pure and zero-dependency.
+ */
+export interface RankedList {
+    /** Ordered ids, most relevant first. */
+    ids: string[];
+    /** Optional weight for this list in the fusion (default 1). */
+    weight?: number;
+}
+export interface FusedHit {
+    id: string;
+    score: number;
+}
+/**
+ * Reciprocal Rank Fusion over any number of ranked lists.
+ * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
+ * contribution of low-ranked items; the canonical TREC value.
+ */
+export declare function reciprocalRankFusion(lists: RankedList[], k?: number): FusedHit[];
+export interface MmrCandidate {
+    id: string;
+    vector: Float32Array;
+}
+/**
+ * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
+ * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
+ * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
+ * should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export declare function maximalMarginalRelevance(queryVec: Float32Array, candidates: MmrCandidate[], topK: number, lambda?: number): string[];
+//# sourceMappingURL=fusion.d.ts.map

package/dist/retrieval/fusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.d.ts","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,UAAU;IACvB,wCAAwC;IACxC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,SAAK,GAAG,QAAQ,EAAE,CAW5E;AAED,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,YAAY,EAAE,EAC1B,IAAI,EAAE,MAAM,EACZ,MAAM,SAAM,GACb,MAAM,EAAE,CAsBV"}

package/dist/retrieval/fusion.js

@@ -0,0 +1,64 @@
+/**
+ * Rank fusion + diversity reranking.
+ *
+ *   • Reciprocal Rank Fusion (RRF) merges the dense (vector) and sparse (BM25)
+ *     rankings into one list without needing the two score scales to be
+ *     commensurable — it fuses on RANK, not raw score. This is the standard,
+ *     parameter-light way to combine hybrid retrieval signals.
+ *   • Maximal Marginal Relevance (MMR) reranks the fused list to trade off
+ *     relevance against novelty, so the top-k isn't five near-duplicate chunks.
+ *
+ * Pure and zero-dependency.
+ */
+import { cosineSimilarity } from '../similarity/index.js';
+/**
+ * Reciprocal Rank Fusion over any number of ranked lists.
+ * score(d) = Σ_lists weight / (k + rank(d)).  `k` (default 60) damps the
+ * contribution of low-ranked items; the canonical TREC value.
+ */
+export function reciprocalRankFusion(lists, k = 60) {
+    const acc = new Map();
+    for (const list of lists) {
+        const weight = list.weight ?? 1;
+        list.ids.forEach((id, rank) => {
+            acc.set(id, (acc.get(id) ?? 0) + weight / (k + rank + 1));
+        });
+    }
+    return [...acc.entries()]
+        .map(([id, score]) => ({ id, score }))
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * Maximal Marginal Relevance rerank. Greedily selects up to `topK` candidates,
+ * each step maximising `λ·sim(query, d) − (1−λ)·max sim(d, already-selected)`.
+ * λ=1 is pure relevance; lower λ injects diversity. Candidates without vectors
+ * should be filtered out by the caller (they cannot be MMR-scored).
+ */
+export function maximalMarginalRelevance(queryVec, candidates, topK, lambda = 0.7) {
+    const remaining = [...candidates];
+    const selected = [];
+    const relevance = new Map();
+    for (const c of remaining)
+        relevance.set(c.id, cosineSimilarity(queryVec, c.vector));
+    while (selected.length < topK && remaining.length > 0) {
+        let bestIdx = 0;
+        let bestScore = -Infinity;
+        for (let i = 0; i < remaining.length; i++) {
+            const c = remaining[i];
+            let maxSimToSelected = 0;
+            for (const s of selected) {
+                const sim = cosineSimilarity(c.vector, s.vector);
+                if (sim > maxSimToSelected)
+                    maxSimToSelected = sim;
+            }
+            const mmr = lambda * relevance.get(c.id) - (1 - lambda) * maxSimToSelected;
+            if (mmr > bestScore) {
+                bestScore = mmr;
+                bestIdx = i;
+            }
+        }
+        selected.push(remaining.splice(bestIdx, 1)[0]);
+    }
+    return selected.map(s => s.id);
+}
+//# sourceMappingURL=fusion.js.map

package/dist/retrieval/fusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.js","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ *
+ * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
+ * dense+sparse search, reranking), implemented zero-dependency so they run in the
+ * browser, Node, and the SSM runtime alike.
+ */
+export { chunkText } from './chunk.js';
+export type { Chunk, ChunkOptions } from './chunk.js';
+export { bm25Search } from './bm25.js';
+export type { Bm25Doc, Bm25Hit, Bm25Options } from './bm25.js';
+export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+export type { RankedList, FusedHit, MmrCandidate } from './fusion.js';
+export { hybridRetrieve } from './HybridRetriever.js';
+export type { RetrievalCandidate, HybridQuery, HybridRetrieveOptions, HybridHit, } from './HybridRetriever.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/retrieval/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACR,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,SAAS,GACZ,MAAM,sBAAsB,CAAC"}

package/dist/retrieval/index.js

@@ -0,0 +1,12 @@
+/**
+ * Retrieval layer — chunking, BM25, rank fusion, and the HybridRetriever.
+ *
+ * The classic RAG pieces the memory stack previously lacked (chunking, hybrid
+ * dense+sparse search, reranking), implemented zero-dependency so they run in the
+ * browser, Node, and the SSM runtime alike.
+ */
+export { chunkText } from './chunk.js';
+export { bm25Search } from './bm25.js';
+export { reciprocalRankFusion, maximalMarginalRelevance } from './fusion.js';
+export { hybridRetrieve } from './HybridRetriever.js';
+//# sourceMappingURL=index.js.map

package/dist/retrieval/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/retrieval/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.6.27",
-  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, and persistent agent memory for BuilderForce.ai agents.",
+  "version": "2026.6.28",
+  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, hybrid RAG retrieval, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./retrieval": {
+      "types": "./dist/retrieval/index.d.ts",
+      "import": "./dist/retrieval/index.js"
     }
   },
   "type": "module",
@@ -49,7 +53,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.6.27"
+    "@seanhogg/builderforce-memory-engine": "^2026.6.28"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -62,7 +66,7 @@
     "jest": "^29.7.0",
     "ts-jest": "^29.2.0",
     "typescript": "^5.0.0",
-    "@seanhogg/builderforce-memory-engine": "2026.6.27"
+    "@seanhogg/builderforce-memory-engine": "2026.6.28"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/index.ts

@@ -68,6 +68,31 @@ export type {
     Region,
 } from '@seanhogg/builderforce-memory-engine';
 
+// ── Mixture-of-Experts (shared-expert hybrid — the Evermind generator's sparsity) ──
+// Re-exported from the engine so consumers reach it from @seanhogg/builderforce-memory.
+export {
+    SharedExpertMoE,
+    LoadBalanceAccumulator,
+    DEFAULT_MOE_CONFIG,
+    DEFAULT_MOE_SEED,
+    MoETrainer,
+    EvermindModelPackage,
+} from '@seanhogg/builderforce-memory-engine';
+export type {
+    MoEConfig,
+    MoEParam,
+    RouteResult,
+    MoESample,
+    MoETrainOptions,
+    MoEEpochResult,
+    EvermindModelManifest,
+    EvermindModelCard,
+    PackageMeta,
+    ValidationResult,
+} from '@seanhogg/builderforce-memory-engine';
+export { EvermindLM, EvermindLMTrainer } from '@seanhogg/builderforce-memory-engine';
+export type { EvermindLMConfig, LMGenerateOptions, TextCodec } from '@seanhogg/builderforce-memory-engine';
+
 // ── Runtime ───────────────────────────────────────────────────────────────────
 export { SSMRuntime }    from './runtime/SSMRuntime.js';
 export type { SSMRuntimeOptions, GenerateOptions } from './runtime/SSMRuntime.js';
@@ -101,6 +126,29 @@ export type {
 // ── Similarity primitives ──────────────────────────────────────────────────────
 export { cosineSimilarity, jaccardSimilarity, tokenize } from './similarity/index.js';
 
+// ── Retrieval (chunking, BM25, rank fusion, hybrid RAG) ────────────────────────
+export {
+    chunkText,
+    bm25Search,
+    reciprocalRankFusion,
+    maximalMarginalRelevance,
+    hybridRetrieve,
+} from './retrieval/index.js';
+export type {
+    Chunk,
+    ChunkOptions,
+    Bm25Doc,
+    Bm25Hit,
+    Bm25Options,
+    RankedList,
+    FusedHit,
+    MmrCandidate,
+    RetrievalCandidate,
+    HybridQuery,
+    HybridRetrieveOptions,
+    HybridHit,
+} from './retrieval/index.js';
+
 // ── Router ────────────────────────────────────────────────────────────────────
 export { InferenceRouter } from './router/InferenceRouter.js';
 export type {

package/src/memory/MemoryStore.ts

@@ -10,6 +10,7 @@
 
 import { SSMError } from '../errors/SSMError.js';
 import { tokenize, jaccardSimilarity, cosineSimilarity } from '../similarity/index.js';
+import { hybridRetrieve, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
 
 export type FactType = 'text' | 'json' | 'number' | 'boolean';
 
@@ -265,6 +266,41 @@ export class MemoryStore {
         return scored.slice(0, topK).map(s => s.entry);
     }
 
+    /**
+     * Hybrid recall: fuses dense (SSM-embedding cosine) and sparse (BM25 lexical)
+     * rankings via Reciprocal Rank Fusion, then applies an MMR diversity rerank.
+     *
+     * This is the production RAG retrieval path — it catches both semantic matches
+     * (embeddings) and exact-token matches (BM25 — identifiers, codes, rare names)
+     * that cosine-only `recallSimilar` misses, and avoids returning near-duplicate
+     * facts. Degrades to BM25-only when no embedding-capable runtime is available,
+     * so it is always strictly at least as good as the lexical fallback.
+     */
+    async recallHybrid(
+        query: string,
+        topK: number,
+        runtime?: SSMRuntimeRef,
+        opts?: HybridRetrieveOptions,
+    ): Promise<MemoryEntry[]> {
+        const all = await this.recallAll();
+        if (all.length === 0) return [];
+
+        // Embed candidates + query where a runtime is available; null vectors are
+        // fine — hybridRetrieve degrades that candidate to BM25-only.
+        const canEmbed = runtime != null && typeof runtime.embed === 'function';
+        const queryVec = canEmbed ? (await this._embedWithCache(runtime, query)) ?? undefined : undefined;
+
+        const candidates: RetrievalCandidate[] = [];
+        for (const entry of all) {
+            const vector = canEmbed ? (await this._embedWithCache(runtime, entry.content)) ?? undefined : undefined;
+            candidates.push({ id: entry.key, text: entry.content, vector });
+        }
+
+        const hits = hybridRetrieve({ text: query, vector: queryVec }, candidates, { topK, ...opts });
+        const byKey = new Map(all.map(e => [e.key, e]));
+        return hits.map(h => byKey.get(h.id)).filter((e): e is MemoryEntry => !!e);
+    }
+
     /**
      * Returns a cached embedding for `text`, computing it via `runtime.embed()`
      * on a cache miss. Returns `null` (never throws) when embedding is

package/src/retrieval/HybridRetriever.ts

@@ -0,0 +1,122 @@
+/**
+ * HybridRetriever — dense + sparse retrieval with rank fusion and diversity rerank.
+ *
+ * This is the piece that takes the memory layer from "cosine-only similarity" to a
+ * full hybrid RAG retriever:
+ *
+ *   1. Dense:  cosine over embeddings (SSM hidden-state vectors, or any embedder).
+ *   2. Sparse: BM25 lexical scoring (catches exact tokens dense search misses).
+ *   3. Fuse:   Reciprocal Rank Fusion combines the two rankings.
+ *   4. Rerank: optional MMR pass for relevance/novelty trade-off (diversity).
+ *
+ * It is storage-agnostic — give it candidates (id + text + optional vector) and a
+ * query (text + optional vector). It degrades gracefully: no query vector / no
+ * candidate vectors → BM25-only; no overlap → dense-only.
+ */
+
+import { cosineSimilarity } from '../similarity/index.js';
+import { bm25Search, type Bm25Options } from './bm25.js';
+import { reciprocalRankFusion, maximalMarginalRelevance, type MmrCandidate } from './fusion.js';
+
+export interface RetrievalCandidate {
+    id: string;
+    text: string;
+    /** Precomputed embedding. Omit to exclude this candidate from the dense pass. */
+    vector?: Float32Array;
+}
+
+export interface HybridQuery {
+    text: string;
+    /** Query embedding. Omit for BM25-only retrieval. */
+    vector?: Float32Array;
+}
+
+export interface HybridRetrieveOptions {
+    /** Number of results to return. Default 5. */
+    topK?: number;
+    /** RRF damping constant. Default 60. */
+    rrfK?: number;
+    /** Relative weight of the dense ranking in fusion. Default 1. */
+    denseWeight?: number;
+    /** Relative weight of the sparse (BM25) ranking in fusion. Default 1. */
+    sparseWeight?: number;
+    /** Apply MMR diversity rerank over the fused top results. Default true. */
+    rerank?: boolean;
+    /** MMR relevance/diversity trade-off (1 = pure relevance). Default 0.7. */
+    mmrLambda?: number;
+    /** BM25 tuning. */
+    bm25?: Bm25Options;
+}
+
+export interface HybridHit {
+    id: string;
+    text: string;
+    /** Fused RRF score (pre-rerank). */
+    score: number;
+}
+
+/**
+ * Runs the full hybrid pipeline over `candidates` and returns the top-K hits.
+ * Pure given its inputs (embeddings are supplied by the caller) so it is directly
+ * unit-testable without a model or vector DB.
+ */
+export function hybridRetrieve(
+    query: HybridQuery,
+    candidates: RetrievalCandidate[],
+    opts: HybridRetrieveOptions = {},
+): HybridHit[] {
+    const topK = opts.topK ?? 5;
+    if (candidates.length === 0) return [];
+
+    const byId = new Map(candidates.map(c => [c.id, c]));
+
+    // ── Dense ranking (cosine) ────────────────────────────────────────────────
+    let denseIds: string[] = [];
+    if (query.vector) {
+        denseIds = candidates
+            .filter(c => c.vector && c.vector.length > 0)
+            .map(c => ({ id: c.id, score: cosineSimilarity(query.vector!, c.vector!) }))
+            .sort((a, b) => b.score - a.score)
+            .map(h => h.id);
+    }
+
+    // ── Sparse ranking (BM25) ─────────────────────────────────────────────────
+    const sparseIds = bm25Search(query.text, candidates, opts.bm25).map(h => h.id);
+
+    // ── Fuse ──────────────────────────────────────────────────────────────────
+    const fused = reciprocalRankFusion(
+        [
+            { ids: denseIds, weight: opts.denseWeight ?? 1 },
+            { ids: sparseIds, weight: opts.sparseWeight ?? 1 },
+        ].filter(l => l.ids.length > 0),
+        opts.rrfK ?? 60,
+    );
+    if (fused.length === 0) return [];
+
+    // ── Rerank (MMR over fused top, using whatever vectors we have) ────────────
+    const rerank = opts.rerank ?? true;
+    let orderedIds: string[];
+    if (rerank && query.vector) {
+        // Consider a generous fused window so MMR has room to diversify.
+        const window = fused.slice(0, Math.max(topK * 4, topK));
+        const mmrCands: MmrCandidate[] = window
+            .map(f => byId.get(f.id))
+            .filter((c): c is RetrievalCandidate => !!c && !!c.vector && c.vector.length > 0)
+            .map(c => ({ id: c.id, vector: c.vector! }));
+        if (mmrCands.length > 0) {
+            const reranked = maximalMarginalRelevance(query.vector, mmrCands, topK, opts.mmrLambda ?? 0.7);
+            // MMR only ranks the vectored subset; append any remaining fused ids after.
+            const seen = new Set(reranked);
+            orderedIds = [...reranked, ...fused.map(f => f.id).filter(id => !seen.has(id))];
+        } else {
+            orderedIds = fused.map(f => f.id);
+        }
+    } else {
+        orderedIds = fused.map(f => f.id);
+    }
+
+    const fusedScore = new Map(fused.map(f => [f.id, f.score]));
+    return orderedIds
+        .slice(0, topK)
+        .map(id => ({ id, text: byId.get(id)!.text, score: fusedScore.get(id)! }));
+}

package/src/retrieval/bm25.ts

@@ -0,0 +1,83 @@
+/**
+ * BM25 (Okapi) lexical ranking.
+ *
+ * The keyword half of hybrid retrieval. Dense vector search matches meaning but
+ * misses exact tokens (identifiers, error codes, rare names); BM25 catches those.
+ * Fusing the two (see {@link ./fusion}) is what lifts the memory layer from
+ * "cosine only" to a hybrid retriever on par with Weaviate-style search.
+ *
+ * Pure and zero-dependency — reuses the shared `tokenize` from ../similarity.
+ */
+
+import { tokenize } from '../similarity/index.js';
+
+export interface Bm25Options {
+    /** Term-frequency saturation. Higher = TF matters more. Default 1.5. */
+    k1?: number;
+    /** Length normalisation, 0..1. Higher = penalise long docs more. Default 0.75. */
+    b?: number;
+}
+
+export interface Bm25Doc {
+    id: string;
+    text: string;
+}
+
+export interface Bm25Hit {
+    id: string;
+    score: number;
+}
+
+/**
+ * Scores every document against `query` with Okapi BM25, returning hits sorted by
+ * descending score (documents with no query-term overlap score 0 and are dropped).
+ * Builds the index inline — for a recall over a bounded candidate set (the memory
+ * store / a vector pre-filter) this is O(N·terms) and needs no persistence.
+ */
+export function bm25Search(query: string, docs: Bm25Doc[], opts: Bm25Options = {}): Bm25Hit[] {
+    const k1 = opts.k1 ?? 1.5;
+    const b = opts.b ?? 0.75;
+    const N = docs.length;
+    if (N === 0) return [];
+
+    const queryTerms = new Set(tokenize(query));
+    if (queryTerms.size === 0) return [];
+
+    // Per-doc term frequencies + document lengths.
+    const docTerms: { id: string; tf: Map<string, number>; len: number }[] = [];
+    const df = new Map<string, number>();
+    let totalLen = 0;
+
+    for (const doc of docs) {
+        const tokens = tokenize(doc.text);
+        const tf = new Map<string, number>();
+        for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
+        for (const t of tf.keys()) if (queryTerms.has(t)) df.set(t, (df.get(t) ?? 0) + 1);
+        docTerms.push({ id: doc.id, tf, len: tokens.length });
+        totalLen += tokens.length;
+    }
+    const avgdl = totalLen / N || 1;
+
+    // idf with the +1 smoothing variant (always non-negative).
+    const idf = new Map<string, number>();
+    for (const term of queryTerms) {
+        const n = df.get(term) ?? 0;
+        idf.set(term, Math.log(1 + (N - n + 0.5) / (n + 0.5)));
+    }
+
+    const hits: Bm25Hit[] = [];
+    for (const d of docTerms) {
+        let score = 0;
+        for (const term of queryTerms) {
+            const f = d.tf.get(term);
+            if (!f) continue;
+            const numer = f * (k1 + 1);
+            const denom = f + k1 * (1 - b + b * (d.len / avgdl));
+            score += idf.get(term)! * (numer / denom);
+        }
+        if (score > 0) hits.push({ id: d.id, score });
+    }
+
+    hits.sort((a, b) => b.score - a.score);
+    return hits;
+}

package/src/retrieval/chunk.ts

@@ -0,0 +1,101 @@
+/**
+ * Document chunking — recursive character text splitter with overlap.
+ *
+ * The classic RAG ingestion step the memory layer was missing: large documents
+ * are split into smaller, semantically-coherent chunks before embedding so that
+ * retrieval returns precise passages rather than whole files. Mirrors the
+ * behaviour of LangChain's RecursiveCharacterTextSplitter (split on the largest
+ * natural boundary that fits, fall back to finer ones) but is zero-dependency.
+ */
+
+export interface ChunkOptions {
+    /** Target maximum chunk size in characters. Default 1000. */
+    chunkSize?: number;
+    /** Characters of overlap carried from the end of one chunk into the next,
+     *  preserving context across boundaries. Default 200. Clamped below chunkSize. */
+    chunkOverlap?: number;
+    /** Separators tried in order, largest natural boundary first. */
+    separators?: string[];
+}
+
+export interface Chunk {
+    /** The chunk text. */
+    text: string;
+    /** 0-based ordinal of this chunk within its source document. */
+    index: number;
+    /** Character offset of this chunk's start within the original document. */
+    start: number;
+}
+
+const DEFAULT_SEPARATORS = ['\n\n', '\n', '. ', ' ', ''];
+
+/**
+ * Splits `text` into overlapping chunks no larger than `chunkSize` characters,
+ * preferring the largest natural separator that keeps a piece under the limit.
+ * Returns `[]` for empty/whitespace input. Deterministic and pure.
+ */
+export function chunkText(text: string, opts: ChunkOptions = {}): Chunk[] {
+    const chunkSize = Math.max(1, opts.chunkSize ?? 1000);
+    const overlap = Math.min(Math.max(0, opts.chunkOverlap ?? 200), chunkSize - 1);
+    const separators = opts.separators ?? DEFAULT_SEPARATORS;
+
+    const trimmed = text.trim();
+    if (trimmed.length === 0) return [];
+    if (trimmed.length <= chunkSize) return [{ text: trimmed, index: 0, start: 0 }];
+
+    const pieces = splitRecursive(trimmed, chunkSize, separators);
+
+    // Merge adjacent pieces up to chunkSize, then stitch overlap between chunks.
+    const chunks: Chunk[] = [];
+    let buf = '';
+    const flush = () => {
+        const t = buf.trim();
+        if (t.length > 0) {
+            const start = chunks.length === 0 ? 0 : Math.max(0, trimmed.indexOf(t));
+            chunks.push({ text: t, index: chunks.length, start });
+        }
+        buf = '';
+    };
+
+    for (const piece of pieces) {
+        if (buf.length + piece.length <= chunkSize) {
+            buf += piece;
+        } else {
+            flush();
+            // Carry overlap from the previous chunk's tail.
+            const prev = chunks[chunks.length - 1]?.text ?? '';
+            buf = (overlap > 0 ? prev.slice(-overlap) : '') + piece;
+            // A single piece longer than chunkSize is hard-split.
+            while (buf.length > chunkSize) {
+                const head = buf.slice(0, chunkSize);
+                chunks.push({ text: head.trim(), index: chunks.length, start: 0 });
+                buf = (overlap > 0 ? head.slice(-overlap) : '') + buf.slice(chunkSize);
+            }
+        }
+    }
+    flush();
+
+    return chunks.map((c, i) => ({ ...c, index: i }));
+}
+
+/** Recursively splits text on the first separator that yields sub-chunkSize pieces. */
+function splitRecursive(text: string, chunkSize: number, separators: string[]): string[] {
+    /* istanbul ignore next -- defensive base case; callers only recurse on parts > chunkSize */
+    if (text.length <= chunkSize) return [text];
+    const [sep, ...rest] = separators;
+    if (sep === undefined) return [text];
+    if (sep === '') {
+        // Last resort: hard character split.
+        const out: string[] = [];
+        for (let i = 0; i < text.length; i += chunkSize) out.push(text.slice(i, i + chunkSize));
+        return out;
+    }
+    const parts = text.split(sep);
+    const out: string[] = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = i < parts.length - 1 ? parts[i]! + sep : parts[i]!;
+        if (part.length > chunkSize) out.push(...splitRecursive(part, chunkSize, rest));
+        else out.push(part);
+    }
+    return out;
+}