@abot-ai/runtime 1.0.0 → 1.2.0

package/dist/src/runtime/long-term-memory/onboarding/configuration.js

@@ -0,0 +1,92 @@
+import { isRecord } from "../../config/utils.js";
+export const DEFAULT_MEMORY_EMBEDDING_PROFILE_ID = "memory-embedding";
+export function projectOnboardingStatus(config) {
+    const memory = isRecord(config.longTermMemory) ? config.longTermMemory : {};
+    const profileId = readText(memory.embeddingProfileId);
+    const embeddingProfiles = readEmbeddingProfiles(config);
+    const profile = profileId ? embeddingProfiles[profileId] : undefined;
+    const providerId = isRecord(profile) ? readText(profile.provider) : undefined;
+    const model = isRecord(profile) ? readText(profile.model) : undefined;
+    return Object.freeze({
+        enabled: memory.enabled === true,
+        emitClientEvents: memory.emitClientEvents === true,
+        providers: listConfiguredProviders(config),
+        ...(profileId ? { profileId } : {}),
+        ...(providerId ? { providerId } : {}),
+        ...(model ? { model } : {}),
+    });
+}
+export function buildEnabledMemoryConfig(params) {
+    const models = isRecord(params.config.models) ? params.config.models : {};
+    const profiles = readEmbeddingProfiles(params.config);
+    const existingProfile = profiles[params.profileId];
+    const existingOptions = readMatchingProfileOptions({
+        profile: existingProfile,
+        providerId: params.providerId,
+        model: params.model,
+    });
+    return {
+        ...params.config,
+        models: {
+            ...models,
+            embeddingProfiles: {
+                ...profiles,
+                [params.profileId]: {
+                    label: "Long-term memory embeddings",
+                    provider: params.providerId,
+                    model: params.model,
+                    ...(existingOptions ? { options: existingOptions } : {}),
+                },
+            },
+        },
+        longTermMemory: {
+            enabled: true,
+            emitClientEvents: params.emitClientEvents,
+            embeddingProfileId: params.profileId,
+        },
+    };
+}
+function readMatchingProfileOptions(params) {
+    if (!isRecord(params.profile)) {
+        return undefined;
+    }
+    const targetsMatchExactly = params.profile.provider === params.providerId &&
+        params.profile.model === params.model;
+    if (!targetsMatchExactly || !isRecord(params.profile.options)) {
+        return undefined;
+    }
+    return params.profile.options;
+}
+export function buildDisabledMemoryConfig(config) {
+    const current = isRecord(config.longTermMemory) ? config.longTermMemory : {};
+    return {
+        ...config,
+        longTermMemory: {
+            ...current,
+            enabled: false,
+        },
+    };
+}
+export function listConfiguredProviders(config) {
+    const models = isRecord(config.models) ? config.models : {};
+    const providers = isRecord(models.providers) ? models.providers : {};
+    return Object.freeze(Object.entries(providers)
+        .flatMap(([id, value]) => {
+        const type = isRecord(value) ? readText(value.type) : undefined;
+        return type ? [{ id, type }] : [];
+    })
+        .sort((left, right) => left.id.localeCompare(right.id)));
+}
+export function requireConfiguredProvider(config, providerId) {
+    const found = listConfiguredProviders(config).some((provider) => provider.id === providerId);
+    if (!found) {
+        throw new Error(`long_term_memory_provider_not_configured:${providerId}`);
+    }
+}
+function readEmbeddingProfiles(config) {
+    const models = isRecord(config.models) ? config.models : {};
+    return isRecord(models.embeddingProfiles) ? models.embeddingProfiles : {};
+}
+function readText(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/dist/src/runtime/long-term-memory/onboarding/contracts.d.ts

@@ -0,0 +1,52 @@
+import type { RuntimeConfigFile } from "../../config/types.js";
+export type LongTermMemoryOnboardingProvider = Readonly<{
+    id: string;
+    type: string;
+}>;
+export type LongTermMemoryOnboardingStatus = Readonly<{
+    enabled: boolean;
+    emitClientEvents: boolean;
+    profileId?: string;
+    providerId?: string;
+    model?: string;
+    providers: readonly LongTermMemoryOnboardingProvider[];
+}>;
+export type LongTermMemoryOnboardingResult = Readonly<{
+    status: LongTermMemoryOnboardingStatus;
+    restartRequired: boolean;
+    configPath: string;
+    backupPath?: string;
+    probe?: Readonly<{
+        modelFingerprint: string;
+        dimensions: number;
+    }>;
+}>;
+export type LongTermMemoryOnboardingConfigSnapshot = Readonly<{
+    config: RuntimeConfigFile;
+    path: string;
+}>;
+export type LongTermMemoryOnboardingConfigRepository = Readonly<{
+    read(): Promise<LongTermMemoryOnboardingConfigSnapshot>;
+    write(config: RuntimeConfigFile, expectedConfig?: RuntimeConfigFile): Promise<Readonly<{
+        configPath: string;
+        backupPath?: string;
+    }>>;
+}>;
+export type LongTermMemoryOnboardingService = Readonly<{
+    status(): Promise<LongTermMemoryOnboardingStatus>;
+    discover(input: Readonly<{
+        providerId: string;
+        abortSignal?: AbortSignal;
+    }>): Promise<Readonly<{
+        supported: boolean;
+        models: readonly string[];
+    }>>;
+    enable(input: Readonly<{
+        providerId: string;
+        model: string;
+        profileId?: string;
+        emitClientEvents?: boolean;
+        abortSignal?: AbortSignal;
+    }>): Promise<LongTermMemoryOnboardingResult>;
+    disable(): Promise<LongTermMemoryOnboardingResult>;
+}>;

package/dist/src/runtime/long-term-memory/onboarding/contracts.js

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

package/dist/src/runtime/long-term-memory/onboarding/service.d.ts

@@ -0,0 +1,21 @@
+import type { ModelGatewayPolicyConfig } from "../../../model-gateway/types.js";
+import type { LongTermMemoryOnboardingConfigRepository, LongTermMemoryOnboardingService } from "./contracts.js";
+export declare function createLongTermMemoryOnboardingService(dependencies: {
+    repository: LongTermMemoryOnboardingConfigRepository;
+    probe(input: Readonly<{
+        profileId: string;
+        modelPolicy: ModelGatewayPolicyConfig;
+        abortSignal: AbortSignal;
+    }>): Promise<Readonly<{
+        modelFingerprint: string;
+        dimensions: number;
+    }>>;
+    discover(input: Readonly<{
+        providerId: string;
+        modelPolicy: ModelGatewayPolicyConfig;
+        abortSignal: AbortSignal;
+    }>): Promise<Readonly<{
+        supported: boolean;
+        models: readonly string[];
+    }>>;
+}): LongTermMemoryOnboardingService;

package/dist/src/runtime/long-term-memory/onboarding/service.js

@@ -0,0 +1,88 @@
+import { buildModelConfig } from "../../config/builders.js";
+import { validateRuntimeConfigFile } from "../../config/validation.js";
+import { buildDisabledMemoryConfig, buildEnabledMemoryConfig, DEFAULT_MEMORY_EMBEDDING_PROFILE_ID, projectOnboardingStatus, requireConfiguredProvider, } from "./configuration.js";
+const PROFILE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+export function createLongTermMemoryOnboardingService(dependencies) {
+    return Object.freeze({
+        async status() {
+            const snapshot = await dependencies.repository.read();
+            return projectOnboardingStatus(snapshot.config);
+        },
+        async discover(input) {
+            const snapshot = await dependencies.repository.read();
+            const providerId = requireText(input.providerId, "providerId");
+            const abortSignal = input.abortSignal ?? new AbortController().signal;
+            abortSignal.throwIfAborted();
+            requireConfiguredProvider(snapshot.config, providerId);
+            return dependencies.discover({
+                providerId,
+                modelPolicy: requireModelPolicy(snapshot.config, snapshot.path),
+                abortSignal,
+            });
+        },
+        async enable(input) {
+            const snapshot = await dependencies.repository.read();
+            const providerId = requireText(input.providerId, "providerId");
+            const model = requireText(input.model, "model");
+            const profileId = readProfileId(input.profileId);
+            const abortSignal = input.abortSignal ?? new AbortController().signal;
+            abortSignal.throwIfAborted();
+            requireConfiguredProvider(snapshot.config, providerId);
+            const candidate = buildEnabledMemoryConfig({
+                config: snapshot.config,
+                providerId,
+                model,
+                profileId,
+                emitClientEvents: input.emitClientEvents === true,
+            });
+            validateRuntimeConfigFile(candidate, snapshot.path);
+            const probe = await dependencies.probe({
+                profileId,
+                modelPolicy: requireModelPolicy(candidate, snapshot.path),
+                abortSignal,
+            });
+            abortSignal.throwIfAborted();
+            const persisted = await dependencies.repository.write(candidate, snapshot.config);
+            return Object.freeze({
+                status: projectOnboardingStatus(candidate),
+                restartRequired: true,
+                configPath: persisted.configPath,
+                ...(persisted.backupPath ? { backupPath: persisted.backupPath } : {}),
+                probe: Object.freeze({ ...probe }),
+            });
+        },
+        async disable() {
+            const snapshot = await dependencies.repository.read();
+            const candidate = buildDisabledMemoryConfig(snapshot.config);
+            validateRuntimeConfigFile(candidate, snapshot.path);
+            const persisted = await dependencies.repository.write(candidate, snapshot.config);
+            return Object.freeze({
+                status: projectOnboardingStatus(candidate),
+                restartRequired: true,
+                configPath: persisted.configPath,
+                ...(persisted.backupPath ? { backupPath: persisted.backupPath } : {}),
+            });
+        },
+    });
+}
+function requireModelPolicy(config, configPath) {
+    const modelPolicy = buildModelConfig(config, { mainConfigPath: configPath });
+    if (!modelPolicy) {
+        throw new Error("long_term_memory_model_policy_required");
+    }
+    return modelPolicy;
+}
+function readProfileId(value) {
+    const profileId = value?.trim() || DEFAULT_MEMORY_EMBEDDING_PROFILE_ID;
+    if (!PROFILE_ID_PATTERN.test(profileId)) {
+        throw new Error("long_term_memory_embedding_profile_id_invalid");
+    }
+    return profileId;
+}
+function requireText(value, field) {
+    const normalized = value.trim();
+    if (!normalized) {
+        throw new Error(`long_term_memory_${field}_required`);
+    }
+    return normalized;
+}

package/dist/src/runtime/long-term-memory/policies/normalization.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryCandidate } from "../contracts.js";
+export declare const MAX_MEMORY_CONTENT_CHARACTERS = 4000;
+export declare const MAX_MEMORY_ID_CHARACTERS = 128;
+export declare const MAX_MEMORY_TAGS = 12;
+export declare const MAX_MEMORY_TAG_CHARACTERS = 64;
+export declare function normalizeMemoryCandidate(candidate: MemoryCandidate): MemoryCandidate | undefined;
+export declare function normalizeMemoryText(value: string): string;
+export declare function normalizeMemoryIdentifier(value: unknown): string | undefined;
+export declare function isMemoryCandidateWithinLimits(candidate: MemoryCandidate): boolean;
+export declare function mergeMemoryTags(left: readonly string[], right: readonly string[]): readonly string[];

package/dist/src/runtime/long-term-memory/policies/normalization.js

@@ -0,0 +1,45 @@
+export const MAX_MEMORY_CONTENT_CHARACTERS = 4_000;
+export const MAX_MEMORY_ID_CHARACTERS = 128;
+export const MAX_MEMORY_TAGS = 12;
+export const MAX_MEMORY_TAG_CHARACTERS = 64;
+export function normalizeMemoryCandidate(candidate) {
+    const content = normalizeWhitespace(candidate.content).slice(0, MAX_MEMORY_CONTENT_CHARACTERS);
+    if (!content) {
+        return undefined;
+    }
+    const tags = normalizeTags(candidate.tags);
+    return Object.freeze({ content, tags });
+}
+export function normalizeMemoryText(value) {
+    return normalizeWhitespace(value).toLocaleLowerCase("und");
+}
+export function normalizeMemoryIdentifier(value) {
+    const id = typeof value === "string" ? value.trim() : "";
+    return id && id.length <= MAX_MEMORY_ID_CHARACTERS ? id : undefined;
+}
+export function isMemoryCandidateWithinLimits(candidate) {
+    if (candidate.tags.some((tag) => typeof tag !== "string")) {
+        return false;
+    }
+    const content = normalizeWhitespace(candidate.content);
+    const tags = candidate.tags
+        .map((tag) => normalizeWhitespace(tag).toLocaleLowerCase("und"))
+        .filter(Boolean);
+    return (content.length <= MAX_MEMORY_CONTENT_CHARACTERS &&
+        tags.every((tag) => tag.length <= MAX_MEMORY_TAG_CHARACTERS) &&
+        new Set(tags).size <= MAX_MEMORY_TAGS);
+}
+export function mergeMemoryTags(left, right) {
+    return normalizeTags([...left, ...right]);
+}
+function normalizeTags(tags) {
+    const normalized = tags
+        .filter((tag) => typeof tag === "string")
+        .map((tag) => normalizeWhitespace(tag).toLocaleLowerCase("und"))
+        .filter(Boolean)
+        .map((tag) => tag.slice(0, MAX_MEMORY_TAG_CHARACTERS));
+    return Object.freeze([...new Set(normalized)].slice(0, MAX_MEMORY_TAGS));
+}
+function normalizeWhitespace(value) {
+    return value.replace(/\s+/gu, " ").trim();
+}

package/dist/src/runtime/long-term-memory/policies/reconciliation.d.ts

@@ -0,0 +1,20 @@
+import type { MemoryCandidate } from "../contracts.js";
+export type SemanticMemoryNeighbor = Readonly<{
+    memoryId: string;
+    similarity: number;
+}>;
+/**
+ * Version one deliberately never treats similarity as proof of identity or
+ * contradiction. The neighbor is retained only as a testable policy input.
+ */
+export declare function reconcileMemoryCandidate(params: {
+    candidate: MemoryCandidate;
+    vector: readonly number[];
+    existingVectors: readonly Readonly<{
+        memoryId: string;
+        vector: readonly number[];
+    }>[];
+}): Readonly<{
+    action: "accept_distinct";
+    nearestNeighbor?: SemanticMemoryNeighbor;
+}>;

package/dist/src/runtime/long-term-memory/policies/reconciliation.js

@@ -0,0 +1,21 @@
+import { cosineSimilarity } from "./scoring.js";
+/**
+ * Version one deliberately never treats similarity as proof of identity or
+ * contradiction. The neighbor is retained only as a testable policy input.
+ */
+export function reconcileMemoryCandidate(params) {
+    let nearestNeighbor;
+    for (const existing of params.existingVectors) {
+        const similarity = cosineSimilarity(params.vector, existing.vector);
+        if (!nearestNeighbor || similarity > nearestNeighbor.similarity) {
+            nearestNeighbor = Object.freeze({
+                memoryId: existing.memoryId,
+                similarity,
+            });
+        }
+    }
+    return Object.freeze({
+        action: "accept_distinct",
+        ...(nearestNeighbor ? { nearestNeighbor } : {}),
+    });
+}

package/dist/src/runtime/long-term-memory/policies/scoring.d.ts

@@ -0,0 +1,13 @@
+import type { LongTermMemoryRecord } from "../contracts.js";
+export type ScoredMemory = Readonly<{
+    record: LongTermMemoryRecord;
+    score: number;
+}>;
+export declare function scoreMemory(params: {
+    record: LongTermMemoryRecord;
+    query: string;
+    queryVector: readonly number[];
+    memoryVector: readonly number[];
+    newestTimestampMs: number;
+}): ScoredMemory | undefined;
+export declare function cosineSimilarity(left: readonly number[], right: readonly number[]): number;

package/dist/src/runtime/long-term-memory/policies/scoring.js

@@ -0,0 +1,55 @@
+const MINIMUM_COSINE_SIMILARITY = 0.25;
+const MINIMUM_RELEVANCE_SCORE = 0.4;
+export function scoreMemory(params) {
+    const cosine = cosineSimilarity(params.queryVector, params.memoryVector);
+    if (cosine < MINIMUM_COSINE_SIMILARITY) {
+        return undefined;
+    }
+    const lexical = lexicalOverlap(params.query, `${params.record.content} ${params.record.tags.join(" ")}`);
+    const recency = recencyTieBreaker(Date.parse(params.record.updatedAt), params.newestTimestampMs);
+    const score = cosine * 0.86 + lexical * 0.12 + recency * 0.02;
+    return score >= MINIMUM_RELEVANCE_SCORE
+        ? Object.freeze({ record: params.record, score })
+        : undefined;
+}
+export function cosineSimilarity(left, right) {
+    if (left.length === 0 || left.length !== right.length) {
+        return -1;
+    }
+    let dot = 0;
+    let leftMagnitude = 0;
+    let rightMagnitude = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        const leftValue = left[index];
+        const rightValue = right[index];
+        dot += leftValue * rightValue;
+        leftMagnitude += leftValue * leftValue;
+        rightMagnitude += rightValue * rightValue;
+    }
+    const divisor = Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude);
+    return divisor > 0 ? dot / divisor : -1;
+}
+function lexicalOverlap(query, candidate) {
+    const queryTerms = tokenize(query);
+    if (queryTerms.size === 0) {
+        return 0;
+    }
+    const candidateTerms = tokenize(candidate);
+    let matches = 0;
+    for (const term of queryTerms) {
+        if (candidateTerms.has(term)) {
+            matches += 1;
+        }
+    }
+    return matches / queryTerms.size;
+}
+function tokenize(value) {
+    return new Set((value.toLocaleLowerCase("und").match(/[\p{L}\p{N}]+/gu) ?? []).filter((term) => term.length > 1));
+}
+function recencyTieBreaker(timestampMs, newestTimestampMs) {
+    if (!Number.isFinite(timestampMs) || newestTimestampMs <= 0) {
+        return 0;
+    }
+    const ageDays = Math.max(0, newestTimestampMs - timestampMs) / 86_400_000;
+    return 1 / (1 + ageDays / 365);
+}

package/dist/src/runtime/long-term-memory/policies/sensitive-data.d.ts

@@ -0,0 +1,5 @@
+export declare function containsSensitiveMemoryData(content: string): boolean;
+export declare function containsSensitiveMemoryCandidateData(candidate: Readonly<{
+    content: string;
+    tags: readonly string[];
+}>): boolean;

package/dist/src/runtime/long-term-memory/policies/sensitive-data.js

@@ -0,0 +1,12 @@
+const PRIVATE_KEY_MARKER = /-----BEGIN [A-Z ]*PRIVATE KEY-----/iu;
+const LABELED_SECRET = /\b(?:password|passwd|api[_ -]?key|access[_ -]?token|refresh[_ -]?token|recovery[_ -]?code|client[_ -]?secret)\b\s*[:=]\s*\S+/iu;
+const COMMON_TOKEN = /\b(?:sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{20,})\b/u;
+export function containsSensitiveMemoryData(content) {
+    return (PRIVATE_KEY_MARKER.test(content) ||
+        LABELED_SECRET.test(content) ||
+        COMMON_TOKEN.test(content));
+}
+export function containsSensitiveMemoryCandidateData(candidate) {
+    return (containsSensitiveMemoryData(candidate.content) ||
+        candidate.tags.some(containsSensitiveMemoryData));
+}

package/dist/src/runtime/long-term-memory/projection.d.ts

@@ -0,0 +1,4 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { LongTermMemoryRecord } from "./contracts.js";
+export declare const LONG_TERM_MEMORY_MESSAGE_KIND: "runtime_long_term_memory_reference_v1";
+export declare function projectLongTermMemoryMessage(rankedRecords: readonly LongTermMemoryRecord[]): ChatMessage | undefined;

package/dist/src/runtime/long-term-memory/projection.js

@@ -0,0 +1,39 @@
+export const LONG_TERM_MEMORY_MESSAGE_KIND = "runtime_long_term_memory_reference_v1";
+const MAX_PROJECTED_MEMORIES = 6;
+const MAX_PROJECTED_CHARACTERS = 6_000;
+export function projectLongTermMemoryMessage(rankedRecords) {
+    const projection = selectWithinBudget(rankedRecords);
+    if (!projection) {
+        return undefined;
+    }
+    return Object.freeze({
+        role: "system",
+        content: projection.serialized,
+    });
+}
+function selectWithinBudget(records) {
+    const selected = [];
+    let serialized;
+    for (const record of records) {
+        const exceedsCount = selected.length >= MAX_PROJECTED_MEMORIES;
+        if (exceedsCount) {
+            break;
+        }
+        const candidate = serializeProjection([...selected, record]);
+        if (candidate.length > MAX_PROJECTED_CHARACTERS) {
+            continue;
+        }
+        selected.push(record);
+        serialized = candidate;
+    }
+    return serialized ? Object.freeze({ serialized }) : undefined;
+}
+function serializeProjection(records) {
+    return JSON.stringify({
+        kind: LONG_TERM_MEMORY_MESSAGE_KIND,
+        authority: "passive_reference",
+        purpose: "support_personalized_terminal_response_authoring",
+        memories: records.map(({ content, tags }) => ({ content, tags })),
+        presenceEffect: "reference_only_not_current_user_intent_assignment_action_authority_or_completion_evidence",
+    });
+}

package/dist/src/runtime/long-term-memory/ranked-search.d.ts

@@ -0,0 +1,11 @@
+import type { LongTermMemoryEmbeddingClient, LongTermMemoryRepository } from "./contracts.js";
+import { type ScoredMemory } from "./policies/scoring.js";
+export declare function searchRankedLongTermMemories(params: {
+    repository: LongTermMemoryRepository;
+    embeddings: LongTermMemoryEmbeddingClient;
+    query: string;
+    context: Readonly<{
+        abortSignal: AbortSignal;
+        debugRequestId?: string;
+    }>;
+}): Promise<readonly ScoredMemory[]>;

package/dist/src/runtime/long-term-memory/ranked-search.js

@@ -0,0 +1,111 @@
+import { embedLongTermMemoryTexts } from "./embedding-batches.js";
+import { scoreMemory } from "./policies/scoring.js";
+export async function searchRankedLongTermMemories(params) {
+    params.context.abortSignal.throwIfAborted();
+    const query = params.query.trim();
+    const snapshot = await params.repository.read();
+    if (!query || snapshot.records.length === 0) {
+        return Object.freeze([]);
+    }
+    const queryEmbedding = await embedLongTermMemoryTexts({
+        embeddings: params.embeddings,
+        texts: [query],
+        abortSignal: params.context.abortSignal,
+        ...(params.context.debugRequestId
+            ? { debugRequestId: params.context.debugRequestId }
+            : {}),
+    });
+    params.context.abortSignal.throwIfAborted();
+    const indexedSnapshot = await ensureCurrentVectorIndex({
+        repository: params.repository,
+        embeddings: params.embeddings,
+        snapshot,
+        modelFingerprint: queryEmbedding.modelFingerprint,
+        dimensions: queryEmbedding.dimensions,
+        context: params.context,
+    });
+    return rankSnapshot({
+        snapshot: indexedSnapshot,
+        query,
+        queryVector: queryEmbedding.vectors[0],
+        modelFingerprint: queryEmbedding.modelFingerprint,
+        dimensions: queryEmbedding.dimensions,
+    });
+}
+async function ensureCurrentVectorIndex(params) {
+    const currentEntries = selectCurrentEntries(params);
+    const indexedIds = new Set(currentEntries.map(({ memoryId }) => memoryId));
+    const missing = params.snapshot.records.filter((record) => !indexedIds.has(record.id));
+    if (missing.length === 0) {
+        return params.snapshot;
+    }
+    const additions = await embedMissingRecords({ ...params, missing });
+    return params.repository.update((current) => ({
+        records: current.records,
+        vectors: mergeCurrentVectorIndex({
+            snapshot: current,
+            modelFingerprint: params.modelFingerprint,
+            dimensions: params.dimensions,
+            additions,
+        }),
+    }));
+}
+async function embedMissingRecords(params) {
+    const embedded = await embedLongTermMemoryTexts({
+        embeddings: params.embeddings,
+        texts: params.missing.map(({ content }) => content),
+        abortSignal: params.context.abortSignal,
+        ...(params.context.debugRequestId
+            ? { debugRequestId: params.context.debugRequestId }
+            : {}),
+        expectedBinding: {
+            modelFingerprint: params.modelFingerprint,
+            dimensions: params.dimensions,
+        },
+    });
+    return Object.freeze(params.missing.map((record, index) => Object.freeze({
+        entry: Object.freeze({
+            memoryId: record.id,
+            modelFingerprint: params.modelFingerprint,
+            dimensions: params.dimensions,
+            vector: embedded.vectors[index],
+        }),
+        sourceContent: record.content,
+    })));
+}
+function selectCurrentEntries(params) {
+    return params.snapshot.vectors.filter((entry) => entry.modelFingerprint === params.modelFingerprint &&
+        entry.dimensions === params.dimensions);
+}
+function mergeCurrentVectorIndex(params) {
+    const recordsById = new Map(params.snapshot.records.map((record) => [record.id, record]));
+    const applicableAdditions = params.additions.filter((addition) => matchesEmbeddingSource(recordsById.get(addition.entry.memoryId), addition));
+    const additionsById = new Map(applicableAdditions.map(({ entry }) => [entry.memoryId, entry]));
+    const retained = selectCurrentEntries(params).filter((entry) => recordsById.has(entry.memoryId) && !additionsById.has(entry.memoryId));
+    return Object.freeze([
+        ...retained,
+        ...applicableAdditions.map(({ entry }) => entry),
+    ]);
+}
+function matchesEmbeddingSource(record, addition) {
+    return record?.content === addition.sourceContent;
+}
+function rankSnapshot(params) {
+    const vectors = new Map(selectCurrentEntries(params).map((entry) => [entry.memoryId, entry.vector]));
+    const newestTimestampMs = Math.max(0, ...params.snapshot.records.map(({ updatedAt }) => Date.parse(updatedAt)));
+    return Object.freeze(params.snapshot.records
+        .map((record) => {
+        const memoryVector = vectors.get(record.id);
+        return memoryVector
+            ? scoreMemory({
+                record,
+                query: params.query,
+                queryVector: params.queryVector,
+                memoryVector,
+                newestTimestampMs,
+            })
+            : undefined;
+    })
+        .filter((entry) => entry !== undefined)
+        .sort((left, right) => right.score - left.score));
+}

package/dist/src/runtime/long-term-memory/repository-state.d.ts

@@ -0,0 +1,4 @@
+import type { LongTermMemoryRepositorySnapshot, LongTermMemoryRepositoryState } from "./contracts.js";
+export declare function createEmptyMemorySnapshot(): LongTermMemoryRepositorySnapshot;
+export declare function advanceMemorySnapshot(current: LongTermMemoryRepositorySnapshot, state: LongTermMemoryRepositoryState): LongTermMemoryRepositorySnapshot;
+export declare function parseMemorySnapshot(value: unknown): LongTermMemoryRepositorySnapshot;