@psiclawops/hypermem 0.9.6 → 0.9.9

package/dist/entity-extractor.js

@@ -0,0 +1,382 @@
+/**
+ * entity-extractor.ts — Entity and facet tagger
+ *
+ * Sprint A: compose-time annotation only.
+ * Sprint B: also used at ingest time. Adds shared key normalization
+ * (`normalizeEntityKey`, `normalizeFacetKey`) and an ingest-friendly
+ * `extractEntityFacetMentions(text)` returning cheap (start,end) offsets
+ * suitable for storing in `message_entity_mentions` / `message_facet_mentions`.
+ *
+ * Exported symbols:
+ *   extractEntitiesFromText(text, knownEntities?)   → ExtractedTextEntities
+ *   annotateRecallGroups(...)                       → AnnotatedGroup[]
+ *   formatStructuredHandoffBlock(...)               → structured block
+ *   buildStructuredHandoffInstruction(...)          → string
+ *   normalizeEntityKey(token)                       → string                (Sprint B)
+ *   normalizeFacetKey(token)                        → string                (Sprint B)
+ *   extractEntityFacetMentions(text)                → EntityFacetMentions    (Sprint B)
+ */
+import { QUESTION_SHAPE_FACETS, extractQueryFacetTerms, } from './question-shape.js';
+// ── Internal helpers ──────────────────────────────────────────────────────
+/** TitleCase word pattern for content scanning */
+const TITLE_CASE_CONTENT_WORD = /\b[A-Z][a-z][a-zA-Z]*\b/g;
+/** Quoted string pattern */
+const QUOTED_STRING_CONTENT = /["']([^"']{2,30})["']/g;
+/** ALL-CAPS abbreviation */
+const ALLCAPS_ABBREV_CONTENT = /\b[A-Z]{2,6}\b/g;
+const CONTENT_STOP_WORDS = new Set([
+    'the', 'a', 'an', 'in', 'on', 'at', 'to', 'for', 'of', 'and', 'or', 'but',
+    'by', 'is', 'it', 'if', 'so', 'do', 'be', 'my', 'we', 'he', 'she', 'they',
+    'you', 'me', 'us', 'his', 'her', 'its', 'our', 'your', 'who', 'what', 'how',
+    'when', 'where', 'which', 'why', 'would', 'could', 'should', 'did', 'does',
+    'was', 'were', 'has', 'have', 'had', 'will', 'can', 'may', 'might', 'shall',
+    'just', 'also', 'both', 'each', 'with', 'from', 'that', 'this', 'these',
+    'those', 'any', 'all', 'not', 'now', 'well', 'too', 'very', 'more', 'most',
+    'some', 'same', 'last', 'next', 'new', 'old', 'then', 'than', 'into', 'upon',
+    // Role labels that appear in recall blocks
+    'user', 'assistant', 'raw', 'transcript', 'group',
+    // Common discourse words
+    'yes', 'yeah', 'okay', 'ok', 'sure', 'right', 'true', 'false',
+    // Date words
+    'january', 'february', 'march', 'april', 'june', 'july', 'august',
+    'september', 'october', 'november', 'december',
+]);
+/**
+ * Extract entity and facet tokens from a block of text content.
+ * When `knownEntities` is provided, the scan is biased toward those tokens
+ * (useful for narrowing to query-relevant entities during structured handoff).
+ */
+export function extractEntitiesFromText(text, knownEntities) {
+    const entities = new Set();
+    const lower = text.toLowerCase();
+    // If caller provides a known entity list, check those first (fast path)
+    if (knownEntities && knownEntities.length > 0) {
+        for (const e of knownEntities) {
+            if (lower.includes(e.toLowerCase())) {
+                entities.add(e.toLowerCase());
+            }
+        }
+    }
+    // Always scan for TitleCase entities (catches entities not in knownEntities)
+    for (const m of text.matchAll(TITLE_CASE_CONTENT_WORD)) {
+        const word = m[0];
+        const wLower = word.toLowerCase();
+        if (!CONTENT_STOP_WORDS.has(wLower)) {
+            entities.add(wLower);
+        }
+    }
+    // Quoted strings
+    for (const m of text.matchAll(QUOTED_STRING_CONTENT)) {
+        const val = m[1].trim().toLowerCase();
+        if (val.length >= 2 && !CONTENT_STOP_WORDS.has(val)) {
+            entities.add(val);
+        }
+    }
+    // ALL-CAPS abbreviations
+    for (const m of text.matchAll(ALLCAPS_ABBREV_CONTENT)) {
+        const abbrev = m[0].toLowerCase();
+        if (abbrev.length >= 2 && !CONTENT_STOP_WORDS.has(abbrev)) {
+            entities.add(abbrev);
+        }
+    }
+    // Facets
+    const facets = new Set();
+    const facetTerms = [];
+    for (const facet of QUESTION_SHAPE_FACETS) {
+        for (const term of facet.terms) {
+            if (lower.includes(term)) {
+                facets.add(facet.name);
+                facetTerms.push(term);
+                break; // one match per facet group is enough
+            }
+        }
+    }
+    return {
+        entities: [...entities],
+        facets: [...facets],
+        facetTerms: [...new Set(facetTerms)],
+    };
+}
+// ── Group annotator ───────────────────────────────────────────────────────
+/**
+ * Parse raw recall content (already grouped by conversation_id) into annotated groups.
+ *
+ * Input is the `recall.content` string from `buildQueryMessageRecall()`,
+ * which uses `### Raw transcript group {id}` headers.
+ *
+ * For each group, annotates which query entities and facets appear in the
+ * group's content lines. This is the core of the Sprint A structured handoff.
+ */
+export function annotateRecallGroups(recallContent, queryEntities, queryFacets) {
+    const groups = [];
+    const queryFacetTerms = extractQueryFacetTerms(queryFacets.join(' '));
+    // Build a set of raw facet terms for matching within group content
+    const facetTermsByGroup = new Map();
+    for (const facetName of queryFacets) {
+        const facet = QUESTION_SHAPE_FACETS.find(f => f.name === facetName);
+        if (facet) {
+            facetTermsByGroup.set(facetName, facet.terms);
+        }
+    }
+    // Split content by group headers
+    const groupHeaderPattern = /^### Raw transcript group (\S+)/m;
+    const parts = recallContent.split(/^(?=### Raw transcript group \S+)/m);
+    for (const part of parts) {
+        if (!part.trim())
+            continue;
+        const headerMatch = part.match(groupHeaderPattern);
+        if (!headerMatch)
+            continue;
+        const groupId = headerMatch[1];
+        const lines = part.split('\n');
+        const contentLines = lines.slice(1); // skip header line
+        // Flatten group text for entity/facet matching
+        const groupText = contentLines.join(' ');
+        const groupLower = groupText.toLowerCase();
+        // Which query entities appear in this group?
+        const matchedEntities = queryEntities.filter(e => groupLower.includes(e.toLowerCase()));
+        // Which query facet groups appear in this group?
+        const matchedFacets = [];
+        const matchedFacetTerms = [];
+        for (const [facetName, terms] of facetTermsByGroup) {
+            const matched = terms.filter(t => groupLower.includes(t));
+            if (matched.length > 0) {
+                matchedFacets.push(facetName);
+                matchedFacetTerms.push(...matched);
+            }
+        }
+        groups.push({
+            groupId,
+            lines: contentLines,
+            matchedEntities,
+            matchedFacets,
+            matchedFacetTerms: [...new Set(matchedFacetTerms)],
+            isRelevant: matchedEntities.length > 0 || matchedFacets.length > 0,
+        });
+    }
+    return groups;
+}
+// ── Structured handoff formatter ──────────────────────────────────────────
+/**
+ * Format annotated groups into structured evidence blocks for multi-hop handoff.
+ *
+ * Each group gets a header that names which query entities/facets it contains,
+ * so the reader can quickly identify which groups are evidence for each hop.
+ *
+ * Token cost is minimal relative to the raw content: only the header changes.
+ * No content is dropped; existing budget accounting from buildQueryMessageRecall
+ * applies before this formatter runs.
+ */
+export function formatStructuredHandoffBlock(groups, queryEntities, queryFacets) {
+    const lines = [];
+    let entityGroupCount = 0;
+    let facetGroupCount = 0;
+    for (const group of groups) {
+        const hasMeaningfulContent = group.lines.some(l => l.trim().startsWith('-'));
+        if (!hasMeaningfulContent)
+            continue;
+        // Build a compact annotation for the group header
+        const annotations = [];
+        if (group.matchedEntities.length > 0) {
+            annotations.push(`entities: ${group.matchedEntities.slice(0, 4).join(', ')}`);
+            entityGroupCount++;
+        }
+        if (group.matchedFacets.length > 0) {
+            annotations.push(`facets: ${group.matchedFacets.slice(0, 3).join(', ')}`);
+            facetGroupCount++;
+        }
+        // Emit header with annotation (or without if no match — still emit the group)
+        if (annotations.length > 0) {
+            lines.push(`### Evidence group ${group.groupId} [${annotations.join('; ')}]`);
+        }
+        else {
+            lines.push(`### Raw transcript group ${group.groupId}`);
+        }
+        // Emit content lines (unchanged from recall output)
+        for (const line of group.lines) {
+            if (line.trim())
+                lines.push(line);
+        }
+        lines.push('');
+    }
+    return {
+        content: lines.join('\n').trimEnd(),
+        entityGroupCount,
+        facetGroupCount,
+    };
+}
+// ── Sprint B: shared key normalization and ingest extraction ─────────────
+/**
+ * Normalize an entity surface form into a canonical bridge key.
+ *
+ * Strategy: lowercase, collapse whitespace, strip leading/trailing punctuation,
+ * preserve internal alphanumerics + a small set of joiners (-, _, .).
+ * The result is the join key used by `memory_entities.entity_key`.
+ */
+export function normalizeEntityKey(token) {
+    if (!token)
+        return '';
+    const trimmed = String(token).trim().toLowerCase();
+    if (!trimmed)
+        return '';
+    // Collapse internal whitespace, strip leading/trailing punctuation.
+    const collapsed = trimmed.replace(/\s+/g, ' ');
+    return collapsed.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '');
+}
+/**
+ * Normalize a facet group name into a canonical bridge key.
+ * Facet keys are already lowercase identifiers in QUESTION_SHAPE_FACETS,
+ * but callers may pass raw terms. We snap raw terms to their facet group.
+ */
+export function normalizeFacetKey(token) {
+    if (!token)
+        return '';
+    const lower = String(token).trim().toLowerCase();
+    if (!lower)
+        return '';
+    // If the token is already a facet group name, return it.
+    for (const f of QUESTION_SHAPE_FACETS) {
+        if (f.name === lower)
+            return lower;
+    }
+    // Otherwise look it up against the term list.
+    for (const f of QUESTION_SHAPE_FACETS) {
+        if (f.terms.includes(lower))
+            return f.name;
+    }
+    return lower.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, '');
+}
+/**
+ * Internal helper: yield a regex that matches the union of facet terms with
+ * word boundaries where possible. Cached at module level.
+ */
+let _facetTermPattern = null;
+let _facetTermLookup = null;
+function getFacetTermPattern() {
+    if (_facetTermPattern && _facetTermLookup) {
+        return { pattern: _facetTermPattern, lookup: _facetTermLookup };
+    }
+    const lookup = new Map();
+    const escaped = [];
+    for (const facet of QUESTION_SHAPE_FACETS) {
+        for (const term of facet.terms) {
+            // Last write wins for ambiguous terms; QUESTION_SHAPE_FACETS authors
+            // are responsible for keeping the lexicon disjoint enough.
+            lookup.set(term.toLowerCase(), facet.name);
+            escaped.push(term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        }
+    }
+    // Sort by length descending so multi-word terms beat single-word prefixes.
+    escaped.sort((a, b) => b.length - a.length);
+    _facetTermPattern = new RegExp(`\\b(?:${escaped.join('|')})\\b`, 'gi');
+    _facetTermLookup = lookup;
+    return { pattern: _facetTermPattern, lookup };
+}
+/**
+ * Extract entity and facet mentions from a text block, with cheap (start,end)
+ * offsets, for ingest indexing into the entity/facet bridge tables.
+ *
+ * Designed to be cheap and deterministic; never calls a model, never reads
+ * a DB. Caller decides whether to write the resulting mentions.
+ */
+export function extractEntityFacetMentions(text) {
+    const entities = [];
+    const facets = [];
+    if (!text)
+        return { entities, facets };
+    const seenEntity = new Map();
+    // TitleCase entities
+    for (const m of text.matchAll(TITLE_CASE_CONTENT_WORD)) {
+        const surface = m[0];
+        const key = normalizeEntityKey(surface);
+        if (!key || CONTENT_STOP_WORDS.has(key))
+            continue;
+        if (seenEntity.has(key))
+            continue;
+        const start = m.index ?? text.indexOf(surface);
+        const end = start + surface.length;
+        const mention = { key, surface, start, end };
+        seenEntity.set(key, mention);
+        entities.push(mention);
+    }
+    // Quoted strings
+    for (const m of text.matchAll(QUOTED_STRING_CONTENT)) {
+        const inner = m[1];
+        const key = normalizeEntityKey(inner);
+        if (!key || key.length < 2 || CONTENT_STOP_WORDS.has(key))
+            continue;
+        if (seenEntity.has(key))
+            continue;
+        const matchStart = m.index ?? text.indexOf(m[0]);
+        const innerStart = matchStart + 1; // skip opening quote
+        const mention = {
+            key,
+            surface: inner,
+            start: innerStart,
+            end: innerStart + inner.length,
+        };
+        seenEntity.set(key, mention);
+        entities.push(mention);
+    }
+    // ALL-CAPS abbreviations
+    for (const m of text.matchAll(ALLCAPS_ABBREV_CONTENT)) {
+        const surface = m[0];
+        const key = normalizeEntityKey(surface);
+        if (!key || key.length < 2 || CONTENT_STOP_WORDS.has(key))
+            continue;
+        if (seenEntity.has(key))
+            continue;
+        const start = m.index ?? text.indexOf(surface);
+        const mention = {
+            key,
+            surface,
+            start,
+            end: start + surface.length,
+        };
+        seenEntity.set(key, mention);
+        entities.push(mention);
+    }
+    // Facet term scan
+    const { pattern, lookup } = getFacetTermPattern();
+    pattern.lastIndex = 0;
+    const seenFacetGroup = new Set();
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+        const term = m[0].toLowerCase();
+        const facetKey = lookup.get(term);
+        if (!facetKey)
+            continue;
+        // Keep the first occurrence per facet group; cheap and bounded.
+        if (seenFacetGroup.has(facetKey))
+            continue;
+        seenFacetGroup.add(facetKey);
+        facets.push({
+            key: facetKey,
+            term,
+            start: m.index,
+            end: m.index + term.length,
+        });
+    }
+    return { entities, facets };
+}
+/**
+ * Build the structured handoff instruction preamble.
+ * Replaces the current flat multi-hop instruction string when structured
+ * handoff is active.
+ */
+export function buildStructuredHandoffInstruction(entities, facets) {
+    const parts = [
+        '## Query-Matched Conversation Memory',
+    ];
+    if (entities.length > 0 || facets.length > 0) {
+        const subjectParts = [];
+        if (entities.length > 0)
+            subjectParts.push(`entities: ${entities.slice(0, 4).join(', ')}`);
+        if (facets.length > 0)
+            subjectParts.push(`facets: ${facets.slice(0, 3).join(', ')}`);
+        parts.push(`Query subjects — ${subjectParts.join('; ')}.`);
+    }
+    parts.push('Evidence groups below are tagged with which query subjects appear in each group.', 'For multi-part questions, scan all groups and collect every relevant item before answering.', 'If the question asks what people share, have in common, bought, planned, pursued, or lost, scan all groups and include every matching item before summarizing.', 'Prefer the shortest complete list of supported items; do not add unsupported extras.', 'For names, places, events, purchases, deaths, goals, or activities, preserve each distinct transcript anchor you find instead of collapsing to a generic category.', 'Do not answer that no information is available when the groups contain supporting evidence.');
+    return parts.join('\n');
+}
+//# sourceMappingURL=entity-extractor.js.map

package/dist/entity-ppr.d.ts

@@ -0,0 +1,55 @@
+/**
+ * entity-ppr.ts \u2014 Sprint B
+ *
+ * Sparse, in-memory Personalized PageRank over a small message/entity/facet
+ * adjacency snapshot from `EntityBridgeStore.buildGraphSnapshot()`.
+ *
+ * Caps:
+ *   - Iteration cap (default 20).
+ *   - Convergence tolerance (default 1e-6).
+ *   - Hard message/edge caps come from the snapshot itself; PPR never grows it.
+ *
+ * Returns ranked message IDs and diagnostics. Never reads from the DB
+ * directly \u2014 callers pass an already-bounded snapshot.
+ */
+import type { BridgeGraphSnapshot } from './entity-bridge-store.js';
+export interface PprOptions {
+    /** Restart probability (alpha). Default 0.15 \u2192 0.85 walk continuation. */
+    teleportProbability?: number;
+    /** Maximum power iterations. Default 20. */
+    maxIterations?: number;
+    /** L1 convergence tolerance over the score vector. Default 1e-6. */
+    convergenceTolerance?: number;
+    /** Optional cap on how many messages to return. Default: all ranked. */
+    topK?: number;
+}
+export interface PprDiagnostics {
+    iterations: number;
+    converged: boolean;
+    /** Final L1 delta. */
+    delta: number;
+    /** Total messages scored. */
+    messageCount: number;
+    /** Number of seeds used. */
+    seedCount: number;
+    /** Whether seeds had no neighbors at all (dead start). */
+    emptyGraph: boolean;
+}
+export interface PprResult {
+    /** Ranked array of `{ messageId, score }` in descending order. */
+    ranked: Array<{
+        messageId: number;
+        score: number;
+    }>;
+    diagnostics: PprDiagnostics;
+}
+/**
+ * Run sparse personalized PageRank. The graph is bipartite-like:
+ *   message <-> entity
+ *   message <-> facet
+ *
+ * We treat each message/entity/facet as a node. Edge weights are uniform
+ * (1.0) within the snapshot \u2014 RRF/recency scoring is the caller's job.
+ */
+export declare function runPersonalizedPageRank(snapshot: BridgeGraphSnapshot, seedEntityKeys: string[], seedFacetKeys: string[], opts?: PprOptions): PprResult;
+//# sourceMappingURL=entity-ppr.d.ts.map

package/dist/entity-ppr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-ppr.d.ts","sourceRoot":"","sources":["../src/entity-ppr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,MAAM,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,WAAW,EAAE,cAAc,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,mBAAmB,EAC7B,cAAc,EAAE,MAAM,EAAE,EACxB,aAAa,EAAE,MAAM,EAAE,EACvB,IAAI,CAAC,EAAE,UAAU,GAChB,SAAS,CA0JX"}

package/dist/entity-ppr.js

@@ -0,0 +1,180 @@
+/**
+ * entity-ppr.ts \u2014 Sprint B
+ *
+ * Sparse, in-memory Personalized PageRank over a small message/entity/facet
+ * adjacency snapshot from `EntityBridgeStore.buildGraphSnapshot()`.
+ *
+ * Caps:
+ *   - Iteration cap (default 20).
+ *   - Convergence tolerance (default 1e-6).
+ *   - Hard message/edge caps come from the snapshot itself; PPR never grows it.
+ *
+ * Returns ranked message IDs and diagnostics. Never reads from the DB
+ * directly \u2014 callers pass an already-bounded snapshot.
+ */
+/**
+ * Run sparse personalized PageRank. The graph is bipartite-like:
+ *   message <-> entity
+ *   message <-> facet
+ *
+ * We treat each message/entity/facet as a node. Edge weights are uniform
+ * (1.0) within the snapshot \u2014 RRF/recency scoring is the caller's job.
+ */
+export function runPersonalizedPageRank(snapshot, seedEntityKeys, seedFacetKeys, opts) {
+    const alpha = clamp(opts?.teleportProbability ?? 0.15, 1e-3, 0.99);
+    const maxIters = Math.max(1, Math.min(200, opts?.maxIterations ?? 20));
+    const tol = Math.max(1e-12, opts?.convergenceTolerance ?? 1e-6);
+    // Build the union of node ids. We use string ids: 'm:<id>', 'e:<key>', 'f:<key>'.
+    const nodeIds = [];
+    const nodeIndex = new Map();
+    const adj = [];
+    function ensureNode(id) {
+        let idx = nodeIndex.get(id);
+        if (idx == null) {
+            idx = nodeIds.length;
+            nodeIds.push(id);
+            nodeIndex.set(id, idx);
+            adj.push([]);
+        }
+        return idx;
+    }
+    // Add edges: entity <-> message
+    for (const [key, msgs] of snapshot.entityMessages) {
+        const eIdx = ensureNode(`e:${key}`);
+        for (const mid of msgs) {
+            const mIdx = ensureNode(`m:${mid}`);
+            adj[eIdx].push(mIdx);
+            adj[mIdx].push(eIdx);
+        }
+    }
+    // facet <-> message (from seed expansion)
+    for (const [key, msgs] of snapshot.facetMessages) {
+        const fIdx = ensureNode(`f:${key}`);
+        for (const mid of msgs) {
+            const mIdx = ensureNode(`m:${mid}`);
+            adj[fIdx].push(mIdx);
+            adj[mIdx].push(fIdx);
+        }
+    }
+    // Add second-hop adjacencies derived from messageEntities / messageFacets.
+    for (const [mid, ents] of snapshot.messageEntities) {
+        const mIdx = ensureNode(`m:${mid}`);
+        for (const ek of ents) {
+            const eIdx = ensureNode(`e:${ek}`);
+            adj[eIdx].push(mIdx);
+            adj[mIdx].push(eIdx);
+        }
+    }
+    for (const [mid, facs] of snapshot.messageFacets) {
+        const mIdx = ensureNode(`m:${mid}`);
+        for (const fk of facs) {
+            const fIdx = ensureNode(`f:${fk}`);
+            adj[fIdx].push(mIdx);
+            adj[mIdx].push(fIdx);
+        }
+    }
+    // Build seed teleport vector.
+    const seedVec = new Float64Array(nodeIds.length);
+    let seedMass = 0;
+    for (const k of seedEntityKeys) {
+        const idx = nodeIndex.get(`e:${k}`);
+        if (idx != null) {
+            seedVec[idx] += 1;
+            seedMass += 1;
+        }
+    }
+    for (const k of seedFacetKeys) {
+        const idx = nodeIndex.get(`f:${k}`);
+        if (idx != null) {
+            seedVec[idx] += 1;
+            seedMass += 1;
+        }
+    }
+    if (seedMass === 0 || nodeIds.length === 0) {
+        return {
+            ranked: [],
+            diagnostics: {
+                iterations: 0,
+                converged: true,
+                delta: 0,
+                messageCount: 0,
+                seedCount: seedEntityKeys.length + seedFacetKeys.length,
+                emptyGraph: true,
+            },
+        };
+    }
+    for (let i = 0; i < seedVec.length; i++)
+        seedVec[i] /= seedMass;
+    // Power iteration: r_{t+1} = alpha * seedVec + (1 - alpha) * Wt * r_t
+    // where Wt is the column-stochastic transpose of the adjacency.
+    // For undirected adjacency we approximate degrees from neighbor counts.
+    const degrees = adj.map(n => n.length);
+    let r = new Float64Array(seedVec); // start at the seed distribution
+    let next = new Float64Array(nodeIds.length);
+    let iterations = 0;
+    let delta = Infinity;
+    let converged = false;
+    for (; iterations < maxIters; iterations++) {
+        next.fill(0);
+        for (let i = 0; i < nodeIds.length; i++) {
+            const ri = r[i];
+            if (ri === 0)
+                continue;
+            const neighbors = adj[i];
+            const deg = degrees[i];
+            if (deg === 0) {
+                // Dangling: contribute back to the seed distribution.
+                for (let s = 0; s < nodeIds.length; s++)
+                    next[s] += ri * seedVec[s];
+                continue;
+            }
+            const share = ri / deg;
+            for (const j of neighbors)
+                next[j] += share;
+        }
+        // Apply teleport.
+        delta = 0;
+        for (let i = 0; i < nodeIds.length; i++) {
+            const v = alpha * seedVec[i] + (1 - alpha) * next[i];
+            delta += Math.abs(v - r[i]);
+            next[i] = v;
+        }
+        // Swap r and next.
+        const tmp = r;
+        r = next;
+        next = tmp;
+        if (delta < tol) {
+            converged = true;
+            iterations++;
+            break;
+        }
+    }
+    // Collect message scores.
+    const ranked = [];
+    for (let i = 0; i < nodeIds.length; i++) {
+        const id = nodeIds[i];
+        if (id.charCodeAt(0) === 109 /* 'm' */ && id.charCodeAt(1) === 58 /* ':' */) {
+            const mid = Number(id.slice(2));
+            if (Number.isFinite(mid))
+                ranked.push({ messageId: mid, score: r[i] });
+        }
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    const topK = opts?.topK;
+    const final = typeof topK === 'number' && topK >= 0 ? ranked.slice(0, topK) : ranked;
+    return {
+        ranked: final,
+        diagnostics: {
+            iterations,
+            converged,
+            delta,
+            messageCount: ranked.length,
+            seedCount: seedEntityKeys.length + seedFacetKeys.length,
+            emptyGraph: false,
+        },
+    };
+}
+function clamp(v, lo, hi) {
+    return Math.max(lo, Math.min(hi, v));
+}
+//# sourceMappingURL=entity-ppr.js.map

package/dist/hybrid-retrieval.d.ts

@@ -64,6 +64,12 @@ export interface HybridSearchOptions {
     minFtsTerms?: number;
     /** Pre-computed embedding for the query — skips Ollama call in VectorStore.search() */
     precomputedEmbedding?: Float32Array;
+    /**
+     * Permit VectorStore.search() to generate a query embedding inline when no
+     * precomputed embedding is available. Default false: memory recall must not
+     * put remote/local embedding generation on the search hot path.
+     */
+    allowInlineQueryEmbedding?: boolean;
     /**
      * Optional reranker applied after RRF fusion. Only runs on the fused path
      * (both FTS and KNN produced results). FTS-only and KNN-only branches are
@@ -100,6 +106,27 @@ export interface HybridSearchOptions {
  * Extracts meaningful words, removes stop words, uses OR conjunction.
  */
 export declare function buildFtsQuery(input: string): string;
+/**
+ * Generic RRF helper, shared by hybridSearch() (library-side fusion) and
+ * the Sprint B entity-bridge compose lane (FTS-over-messages + PPR-over-
+ * bridge-graph). This helper does NOT change hybridSearch() semantics —
+ * the legacy in-place fusion below still owns adjacency boosting and the
+ * reranker hook for the FTS+KNN path.
+ */
+export interface RrfList<T> {
+    ranked: Array<{
+        key: string;
+        item: T;
+    }>;
+    weight?: number;
+}
+export interface RrfFusedEntry<T> {
+    key: string;
+    item: T;
+    score: number;
+    ranks: number[];
+}
+export declare function reciprocalRankFuse<T>(lists: Array<RrfList<T>>, k?: number): Array<RrfFusedEntry<T>>;
 /**
  * Hybrid search combining FTS5 keyword search and KNN vector search.
  *

package/dist/hybrid-retrieval.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hybrid-retrieval.d.ts","sourceRoot":"","sources":["../src/hybrid-retrieval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAsB,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAQtD,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,oBAAoB,GACpB,wBAAwB,GACxB,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;CACxB;AAcD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,CAAC,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,YAAY,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,CAAC,EAAE,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACtD,6DAA6D;IAC7D,oBAAoB,CAAC,EAAE,CAAC,EAAE,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACzD;AAqBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBnD;AAkUD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,YAAY,EACvB,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,mBAAmB,GACzB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAqJ/B"}
+{"version":3,"file":"hybrid-retrieval.d.ts","sourceRoot":"","sources":["../src/hybrid-retrieval.ts"],"names":[],"mappings":"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"}