wolbarg 0.3.2 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { DatabaseSync } from 'node:sqlite';
+
 /**
  * Metadata filter AST for advanced recall filtering.
  */
@@ -47,7 +49,7 @@ declare const meta: {
  * Schema is intentionally extensible for future providers (Postgres, cloud).
  */
 /** Public operation names recorded as telemetry events. */
-type TelemetryOperation = "remember" | "recall" | "forget" | "compress" | "rememberBatch" | "recallBatch" | "export" | "import" | "checkpoint" | "rollback" | "error" | "startup" | "shutdown" | "ingest" | "history" | "stats" | "clear" | "deleteCheckpoint" | "listCheckpoints" | "getCheckpoint";
+type TelemetryOperation = "remember" | "recall" | "forget" | "compress" | "rememberBatch" | "recallBatch" | "export" | "import" | "checkpoint" | "rollback" | "error" | "startup" | "shutdown" | "ingest" | "history" | "stats" | "clear" | "deleteCheckpoint" | "listCheckpoints" | "getCheckpoint" | "linkMemories" | "getRelated" | "graphQuery";
 type TelemetryStatus = "ok" | "error" | "cancelled";
 type TelemetryLogLevel = "off" | "error" | "warn" | "info" | "debug" | "trace";
 /** Stage-level latency breakdown recorded on each event. */
@@ -224,8 +226,10 @@ interface PostgresDatabaseConfig {
     connectionString?: string;
     /** v0.3 preferred alias for the Postgres connection string. */
     url?: string;
-    /** Optional max pool size. Defaults to 10. */
+    /** Optional max pool size. Defaults to 64. */
     maxPoolSize?: number;
+    /** When false, uses asynchronous commit for higher write throughput. */
+    durableWrites?: boolean;
 }
 /** Discriminated union of database configs. */
 type DatabaseConfig = SqliteDatabaseConfig | PostgresDatabaseConfig;
@@ -302,6 +306,30 @@ interface InitOptions {
      */
     llm?: LlmConfig;
 }
+/** Write-time memory dedupe strategy. */
+type MemoryDedupeStrategy = "exact" | "near" | "exact-or-near";
+/** Constructor / per-call memory dedupe configuration. */
+interface MemoryDedupeConfig {
+    enabled?: boolean;
+    strategy?: MemoryDedupeStrategy;
+    /** Cosine similarity threshold for near-dup matching. Default 0.92 */
+    nearThreshold?: number;
+    /** Max vector candidates considered for near-dup. Default 8 */
+    nearCandidateLimit?: number;
+}
+/** SQLite multi-writer concurrency tuning. */
+interface ConcurrencyConfig$1 {
+    maxRetries?: number;
+    baseBackoffMs?: number;
+    maxBackoffMs?: number;
+    lockTimeoutMs?: number;
+}
+/** Transparent embedding cache configuration. */
+interface EmbeddingCacheConfig {
+    enabled?: boolean;
+    ttlMs?: number;
+    maxEntries?: number;
+}
 /** Input for {@link Wolbarg.remember}. */
 interface RememberOptions {
     /** Agent identifier that owns this memory. */
@@ -310,6 +338,14 @@ interface RememberOptions {
     content: MemoryContent;
     /** Optional opaque metadata. Stored and returned as-is. */
     metadata?: MemoryMetadata;
+    /** Per-call dedupe override; undefined uses constructor `memory.dedupe`. */
+    dedupe?: boolean | MemoryDedupeConfig;
+}
+/** Whether remember created a new row or updated an existing one. */
+type RememberAction = "created" | "updated";
+/** Result of {@link Wolbarg.remember} — MemoryRecord plus upsert action. */
+interface RememberResult extends MemoryRecord {
+    action: RememberAction;
 }
 /** Optional filter applied to recall / forget / compress operations. */
 interface MemoryFilter {
@@ -352,6 +388,12 @@ interface RecallOptions {
      * When `true`, return enriched explain results instead of plain RecallResult[].
      */
     explain?: boolean;
+    /**
+     * When `true` and a graph provider is configured, each hit includes
+     * `related` memories from {@link GraphProvider.getRelated}.
+     * Omitted / false → no behavior change (related is absent).
+     */
+    includeGraph?: boolean;
 }
 /** A single recalled memory with similarity score. */
 interface RecallResult {
@@ -364,6 +406,11 @@ interface RecallResult {
     similarity: number;
     createdAt: Date;
     updatedAt: Date;
+    /**
+     * Present only when `recall({ includeGraph: true })` and a graph provider
+     * is configured. Related memories via graph traversal (depth 1, both dirs).
+     */
+    related?: MemoryRecord[];
 }
 /** Enriched recall hit when `explain: true`. */
 interface RecallExplanationHit {
@@ -465,7 +512,7 @@ interface HistoryOptions {
 interface HistoryEvent {
     id: string;
     memoryId: string;
-    eventType: "created" | "archived" | "compressed";
+    eventType: "created" | "archived" | "compressed" | "updated";
     relatedMemoryId: string | null;
     createdAt: Date;
 }
@@ -543,6 +590,107 @@ interface IngestResult {
     usedVision: boolean;
 }
 
+/**
+ * Graph memory provider contract.
+ *
+ * Mirrors {@link StorageProvider} lifecycle naming (`open` / `close` / `health`
+ * pattern via `health()`). Fully optional — omitting a graph provider does not
+ * change existing memory behavior.
+ *
+ * ## Portability contract
+ *
+ * - The five typed methods (`linkMemories`, `unlinkMemories`, `getRelated`,
+ *   `upsertEntity`, `linkEntityToMemory`) are **guaranteed** identical behavior
+ *   across SQLite and Neo4j. This is the tested, supported contract (see
+ *   `graph-parity.test.ts`).
+ * - `query(cypher, params)` is supported on Neo4j only. The SQLite graph
+ *   provider **hard-errors** immediately — SQLite has no Cypher. Use typed
+ *   methods for portable code, or query the graph SQLite tables directly if you
+ *   need raw SQL locally.
+ * - `health()` guarantees only `ok` and `backend`. The `details` payload
+ *   differs (embedded file path vs networked cluster/connection info).
+ * - `deleteMemory` supports hard-delete cascade from `forget` / `clear` and is
+ *   part of the portable typed surface.
+ */
+
+/** Direction for {@link GraphProvider.getRelated}. */
+type GraphDirection = "in" | "out" | "both";
+interface GetRelatedOptions {
+    relation?: string;
+    /** Traversal depth (default 1). */
+    depth?: number;
+    direction?: GraphDirection;
+}
+interface GraphEntityInput {
+    name: string;
+    type: string;
+    metadata?: Record<string, unknown>;
+}
+interface GraphHealthResult {
+    ok: boolean;
+    backend: string;
+    details?: unknown;
+}
+/**
+ * Pluggable graph store for memory–memory and entity–memory relations.
+ *
+ * Typed CRUD methods MUST be implemented with each backend’s native driver API
+ * (not by routing through {@link GraphProvider.query}). `query()` is the
+ * user-facing raw escape hatch only (Neo4j); SQLite throws.
+ */
+interface GraphProvider {
+    readonly name: string;
+    /** Open connection / embedded database and ensure schema. */
+    open(): Promise<void>;
+    /** Close the underlying connection. */
+    close(): Promise<void>;
+    /**
+     * Create (or ensure) a directed relation between two memory nodes.
+     * Implementations create stub Memory nodes when missing.
+     */
+    linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Remove relation(s) between two memory nodes. */
+    unlinkMemories(fromId: string, toId: string, relation?: string): Promise<void>;
+    /**
+     * Traverse from a memory node and return related Memory records as stored
+     * in the graph (facade may re-hydrate from SQL storage).
+     */
+    getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
+    /** Upsert an entity node; returns stable entity id. */
+    upsertEntity(entity: GraphEntityInput): Promise<string>;
+    /** Link an entity to a memory with an optional role. */
+    linkEntityToMemory(entityId: string, memoryId: string, role?: string): Promise<void>;
+    /**
+     * Hard-delete a memory node and all incident edges (cascade for forget/clear).
+     */
+    deleteMemory(memoryId: string): Promise<void>;
+    /**
+     * Raw Cypher escape hatch. Supported on Neo4j only — the SQLite provider
+     * throws a typed error. See module portability contract above.
+     */
+    query(cypher: string, params?: Record<string, unknown>): Promise<unknown>;
+    health(): Promise<GraphHealthResult>;
+    /**
+     * When true, checkpoint/export may snapshot {@link getDataPath}.
+     * Network-backed providers (Neo4j) return false.
+     */
+    supportsFileSnapshot(): boolean;
+    /** Absolute path to the embedded graph data directory/file, if any. */
+    getDataPath(): string | null;
+}
+/** Config shape accepted by `wolbarg({ graph: … })` when not passing an instance. */
+type GraphConfig = {
+    provider: "sqlite";
+    path: string;
+} | {
+    provider: "neo4j";
+    url: string;
+    username: string;
+    password: string;
+    database?: string;
+};
+type GraphInput$1 = GraphProvider | GraphConfig;
+
 /**
  * Chunking strategies for document ingestion.
  */
@@ -768,6 +916,7 @@ interface MemoryRow {
     metadata_json: string;
     archived: number;
     compressed_into: string | null;
+    content_hash?: string | null;
     created_at: string;
     updated_at: string;
     rowid?: number;
@@ -776,7 +925,7 @@ interface MemoryRow {
 interface HistoryRow {
     id: string;
     memory_id: string;
-    event_type: "created" | "archived" | "compressed";
+    event_type: "created" | "archived" | "compressed" | "updated";
     related_memory_id: string | null;
     created_at: string;
 }
@@ -790,6 +939,7 @@ interface InsertMemoryInput {
     embedding: Float32Array;
     createdAt: string;
     updatedAt: string;
+    contentHash?: string | null;
 }
 /** Payload for updating memory content / metadata. */
 interface UpdateMemoryInput {
@@ -799,6 +949,7 @@ interface UpdateMemoryInput {
     metadata?: MemoryMetadata;
     embedding?: Float32Array;
     updatedAt: string;
+    contentHash?: string | null;
 }
 /** Filters used by repository queries. */
 interface RepositoryFilter {
@@ -834,6 +985,11 @@ interface StorageProvider {
     insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
     /** Update memory fields and optionally replace embedding. */
     updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    /**
+     * Find an active (non-archived) memory by content hash within org+agent.
+     * Used by write-time exact dedupe.
+     */
+    findActiveByContentHash?(organization: string, agent: string, contentHash: string): Promise<MemoryRow | null>;
     /** Fetch a memory by UUID. */
     getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
     /** Fetch a memory by its integer rowid. */
@@ -990,6 +1146,7 @@ declare function openaiVision(options: {
 type EmbeddingInput = EmbeddingProvider | EmbeddingConfig;
 type LlmInput = LlmProvider | LlmConfig;
 type StorageInput = StorageProvider | StorageConfig | DatabaseConfig;
+type GraphInput = GraphProvider | GraphConfig;
 interface WolbargOptionsBase {
     /** Organization namespace isolating memories within a shared database. */
     organization: string;
@@ -1018,12 +1175,26 @@ interface WolbargOptionsBase {
     ocr?: OCRProvider;
     /** Optional vision model for image captions. */
     vision?: VisionProvider;
+    /**
+     * Optional graph memory layer (SQLite embedded or Neo4j networked).
+     * Fully optional — omitting it does not change existing memory behavior.
+     * Accepts a {@link GraphProvider} instance or a recognized config shape.
+     */
+    graph?: GraphInput;
     /** Optional compression provider (overrides llm-backed default). */
     compression?: CompressionProvider;
     /** Optional default chunking strategy for ingest. */
     chunking?: ChunkingStrategy;
     /** Optional retrieval defaults. */
     retrieval?: RetrievalConfig;
+    /** SQLite multi-writer concurrency tuning (ignored for Postgres). */
+    concurrency?: ConcurrencyConfig$1;
+    /** Transparent embedding cache (default enabled). */
+    embeddingCache?: EmbeddingCacheConfig;
+    /** Memory write-path options (dedupe / upsert). */
+    memory?: {
+        dedupe?: MemoryDedupeConfig;
+    };
 }
 interface WolbargOptionsWithoutLlm extends WolbargOptionsBase {
     llm?: undefined;
@@ -1034,6 +1205,29 @@ interface WolbargOptionsWithLlm extends WolbargOptionsBase {
 }
 type WolbargOptions = WolbargOptionsWithoutLlm | WolbargOptionsWithLlm;
 
+/**
+ * Public subscribe() types for real-time memory change events.
+ */
+type SubscribableEvent = "remember" | "update" | "forget" | "compress" | "ingest" | "*";
+interface SubscribeFilter {
+    organization: string;
+    agent?: string;
+    event?: SubscribableEvent | SubscribableEvent[];
+}
+interface MemoryChangeEvent {
+    event: Exclude<SubscribableEvent, "*">;
+    organization: string;
+    agent: string;
+    memoryId: string | string[];
+    timestamp: string;
+    traceId?: string;
+    sessionId?: string;
+    /** Present when upsert path ran during remember/ingest. */
+    upsertAction?: "created" | "updated" | "skipped";
+}
+type MemoryChangeCallback = (event: MemoryChangeEvent) => void;
+type Unsubscribe = () => void;
+
 /**
  * Wolbarg — modular semantic memory SDK for AI agents (v0.3).
  *
@@ -1074,6 +1268,7 @@ declare class Wolbarg<HasLlm extends boolean = false> {
     private keywordSearch;
     private ocr;
     private vision;
+    private graph;
     private chunking;
     private retrievalConfig;
     private embeddingDimensions;
@@ -1082,6 +1277,11 @@ declare class Wolbarg<HasLlm extends boolean = false> {
     private checkpointProvider;
     private memoryDbPath;
     private readonly transfer;
+    private subscribeBackend;
+    private pgListenBackend;
+    private memoryDedupe;
+    private embeddingCacheConfig;
+    private rawEmbedding;
     constructor(options: WolbargOptionsWithLlm);
     constructor(options: WolbargOptionsWithoutLlm);
     constructor();
@@ -1092,10 +1292,31 @@ declare class Wolbarg<HasLlm extends boolean = false> {
     /** Ensure storage (and optional telemetry) are open. */
     ready(): Promise<void>;
     private boot;
-    /** Store a semantic memory for an agent. */
-    remember(options: RememberOptions): Promise<MemoryRecord>;
-    /** Batch remember — one parent event + child traces per item. */
-    rememberBatch(items: RememberOptions[]): Promise<MemoryRecord[]>;
+    /** Store a semantic memory for an agent (may upsert when dedupe is enabled). */
+    remember(options: RememberOptions): Promise<RememberResult>;
+    /** Batch remember — sequential when dedupe enabled; otherwise one TX batch. */
+    rememberBatch(items: RememberOptions[]): Promise<RememberResult[]>;
+    /**
+     * Update an existing memory by id (re-embeds when content changes).
+     */
+    update(options: {
+        id: string;
+        content?: {
+            text: string;
+        };
+        metadata?: MemoryMetadata;
+    }): Promise<RememberResult>;
+    /**
+     * Subscribe to memory change events.
+     *
+     * **SQLite:** delivers events only within this Node.js process.
+     * A second process writing the same `memory.db` will not notify subscribers here.
+     */
+    subscribe(filter: SubscribeFilter, callback: (event: MemoryChangeEvent) => void): Unsubscribe;
+    private emitChange;
+    /** Internal remember with optional upsert/dedupe. */
+    private rememberOne;
+    private findNearDuplicate;
     /**
      * Semantic / hybrid search over stored memories.
      * Pass `{ explain: true }` for enriched ranking diagnostics.
@@ -1113,6 +1334,17 @@ declare class Wolbarg<HasLlm extends boolean = false> {
     /** @internal */
     private runCompress;
     ingest(options: IngestOptions): Promise<IngestResult>;
+    /**
+     * Link two memories in the optional graph layer.
+     * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
+     */
+    linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Traverse related memories via the optional graph layer.
+     * Throws {@link ProviderNotConfiguredError} when no graph provider is set.
+     * Results are re-hydrated from SQL storage when available.
+     */
+    getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
     forget(options: ForgetOptions): Promise<number>;
     history(options: HistoryOptions): Promise<HistoryResult>;
     stats(): Promise<StatsResult>;
@@ -1132,17 +1364,32 @@ declare class Wolbarg<HasLlm extends boolean = false> {
     flushTelemetry(): Promise<void>;
     /** Session id for this SDK instance (telemetry traces). */
     get sessionId(): string;
+    /**
+     * Optional process-wide lock for SQLite read-modify-write (dedupe upsert).
+     * Plain inserts must NOT take this lock — the provider coalesces concurrent
+     * insertMemory calls under a single BEGIN IMMEDIATE for multi-writer throughput.
+     */
     private withWriteLock;
     close(): Promise<void>;
     get isInitialized(): boolean;
     private requireReady;
     private assertEmbeddingDimensions;
     private requireCheckpointProvider;
+    private requireGraph;
+    private assertGraphCheckpointSupported;
+    private graphSnapshotDir;
+    private closeGraphForSnapshot;
+    private snapshotGraphAlongside;
+    private restoreGraphAlongside;
+    private hydrateRelated;
     private requireMemoryDbPath;
 }
 /** Preferred v0.3 entry — re-exported from factories as well. */
 declare function wolbarg$1(options: WolbargOptions): Wolbarg;
 
+/** Published SDK semver — keep in sync with package.json `version`. */
+declare const SDK_VERSION = "0.5.0";
+
 /**
  * Operation-scoped errors with reason + suggestion for developer experience.
  */
@@ -1190,6 +1437,17 @@ declare class DatabaseError extends WolbargError {
         operation?: string;
     });
 }
+/**
+ * Thrown when SQLite write-lock retries are exhausted.
+ * Stable code: WOLBARG_STORAGE_LOCKED
+ */
+declare class StorageLockedError extends WolbargError {
+    constructor(message: string, options?: ErrorOptions & {
+        reason?: string;
+        suggestion?: string;
+        operation?: string;
+    });
+}
 /** Thrown when an embedding request fails. */
 declare class EmbeddingError extends WolbargError {
     constructor(message: string, options?: ErrorOptions & {
@@ -1221,6 +1479,14 @@ declare class ProviderNotConfiguredError extends ConfigurationError {
     readonly provider: string;
     constructor(provider: string, method: string, hint: string);
 }
+/**
+ * Thrown when graph checkpoint / rollback / export / import is requested for a
+ * network-backed graph provider (e.g. Neo4j). File-backed SQLite graph supports
+ * snapshots; Neo4j does not in v1 — we refuse rather than silently skip.
+ */
+declare class GraphCheckpointNotSupportedError extends WolbargError {
+    constructor(backend: string, operation: string);
+}
 /** Map low-level SQLite / driver errors into actionable operation errors. */
 declare function wrapOperationError(operation: string, error: unknown): WolbargError;
 
@@ -1236,15 +1502,29 @@ declare function sqliteConfig(connectionString: string): SqliteDatabaseConfig;
 declare function postgres(options: string | {
     connectionString: string;
     maxPoolSize?: number;
+    /** Default true. Set false for higher write throughput (async commit). */
+    durableWrites?: boolean;
 }): StorageProvider;
 /** Create a PostgreSQL storage config object. */
 declare function postgresConfig(connectionString: string, options?: {
     maxPoolSize?: number;
+    durableWrites?: boolean;
 }): PostgresDatabaseConfig;
 /** Create a SQLite telemetry provider for an independent event database. */
 declare function sqliteTelemetry(url: string): TelemetryProvider;
 /** Create a SQLite checkpoint provider. */
 declare function sqliteCheckpoint(directory?: string): CheckpointProvider;
+/** Create an embedded SQLite graph provider (file-backed, local/dev). */
+declare function sqliteGraph(options: {
+    path: string;
+}): GraphProvider;
+/** Create a Neo4j graph provider (networked). Requires optional peer `neo4j-driver`. */
+declare function neo4jGraph(options: {
+    url: string;
+    username: string;
+    password: string;
+    database?: string;
+}): GraphProvider;
 /** Create a telemetry provider from config (SQLite only in v0.3). */
 declare function createTelemetryProvider(config: TelemetryConfig): TelemetryProvider;
 /**
@@ -1252,6 +1532,20 @@ declare function createTelemetryProvider(config: TelemetryConfig): TelemetryProv
  */
 declare function wolbarg(options: WolbargOptions): Wolbarg;
 
+/**
+ * SQLite multi-writer concurrency defaults and validation.
+ */
+interface ConcurrencyConfig {
+    /** Max retry attempts after SQLITE_BUSY. Default: 5 */
+    maxRetries?: number;
+    /** Base backoff in ms before jitter. Default: 50 */
+    baseBackoffMs?: number;
+    /** Cap on backoff delay in ms. Default: 2000 */
+    maxBackoffMs?: number;
+    /** SQLite busy_timeout pragma in ms. Default: 5000 */
+    lockTimeoutMs?: number;
+}
+
 /**
  * SQLite + sqlite-vec database provider (Node.js built-in `node:sqlite`).
  *
@@ -1266,10 +1560,12 @@ declare function wolbarg(options: WolbargOptions): Wolbarg;
 
 interface SqliteProviderOptions {
     connectionString: string;
+    concurrency?: ConcurrencyConfig;
 }
 declare class SqliteStorageProvider implements StorageProvider {
     readonly name = "sqlite";
     private readonly connectionString;
+    private readonly concurrency;
     private db;
     private statements;
     private vectorDimensions;
@@ -1280,17 +1576,41 @@ declare class SqliteStorageProvider implements StorageProvider {
     private memoryIndexDirty;
     /** Resolved absolute path (or `:memory:`) — avoid re-resolving on size checks. */
     private resolvedPath;
+    private retryLog;
+    /** Cached prepared statements for `rowid IN (…)` lookups keyed by list length. */
+    private rowidInStatements;
+    /** Cached list SQL statements keyed by clause shape. */
+    private listStatements;
+    /** Cached multi-row insert statements keyed by row count. */
+    private batchInsertStatements;
+    /** Cached multi-row history inserts keyed by row count. */
+    private batchHistoryStatements;
+    /** Cached multi-row FTS inserts keyed by row count. */
+    private batchFtsStatements;
+    /** Cached multi-row blob embedding inserts keyed by row count. */
+    private batchBlobEmbStatements;
+    /** Coalesce concurrent insertMemory callers into one IMMEDIATE transaction. */
+    private insertQueue;
+    private insertFlushScheduled;
     constructor(options: SqliteProviderOptions);
     /** Absolute or relative path / `:memory:` used by this provider. */
     get path(): string;
+    /** Expose DB for embedding cache store (same connection). */
+    getDatabase(): DatabaseSync | null;
+    setRetryLogger(fn: ((msg: string) => void) | null): void;
     open(): Promise<void>;
     close(): Promise<void>;
     ensureVectorSchema(dimensions: number): Promise<void>;
     getEmbeddingDimensions(): Promise<number | null>;
     setEmbeddingDimensions(dimensions: number): Promise<void>;
     insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
+    private scheduleInsertFlush;
+    private flushInsertQueue;
+    /** Single-row insert without coalescing (used by flush of size 1). */
+    private insertMemoryImmediate;
     insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
     updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    findActiveByContentHash(organization: string, agent: string, contentHash: string): Promise<MemoryRow | null>;
     searchByMetadata(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
     /** Keyword search via FTS5 BM25. Returns memory IDs ranked by relevance. */
     searchKeyword(query: string, organization: string, topK: number): Promise<Array<{
@@ -1303,8 +1623,8 @@ declare class SqliteStorageProvider implements StorageProvider {
     listMemories(filter: RepositoryFilter, limit?: number): Promise<MemoryRow[]>;
     searchVectors(embedding: Float32Array, topK: number): Promise<VectorSearchHit[]>;
     /**
-     * Org-scoped KNN + memory rows.
-     * Caller (Wolbarg.recall) already passes an overfetched topK — do not multiply again.
+     * Org-scoped KNN + memory rows with adaptive overfetch.
+     * Global ANN is post-filtered by org/agent/archived; underfill triggers larger k.
      */
     searchVectorsWithMemories(embedding: Float32Array, topK: number, organization: string, options?: {
         agent?: string;
@@ -1326,9 +1646,21 @@ declare class SqliteStorageProvider implements StorageProvider {
         totalAgents: number;
     }>;
     getDatabaseSizeBytes(): Promise<number>;
-    withTransaction<T>(fn: () => T): T;
+    withTransaction<T>(fn: () => T | Promise<T>): Promise<T>;
     private tryLoadSqliteVec;
+    private static sqliteVecUnsupported;
     private runMigrations;
+    /**
+     * Schema v4: drop unused global created_at index, strip archived vectors
+     * from ANN, add agent-active covering index (via CREATE_INDEXES).
+     */
+    private migrateToV4;
+    /**
+     * Schema v3: content_hash column, history 'updated' event, embedding_cache.
+     * SQLite cannot ALTER CHECK constraints — rebuild memory_history when needed.
+     */
+    private migrateToV3;
+    private migrateHistoryAllowUpdated;
     /**
      * Rebuild FTS from active (non-archived) memories when counts diverge.
      * Guarantees keyword/hybrid correctness after crashes or interrupted writes.
@@ -1336,7 +1668,19 @@ declare class SqliteStorageProvider implements StorageProvider {
     private ensureFtsConsistency;
     private backfillFts;
     private prepareStatements;
-    private listMemoriesSync;
+    private listMemoriesIndexed;
+    /**
+     * Metadata-filtered list: push filters to json_extract when possible;
+     * otherwise page with a hard scan cap (never load unbounded orgs into RAM).
+     */
+    private listMemoriesWithMetadata;
+    private getRowidInStatement;
+    private insertMemoryChunk;
+    private insertEmbeddingsBatch;
+    private insertFtsBatch;
+    private insertHistoryBatch;
+    private deleteEmbeddingsForScope;
+    private deleteFtsForScope;
     /** Insert-only FTS row (new memory IDs never collide). */
     private insertFtsRow;
     private upsertFts;
@@ -1371,30 +1715,63 @@ declare const SqliteDatabaseProvider: typeof SqliteStorageProvider;
  * - AsyncLocalStorage for nested transactions
  * - Single-statement CTE inserts (no BEGIN/COMMIT for one memory)
  * - Named prepared statements (parse/plan once per connection)
- * - Concurrent insert coalescing into unnest batches; sequential path is immediate
- * - COPY protocol for large ingest batches
- * - Org-filtered ANN with adaptive overfetch + HNSW iterative scan when available
- * - Joined vector search returning memories in one round-trip when possible
+ * - Concurrent insert coalescing into unnest batches
+ * - float4[] vector bind (no text "[f,f,…]" parse tax)
+ * - Org/agent/archived denormalized on embeddings for filtered ANN
+ * - Large bulk inserts via sequential fat unnest (COPY-class amortization)
+ * - JSONB metadata filter pushdown
  */
 
+type PgQueryResult = {
+    rows: Record<string, unknown>[];
+    rowCount: number | null;
+};
+type PgQueryable = {
+    query: (textOrConfig: string | {
+        name?: string;
+        text: string;
+        values?: unknown[];
+    }, params?: unknown[]) => Promise<PgQueryResult>;
+};
+type PgPoolClient = PgQueryable & {
+    release: () => void;
+    query: PgQueryable["query"];
+};
+type PgPool = PgQueryable & {
+    end: () => Promise<void>;
+    connect: () => Promise<PgPoolClient>;
+    on?: (event: "connect", listener: (client: PgPoolClient) => void) => void;
+    totalCount?: number;
+    idleCount?: number;
+    waitingCount?: number;
+};
 interface PostgresProviderOptions {
     connectionString: string;
     maxPoolSize?: number;
+    /**
+     * When false, uses `synchronous_commit=off` on every pool connection.
+     * Much higher write throughput; recent commits can be lost on OS crash.
+     * Default true (full durability).
+     */
+    durableWrites?: boolean;
 }
 declare class PostgresStorageProvider implements StorageProvider {
     readonly name = "postgres";
     private readonly connectionString;
     private readonly maxPoolSize;
+    private readonly durableWrites;
     private pool;
     private vectorDimensions;
     private hasPgvector;
     private hnswIndexEnsured;
     private hnswCreateFailures;
+    /** Dedup concurrent CREATE INDEX so mixed read/write storms don't pile up. */
+    private hnswBuildInFlight;
     private hasContentTsv;
-    private iterativeScanEnabled;
     /** Coalesce concurrent insertMemory callers into one unnest batch. */
     private insertQueue;
     private insertFlushScheduled;
+    private insertFlushTimer;
     private insertFlushInFlight;
     constructor(options: PostgresProviderOptions);
     getPoolStats(): {
@@ -1403,10 +1780,26 @@ declare class PostgresStorageProvider implements StorageProvider {
         idle: number;
         waiting: number;
     };
+    /** Dedicated pool accessor for LISTEN/NOTIFY subscribe backend. */
+    getPool(): PgPool | null;
     open(): Promise<void>;
     close(): Promise<void>;
+    /**
+     * Run a search query. HNSW GUCs are baked into pool startup options —
+     * no per-recall connect()+set_config round-trip.
+     */
+    private withSearchSession;
+    /**
+     * Drop HNSW so bulk / concurrent inserts avoid graph maintenance.
+     * Next recall rebuilds the index (lazy).
+     */
+    dropVectorIndex(): Promise<void>;
+    /** Force HNSW build now (e.g. before timed recall benches). */
+    ensureVectorIndex(): Promise<void>;
     ensureVectorSchema(dimensions: number): Promise<void>;
     private ensureVectorTables;
+    /** Cross-process subscribe: NOTIFY after a committed write. */
+    notifyChange(event: MemoryChangeEvent): Promise<void>;
     /**
      * Soft reset for a single organization. Drops HNSW only when the embeddings
      * table is empty so other corpora on a shared bench DB stay intact.
@@ -1418,18 +1811,23 @@ declare class PostgresStorageProvider implements StorageProvider {
     wipeAllData(): Promise<void>;
     /** Build HNSW once before the first KNN query (bulk-friendly inserts). */
     private ensureHnswIndex;
+    private buildHnswIndex;
     getEmbeddingDimensions(): Promise<number | null>;
     setEmbeddingDimensions(dimensions: number): Promise<void>;
     insertMemory(input: InsertMemoryInput): Promise<MemoryRow>;
+    private clearInsertFlushTimer;
+    /** Flush coalesced inserts after a turn so concurrent remember() can join. */
+    private scheduleInsertFlush;
     private flushInsertQueue;
     /** Single-row insert without coalescing (used by flush + batch of 1). */
     private insertMemoryImmediate;
     insertMemoriesBatch(inputs: InsertMemoryInput[]): Promise<MemoryRow[]>;
     private insertBatchPgvector;
-    /** Split large ingest batches into parallel unnest chunks (pool pipelining). */
+    /** Parallel unnest when HNSW is absent; sequential when index must stay consistent. */
     private insertBatchChunked;
     private insertOneBlob;
     updateMemory(input: UpdateMemoryInput): Promise<MemoryRow | null>;
+    findActiveByContentHash(organization: string, agent: string, contentHash: string): Promise<MemoryRow | null>;
     getMemoryById(id: string, organization: string): Promise<MemoryRow | null>;
     getMemoryByRowid(rowid: number, organization: string): Promise<MemoryRow | null>;
     getMemoriesByRowids(rowids: number[], organization: string): Promise<Map<number, MemoryRow>>;
@@ -1463,6 +1861,8 @@ declare class PostgresStorageProvider implements StorageProvider {
     withTransaction<T>(fn: () => T | Promise<T>): Promise<T>;
     private runMigrations;
     private tryEnablePgvector;
+    private static pgvectorByConn;
+    private static vectorSchemaReady;
     private insertEmbedding;
     private deleteEmbedding;
     private query;
@@ -1474,13 +1874,115 @@ declare class PostgresStorageProvider implements StorageProvider {
     private describe;
 }
 
+declare function createStorageProvider(config: StorageConfig | DatabaseConfig, options?: {
+    concurrency?: ConcurrencyConfig$1;
+}): StorageProvider;
+/** @deprecated Prefer {@link createStorageProvider}. */
+declare function createDatabaseProvider(config: DatabaseConfig): StorageProvider;
+
+/**
+ * Embedded SQLite graph provider (file-backed, local/dev).
+ *
+ * Implements the five typed {@link GraphProvider} methods with plain SQL and
+ * recursive CTEs — no Cypher. Schema is created on open (plain CREATE TABLE IF
+ * NOT EXISTS; no graph-engine DDL / schema-creation-on-first-write complexity).
+ *
+ * Uses the same `node:sqlite` + {@link withImmediateTransaction} patterns as
+ * {@link SqliteStorageProvider}. Graph data lives in a separate SQLite file from
+ * the memory store by default.
+ */
+
+interface SqliteGraphProviderOptions {
+    /** Path to the graph SQLite file (separate from the memory store by default). */
+    path: string;
+    /** Optional write-concurrency tuning (same shape as memory SQLite). */
+    concurrency?: ConcurrencyConfig;
+}
+declare class SqliteGraphProvider implements GraphProvider {
+    readonly name = "sqlite";
+    private readonly dbPath;
+    private readonly concurrency;
+    private db;
+    private opened;
+    constructor(options: SqliteGraphProviderOptions);
+    supportsFileSnapshot(): boolean;
+    getDataPath(): string | null;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
+    unlinkMemories(fromId: string, toId: string, relation?: string): Promise<void>;
+    /**
+     * Bounded recursive CTE over `graph_edges`.
+     *
+     * Default depth: {@link DEFAULT_GET_RELATED_DEPTH} (1). Cap: 16.
+     * Only memory↔memory edges are walked (entity MENTIONS edges are excluded).
+     * Cycle-safe via path membership (`instr`) so A→B→C→A terminates.
+     *
+     * Returns stub {@link MemoryRecord}s (id + empty fields). The facade
+     * re-hydrates full rows via `toMemoryRecord` from storage when possible.
+     */
+    getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
+    upsertEntity(entity: GraphEntityInput): Promise<string>;
+    linkEntityToMemory(entityId: string, memoryId: string, role?: string): Promise<void>;
+    deleteMemory(memoryId: string): Promise<void>;
+    /**
+     * Raw Cypher escape hatch — **not supported** on the SQLite graph provider.
+     * Use the typed methods, or open the underlying SQLite file yourself for raw SQL.
+     */
+    query(_cypher: string, _params?: Record<string, unknown>): Promise<unknown>;
+    health(): Promise<GraphHealthResult>;
+    private withTx;
+    private requireDb;
+    private findMemoryNodeId;
+    private ensureMemoryNodeSync;
+}
+
 /**
- * Storage provider factory and re-exports.
+ * Neo4j graph provider (networked, production).
+ *
+ * Uses neo4j-driver session.run with parameterized Cypher for typed methods —
+ * NOT GraphProvider.query(). Schema-flexible: nodes/relationships are created
+ * freely without DDL.
+ *
+ * Install as optional peer: `npm install neo4j-driver`.
  */
 
-declare function createStorageProvider(config: StorageConfig | DatabaseConfig): StorageProvider;
-/** @deprecated Prefer {@link createStorageProvider}. */
-declare function createDatabaseProvider(config: DatabaseConfig): StorageProvider;
+interface Neo4jGraphProviderOptions {
+    url: string;
+    username: string;
+    password: string;
+    database?: string;
+}
+declare class Neo4jGraphProvider implements GraphProvider {
+    readonly name = "neo4j";
+    private readonly url;
+    private readonly username;
+    private readonly password;
+    private readonly database;
+    private driver;
+    private opened;
+    constructor(options: Neo4jGraphProviderOptions);
+    supportsFileSnapshot(): boolean;
+    getDataPath(): string | null;
+    open(): Promise<void>;
+    close(): Promise<void>;
+    private requireDriver;
+    private withSession;
+    private run;
+    private ensureMemoryNode;
+    linkMemories(fromId: string, toId: string, relation: string, metadata?: Record<string, unknown>): Promise<void>;
+    unlinkMemories(fromId: string, toId: string, relation?: string): Promise<void>;
+    /**
+     * Native Neo4j variable-length path traversal.
+     * Relationship filter uses RELATED.relation property for parity with Kuzu.
+     */
+    getRelated(memoryId: string, options?: GetRelatedOptions): Promise<MemoryRecord[]>;
+    upsertEntity(entity: GraphEntityInput): Promise<string>;
+    linkEntityToMemory(entityId: string, memoryId: string, role?: string): Promise<void>;
+    deleteMemory(memoryId: string): Promise<void>;
+    query(cypher: string, params?: Record<string, unknown>): Promise<unknown>;
+    health(): Promise<GraphHealthResult>;
+}
 
 /**
  * Database-agnostic memory persistence contract.
@@ -1592,6 +2094,22 @@ declare class SqliteCheckpointProvider implements CheckpointProvider {
     deleteCheckpoint(name: string): Promise<boolean>;
     listCheckpoints(): Promise<CheckpointMeta[]>;
     getCheckpoint(name: string): Promise<CheckpointMeta | null>;
+    /**
+     * Consistent SQLite file backup (WAL checkpoint + backup API / copy).
+     * Used for memory snapshots and for secondary files such as the graph DB.
+     */
+    backupSqliteFile(sourcePath: string, destPath: string): Promise<void>;
+    /**
+     * Snapshot a secondary SQLite file (typically the graph DB) next to a named
+     * memory checkpoint as `{name}.graph.db`.
+     */
+    checkpointGraph(name: string, graphSourcePath: string): Promise<string>;
+    /**
+     * Restore a previously snapshotted graph SQLite file into `targetPath`.
+     */
+    rollbackGraph(name: string, targetPath: string): Promise<void>;
+    /** Absolute path of the graph snapshot for a named checkpoint, if present. */
+    graphSnapshotPath(name: string): string;
     private metaPath;
     private snapshotPath;
     private requireReady;
@@ -1690,4 +2208,4 @@ interface BenchmarkReport {
 declare function runBenchmark(name: string, iterations: number, fn: () => Promise<void> | void): Promise<BenchmarkSample[]>;
 declare function summarizeBenchmark(samples: BenchmarkSample[], startedAt: string, finishedAt: string): BenchmarkReport;
 
-export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, ConfigurationError, type CreateCheckpointOptions, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryContent, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberOptions, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, type StorageProvider, type StorageProviderName, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, wolbarg as createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };
+export { type BenchmarkReport, type BenchmarkSample, type ChatMessage, type CheckpointInfo, type CheckpointMeta, type CheckpointOptions, type CheckpointProvider, type Chunk, type ChunkingOptions, type ChunkingStrategy, type ClearOptions, type CompressOptions, type CompressResult, CompressionError, type CompressionProvider, type ConcurrencyConfig$1 as ConcurrencyConfig, ConfigurationError, type CreateCheckpointOptions, type DatabaseConfig, DatabaseError, type DatabaseProvider, type DatabaseProviderName, type EmbeddingCacheConfig, type EmbeddingConfig, EmbeddingError, type EmbeddingProvider, type EventDatabase, type ExportResult, FixedChunkingStrategy, type ForgetByFilterOptions, type ForgetByIdOptions, type ForgetOptions, type GetRelatedOptions, GraphCheckpointNotSupportedError, type GraphConfig, type GraphDirection, type GraphEntityInput, type GraphHealthResult, type GraphInput$1 as GraphInput, type GraphProvider, HeadingChunkingStrategy, type HistoryEvent, type HistoryOptions, type HistoryResult, type HybridConfig, type ImportResult, type IngestOptions, type IngestResult, type InitOptions, InitializationError, type KeywordDocument, type KeywordSearchHit, type KeywordSearchProvider, type LatencyBreakdown, LlmCompressionProvider, type LlmConfig, type LlmProvider, MarkdownChunkingStrategy, type MemoryChangeCallback, type MemoryChangeEvent, type MemoryContent, type MemoryDedupeConfig, type MemoryDedupeStrategy, type MemoryFilter, type MemoryMetadata, MemoryNotFoundError, type MemoryProvider, type MemoryRecord, type MetadataFilter as MetaFilter, type MetadataComparison, type MetadataFilter, type MmrConfig, Neo4jGraphProvider, NoopTelemetryProvider, type OCRProvider, type OcrResult, ParagraphChunkingStrategy, type PersistedRecallExplainPayload, type PostgresDatabaseConfig, PostgresStorageProvider, ProviderNotConfiguredError, type RecallExplainResponse, type RecallExplanationHit, type RecallOptions, type RecallResult, type RememberAction, type RememberOptions, type RememberResult, type RerankDocument, type RerankHit, type RerankerProvider, type RetrievalConfig, SDK_VERSION, SentenceChunkingStrategy, SqliteCheckpointProvider, type SqliteDatabaseConfig, SqliteDatabaseProvider, SqliteEventDatabase, SqliteGraphProvider, SqliteStorageProvider, SqliteTelemetryProvider, type StageSpan, type StatsResult, type StorageConfig, StorageLockedError, type StorageProvider, type StorageProviderName, type SubscribableEvent, type SubscribeFilter, type TelemetryConfig, TelemetryEmitter, type TelemetryEvent, type TelemetryEventInput, type TelemetryLogLevel, type TelemetryOperation, type TelemetryProvider, type TelemetryQuery, type TelemetryQueryResult, type TelemetryStatus, type Unsubscribe, ValidationError, type VisionProvider, type VisionResult, Wolbarg, WolbargError, WolbargLogger, type WolbargOptions, type WolbargOptionsWithLlm, type WolbargOptionsWithoutLlm, bgeReranker, bm25, cohereReranker, createChunkingStrategy, createCompressionProvider, createDatabaseProvider, createEmbeddingProvider, createLlmProvider, createStorageProvider, createTelemetryProvider, wolbarg as createWolbarg, crossEncoder, geminiEmbedding, geminiVision, jinaReranker, lmStudioEmbedding, meta, neo4jGraph, ollamaEmbedding, ollamaLlm, openRouterEmbedding, openRouterLlm, openaiCompatibleEmbedding, openaiCompatibleLlm, openaiEmbedding, openaiLlm, openaiReranker, openaiVision, postgres, postgresConfig, runBenchmark, sqlite, sqliteCheckpoint, sqliteConfig, sqliteGraph, sqliteTelemetry, summarizeBenchmark, tesseract, togetherEmbedding, vllmEmbedding, wolbarg$1 as wolbarg, wrapOperationError };