@jbarket/loomai 0.5.0

package/dist/backends/sqlite-vec.d.ts

@@ -0,0 +1,64 @@
+import { type Database } from 'better-sqlite3';
+import type { MemoryBackend, MemoryInput, MemoryRef, RecallInput, MemoryMatch, ForgetInput, ForgetResult, UpdateInput, UpdateResult, PruneResult, ListInput, MemoryEntry, EmbeddingProvider, FindSimilarInput, AuditOptions, AuditReport, ArchiveInput, ArchiveResult, RestoreInput, RestoreResult, RecallObservation, MemoryRevisionMeta, MemoryRevision, MemoryRevisionRestoreInput, MemoryRevisionRestoreResult, MemorySupersededInput, MemorySupersededResult } from './types.js';
+export interface SqliteVecConfig {
+    /** Absolute path to the SQLite database file */
+    dbPath: string;
+    /**
+     * Observer for the recall observation log. Called once per recall with
+     * the search's telemetry; errors it throws are swallowed — a failed
+     * observation never fails a search.
+     */
+    onRecall?: (obs: RecallObservation) => void;
+}
+export declare class SqliteVecBackend implements MemoryBackend {
+    private readonly config;
+    private readonly embedder;
+    private readonly db;
+    constructor(config: SqliteVecConfig, embedder: EmbeddingProvider);
+    remember(input: MemoryInput): Promise<MemoryRef>;
+    recall(input: RecallInput): Promise<MemoryMatch[]>;
+    forget(input: ForgetInput): Promise<ForgetResult>;
+    update(input: UpdateInput): Promise<UpdateResult>;
+    prune(options?: {
+        dryRun?: boolean;
+        staleDays?: number;
+    }): Promise<PruneResult>;
+    list(input: ListInput): Promise<MemoryEntry[]>;
+    findSimilar(input: FindSimilarInput): Promise<MemoryMatch[]>;
+    audit(options?: AuditOptions): Promise<AuditReport>;
+    archive(input: ArchiveInput): Promise<ArchiveResult>;
+    restore(input: RestoreInput): Promise<RestoreResult>;
+    listRevisions(ref: string): Promise<MemoryRevisionMeta[]>;
+    getRevision(revisionId: number): Promise<MemoryRevision | null>;
+    restoreRevision(input: MemoryRevisionRestoreInput): Promise<MemoryRevisionRestoreResult>;
+    supersede(input: MemorySupersededInput): Promise<MemorySupersededResult>;
+    close(): void;
+    getDatabase(): Database;
+    /**
+     * Insert a content snapshot into memory_revisions and prune beyond the per-memory
+     * cap. Mirrors the knowledge wing's snapshotRevision() in sqlite-knowledge.ts.
+     */
+    private snapshotRevision;
+    /**
+     * KNN search with a growing-k loop.
+     *
+     * sqlite-vec's KNN returns the k nearest rows regardless of archived
+     * status or category/project filters (those live in `memories`, not in
+     * the vec table). A single over-fetch can therefore starve the result
+     * set when many near neighbours are filtered out — e.g. legacy archived
+     * rows whose vectors predate delete-on-archive, or a narrow category.
+     *
+     * Policy: start at `startK`, multiply by 4 each round, stop when
+     * `limit` accepted matches are collected, k has covered every vec row,
+     * or a round surfaces no new candidates. Candidates are deduped across
+     * rounds; because each round's KNN is distance-ordered and new
+     * candidates always rank deeper than already-seen ones, appending
+     * preserves global distance order.
+     */
+    private searchVectors;
+    private observeRecall;
+    /** Stored embeddings for a set of memory ids (point lookups; pools are small). */
+    private loadVectors;
+    private initSchema;
+    private deleteById;
+}