@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/core/memory/consolidation/consolidator.js

@@ -0,0 +1,318 @@
+/**
+ * @boombot/core — LLM memory consolidation as a background job.
+ *
+ * Lesson from Hermes (and ChatGPT "Dreaming" / Mem0 research): consolidation
+ * — extracting durable facts from past conversations into long-term memory —
+ * must run as a background job with its own cursor, NEVER inside the agent
+ * turn loop. The loop is latency-sensitive and every extraction costs an LLM
+ * call; a per-turn hook would burn calls on small talk and touch the hot
+ * path. The host drives `runConsolidation` (or `ConsolidationJob`) on a
+ * timer, far away from turns.
+ *
+ * Design (non-destructive, Mem0-style):
+ * - Extraction is per conversation, via an injected LLM. The core never
+ *   imports agent-worker: the model arrives as `ConsolidationLlm`.
+ * - Writes are append-only through `MemoryProvider.save()` with
+ *   `provenance.source = 'model'`. There is no update path and no atomic
+ *   swap — superseding, if ever needed, is a host concern.
+ * - Deduplication is rule-based (normalized exact match, Mem0's NOOP):
+ *   no extra LLM call is spent deciding whether a fact already exists.
+ * - A relevance pre-filter skips conversations shorter than
+ *   `budget.minConversationChars` before any LLM call (AgentX-style).
+ * - Progress is a watermark cursor under `CONSOLIDATION_STATE_ID`, advanced
+ *   only past fully-processed conversations, so a crash or restart never
+ *   loses work and never reprocesses.
+ * - Four hard budget axes (conversations / input chars / LLM calls /
+ *   wall-clock) stop the run cleanly with a reason. The job never throws
+ *   for LLM or budget reasons — it reports.
+ *
+ * Pure with respect to the agent loop: this module never sees a turn.
+ */
+import { DEFAULT_CONSOLIDATION_BUDGET, ConsolidationBudgetTracker, } from './budget.js';
+/**
+ * Sentinel memory id under which consolidation run state (the watermark
+ * cursor) is kept. Mirrors the host's `memory:curation` convention: the
+ * state lives in the store's audit trail, not in a separate KV table.
+ */
+export const CONSOLIDATION_STATE_ID = 'memory:consolidation';
+/** Actor id recorded in provenance for consolidation-written records. */
+export const CONSOLIDATION_ACTOR_ID = 'memory-consolidation';
+/** Upper bound on one extracted fact (chars). Extraction output is capped. */
+const MAX_FACT_CHARS = 280;
+/** Sanity cap on facts accepted from a single conversation. */
+const MAX_FACTS_PER_CONVERSATION = 50;
+/** Hard cap on raw extraction output accumulated from a streaming LLM. */
+const MAX_EXTRACTION_CHARS = 32_768;
+/**
+ * Build the extraction prompt for one conversation transcript. Exported so
+ * hosts (and tests) can see the exact contract, including the no-secrets
+ * guardrail: consolidation reads raw transcripts, so the extraction prompt
+ * must explicitly forbid persisting credentials.
+ */
+export function buildExtractionPrompt(transcript) {
+    return [
+        'You extract durable facts about the user from a conversation transcript.',
+        'Durable means still true and useful in a future session: preferences,',
+        'constraints, stable personal context, long-running projects.',
+        'Skip greetings, small talk, one-off questions, and anything already obvious.',
+        'SECURITY RULE: never extract secrets — API keys, tokens, passwords,',
+        'credentials, private keys, session cookies. If a candidate fact contains',
+        'one, drop it silently.',
+        'Output ONLY a JSON array of objects with a "text" field, e.g.',
+        '[{"text": "User prefers dark mode in every app."}].',
+        'No prose, no markdown fences, no commentary. One sentence per fact,',
+        'max 280 characters each.',
+        '',
+        'Transcript:',
+        transcript,
+    ].join('\n');
+}
+/**
+ * Parse the model's extraction output into fact strings. Tolerant: accepts
+ * a bare array, objects with a "text" field, or plain strings; extracts the
+ * first `[...]` block when the model adds prose anyway. Unparseable output
+ * yields an empty list (the conversation is skipped, never fatal).
+ */
+export function parseExtractedFacts(raw) {
+    const text = raw.trim();
+    if (text.length === 0)
+        return [];
+    let parsed = undefined;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        const start = text.indexOf('[');
+        const end = text.lastIndexOf(']');
+        if (start !== -1 && end > start) {
+            try {
+                parsed = JSON.parse(text.slice(start, end + 1));
+            }
+            catch {
+                return [];
+            }
+        }
+        else {
+            return [];
+        }
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const facts = [];
+    const seen = new Set();
+    for (const item of parsed.slice(0, MAX_FACTS_PER_CONVERSATION)) {
+        let fact;
+        if (typeof item === 'string') {
+            fact = item;
+        }
+        else if (item !== null && typeof item === 'object' && 'text' in item) {
+            const t = item.text;
+            if (typeof t === 'string')
+                fact = t;
+        }
+        if (fact === undefined)
+            continue;
+        const normalized = fact.trim().slice(0, MAX_FACT_CHARS);
+        if (normalized.length === 0 || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        facts.push(normalized);
+    }
+    return facts;
+}
+function normalizeForDedupe(text) {
+    return text.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+/**
+ * Rule-based exact-match dedupe (Mem0's NOOP without the extra LLM call).
+ * Loads the scope's live records once per run, then answers from the cache;
+ * newly written facts are registered so a run never duplicates itself. When
+ * the provider has no `list`, falls back to a best-effort FTS probe per fact.
+ */
+class DedupeIndex {
+    store;
+    cache = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    scopeKey(scope) {
+        return `${scope.kind}\n${scope.id}`;
+    }
+    load(scope) {
+        const key = this.scopeKey(scope);
+        let set = this.cache.get(key);
+        if (set === undefined) {
+            set = new Set();
+            try {
+                for (const record of this.store.list?.(scope, 5000) ?? []) {
+                    set.add(normalizeForDedupe(record.text));
+                }
+            }
+            catch {
+                // Transient failure: per-fact FTS fallback below still applies when
+                // the provider has no list; otherwise we accept best-effort.
+            }
+            this.cache.set(key, set);
+        }
+        return set;
+    }
+    isDuplicate(scope, text) {
+        const norm = normalizeForDedupe(text);
+        if (norm === '')
+            return true;
+        const set = this.load(scope);
+        if (set.has(norm))
+            return true;
+        if (this.store.list === undefined) {
+            try {
+                for (const hit of this.store.search(text.slice(0, 200), 50)) {
+                    const hitNorm = normalizeForDedupe(hit.record.text);
+                    set.add(hitNorm);
+                    if (hitNorm === norm)
+                        return true;
+                }
+            }
+            catch {
+                // Best effort only — a failed probe must not block the write.
+            }
+        }
+        return false;
+    }
+    markStored(scope, text) {
+        this.load(scope).add(normalizeForDedupe(text));
+    }
+}
+/**
+ * Run one consolidation pass: read the watermark, extract durable facts from
+ * each new conversation via the injected LLM, and append them to memory.
+ *
+ * Never throws for LLM or budget reasons — failures are reported in
+ * `stopReason`. The watermark advances only past fully-processed
+ * conversations, so an LLM failure leaves the failed conversation for the
+ * next run while keeping everything already written.
+ */
+export async function runConsolidation(deps) {
+    const budget = deps.budget ?? DEFAULT_CONSOLIDATION_BUDGET;
+    const tracker = new ConsolidationBudgetTracker(budget);
+    const dedupe = new DedupeIndex(deps.store);
+    let processed = 0;
+    let factsCreated = 0;
+    let skippedShort = 0;
+    let skippedDuplicate = 0;
+    let stopReason = 'completed';
+    const watermark = deps.watermarks.get(CONSOLIDATION_STATE_ID);
+    let cursor = watermark;
+    const advance = (endedAt) => {
+        if (cursor === null || endedAt > cursor)
+            cursor = endedAt;
+    };
+    const conversations = await deps.conversations.listEndedAfter(watermark, budget.maxConversationsPerRun);
+    for (const conv of conversations) {
+        const convStop = tracker.admitConversation(conv.transcript.length);
+        if (convStop !== null) {
+            stopReason = convStop;
+            break;
+        }
+        if (tracker.isBelowMinChars(conv.transcript.length)) {
+            skippedShort += 1;
+            processed += 1;
+            advance(conv.endedAt);
+            continue;
+        }
+        const llmStop = tracker.admitLlmCall();
+        if (llmStop !== null) {
+            stopReason = llmStop;
+            break;
+        }
+        let raw;
+        try {
+            raw = await deps.llm.completeText(buildExtractionPrompt(conv.transcript), {
+                maxTokens: 1024,
+            });
+        }
+        catch {
+            // Keep the watermark at the last fully-processed conversation: the
+            // failed one retries on the next run. Already-written facts stay.
+            stopReason = 'llm-error';
+            break;
+        }
+        for (const fact of parseExtractedFacts(raw.slice(0, MAX_EXTRACTION_CHARS))) {
+            if (dedupe.isDuplicate(conv.scope, fact)) {
+                skippedDuplicate += 1;
+                continue;
+            }
+            deps.store.save({
+                scope: conv.scope,
+                text: fact,
+                provenance: {
+                    source: 'model',
+                    reference: conv.id,
+                    actorId: CONSOLIDATION_ACTOR_ID,
+                },
+            });
+            dedupe.markStored(conv.scope, fact);
+            factsCreated += 1;
+        }
+        processed += 1;
+        advance(conv.endedAt);
+    }
+    if (cursor !== null && cursor !== watermark) {
+        deps.watermarks.set(CONSOLIDATION_STATE_ID, cursor);
+    }
+    return {
+        at: new Date().toISOString(),
+        processed,
+        factsCreated,
+        skippedShort,
+        skippedDuplicate,
+        stopReason,
+        usage: tracker.usage,
+    };
+}
+const DEFAULT_JOB_INTERVAL_MS = 1_800_000; // 30 min
+/**
+ * Background job that runs consolidation on a timer. Start it once at host
+ * boot; it never touches the agent loop. `runOnce()` exists for tests and
+ * for hosts that drive scheduling themselves (e.g. cron). Mirrors
+ * `CurationJob`, except the run is async (the LLM is remote).
+ */
+export class ConsolidationJob {
+    options;
+    timer;
+    running = false;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const intervalMs = this.options.intervalMs ?? DEFAULT_JOB_INTERVAL_MS;
+        this.timer = setInterval(() => {
+            this.runOnce().catch((error) => {
+                this.options.onError?.(error);
+            });
+        }, intervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    get isRunning() {
+        return this.running;
+    }
+    runOnce() {
+        return runConsolidation({
+            llm: this.options.llm,
+            store: this.options.store,
+            conversations: this.options.conversations,
+            watermarks: this.options.watermarks,
+            budget: this.options.budget,
+        });
+    }
+}

package/dist/node_modules/@boombot/core/memory/consolidation/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @boombot/core — LLM memory consolidation (background job).
+ *
+ * Public surface:
+ * - `runConsolidation` / `ConsolidationJob`: the pass and its timer.
+ * - `buildExtractionPrompt` / `parseExtractedFacts`: the LLM contract.
+ * - `CONSOLIDATION_STATE_ID`: the watermark key (audit-trail convention).
+ * - budget: `ConsolidationBudget`, `DEFAULT_CONSOLIDATION_BUDGET`,
+ *   `ConsolidationBudgetTracker`.
+ */
+export { CONSOLIDATION_STATE_ID, CONSOLIDATION_ACTOR_ID, ConsolidationJob, buildExtractionPrompt, parseExtractedFacts, runConsolidation, type ConsolidationJobOptions, type ConsolidationLlm, type ConsolidationReport, type ConversationSource, type EndedConversation, type RunConsolidationDeps, type WatermarkStore, } from './consolidator.js';
+export { DEFAULT_CONSOLIDATION_BUDGET, ConsolidationBudgetTracker, type BudgetStopReason, type BudgetUsage, type ConsolidationBudget, } from './budget.js';

package/dist/node_modules/@boombot/core/memory/consolidation/index.js

@@ -0,0 +1,12 @@
+/**
+ * @boombot/core — LLM memory consolidation (background job).
+ *
+ * Public surface:
+ * - `runConsolidation` / `ConsolidationJob`: the pass and its timer.
+ * - `buildExtractionPrompt` / `parseExtractedFacts`: the LLM contract.
+ * - `CONSOLIDATION_STATE_ID`: the watermark key (audit-trail convention).
+ * - budget: `ConsolidationBudget`, `DEFAULT_CONSOLIDATION_BUDGET`,
+ *   `ConsolidationBudgetTracker`.
+ */
+export { CONSOLIDATION_STATE_ID, CONSOLIDATION_ACTOR_ID, ConsolidationJob, buildExtractionPrompt, parseExtractedFacts, runConsolidation, } from './consolidator.js';
+export { DEFAULT_CONSOLIDATION_BUDGET, ConsolidationBudgetTracker, } from './budget.js';

package/dist/node_modules/@boombot/core/memory/curation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @boombot/core — memory curation as a background job.
+ *
+ * Lesson from Hermes/OpenClaw analysis (#6): curation (pin/archive/
+ * consolidate) must run as a background job with its own state — NEVER
+ * inside the agent turn loop. This module defines the curator interface,
+ * one honest TTL-based implementation, and the `CurationJob` that
+ * schedules it on a timer outside the loop.
+ */
+import { type MemoryProvider } from './provider.js';
+import { type MemoryScope } from './types.js';
+/** What the curator decided for one record. */
+export type CurationDecision = {
+    kind: 'keep';
+    id: string;
+    scope: MemoryScope;
+} | {
+    kind: 'archive';
+    id: string;
+    scope: MemoryScope;
+    reason: string;
+} | {
+    kind: 'skip';
+    id: string;
+    scope: MemoryScope;
+    reason: string;
+};
+export interface CurationPolicy {
+    /** Archive records older than this (days). Must be >= 1. */
+    maxAgeDays: number;
+    /** Max records scanned per scope per run. Default 500. */
+    batchSize?: number;
+    /** When true, report decisions without archiving anything. */
+    dryRun?: boolean;
+    /** Scopes to curate. Defaults to the provider's principal + global scope. */
+    scopes?: readonly MemoryScope[];
+}
+export interface CurationReport {
+    at: string;
+    dryRun: boolean;
+    scanned: number;
+    kept: number;
+    archived: string[];
+    skipped: number;
+    decisions: readonly CurationDecision[];
+}
+/**
+ * A curation strategy. Implementations decide pin/archive/keep per
+ * record; the job only drives scheduling. Strategies must be pure with
+ * respect to the agent loop — they never see a turn.
+ */
+export interface MemoryCurator {
+    readonly name: string;
+    curate(provider: MemoryProvider, policy: CurationPolicy): CurationReport;
+}
+/**
+ * TTL curator: archives records older than `maxAgeDays` that are not
+ * pinned. Archiving = tombstone (revoke), never hard delete — the audit
+ * trail survives and the record can be restored by re-saving.
+ */
+export declare class TtlMemoryCurator implements MemoryCurator {
+    readonly name = "ttl";
+    curate(provider: MemoryProvider, policy: CurationPolicy): CurationReport;
+}
+export interface CurationJobOptions {
+    curator: MemoryCurator;
+    provider: MemoryProvider;
+    policy: CurationPolicy;
+    /** Interval between runs in ms. Default 1 hour. */
+    intervalMs?: number;
+}
+/**
+ * Background job that runs a `MemoryCurator` on a timer. Start it once at
+ * host boot; it never touches the agent loop. `runOnce()` exists for
+ * tests and for hosts that drive scheduling themselves (e.g. cron).
+ */
+export declare class CurationJob {
+    private readonly options;
+    private timer;
+    private running;
+    constructor(options: CurationJobOptions);
+    start(): void;
+    stop(): void;
+    get isRunning(): boolean;
+    runOnce(): CurationReport;
+}

package/dist/node_modules/@boombot/core/memory/curation.js

@@ -0,0 +1,120 @@
+/**
+ * @boombot/core — memory curation as a background job.
+ *
+ * Lesson from Hermes/OpenClaw analysis (#6): curation (pin/archive/
+ * consolidate) must run as a background job with its own state — NEVER
+ * inside the agent turn loop. This module defines the curator interface,
+ * one honest TTL-based implementation, and the `CurationJob` that
+ * schedules it on a timer outside the loop.
+ */
+import {} from './provider.js';
+import {} from './types.js';
+function toScope(scope) {
+    return { kind: scope.kind, id: scope.id };
+}
+function ageDays(createdAt, nowMs) {
+    const created = Date.parse(createdAt);
+    if (Number.isNaN(created))
+        return 0;
+    return (nowMs - created) / 86_400_000;
+}
+/**
+ * TTL curator: archives records older than `maxAgeDays` that are not
+ * pinned. Archiving = tombstone (revoke), never hard delete — the audit
+ * trail survives and the record can be restored by re-saving.
+ */
+export class TtlMemoryCurator {
+    name = 'ttl';
+    curate(provider, policy) {
+        if (!Number.isFinite(policy.maxAgeDays) || policy.maxAgeDays < 1) {
+            throw new Error('TtlMemoryCurator: maxAgeDays must be >= 1');
+        }
+        const batchSize = Math.min(Math.max(Math.floor(policy.batchSize ?? 500), 1), 10_000);
+        const dryRun = policy.dryRun === true;
+        const nowMs = Date.now();
+        const decisions = [];
+        let scanned = 0;
+        let skipped = 0;
+        const scopes = policy.scopes;
+        if (scopes === undefined || scopes.length === 0) {
+            throw new Error('TtlMemoryCurator: policy.scopes must be non-empty');
+        }
+        for (const scope of scopes) {
+            const storeScope = toScope(scope);
+            const records = provider.list?.(storeScope, batchSize) ?? [];
+            for (const record of records) {
+                scanned += 1;
+                if (provider.isPinned?.(record.id, storeScope) === true) {
+                    skipped += 1;
+                    decisions.push({ kind: 'skip', id: record.id, scope: storeScope, reason: 'pinned' });
+                    continue;
+                }
+                if (ageDays(record.createdAt, nowMs) < policy.maxAgeDays) {
+                    decisions.push({ kind: 'keep', id: record.id, scope: storeScope });
+                    continue;
+                }
+                const reason = `ttl: older than ${policy.maxAgeDays}d`;
+                if (dryRun) {
+                    decisions.push({ kind: 'archive', id: record.id, scope: storeScope, reason: `${reason} (dry-run)` });
+                }
+                else if (provider.archive !== undefined) {
+                    provider.archive(record.id, storeScope, reason);
+                    decisions.push({ kind: 'archive', id: record.id, scope: storeScope, reason });
+                }
+                else {
+                    skipped += 1;
+                    decisions.push({ kind: 'skip', id: record.id, scope: storeScope, reason: 'provider has no archive' });
+                }
+            }
+        }
+        const archived = decisions
+            .filter((d) => d.kind === 'archive' && !dryRun)
+            .map((d) => d.id);
+        return {
+            at: new Date(nowMs).toISOString(),
+            dryRun,
+            scanned,
+            kept: decisions.filter((d) => d.kind === 'keep').length,
+            archived,
+            skipped,
+            decisions,
+        };
+    }
+}
+/**
+ * Background job that runs a `MemoryCurator` on a timer. Start it once at
+ * host boot; it never touches the agent loop. `runOnce()` exists for
+ * tests and for hosts that drive scheduling themselves (e.g. cron).
+ */
+export class CurationJob {
+    options;
+    timer;
+    running = false;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        const intervalMs = this.options.intervalMs ?? 3_600_000;
+        this.timer = setInterval(() => {
+            this.runOnce();
+        }, intervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        this.running = false;
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    get isRunning() {
+        return this.running;
+    }
+    runOnce() {
+        return this.options.curator.curate(this.options.provider, this.options.policy);
+    }
+}

package/dist/node_modules/@boombot/core/memory/errors.d.ts

@@ -0,0 +1,12 @@
+/** Typed errors for the memory-fts module. */
+export type MemoryFtsErrorCode = 'MEMORY_FTS_VALIDATION' | 'MEMORY_FTS_NOT_FOUND' | 'MEMORY_FTS_FORBIDDEN' | 'MEMORY_FTS_CONFLICT' | 'MEMORY_FTS_STORAGE';
+export declare class MemoryFtsError extends Error {
+    readonly code: MemoryFtsErrorCode;
+    /** Never includes record content or raw scope ids of other principals. */
+    constructor(code: MemoryFtsErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function validationError(message: string): MemoryFtsError;
+export declare function notFoundError(id: string): MemoryFtsError;
+export declare function forbiddenError(message: string): MemoryFtsError;

package/dist/node_modules/@boombot/core/memory/errors.js

@@ -0,0 +1,20 @@
+/** Typed errors for the memory-fts module. */
+export class MemoryFtsError extends Error {
+    code;
+    /** Never includes record content or raw scope ids of other principals. */
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'MemoryFtsError';
+        this.code = code;
+    }
+}
+export function validationError(message) {
+    return new MemoryFtsError('MEMORY_FTS_VALIDATION', message);
+}
+export function notFoundError(id) {
+    // Deliberately vague: existence of another principal's record must not leak.
+    return new MemoryFtsError('MEMORY_FTS_NOT_FOUND', `memory record '${id}' not found in the requested scope`);
+}
+export function forbiddenError(message) {
+    return new MemoryFtsError('MEMORY_FTS_FORBIDDEN', message);
+}

package/dist/node_modules/@boombot/core/memory/hybrid-search.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hybrid Search Fusion (Reciprocal Rank Fusion - RRF).
+ *
+ * Merges lexical (BM25 FTS) and semantic (Vector Cosine) ranking lists
+ * into a single unified relevance score.
+ */
+export interface RankedItem<T = unknown> {
+    readonly id: string;
+    readonly item: T;
+    readonly score: number;
+}
+export interface HybridScoreResult<T = unknown> {
+    readonly id: string;
+    readonly item: T;
+    readonly rrfScore: number;
+    readonly lexicalRank?: number;
+    readonly semanticRank?: number;
+}
+/** Default RRF smoothing constant (standard IR benchmark value: 60). */
+export declare const DEFAULT_RRF_K = 60;
+/**
+ * Merges two ranked lists using Reciprocal Rank Fusion.
+ *
+ * Formula: RRF_score(d) = 1 / (k + rank_lexical(d)) + 1 / (k + rank_semantic(d))
+ */
+export declare function reciprocalRankFusion<T>(lexicalList: readonly RankedItem<T>[], semanticList: readonly RankedItem<T>[], options?: {
+    k?: number;
+    limit?: number;
+}): HybridScoreResult<T>[];

package/dist/node_modules/@boombot/core/memory/hybrid-search.js

@@ -0,0 +1,52 @@
+/**
+ * Hybrid Search Fusion (Reciprocal Rank Fusion - RRF).
+ *
+ * Merges lexical (BM25 FTS) and semantic (Vector Cosine) ranking lists
+ * into a single unified relevance score.
+ */
+/** Default RRF smoothing constant (standard IR benchmark value: 60). */
+export const DEFAULT_RRF_K = 60;
+/**
+ * Merges two ranked lists using Reciprocal Rank Fusion.
+ *
+ * Formula: RRF_score(d) = 1 / (k + rank_lexical(d)) + 1 / (k + rank_semantic(d))
+ */
+export function reciprocalRankFusion(lexicalList, semanticList, options = {}) {
+    const k = options.k ?? DEFAULT_RRF_K;
+    const limit = options.limit ?? 20;
+    const itemMap = new Map();
+    const lexicalRanks = new Map();
+    const semanticRanks = new Map();
+    const combinedScores = new Map();
+    // Process lexical rankings (1-based rank)
+    for (let i = 0; i < lexicalList.length; i++) {
+        const entry = lexicalList[i];
+        const rank = i + 1;
+        itemMap.set(entry.id, entry.item);
+        lexicalRanks.set(entry.id, rank);
+        const score = 1 / (k + rank);
+        combinedScores.set(entry.id, (combinedScores.get(entry.id) ?? 0) + score);
+    }
+    // Process semantic rankings (1-based rank)
+    for (let i = 0; i < semanticList.length; i++) {
+        const entry = semanticList[i];
+        const rank = i + 1;
+        itemMap.set(entry.id, entry.item);
+        semanticRanks.set(entry.id, rank);
+        const score = 1 / (k + rank);
+        combinedScores.set(entry.id, (combinedScores.get(entry.id) ?? 0) + score);
+    }
+    const results = [];
+    for (const [id, rrfScore] of combinedScores.entries()) {
+        results.push({
+            id,
+            item: itemMap.get(id),
+            rrfScore,
+            lexicalRank: lexicalRanks.get(id),
+            semanticRank: semanticRanks.get(id),
+        });
+    }
+    // Sort descending by RRF score
+    results.sort((a, b) => b.rrfScore - a.rrfScore);
+    return results.slice(0, limit);
+}