@getplumb/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plumb Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @getplumb/core
+
+> Cross-session AI memory — storage abstraction, types, and local SQLite driver
+
+The core library for [Plumb](https://getplumb.dev) — a local-first, MCP-native memory layer for AI agents.
+
+## What it does
+
+- **Two-layer memory:** raw conversation log (Layer 1) + extracted fact graph (Layer 2)
+- **Hybrid search:** BM25 + semantic vectors + RRF fusion + cross-encoder reranking
+- **Local storage:** SQLite + sqlite-vec, zero external dependencies
+- **Pluggable LLM:** bring your own OpenAI or Anthropic client for fact extraction
+
+## Install
+
+```bash
+npm install @getplumb/core
+```
+
+## Quick start
+
+```ts
+import { LocalStore } from '@getplumb/core';
+
+const store = new LocalStore({ dbPath: '~/.plumb/memory.db' });
+await store.init();
+
+// Ingest a conversation turn
+await store.ingest({
+  sessionId: 'my-session',
+  userId: 'user-123',
+  userMessage: 'I prefer TypeScript over Python',
+  assistantMessage: 'Noted! TypeScript it is.'
+});
+
+// Retrieve relevant memory
+const results = await store.searchRawLog('TypeScript preferences', 5);
+```
+
+## Links
+
+- [Docs](https://docs.getplumb.dev)
+- [GitHub](https://github.com/getplumb/plumb)
+- [getplumb.dev](https://getplumb.dev)
+
+## License
+
+MIT

package/dist/bm25.d.ts

@@ -0,0 +1,23 @@
+/**
+ * BM25 Okapi — pure TypeScript in-memory implementation.
+ *
+ * Parameters: k1 = 1.5, b = 0.75 (standard values from the original paper).
+ * IDF variant: Robertson-Walker smooth IDF to avoid negative values for
+ * very common terms: IDF(q) = log((N - df + 0.5) / (df + 0.5) + 1)
+ *
+ * Usage:
+ *   const index = new Bm25(corpus);     // corpus: string[]
+ *   const scores = index.scores(query); // scores: number[], same order as corpus
+ */
+/** Tokenize text to lowercase alphanumeric tokens. */
+export declare function tokenize(text: string): string[];
+export declare class Bm25 {
+    #private;
+    constructor(corpus: readonly string[]);
+    /**
+     * Compute BM25 scores for all corpus documents against the query.
+     * Returns an array of scores in the same order as the constructor corpus.
+     */
+    scores(query: string): number[];
+}
+//# sourceMappingURL=bm25.d.ts.map

package/dist/bm25.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25.d.ts","sourceRoot":"","sources":["../src/bm25.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE/C;AAED,qBAAa,IAAI;;gBAOH,MAAM,EAAE,SAAS,MAAM,EAAE;IA4BrC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE;CAqBhC"}

package/dist/bm25.js

@@ -0,0 +1,74 @@
+/**
+ * BM25 Okapi — pure TypeScript in-memory implementation.
+ *
+ * Parameters: k1 = 1.5, b = 0.75 (standard values from the original paper).
+ * IDF variant: Robertson-Walker smooth IDF to avoid negative values for
+ * very common terms: IDF(q) = log((N - df + 0.5) / (df + 0.5) + 1)
+ *
+ * Usage:
+ *   const index = new Bm25(corpus);     // corpus: string[]
+ *   const scores = index.scores(query); // scores: number[], same order as corpus
+ */
+const K1 = 1.5;
+const B = 0.75;
+/** Tokenize text to lowercase alphanumeric tokens. */
+export function tokenize(text) {
+    return text.toLowerCase().match(/\b[a-z0-9]+\b/g) ?? [];
+}
+export class Bm25 {
+    #n;
+    #avgdl;
+    #idf;
+    #tf;
+    #docLengths;
+    constructor(corpus) {
+        this.#n = corpus.length;
+        const tokenized = corpus.map(tokenize);
+        this.#docLengths = tokenized.map((t) => t.length);
+        const totalLen = this.#docLengths.reduce((a, b) => a + b, 0);
+        this.#avgdl = this.#n > 0 ? totalLen / this.#n : 1;
+        // Build term-frequency maps and document-frequency counts.
+        const df = new Map();
+        this.#tf = tokenized.map((tokens) => {
+            const freq = new Map();
+            for (const tok of tokens) {
+                freq.set(tok, (freq.get(tok) ?? 0) + 1);
+            }
+            for (const tok of freq.keys()) {
+                df.set(tok, (df.get(tok) ?? 0) + 1);
+            }
+            return freq;
+        });
+        // Precompute IDF for each unique term.
+        this.#idf = new Map();
+        const N = this.#n;
+        for (const [term, dfTerm] of df) {
+            this.#idf.set(term, Math.log((N - dfTerm + 0.5) / (dfTerm + 0.5) + 1));
+        }
+    }
+    /**
+     * Compute BM25 scores for all corpus documents against the query.
+     * Returns an array of scores in the same order as the constructor corpus.
+     */
+    scores(query) {
+        const queryTerms = tokenize(query);
+        const result = new Array(this.#n).fill(0);
+        if (queryTerms.length === 0 || this.#n === 0)
+            return result;
+        for (const term of queryTerms) {
+            const idf = this.#idf.get(term);
+            if (idf === undefined)
+                continue;
+            for (let i = 0; i < this.#n; i++) {
+                const tf = this.#tf[i]?.get(term) ?? 0;
+                if (tf === 0)
+                    continue;
+                const dl = this.#docLengths[i] ?? 0;
+                const norm = tf * (K1 + 1) / (tf + K1 * (1 - B + B * dl / this.#avgdl));
+                result[i] = (result[i] ?? 0) + idf * norm;
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=bm25.js.map

package/dist/bm25.js.map

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

package/dist/chunker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Chunker — splits a MessageExchange into overlapping text chunks for indexing.
+ *
+ * Design (T-004):
+ *   - Each exchange is formatted as "User: {msg}\nAgent: {response}"
+ *   - Short exchanges (≤ CHUNK_WORDS words) produce one chunk
+ *   - Long exchanges are split with OVERLAP_WORDS word overlap to preserve
+ *     context at chunk boundaries
+ *
+ * Word-based splitting is used (not token-based) to avoid a tokenizer
+ * dependency at ingest time. At 384-dim bge-small, 300 words ≈ 400 tokens
+ * which is within the model's 512-token limit.
+ */
+import type { MessageExchange } from './types.js';
+export declare const CHUNK_WORDS = 300;
+export declare const OVERLAP_WORDS = 50;
+export interface Chunk {
+    /** Full formatted text of this chunk. */
+    readonly text: string;
+    /** 0-based index within this exchange's chunk sequence. */
+    readonly chunkIndex: number;
+    /** Total chunks produced from this exchange. */
+    readonly totalChunks: number;
+}
+/**
+ * Format a MessageExchange into its canonical chunk text.
+ * Used both by the chunker and by ingest() for the stored chunk_text column.
+ */
+export declare function formatExchange(exchange: MessageExchange): string;
+/**
+ * Split a MessageExchange into one or more overlapping text chunks.
+ * Returns at least one chunk (even for empty exchanges).
+ */
+export declare function chunkExchange(exchange: MessageExchange): Chunk[];
+//# sourceMappingURL=chunker.d.ts.map

package/dist/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../src/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,eAAO,MAAM,WAAW,MAAM,CAAC;AAC/B,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,MAAM,WAAW,KAAK;IACpB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,KAAK,EAAE,CAmBhE"}

package/dist/chunker.js

@@ -0,0 +1,45 @@
+/**
+ * Chunker — splits a MessageExchange into overlapping text chunks for indexing.
+ *
+ * Design (T-004):
+ *   - Each exchange is formatted as "User: {msg}\nAgent: {response}"
+ *   - Short exchanges (≤ CHUNK_WORDS words) produce one chunk
+ *   - Long exchanges are split with OVERLAP_WORDS word overlap to preserve
+ *     context at chunk boundaries
+ *
+ * Word-based splitting is used (not token-based) to avoid a tokenizer
+ * dependency at ingest time. At 384-dim bge-small, 300 words ≈ 400 tokens
+ * which is within the model's 512-token limit.
+ */
+export const CHUNK_WORDS = 300;
+export const OVERLAP_WORDS = 50;
+/**
+ * Format a MessageExchange into its canonical chunk text.
+ * Used both by the chunker and by ingest() for the stored chunk_text column.
+ */
+export function formatExchange(exchange) {
+    return `User: ${exchange.userMessage}\nAgent: ${exchange.agentResponse}`;
+}
+/**
+ * Split a MessageExchange into one or more overlapping text chunks.
+ * Returns at least one chunk (even for empty exchanges).
+ */
+export function chunkExchange(exchange) {
+    const text = formatExchange(exchange);
+    const words = text.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length <= CHUNK_WORDS) {
+        return [{ text, chunkIndex: 0, totalChunks: 1 }];
+    }
+    const chunks = [];
+    let start = 0;
+    while (start < words.length) {
+        const end = Math.min(start + CHUNK_WORDS, words.length);
+        chunks.push(words.slice(start, end).join(' '));
+        if (end >= words.length)
+            break;
+        start += CHUNK_WORDS - OVERLAP_WORDS;
+    }
+    const totalChunks = chunks.length;
+    return chunks.map((chunkText, chunkIndex) => ({ text: chunkText, chunkIndex, totalChunks }));
+}
+//# sourceMappingURL=chunker.js.map

package/dist/chunker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.js","sourceRoot":"","sources":["../src/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAC/B,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAWhC;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,QAAyB;IACtD,OAAO,SAAS,QAAQ,CAAC,WAAW,YAAY,QAAQ,CAAC,aAAa,EAAE,CAAC;AAC3E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAyB;IACrD,MAAM,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE5D,IAAI,KAAK,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;QAChC,OAAO,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/C,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM;YAAE,MAAM;QAC/B,KAAK,IAAI,WAAW,GAAG,aAAa,CAAC;IACvC,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IAClC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;AAC/F,CAAC"}

package/dist/context-builder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Context builder — formats a MemoryContext into a [MEMORY CONTEXT] string
+ * suitable for injection into an agent's system prompt.
+ *
+ * Output format (example):
+ *
+ *   [MEMORY CONTEXT]
+ *
+ *   ## High confidence facts
+ *   - user is building a product called Plumb (0.98, session: tech-planning, today)
+ *
+ *   ## Medium confidence facts
+ *   - user uses TypeScript (0.65, session: dev-chat, 2 days ago)
+ *
+ *   ## Related conversations
+ *   - [tech-planning] today: "Let me help you design the memory system..."
+ *
+ * Empty MemoryContext returns an empty string — no block is injected.
+ */
+import type { MemoryContext } from './read-path.js';
+/**
+ * Converts an age in fractional days to a human-readable string.
+ * Examples: 'today', 'yesterday', '3 days ago', '2 weeks ago', '1 month ago'.
+ */
+export declare function formatAge(ageInDays: number): string;
+/**
+ * Formats a MemoryContext into a [MEMORY CONTEXT] prompt block.
+ *
+ * Returns an empty string if the context has no facts and no raw chunks,
+ * so callers can skip injection without additional checks.
+ */
+export declare function formatContextBlock(context: MemoryContext): string;
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../src/context-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAwB,MAAM,gBAAgB,CAAC;AAI1E;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAUnD;AAsBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAsCjE"}

package/dist/context-builder.js

@@ -0,0 +1,101 @@
+/**
+ * Context builder — formats a MemoryContext into a [MEMORY CONTEXT] string
+ * suitable for injection into an agent's system prompt.
+ *
+ * Output format (example):
+ *
+ *   [MEMORY CONTEXT]
+ *
+ *   ## High confidence facts
+ *   - user is building a product called Plumb (0.98, session: tech-planning, today)
+ *
+ *   ## Medium confidence facts
+ *   - user uses TypeScript (0.65, session: dev-chat, 2 days ago)
+ *
+ *   ## Related conversations
+ *   - [tech-planning] today: "Let me help you design the memory system..."
+ *
+ * Empty MemoryContext returns an empty string — no block is injected.
+ */
+// ─── Age formatting ───────────────────────────────────────────────────────────
+/**
+ * Converts an age in fractional days to a human-readable string.
+ * Examples: 'today', 'yesterday', '3 days ago', '2 weeks ago', '1 month ago'.
+ */
+export function formatAge(ageInDays) {
+    if (ageInDays < 1)
+        return 'today';
+    if (ageInDays < 2)
+        return 'yesterday';
+    if (ageInDays < 7)
+        return `${Math.floor(ageInDays)} days ago`;
+    if (ageInDays < 14)
+        return '1 week ago';
+    if (ageInDays < 30)
+        return `${Math.floor(ageInDays / 7)} weeks ago`;
+    if (ageInDays < 60)
+        return '1 month ago';
+    if (ageInDays < 365)
+        return `${Math.floor(ageInDays / 30)} months ago`;
+    if (ageInDays < 730)
+        return '1 year ago';
+    return `${Math.floor(ageInDays / 365)} years ago`;
+}
+// ─── Line formatters ──────────────────────────────────────────────────────────
+function formatFactLine(sf) {
+    const { fact, score, ageInDays } = sf;
+    const description = `${fact.subject} ${fact.predicate} ${fact.object}`;
+    const sessionLabel = fact.sourceSessionLabel ?? fact.sourceSessionId;
+    const age = formatAge(ageInDays);
+    return `- ${description} (${score.toFixed(2)}, session: ${sessionLabel}, ${age})`;
+}
+function formatChunkLine(chunk) {
+    const excerpt = chunk.chunkText.slice(0, 200);
+    const sessionLabel = chunk.sessionLabel ?? chunk.sessionId;
+    const ageInDays = (Date.now() - chunk.timestamp.getTime()) / (1_000 * 60 * 60 * 24);
+    const age = formatAge(ageInDays);
+    return `- [${sessionLabel}] ${age}: "${excerpt}"`;
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Formats a MemoryContext into a [MEMORY CONTEXT] prompt block.
+ *
+ * Returns an empty string if the context has no facts and no raw chunks,
+ * so callers can skip injection without additional checks.
+ */
+export function formatContextBlock(context) {
+    const { highConfidence, mediumConfidence, lowConfidence, relatedConversations } = context;
+    const isEmpty = highConfidence.length === 0 &&
+        mediumConfidence.length === 0 &&
+        lowConfidence.length === 0 &&
+        relatedConversations.length === 0;
+    if (isEmpty)
+        return '';
+    const lines = ['[MEMORY CONTEXT]'];
+    if (highConfidence.length > 0) {
+        lines.push('');
+        lines.push('## High confidence facts');
+        for (const sf of highConfidence)
+            lines.push(formatFactLine(sf));
+    }
+    if (mediumConfidence.length > 0) {
+        lines.push('');
+        lines.push('## Medium confidence facts');
+        for (const sf of mediumConfidence)
+            lines.push(formatFactLine(sf));
+    }
+    if (lowConfidence.length > 0) {
+        lines.push('');
+        lines.push('## Low confidence facts');
+        for (const sf of lowConfidence)
+            lines.push(formatFactLine(sf));
+    }
+    if (relatedConversations.length > 0) {
+        lines.push('');
+        lines.push('## Related conversations');
+        for (const chunk of relatedConversations)
+            lines.push(formatChunkLine(chunk));
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=context-builder.js.map

package/dist/context-builder.js.map

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

package/dist/embedder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Embedder — wraps @xenova/transformers for local CPU inference.
+ *
+ * Models:
+ *   Passage embedder: Xenova/bge-small-en-v1.5 (384-dim, normalized cosine)
+ *   Cross-encoder:    Xenova/ms-marco-MiniLM-L-6-v2 (relevance logit)
+ *
+ * BGE convention:
+ *   - Index-time text: no prefix (raw passage)
+ *   - Query-time text: "query: " prefix (improves asymmetric retrieval)
+ *
+ * First call downloads the model (~100 MB for bge-small). Subsequent calls
+ * use the local cache at ~/.cache/huggingface/hub/.
+ */
+/** Embedding dimension for BAAI/bge-small-en-v1.5. */
+export declare const EMBED_DIM = 384;
+/**
+ * Embed a passage for indexing (no query prefix).
+ * Returns a normalized Float32Array of length EMBED_DIM.
+ */
+export declare function embed(text: string): Promise<Float32Array>;
+/**
+ * Embed a search query with BGE "query: " prefix.
+ * Returns a normalized Float32Array of length EMBED_DIM.
+ */
+export declare function embedQuery(query: string): Promise<Float32Array>;
+/**
+ * Score (query, passage) pairs with the cross-encoder.
+ * Returns raw logits (higher = more relevant).
+ * Falls back to zeros if the reranker model is unavailable — callers
+ * should detect all-zero arrays and fall back to RRF order.
+ */
+export declare function rerankScores(query: string, passages: string[]): Promise<number[]>;
+//# sourceMappingURL=embedder.d.ts.map

package/dist/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,sDAAsD;AACtD,eAAO,MAAM,SAAS,MAAM,CAAC;AAiB7B;;;GAGG;AACH,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAI/D;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAIrE;AA4BD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBvF"}

package/dist/embedder.js

@@ -0,0 +1,88 @@
+/**
+ * Embedder — wraps @xenova/transformers for local CPU inference.
+ *
+ * Models:
+ *   Passage embedder: Xenova/bge-small-en-v1.5 (384-dim, normalized cosine)
+ *   Cross-encoder:    Xenova/ms-marco-MiniLM-L-6-v2 (relevance logit)
+ *
+ * BGE convention:
+ *   - Index-time text: no prefix (raw passage)
+ *   - Query-time text: "query: " prefix (improves asymmetric retrieval)
+ *
+ * First call downloads the model (~100 MB for bge-small). Subsequent calls
+ * use the local cache at ~/.cache/huggingface/hub/.
+ */
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore — @xenova/transformers has incomplete typings
+import { pipeline, env } from '@xenova/transformers';
+/** Embedding dimension for BAAI/bge-small-en-v1.5. */
+export const EMBED_DIM = 384;
+// Disable the remote model check in test/offline environments to use cache.
+// env.allowRemoteModels is already true by default; this line is a no-op but documents intent.
+env.allowLocalModels = true;
+let _embedPipeline = null;
+async function getEmbedPipeline() {
+    if (_embedPipeline === null) {
+        _embedPipeline = (await pipeline('feature-extraction', 'Xenova/bge-small-en-v1.5'));
+    }
+    return _embedPipeline;
+}
+/**
+ * Embed a passage for indexing (no query prefix).
+ * Returns a normalized Float32Array of length EMBED_DIM.
+ */
+export async function embed(text) {
+    const pipe = await getEmbedPipeline();
+    const output = await pipe(text, { pooling: 'mean', normalize: true });
+    return new Float32Array(output.data);
+}
+/**
+ * Embed a search query with BGE "query: " prefix.
+ * Returns a normalized Float32Array of length EMBED_DIM.
+ */
+export async function embedQuery(query) {
+    const pipe = await getEmbedPipeline();
+    const output = await pipe(`query: ${query}`, { pooling: 'mean', normalize: true });
+    return new Float32Array(output.data);
+}
+let _rerankPipeline = null;
+let _rerankLoadFailed = false;
+async function getRerankPipeline() {
+    if (_rerankLoadFailed)
+        return null;
+    if (_rerankPipeline === null) {
+        try {
+            _rerankPipeline = (await pipeline('text-classification', 'Xenova/ms-marco-MiniLM-L-6-v2'));
+        }
+        catch {
+            _rerankLoadFailed = true;
+            return null;
+        }
+    }
+    return _rerankPipeline;
+}
+/**
+ * Score (query, passage) pairs with the cross-encoder.
+ * Returns raw logits (higher = more relevant).
+ * Falls back to zeros if the reranker model is unavailable — callers
+ * should detect all-zero arrays and fall back to RRF order.
+ */
+export async function rerankScores(query, passages) {
+    const pipe = await getRerankPipeline();
+    if (pipe === null || passages.length === 0) {
+        return passages.map(() => 0);
+    }
+    const scores = [];
+    for (const passage of passages) {
+        try {
+            const result = await pipe([query, passage], { function_to_apply: 'none' });
+            const raw = (Array.isArray(result) ? result[0] : result);
+            scores.push(raw?.score ?? 0);
+        }
+        catch {
+            scores.push(0);
+        }
+    }
+    return scores;
+}
+//# sourceMappingURL=embedder.js.map

package/dist/embedder.js.map

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

package/dist/extractor.d.ts

@@ -0,0 +1,21 @@
+import type { MemoryStore } from './store.js';
+import { type Fact, type MessageExchange } from './types.js';
+/**
+ * Extract facts from a conversation exchange via an LLM call.
+ *
+ * Makes one LLM call, parses the JSON array response, persists each fact via
+ * the provided store, and returns the stored Fact[].
+ *
+ * Dedup strategy: always insert as a new entry — never update an existing fact
+ * with the same subject+predicate. Decay scoring (T-006) handles ranking.
+ *
+ * @param exchange - The conversation exchange to extract facts from.
+ * @param userId   - The user ID to scope facts to (passed to store.store()).
+ *                   NOTE: LocalStore captures userId at construction time, so
+ *                   this param is accepted here for documentation/future use
+ *                   but the store itself enforces the scope.
+ * @param store    - The MemoryStore instance to persist facts into.
+ * @param llmFn    - Optional LLM function to use (injectable for testing).
+ */
+export declare function extractFacts(exchange: MessageExchange, _userId: string, store: MemoryStore, llmFn?: (prompt: string) => Promise<string>): Promise<Fact[]>;
+//# sourceMappingURL=extractor.d.ts.map

package/dist/extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../src/extractor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAa,KAAK,IAAI,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAmDxE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,EAClB,KAAK,GAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAW,GACnD,OAAO,CAAC,IAAI,EAAE,CAAC,CAkCjB"}