vesper-memory 0.5.3 → 0.6.0

package/dist/retrieval/index-outbox.js

@@ -0,0 +1,225 @@
+export function initializeIndexOutboxSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS index_outbox (
+      memory_id TEXT PRIMARY KEY,
+      operation TEXT NOT NULL CHECK (operation IN ('upsert', 'delete')),
+      namespace TEXT NOT NULL,
+      content TEXT,
+      memory_type TEXT,
+      metadata TEXT,
+      agent_id TEXT,
+      task_id TEXT,
+      created_at INTEGER NOT NULL,
+      qdrant_pending INTEGER NOT NULL DEFAULT 1,
+      redis_pending INTEGER NOT NULL DEFAULT 1,
+      attempts INTEGER NOT NULL DEFAULT 0,
+      last_error TEXT,
+      revision INTEGER NOT NULL DEFAULT 1,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_index_outbox_pending
+      ON index_outbox(qdrant_pending, redis_pending, updated_at);
+  `);
+    const columns = db.prepare("PRAGMA table_info(index_outbox)").all();
+    if (!columns.some((column) => column.name === "revision")) {
+        db.exec("ALTER TABLE index_outbox ADD COLUMN revision INTEGER NOT NULL DEFAULT 1");
+    }
+}
+/**
+ * Keeps Redis and Qdrant as rebuildable projections of canonical SQLite rows.
+ * Enqueue methods are synchronous so callers can include them in a SQLite
+ * transaction. Draining is best-effort and may be retried safely.
+ */
+export class IndexOutboxProcessor {
+    db;
+    dependencies;
+    activeDrain;
+    desiredQdrantProjection;
+    desiredRedisProjection;
+    constructor(db, dependencies) {
+        this.db = db;
+        this.dependencies = dependencies;
+        this.desiredQdrantProjection =
+            dependencies.projectionConfig?.qdrant ??
+                Boolean(dependencies.embeddingClient && dependencies.hybridSearch);
+        this.desiredRedisProjection =
+            dependencies.projectionConfig?.redis ?? Boolean(dependencies.workingMemory);
+    }
+    enqueue(mutation) {
+        const now = Date.now();
+        const qdrantPending = this.desiredQdrantProjection ? 1 : 0;
+        const redisPending = this.desiredRedisProjection ? 1 : 0;
+        if (qdrantPending === 0 && redisPending === 0) {
+            // SQLite + FTS are already canonical and synchronous. Do not report an
+            // intentionally unconfigured projection as a permanent failed write.
+            this.db.prepare("DELETE FROM index_outbox WHERE memory_id = ?").run(mutation.memoryId);
+            return;
+        }
+        this.db
+            .prepare(`
+      INSERT INTO index_outbox (
+        memory_id, operation, namespace, content, memory_type, metadata,
+        agent_id, task_id, created_at, qdrant_pending, redis_pending,
+        attempts, last_error, revision, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, 1, ?)
+      ON CONFLICT(memory_id) DO UPDATE SET
+        operation = excluded.operation,
+        namespace = excluded.namespace,
+        content = excluded.content,
+        memory_type = excluded.memory_type,
+        metadata = excluded.metadata,
+        agent_id = excluded.agent_id,
+        task_id = excluded.task_id,
+        created_at = excluded.created_at,
+        qdrant_pending = excluded.qdrant_pending,
+        redis_pending = excluded.redis_pending,
+        attempts = 0,
+        last_error = NULL,
+        revision = index_outbox.revision + 1,
+        updated_at = excluded.updated_at
+    `)
+            .run(mutation.memoryId, mutation.operation, mutation.namespace, mutation.content ?? null, mutation.memoryType ?? null, JSON.stringify(mutation.metadata ?? {}), mutation.agentId ?? null, mutation.taskId ?? null, mutation.createdAt, qdrantPending, redisPending, now);
+    }
+    getState(memoryId) {
+        const pending = this.db.prepare("SELECT 1 FROM index_outbox WHERE memory_id = ?").get(memoryId);
+        return pending ? "pending" : "indexed";
+    }
+    getPendingCount() {
+        const row = this.db.prepare("SELECT COUNT(*) AS count FROM index_outbox").get();
+        return row.count;
+    }
+    drain(limit = 100) {
+        if (this.activeDrain)
+            return this.activeDrain;
+        const operation = this.performDrain(limit).finally(() => {
+            if (this.activeDrain === operation)
+                this.activeDrain = undefined;
+        });
+        this.activeDrain = operation;
+        return operation;
+    }
+    async performDrain(limit) {
+        const rows = this.db
+            .prepare(`
+      SELECT * FROM index_outbox
+      WHERE qdrant_pending = 1 OR redis_pending = 1
+      ORDER BY updated_at ASC
+      LIMIT ?
+    `)
+            .all(limit);
+        const stats = {
+            examined: rows.length,
+            completed: 0,
+            pending: 0,
+            errors: [],
+        };
+        for (const row of rows) {
+            const errors = [];
+            let qdrantPending = row.qdrant_pending === 1;
+            let redisPending = row.redis_pending === 1;
+            const hybridSearch = this.dependencies.hybridSearch;
+            const qdrantReady = hybridSearch && (row.operation === "delete" || this.dependencies.embeddingClient);
+            if (qdrantPending && qdrantReady) {
+                try {
+                    if (row.operation === "delete") {
+                        await hybridSearch.deleteMemory(row.memory_id);
+                    }
+                    else if (row.content && row.memory_type) {
+                        const vector = await this.dependencies.embeddingClient.embed(row.content);
+                        const metadata = parseMetadata(row.metadata);
+                        await hybridSearch.upsertMemory(row.memory_id, vector, {
+                            ...metadata,
+                            content: row.content,
+                            memory_type: row.memory_type,
+                            created_at: row.created_at,
+                            namespace: row.namespace,
+                            agent_id: row.agent_id ?? undefined,
+                            task_id: row.task_id ?? undefined,
+                        });
+                    }
+                    qdrantPending = false;
+                }
+                catch (error) {
+                    errors.push(`qdrant: ${errorMessage(error)}`);
+                }
+            }
+            if (redisPending && this.dependencies.workingMemory) {
+                try {
+                    if (row.operation === "delete") {
+                        await this.dependencies.workingMemory.delete(row.memory_id, row.namespace);
+                    }
+                    else if (row.content && row.memory_type) {
+                        const metadata = parseMetadata(row.metadata);
+                        await this.dependencies.workingMemory.store({
+                            conversationId: row.memory_id,
+                            timestamp: new Date(row.created_at),
+                            fullText: row.content,
+                            keyEntities: stringArray(metadata.key_entities),
+                            topics: stringArray(metadata.topics ?? metadata.tags),
+                            userIntent: typeof metadata.user_intent === "string" ? metadata.user_intent : row.memory_type,
+                        }, row.namespace);
+                    }
+                    redisPending = false;
+                }
+                catch (error) {
+                    errors.push(`redis: ${errorMessage(error)}`);
+                }
+            }
+            if (!qdrantPending && !redisPending) {
+                const deleted = this.db
+                    .prepare("DELETE FROM index_outbox WHERE memory_id = ? AND revision = ?")
+                    .run(row.memory_id, row.revision);
+                if (deleted.changes > 0)
+                    stats.completed++;
+                else
+                    stats.pending++;
+            }
+            else {
+                const unavailable = [];
+                if (qdrantPending &&
+                    (!this.dependencies.hybridSearch ||
+                        (row.operation !== "delete" && !this.dependencies.embeddingClient))) {
+                    unavailable.push("qdrant dependencies unavailable");
+                }
+                if (redisPending && !this.dependencies.workingMemory) {
+                    unavailable.push("redis unavailable");
+                }
+                const messages = [...errors, ...unavailable];
+                const updated = this.db
+                    .prepare(`
+          UPDATE index_outbox
+          SET qdrant_pending = ?, redis_pending = ?, attempts = attempts + ?,
+              last_error = ?, updated_at = ?
+          WHERE memory_id = ? AND revision = ?
+        `)
+                    .run(qdrantPending ? 1 : 0, redisPending ? 1 : 0, errors.length > 0 ? 1 : 0, messages.join("; ") || null, Date.now(), row.memory_id, row.revision);
+                stats.pending++;
+                if (updated.changes > 0) {
+                    stats.errors.push(...errors.map((message) => `${row.memory_id}: ${message}`));
+                }
+            }
+        }
+        return stats;
+    }
+}
+function parseMetadata(value) {
+    if (!value)
+        return {};
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=index-outbox.js.map

package/dist/retrieval/index-outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-outbox.js","sourceRoot":"","sources":["../../src/retrieval/index-outbox.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/memory-retriever.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Canonical memory retrieval.
+ *
+ * SQLite owns memory contents and authorization-relevant attributes. FTS5 and
+ * Qdrant are derived indexes: they may nominate ids, but their payloads are
+ * never returned or trusted for filtering.
+ */
+import Database from "better-sqlite3";
+import type { EmbeddingClient } from "../embeddings/client.js";
+import type { HybridSearchEngine } from "./hybrid-search.js";
+export type RetrievalStrategy = "auto" | "hybrid" | "full_text" | "semantic";
+export type EffectiveRetrievalStrategy = Exclude<RetrievalStrategy, "auto">;
+export type RetrievalSource = "lexical" | "dense" | "fast_path";
+export interface RetrieveMemoriesInput {
+    query: string;
+    namespace?: string;
+    memoryTypes?: string[];
+    maxResults?: number;
+    strategy?: RetrievalStrategy;
+    agentId?: string;
+    taskId?: string;
+    excludeAgent?: string;
+    includeSuperseded?: boolean;
+    includeArchived?: boolean;
+    /** Unix epoch milliseconds at which the memory must have been valid. */
+    asOf?: number;
+    /** Include a content-free account of the retrieval stages. */
+    explain?: boolean;
+}
+export interface MemoryRetrievalResult {
+    id: string;
+    content: string;
+    memoryType: string;
+    createdAt: string | number;
+    updatedAt: string | number;
+    metadata: Record<string, unknown>;
+    namespace: string;
+    agentId?: string;
+    agentRole?: string;
+    taskId?: string;
+    similarityScore?: number;
+    denseScore?: number;
+    /** Positive SQLite BM25 relevance (-1 * SQLite's lower-is-better value). */
+    lexicalScore?: number;
+    /** Reciprocal-rank-fusion score; present only for hybrid retrieval. */
+    fusedScore?: number;
+    rank: number;
+    sources: RetrievalSource[];
+}
+export interface RetrievalTraceStage {
+    stage: "lexical" | "dense" | "fusion" | "hydration" | "filtering";
+    candidateCount: number;
+    status: "ok" | "skipped" | "unavailable";
+    fallback?: "unfiltered_legacy_vectors";
+}
+export interface RetrievalTrace {
+    requestedStrategy: RetrievalStrategy;
+    effectiveStrategy: EffectiveRetrievalStrategy;
+    candidateLimit: number;
+    stages: RetrievalTraceStage[];
+    returnedCount: number;
+}
+export interface MemoryRetrievalResponse {
+    strategy: EffectiveRetrievalStrategy;
+    results: MemoryRetrievalResult[];
+    trace?: RetrievalTrace;
+}
+export interface RetrieveByIdsInput {
+    namespace?: string;
+    memoryTypes?: string[];
+    maxResults?: number;
+    agentId?: string;
+    taskId?: string;
+    excludeAgent?: string;
+    includeSuperseded?: boolean;
+    includeArchived?: boolean;
+    asOf?: number;
+    /** Optional scores from the candidate source, keyed by canonical memory id. */
+    similarityScores?: ReadonlyMap<string, number>;
+    source?: RetrievalSource;
+}
+export interface MemoryRetrieverDependencies {
+    db: Database.Database;
+    embeddingClient?: Pick<EmbeddingClient, "embed">;
+    hybridSearch?: Pick<HybridSearchEngine, "denseSearch">;
+    now?: () => number;
+    rrfK?: number;
+    candidateMultiplier?: number;
+}
+export declare class MemoryRetriever {
+    private readonly db;
+    private readonly embeddingClient?;
+    private readonly hybridSearch?;
+    private readonly now;
+    private readonly rrfK;
+    private readonly candidateMultiplier;
+    private memoryColumns;
+    constructor(dependencies: MemoryRetrieverDependencies);
+    /**
+     * Create the external-content FTS5 index and synchronization triggers.
+     * Existing rows are backfilled only when the index is first created.
+     */
+    initialize(): void;
+    retrieve(input: RetrieveMemoriesInput): Promise<MemoryRetrievalResponse>;
+    /**
+     * Canonically hydrate an ordered candidate list from a cache or legacy index.
+     * Supplied order is preserved, duplicate/missing ids are removed, all filters
+     * are applied to SQLite rows, and only returned rows receive access credit.
+     */
+    retrieveByIds(ids: readonly string[], input?: RetrieveByIdsInput): MemoryRetrievalResult[];
+    private validateInput;
+    private effectiveStrategy;
+    private lexicalSearch;
+    private denseSearch;
+    private rankCandidates;
+    private hydrate;
+    private matchesFilters;
+    private reinforceAccess;
+    private getMemoryColumns;
+}
+/** Convert arbitrary text into literal FTS tokens, never executable FTS syntax. */
+export declare function sanitizeFtsQuery(query: string): string | null;
+//# sourceMappingURL=memory-retriever.d.ts.map

package/dist/retrieval/memory-retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-retriever.d.ts","sourceRoot":"","sources":["../../src/retrieval/memory-retriever.ts"],"names":[],"mappings":"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"}