@rine-kit/agent-memory 0.0.0-stage → 0.1.1

package/dist/dreaming/runner.js

@@ -0,0 +1,54 @@
+function failed(status) {
+    return status === 'retry' || status === 'dead' || status === 'timed_out';
+}
+async function drain(worker, stage, maxBatches, signal) {
+    let processed = 0;
+    for (let batch = 0; batch < maxBatches && !signal.aborted; batch += 1) {
+        const status = await worker.processNext(stage, signal);
+        if (status === 'skipped')
+            break;
+        if (failed(status))
+            throw new Error(`memory_dreaming_${stage}_failed`);
+        processed += 1;
+    }
+    if (signal.aborted)
+        throw new Error('memory_dreaming_aborted');
+    return processed;
+}
+/** Generic bounded Light -> REM -> Deep orchestration over host-owned workers. */
+export async function runMemoryDreamingStages(worker, signal, options = {}) {
+    const maxLightBatches = options.maxLightBatches ?? 8;
+    const maxRemBatches = options.maxRemBatches ?? 8;
+    if (!Number.isSafeInteger(maxLightBatches) ||
+        maxLightBatches < 1 ||
+        maxLightBatches > 32 ||
+        !Number.isSafeInteger(maxRemBatches) ||
+        maxRemBatches < 1 ||
+        maxRemBatches > 32) {
+        throw new Error('memory_dreaming_limits_invalid');
+    }
+    const now = options.now ?? (() => new Date());
+    const startedAt = now().toISOString();
+    const light = await drain(worker, 'light', maxLightBatches, signal);
+    const rem = await drain(worker, 'rem', maxRemBatches, signal);
+    if (signal.aborted)
+        throw new Error('memory_dreaming_aborted');
+    const deep = await worker.processDeep(signal);
+    if (signal.aborted)
+        throw new Error('memory_dreaming_aborted');
+    if (failed(deep.status))
+        throw new Error('memory_dreaming_deep_failed');
+    return {
+        startedAt,
+        completedAt: now().toISOString(),
+        stages: [
+            { stage: 'light', status: light ? 'completed' : 'skipped', processed: light },
+            { stage: 'rem', status: rem ? 'completed' : 'skipped', processed: rem },
+            {
+                stage: 'deep',
+                status: deep.status === 'processed' ? 'completed' : 'skipped',
+                processed: deep.status === 'processed' ? deep.processed : 0,
+            },
+        ],
+    };
+}

package/dist/dreaming/schedule.d.ts

@@ -0,0 +1,3 @@
+/** Returns the next strictly future 03:00 wall-clock instant; startup never catches up a missed run. */
+export declare function nextMemoryDreamingAt(now: number, timezone: string): number;
+export declare function memoryDreamingLocalDateAt(timestamp: number, timezone: string): string;

package/dist/dreaming/schedule.js

@@ -0,0 +1,72 @@
+function localParts(timestamp, timezone) {
+    const formatter = new Intl.DateTimeFormat('en-CA', {
+        timeZone: timezone,
+        calendar: 'iso8601',
+        numberingSystem: 'latn',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+    });
+    const values = new Map(formatter
+        .formatToParts(new Date(timestamp))
+        .filter((part) => part.type !== 'literal')
+        .map((part) => [part.type, Number(part.value)]));
+    const result = {
+        year: values.get('year'),
+        month: values.get('month'),
+        day: values.get('day'),
+        hour: values.get('hour'),
+        minute: values.get('minute'),
+        second: values.get('second'),
+    };
+    if (Object.values(result).some((value) => value === undefined || !Number.isSafeInteger(value))) {
+        throw new Error('memory_dreaming_timezone_invalid');
+    }
+    return result;
+}
+function wallClockToTimestamp(value, timezone) {
+    const target = Date.UTC(value.year, value.month - 1, value.day, value.hour, value.minute, value.second);
+    let timestamp = target;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const actual = localParts(timestamp, timezone);
+        const represented = Date.UTC(actual.year, actual.month - 1, actual.day, actual.hour, actual.minute, actual.second);
+        const delta = target - represented;
+        if (delta === 0)
+            return timestamp;
+        timestamp += delta;
+    }
+    throw new Error('memory_dreaming_local_time_unresolvable');
+}
+function addLocalDays(value, days) {
+    const date = new Date(Date.UTC(value.year, value.month - 1, value.day + days));
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+        hour: value.hour,
+        minute: value.minute,
+        second: value.second,
+    };
+}
+function dateKey(value) {
+    return `${String(value.year).padStart(4, '0')}-${String(value.month).padStart(2, '0')}-${String(value.day).padStart(2, '0')}`;
+}
+/** Returns the next strictly future 03:00 wall-clock instant; startup never catches up a missed run. */
+export function nextMemoryDreamingAt(now, timezone) {
+    if (!Number.isFinite(now))
+        throw new Error('memory_dreaming_clock_invalid');
+    const localNow = localParts(now, timezone);
+    const todayAtThree = wallClockToTimestamp({ ...localNow, hour: 3, minute: 0, second: 0 }, timezone);
+    if (todayAtThree > now)
+        return todayAtThree;
+    return wallClockToTimestamp({ ...addLocalDays(localNow, 1), hour: 3, minute: 0, second: 0 }, timezone);
+}
+export function memoryDreamingLocalDateAt(timestamp, timezone) {
+    if (!Number.isFinite(timestamp))
+        throw new Error('memory_dreaming_clock_invalid');
+    return dateKey(localParts(timestamp, timezone));
+}

package/dist/dreaming/scheduler.d.ts

@@ -0,0 +1,22 @@
+import type { DreamingReport } from '../contracts.js';
+export interface MemoryDreamingSchedulePoint {
+    timezone: string;
+    localDate: string;
+    scheduledAt: Date;
+}
+export interface MemoryDreamingRunStore<TIdentity> {
+    claim(identity: TIdentity): Promise<string | null>;
+    finish(identity: TIdentity, runId: string, status: 'succeeded' | 'failed'): Promise<void>;
+}
+export interface MemoryDreamingSchedulerOptions<TIdentity> {
+    timezone?: string;
+    fallbackTimezone: string;
+    identity(point: MemoryDreamingSchedulePoint): TIdentity;
+    now?: () => number;
+    sleepUntil?: (timestamp: number, signal: AbortSignal) => Promise<void>;
+}
+export interface MemoryDreamingRunner {
+    runDreaming(signal?: AbortSignal): Promise<DreamingReport>;
+}
+/** Single host-process scheduler: one local 03:00 run, durable claim, and next-date retry. */
+export declare function runMemoryDreamingScheduler<TIdentity>(runner: MemoryDreamingRunner, store: MemoryDreamingRunStore<TIdentity>, signal: AbortSignal, onRun: (value: Record<string, unknown>) => void, options: MemoryDreamingSchedulerOptions<TIdentity>): Promise<void>;

package/dist/dreaming/scheduler.js

@@ -0,0 +1,96 @@
+import { memoryDreamingLocalDateAt, nextMemoryDreamingAt } from './schedule.js';
+async function defaultSleepUntil(timestamp, signal) {
+    if (signal.aborted)
+        return;
+    const delay = Math.max(0, timestamp - Date.now());
+    await new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, delay);
+        signal.addEventListener('abort', finish, { once: true });
+    });
+}
+/** Single host-process scheduler: one local 03:00 run, durable claim, and next-date retry. */
+export async function runMemoryDreamingScheduler(runner, store, signal, onRun, options) {
+    const now = options.now ?? Date.now;
+    const sleepUntil = options.sleepUntil ?? defaultSleepUntil;
+    const requestedTimezone = options.timezone?.trim() || options.fallbackTimezone;
+    try {
+        nextMemoryDreamingAt(now(), requestedTimezone);
+    }
+    catch {
+        onRun({ event: 'dreaming_timezone_fallback', timezone: options.fallbackTimezone });
+    }
+    const effectiveTimezone = (() => {
+        try {
+            nextMemoryDreamingAt(now(), requestedTimezone);
+            return requestedTimezone;
+        }
+        catch {
+            return options.fallbackTimezone;
+        }
+    })();
+    while (!signal.aborted) {
+        let scheduledAt;
+        try {
+            scheduledAt = nextMemoryDreamingAt(now(), effectiveTimezone);
+        }
+        catch {
+            onRun({ event: 'dreaming_schedule_failed', status: 'failed' });
+            return;
+        }
+        try {
+            while (!signal.aborted && now() < scheduledAt)
+                await sleepUntil(scheduledAt, signal);
+        }
+        catch {
+            onRun({ event: 'dreaming_schedule_failed', status: 'failed' });
+            return;
+        }
+        if (signal.aborted)
+            return;
+        const identity = options.identity({
+            timezone: effectiveTimezone,
+            localDate: memoryDreamingLocalDateAt(scheduledAt, effectiveTimezone),
+            scheduledAt: new Date(scheduledAt),
+        });
+        let runId;
+        try {
+            runId = await store.claim(identity);
+        }
+        catch {
+            onRun({ event: 'dreaming_run_failed', status: 'failed', errorCode: 'dreaming_claim_failed' });
+            continue;
+        }
+        if (!runId) {
+            onRun({
+                event: 'dreaming_run_skipped',
+                status: 'duplicate',
+                localDate: memoryDreamingLocalDateAt(scheduledAt, effectiveTimezone),
+            });
+            continue;
+        }
+        try {
+            const report = await runner.runDreaming(signal);
+            await store.finish(identity, runId, 'succeeded');
+            onRun({
+                event: 'dreaming_run_completed',
+                status: 'succeeded',
+                localDate: memoryDreamingLocalDateAt(scheduledAt, effectiveTimezone),
+                report,
+            });
+        }
+        catch {
+            await store.finish(identity, runId, 'failed').catch(() => undefined);
+            onRun({
+                event: 'dreaming_run_failed',
+                status: 'failed',
+                localDate: memoryDreamingLocalDateAt(scheduledAt, effectiveTimezone),
+                errorCode: 'dreaming_run_failed',
+            });
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from './contracts.js';
+export * from './plugin.js';
+export * from './runtime.js';
+export * from './ports/index.js';
+export * from './signals.js';
+export * from './dreaming/deep.js';
+export * from './dreaming/candidates.js';
+export * from './dreaming/schedule.js';
+export * from './dreaming/runner.js';
+export * from './dreaming/scheduler.js';
+export * from './recall/search.js';
+export * from './recall/fusion.js';
+export * from './recall/service.js';
+export * from './write/service.js';
+export * from './write/conflicts.js';
+export * from './context/budget.js';
+export * from './context/checkpoint.js';

package/dist/index.js

@@ -0,0 +1,17 @@
+export * from './contracts.js';
+export * from './plugin.js';
+export * from './runtime.js';
+export * from './ports/index.js';
+export * from './signals.js';
+export * from './dreaming/deep.js';
+export * from './dreaming/candidates.js';
+export * from './dreaming/schedule.js';
+export * from './dreaming/runner.js';
+export * from './dreaming/scheduler.js';
+export * from './recall/search.js';
+export * from './recall/fusion.js';
+export * from './recall/service.js';
+export * from './write/service.js';
+export * from './write/conflicts.js';
+export * from './context/budget.js';
+export * from './context/checkpoint.js';

package/dist/plugin.d.ts

@@ -0,0 +1,11 @@
+import type { DreamingReport, ExplicitMemoryWrite, MemoryForgetRequest, MemoryHealth, MemoryObservation, MemoryRecallRequest, MemoryRecallResult, MemoryRetrievedCandidate, MemoryWriteResult } from './contracts.js';
+/** Authorization stays opaque to the generic package and is supplied by the host for each request. */
+export interface AgentMemoryPlugin<TAuthorization = unknown> {
+    observe(authorization: TAuthorization, turn: MemoryObservation): Promise<void>;
+    recall(authorization: TAuthorization, request: MemoryRecallRequest): Promise<MemoryRecallResult>;
+    remember(authorization: TAuthorization, write: ExplicitMemoryWrite): Promise<MemoryWriteResult>;
+    forget(authorization: TAuthorization, request: MemoryForgetRequest): Promise<MemoryWriteResult>;
+    recordUsed(authorization: TAuthorization, query: string, candidates: readonly MemoryRetrievedCandidate[]): Promise<void>;
+    runDreaming(signal?: AbortSignal): Promise<DreamingReport>;
+    health(): Promise<MemoryHealth>;
+}

package/dist/plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/ports/index.d.ts

@@ -0,0 +1,42 @@
+import type { ExplicitMemoryWrite, MemoryEmbeddingBatch, MemoryEmbeddingContract, MemoryEntry, MemoryForgetRequest, MemoryObservation, MemoryPlanningRequest, MemorySearchReason, MemoryUsageSignal, MemoryUsageSignalKind, MemoryWriteResult } from '../contracts.js';
+export interface MemorySearchSources {
+    exact(query: string, limit?: number): Promise<MemoryEntry[]>;
+    lexical(query: string, limit?: number): Promise<MemoryEntry[]>;
+    semantic(query: string, limit?: number): Promise<{
+        matches: MemoryEntry[];
+        reason: MemorySearchReason;
+    }>;
+}
+/** The caller keeps its identity/authorization token opaque to this package. */
+export interface MemoryStoragePort<TAuthorization = unknown> {
+    withAuthorizedSearch<T>(authorization: TAuthorization, work: (sources: MemorySearchSources) => Promise<T>): Promise<T>;
+    observe(authorization: TAuthorization, observation: MemoryObservation): Promise<void>;
+    recordUsageSignals(authorization: TAuthorization, kind: MemoryUsageSignalKind, signals: readonly MemoryUsageSignal[]): Promise<void>;
+    remember(authorization: TAuthorization, write: ExplicitMemoryWrite): Promise<MemoryWriteResult>;
+    forget(authorization: TAuthorization, request: MemoryForgetRequest): Promise<MemoryWriteResult>;
+}
+export interface MemoryModelPort {
+    plan(request: MemoryPlanningRequest, signal: AbortSignal): Promise<readonly unknown[]>;
+}
+export interface MemoryEmbeddingPort {
+    embedMany(values: readonly string[], signal?: AbortSignal): Promise<MemoryEmbeddingBatch>;
+}
+export interface MemoryEmbeddingClient extends MemoryEmbeddingPort {
+    readonly contract: MemoryEmbeddingContract;
+    readonly dailyTokenBudget: number;
+    readonly dailyRequestBudget: number;
+}
+export declare function estimateMemoryEmbeddingTokens(values: readonly string[]): number;
+export interface MemoryClockPort {
+    now(): Date;
+    sleepUntil(deadline: Date, signal: AbortSignal): Promise<void>;
+}
+export interface MemoryLogEvent {
+    event: string;
+    fields?: Readonly<Record<string, string | number | boolean | null>>;
+}
+export interface MemoryLogPort {
+    info(event: MemoryLogEvent): void;
+    warn(event: MemoryLogEvent): void;
+    error(event: MemoryLogEvent): void;
+}

package/dist/ports/index.js

@@ -0,0 +1,3 @@
+export function estimateMemoryEmbeddingTokens(values) {
+    return values.reduce((total, value) => total + Buffer.byteLength(value, 'utf8'), 0);
+}

package/dist/recall/fusion.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEntry, MemoryRecallPolicyOptions, MemoryRetrievedCandidate } from '../contracts.js';
+export declare function fuseMemoryCandidates(query: string, exact: readonly MemoryEntry[], lexical: readonly MemoryEntry[], semantic: readonly MemoryEntry[], options: MemoryRecallPolicyOptions, now?: Date): MemoryRetrievedCandidate[];

package/dist/recall/fusion.js

@@ -0,0 +1,96 @@
+import { memorySearchTokens, normalizeMemoryKey } from './search.js';
+const RRF_K = 60;
+function lexicalOverlap(entry, query) {
+    const normalized = query.normalize('NFC').trim().toLocaleLowerCase('en-US');
+    const haystack = `${entry.key} ${entry.content}`.normalize('NFC').toLocaleLowerCase('en-US');
+    if (haystack.includes(normalized))
+        return 1;
+    const tokens = memorySearchTokens(normalized);
+    if (!tokens.length)
+        return 0;
+    return tokens.filter((token) => haystack.includes(token)).length / tokens.length;
+}
+function sourceReliability(entry) {
+    const declared = Number.isFinite(entry.sourceReliability)
+        ? Math.min(1, Math.max(0, entry.sourceReliability / 100))
+        : 0;
+    const sourceCap = {
+        trusted_ingress: 0.85,
+        user_confirmed: 0.98,
+        system_verified: 1,
+        unknown: 0,
+    };
+    return Math.min(declared, sourceCap[entry.sourceKind]);
+}
+function freshness(entry, nowMs) {
+    const updatedAt = Date.parse(entry.updatedAt);
+    if (!Number.isFinite(updatedAt))
+        return 0.7;
+    const ageDays = Math.max(0, (nowMs - updatedAt) / 86_400_000);
+    return 0.7 + 0.3 * Math.exp(-ageDays / 1_825);
+}
+function addRanked(candidates, entry, source, rank, weight, reason, nowMs, quality = 1) {
+    if (entry.sourceKind === 'unknown' ||
+        (entry.validUntil && Date.parse(entry.validUntil) <= nowMs) ||
+        !entry.content ||
+        !Number.isSafeInteger(entry.revision) ||
+        entry.revision < 1)
+        return;
+    const normalizedKey = normalizeMemoryKey(entry.key);
+    if (!normalizedKey)
+        return;
+    const candidateKey = `${normalizedKey}\0${entry.revision}`;
+    let candidate = candidates.get(candidateKey);
+    if (!candidate) {
+        candidate = { entry, score: 0, sources: new Set(), reasons: new Set() };
+        candidates.set(candidateKey, candidate);
+    }
+    candidate.score +=
+        ((weight * quality) / (RRF_K + rank)) * sourceReliability(entry) * freshness(entry, nowMs);
+    candidate.sources.add(source);
+    candidate.reasons.add(reason);
+}
+export function fuseMemoryCandidates(query, exact, lexical, semantic, options, now = new Date()) {
+    const nowMs = now.getTime();
+    const ranked = new Map();
+    exact.forEach((entry, index) => addRanked(ranked, entry, 'exact', index + 1, 4, 'exact_key_or_content_match', nowMs));
+    lexical.forEach((entry, index) => {
+        const overlap = lexicalOverlap(entry, query);
+        if (overlap >= 0.2)
+            addRanked(ranked, entry, 'lexical', index + 1, 1, `lexical_overlap_${overlap.toFixed(2)}`, nowMs, overlap);
+    });
+    semantic.forEach((entry, index) => {
+        const similarity = entry.semanticSimilarity;
+        if (similarity !== undefined && similarity >= options.semanticSimilarityThreshold) {
+            addRanked(ranked, entry, 'semantic', index + 1, 1.5, `cosine_similarity_${similarity.toFixed(3)}`, nowMs, similarity);
+        }
+    });
+    const newestByKey = new Map();
+    for (const candidate of ranked.values()) {
+        const key = normalizeMemoryKey(candidate.entry.key);
+        const previous = newestByKey.get(key);
+        if (!previous ||
+            candidate.entry.revision > previous.entry.revision ||
+            (candidate.entry.revision === previous.entry.revision && candidate.score > previous.score)) {
+            newestByKey.set(key, candidate);
+        }
+    }
+    return [...newestByKey.values()]
+        .filter((candidate) => candidate.sources.has('exact') || candidate.score >= options.minimumScore)
+        .sort((left, right) => right.score - left.score ||
+        right.entry.revision - left.entry.revision ||
+        left.entry.key.localeCompare(right.entry.key))
+        .slice(0, options.topK)
+        .map((candidate) => ({
+        canonicalKey: normalizeMemoryKey(candidate.entry.key),
+        key: candidate.entry.key,
+        content: candidate.entry.content,
+        revision: candidate.entry.revision,
+        updatedAt: candidate.entry.updatedAt,
+        sourceEventId: candidate.entry.sourceEventId,
+        sourceKind: candidate.entry.sourceKind,
+        score: candidate.score,
+        sources: [...candidate.sources].sort(),
+        reasons: [...candidate.reasons].sort(),
+    }));
+}

package/dist/recall/search.d.ts

@@ -0,0 +1,12 @@
+import type { MemoryDraft, MemoryEntry } from '../contracts.js';
+export declare const MAX_MEMORY_RESULTS = 24;
+export declare class MemoryPolicyError extends Error {
+    readonly code: 'input_invalid' | 'limit_invalid';
+    constructor(code: 'input_invalid' | 'limit_invalid');
+}
+export declare function normalizeMemoryKey(value: string): string;
+export declare function canonicalizeMemoryKey(value: string): string;
+export declare function validateMemoryDraft(input: MemoryDraft): MemoryDraft;
+/** Bounded script-aware terms used by the lexical candidate and fallback policies. */
+export declare function memorySearchTokens(query: string): string[];
+export declare function rankMemoryEntries<T extends MemoryEntry>(entries: readonly T[], query: string, limit?: number): T[];

package/dist/recall/search.js

@@ -0,0 +1,81 @@
+export const MAX_MEMORY_RESULTS = 24;
+export class MemoryPolicyError extends Error {
+    code;
+    constructor(code) {
+        super(`memory_${code}`);
+        this.code = code;
+        this.name = 'MemoryPolicyError';
+    }
+}
+function boundedText(value, max, emojiSequence = false) {
+    if (typeof value !== 'string')
+        throw new MemoryPolicyError('input_invalid');
+    const text = value.normalize('NFC').trim();
+    if (!text || text.length > max || /[\p{Cc}\p{Cs}]/u.test(text))
+        throw new MemoryPolicyError('input_invalid');
+    for (let i = 0; i < text.length; i += 1) {
+        if (!/\p{Cf}/u.test(text[i]))
+            continue;
+        if (!emojiSequence ||
+            text[i] !== '\u200d' ||
+            !/\p{Extended_Pictographic}(?:\p{Emoji_Modifier}|\uFE0F)?$/u.test(text.slice(0, i)) ||
+            !/^\p{Extended_Pictographic}/u.test(text.slice(i + 1)))
+            throw new MemoryPolicyError('input_invalid');
+    }
+    return text;
+}
+export function normalizeMemoryKey(value) {
+    return value
+        .normalize('NFKC')
+        .trim()
+        .toLocaleLowerCase('en-US')
+        .replace(/[^\p{L}\p{N}]+/gu, '_')
+        .replace(/^_+|_+$/gu, '');
+}
+export function canonicalizeMemoryKey(value) {
+    const normalized = normalizeMemoryKey(boundedText(value, 96));
+    if (!normalized || normalized.length > 96)
+        throw new MemoryPolicyError('input_invalid');
+    return normalized;
+}
+export function validateMemoryDraft(input) {
+    return {
+        key: canonicalizeMemoryKey(input.key),
+        content: boundedText(input.content, 800, true),
+    };
+}
+/** Bounded script-aware terms used by the lexical candidate and fallback policies. */
+export function memorySearchTokens(query) {
+    const normalized = boundedText(query, 240, true).toLocaleLowerCase('en-US');
+    const tokens = [];
+    for (const match of normalized.matchAll(/[\p{L}\p{N}]+/gu)) {
+        for (const chunk of match[0].match(/\p{Script=Han}+|[^\p{Script=Han}]+/gu) ?? []) {
+            if (/^\p{Script=Han}+$/u.test(chunk)) {
+                const chars = Array.from(chunk);
+                for (let index = 0; index + 1 < chars.length; index += 1)
+                    tokens.push(chars[index] + chars[index + 1]);
+            }
+            else if (chunk.length > 1)
+                tokens.push(chunk);
+        }
+    }
+    return [...new Set(tokens)].slice(0, 240);
+}
+export function rankMemoryEntries(entries, query, limit = 8) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_MEMORY_RESULTS)
+        throw new MemoryPolicyError('limit_invalid');
+    const search = boundedText(query, 240, true).toLocaleLowerCase('en-US');
+    const words = memorySearchTokens(search);
+    return entries
+        .map((item, index) => {
+        const haystack = (item.key + ' ' + item.content).toLocaleLowerCase('en-US');
+        const score = haystack.includes(search)
+            ? 1000
+            : words.reduce((value, word) => value + (haystack.includes(word) ? 1 : 0), 0);
+        return { item, index, score };
+    })
+        .filter((match) => match.score > 0)
+        .sort((a, b) => b.score - a.score || a.index - b.index)
+        .slice(0, limit)
+        .map((match) => match.item);
+}

package/dist/recall/service.d.ts

@@ -0,0 +1,26 @@
+import type { MemoryRecallPolicyOptions, MemoryRecallResult, MemoryRetrievedCandidate, MemoryRetrievalMetric, MemoryUsageSignal, MemoryUsageSignalKind } from '../contracts.js';
+import type { MemorySearchSources } from '../ports/index.js';
+export interface MemoryRecallStoragePort<TAuthorization> {
+    withAuthorizedSearch<T>(authorization: TAuthorization, work: (sources: MemorySearchSources) => Promise<T>): Promise<T>;
+    recordUsageSignals(authorization: TAuthorization, kind: MemoryUsageSignalKind, signals: readonly MemoryUsageSignal[]): Promise<void>;
+}
+export interface MemoryRecallServiceOptions extends Partial<MemoryRecallPolicyOptions> {
+    candidateLimit?: number;
+    now?: () => number;
+    renderContext?: (candidates: readonly MemoryRetrievedCandidate[]) => string | null;
+    onMetric?: (metric: MemoryRetrievalMetric) => void;
+}
+/** Generic authorization-fenced recall orchestration; the host supplies scoped storage and rendering. */
+export declare class MemoryRecallService<TAuthorization> {
+    private readonly storage;
+    private readonly options;
+    private readonly topK;
+    private readonly candidateLimit;
+    private readonly semanticSimilarityThreshold;
+    private readonly minimumScore;
+    private readonly now;
+    constructor(storage: MemoryRecallStoragePort<TAuthorization>, options?: MemoryRecallServiceOptions);
+    private report;
+    recall(authorization: TAuthorization, query: string, limit?: number): Promise<MemoryRecallResult>;
+    recordUsed(authorization: TAuthorization, query: string, candidates: readonly MemoryRetrievedCandidate[]): Promise<void>;
+}