nodebench-mcp 2.32.0 → 2.34.0

package/dist/providers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Providers barrel export — Ambient Intelligence Layer.
+ *
+ * Re-exports all memory provider interfaces, implementations, and the registry.
+ */
+export type { MemoryProvider, ProviderType, ProviderConfig, MemoryInput, Memory, MemoryRelation, RelationType, StoredRelation, RecallOptions, ListOptions, UserProfile, SyncResult, } from "./memoryProvider.js";
+export { LocalMemoryProvider } from "./localMemoryProvider.js";
+export { SupermemoryProvider, SupermemoryError, SupermemoryAuthError, SupermemoryRateLimitError, } from "./supermemoryProvider.js";
+export { MemoryProviderRegistry } from "./memoryProviderRegistry.js";

package/dist/providers/index.js

@@ -0,0 +1,12 @@
+/**
+ * Providers barrel export — Ambient Intelligence Layer.
+ *
+ * Re-exports all memory provider interfaces, implementations, and the registry.
+ */
+// Local SQLite implementation
+export { LocalMemoryProvider } from "./localMemoryProvider.js";
+// Supermemory cloud implementation
+export { SupermemoryProvider, SupermemoryError, SupermemoryAuthError, SupermemoryRateLimitError, } from "./supermemoryProvider.js";
+// Singleton registry
+export { MemoryProviderRegistry } from "./memoryProviderRegistry.js";
+//# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,8BAA8B;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,mCAAmC;AACnC,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC;AAElC,qBAAqB;AACrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/providers/localMemoryProvider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * LocalMemoryProvider — SQLite-backed MemoryProvider implementation.
+ *
+ * Uses the existing NodeBench SQLite database (via getDb()) with FTS5
+ * for full-text recall. All data stays local on disk at ~/.nodebench/nodebench.db.
+ *
+ * Tables created on connect:
+ *   - memory_items       — core memory storage
+ *   - memory_items_fts   — FTS5 virtual table for search
+ *   - memory_relations   — directed edges between memories
+ *   - memory_profiles    — cached user profile aggregates (optional)
+ *
+ * Follows the same schema patterns as db.ts (triggers for FTS sync, indexes).
+ */
+import type { MemoryProvider, ProviderConfig, MemoryInput, Memory, MemoryRelation, RecallOptions, ListOptions, UserProfile, SyncResult } from "./memoryProvider.js";
+export declare class LocalMemoryProvider implements MemoryProvider {
+    readonly name = "local-sqlite";
+    readonly type: "local";
+    private db;
+    private config;
+    private connected;
+    connect(config: ProviderConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    private ensureConnected;
+    store(memory: MemoryInput): Promise<string>;
+    update(id: string, memory: MemoryInput): Promise<void>;
+    delete(id: string): Promise<void>;
+    recall(query: string, options?: RecallOptions): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    list(options?: ListOptions): Promise<Memory[]>;
+    relate(fromId: string, toId: string, relation: MemoryRelation): Promise<void>;
+    getProfile(userId?: string): Promise<UserProfile | null>;
+    sync(direction: "push" | "pull" | "both"): Promise<SyncResult>;
+}

package/dist/providers/localMemoryProvider.js

@@ -0,0 +1,370 @@
+/**
+ * LocalMemoryProvider — SQLite-backed MemoryProvider implementation.
+ *
+ * Uses the existing NodeBench SQLite database (via getDb()) with FTS5
+ * for full-text recall. All data stays local on disk at ~/.nodebench/nodebench.db.
+ *
+ * Tables created on connect:
+ *   - memory_items       — core memory storage
+ *   - memory_items_fts   — FTS5 virtual table for search
+ *   - memory_relations   — directed edges between memories
+ *   - memory_profiles    — cached user profile aggregates (optional)
+ *
+ * Follows the same schema patterns as db.ts (triggers for FTS sync, indexes).
+ */
+import { randomUUID } from "node:crypto";
+import { getDb } from "../db.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// Schema SQL — executed once on connect
+// ═══════════════════════════════════════════════════════════════════════════
+const MEMORY_SCHEMA_SQL = `
+-- Core memory storage
+CREATE TABLE IF NOT EXISTS memory_items (
+  id          TEXT PRIMARY KEY,
+  content     TEXT NOT NULL,
+  metadata    TEXT NOT NULL DEFAULT '{}',
+  scope       TEXT NOT NULL DEFAULT 'general',
+  tags        TEXT NOT NULL DEFAULT '[]',
+  source      TEXT NOT NULL DEFAULT '',
+  user_id     TEXT NOT NULL DEFAULT 'default',
+  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_items_scope ON memory_items(scope);
+CREATE INDEX IF NOT EXISTS idx_memory_items_source ON memory_items(source);
+CREATE INDEX IF NOT EXISTS idx_memory_items_user ON memory_items(user_id);
+CREATE INDEX IF NOT EXISTS idx_memory_items_created ON memory_items(created_at);
+
+-- FTS5 for full-text search
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_items_fts USING fts5(
+  content,
+  scope,
+  tags,
+  source,
+  content='memory_items',
+  content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS memory_items_fts_insert AFTER INSERT ON memory_items BEGIN
+  INSERT INTO memory_items_fts(rowid, content, scope, tags, source)
+  VALUES (new.rowid, new.content, new.scope, new.tags, new.source);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memory_items_fts_delete AFTER DELETE ON memory_items BEGIN
+  INSERT INTO memory_items_fts(memory_items_fts, rowid, content, scope, tags, source)
+  VALUES ('delete', old.rowid, old.content, old.scope, old.tags, old.source);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memory_items_fts_update AFTER UPDATE ON memory_items BEGIN
+  INSERT INTO memory_items_fts(memory_items_fts, rowid, content, scope, tags, source)
+  VALUES ('delete', old.rowid, old.content, old.scope, old.tags, old.source);
+  INSERT INTO memory_items_fts(rowid, content, scope, tags, source)
+  VALUES (new.rowid, new.content, new.scope, new.tags, new.source);
+END;
+
+-- Directed relations between memories
+CREATE TABLE IF NOT EXISTS memory_relations (
+  id          TEXT PRIMARY KEY,
+  from_id     TEXT NOT NULL REFERENCES memory_items(id) ON DELETE CASCADE,
+  to_id       TEXT NOT NULL REFERENCES memory_items(id) ON DELETE CASCADE,
+  type        TEXT NOT NULL,
+  label       TEXT,
+  confidence  REAL DEFAULT 1.0,
+  metadata    TEXT NOT NULL DEFAULT '{}',
+  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(from_id, to_id, type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id);
+CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id);
+CREATE INDEX IF NOT EXISTS idx_memory_relations_type ON memory_relations(type);
+`;
+function rowToMemory(row, relevanceScore) {
+    let metadata = {};
+    try {
+        metadata = JSON.parse(row.metadata);
+    }
+    catch { /* keep empty */ }
+    let tags = [];
+    try {
+        tags = JSON.parse(row.tags);
+    }
+    catch { /* keep empty */ }
+    return {
+        id: row.id,
+        content: row.content,
+        metadata,
+        scope: row.scope,
+        tags,
+        source: row.source,
+        userId: row.user_id,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        ...(relevanceScore !== undefined ? { relevanceScore } : {}),
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// LocalMemoryProvider
+// ═══════════════════════════════════════════════════════════════════════════
+export class LocalMemoryProvider {
+    name = "local-sqlite";
+    type = "local";
+    db = null;
+    config = {};
+    connected = false;
+    // ── Lifecycle ──────────────────────────────────────────────────────────
+    async connect(config) {
+        this.config = config;
+        this.db = getDb();
+        this.db.exec(MEMORY_SCHEMA_SQL);
+        this.connected = true;
+    }
+    async disconnect() {
+        // We don't close the shared DB — other modules use it.
+        // Just mark ourselves as disconnected.
+        this.connected = false;
+        this.db = null;
+    }
+    isConnected() {
+        return this.connected && this.db !== null;
+    }
+    ensureConnected() {
+        if (!this.db || !this.connected) {
+            throw new Error("LocalMemoryProvider is not connected — call connect() first");
+        }
+        return this.db;
+    }
+    // ── CRUD ───────────────────────────────────────────────────────────────
+    async store(memory) {
+        const db = this.ensureConnected();
+        const id = randomUUID();
+        const now = new Date().toISOString();
+        const userId = memory.userId ?? this.config.userId ?? "default";
+        db.prepare(`
+      INSERT INTO memory_items (id, content, metadata, scope, tags, source, user_id, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, memory.content, JSON.stringify(memory.metadata ?? {}), memory.scope ?? "general", JSON.stringify(memory.tags ?? []), memory.source ?? "", userId, memory.timestamp ?? now, now);
+        return id;
+    }
+    async update(id, memory) {
+        const db = this.ensureConnected();
+        const now = new Date().toISOString();
+        const existing = db.prepare("SELECT id FROM memory_items WHERE id = ?").get(id);
+        if (!existing) {
+            throw new Error(`Memory not found: ${id}`);
+        }
+        db.prepare(`
+      UPDATE memory_items
+      SET content = ?, metadata = ?, scope = ?, tags = ?, source = ?, updated_at = ?
+      WHERE id = ?
+    `).run(memory.content, JSON.stringify(memory.metadata ?? {}), memory.scope ?? "general", JSON.stringify(memory.tags ?? []), memory.source ?? "", now, id);
+    }
+    async delete(id) {
+        const db = this.ensureConnected();
+        const result = db.prepare("DELETE FROM memory_items WHERE id = ?").run(id);
+        if (result.changes === 0) {
+            throw new Error(`Memory not found: ${id}`);
+        }
+    }
+    // ── Retrieval ──────────────────────────────────────────────────────────
+    async recall(query, options) {
+        const db = this.ensureConnected();
+        const limit = options?.limit ?? 10;
+        // Build FTS5 query — escape special characters for safety
+        const safeQuery = query
+            .replace(/['"]/g, " ")
+            .replace(/[^\w\s-]/g, " ")
+            .trim();
+        if (!safeQuery)
+            return [];
+        // FTS5 search with BM25 ranking
+        const whereClauses = [];
+        const params = [];
+        // Base FTS match
+        const ftsQuery = safeQuery
+            .split(/\s+/)
+            .filter((w) => w.length > 0)
+            .map((w) => `"${w}"`)
+            .join(" OR ");
+        if (!ftsQuery)
+            return [];
+        // Optional filters applied as post-filter on joined rows
+        let filterSql = "";
+        if (options?.scope) {
+            whereClauses.push("m.scope = ?");
+            params.push(options.scope);
+        }
+        if (options?.source) {
+            whereClauses.push("m.source = ?");
+            params.push(options.source);
+        }
+        if (options?.userId) {
+            whereClauses.push("m.user_id = ?");
+            params.push(options.userId);
+        }
+        else if (this.config.userId) {
+            whereClauses.push("m.user_id = ?");
+            params.push(this.config.userId);
+        }
+        if (options?.after) {
+            whereClauses.push("m.created_at > ?");
+            params.push(options.after);
+        }
+        if (options?.before) {
+            whereClauses.push("m.created_at < ?");
+            params.push(options.before);
+        }
+        if (whereClauses.length > 0) {
+            filterSql = " AND " + whereClauses.join(" AND ");
+        }
+        const sql = `
+      SELECT m.*, rank
+      FROM memory_items_fts fts
+      JOIN memory_items m ON m.rowid = fts.rowid
+      WHERE memory_items_fts MATCH ?${filterSql}
+      ORDER BY rank
+      LIMIT ?
+    `;
+        const rows = db.prepare(sql).all(ftsQuery, ...params, limit);
+        // Normalize BM25 rank to 0-1 relevance score
+        const maxRank = rows.length > 0
+            ? Math.max(...rows.map((r) => Math.abs(r.rank ?? 0)), 1)
+            : 1;
+        const results = rows.map((row) => {
+            const absRank = Math.abs(row.rank ?? 0);
+            const score = maxRank > 0 ? absRank / maxRank : 0;
+            return rowToMemory(row, score);
+        });
+        // Post-filter by tags if specified
+        if (options?.tags && options.tags.length > 0) {
+            const tagSet = new Set(options.tags);
+            return results.filter((m) => m.tags.some((t) => tagSet.has(t)));
+        }
+        // Post-filter by minScore
+        if (options?.minScore !== undefined) {
+            return results.filter((m) => (m.relevanceScore ?? 0) >= (options.minScore ?? 0));
+        }
+        return results;
+    }
+    async get(id) {
+        const db = this.ensureConnected();
+        const row = db.prepare("SELECT * FROM memory_items WHERE id = ?").get(id);
+        return row ? rowToMemory(row) : null;
+    }
+    async list(options) {
+        const db = this.ensureConnected();
+        const limit = options?.limit ?? 50;
+        const offset = options?.offset ?? 0;
+        const orderBy = options?.orderBy === "updatedAt"
+            ? "updated_at"
+            : "created_at";
+        const direction = options?.orderDirection === "asc" ? "ASC" : "DESC";
+        const whereClauses = [];
+        const params = [];
+        if (options?.scope) {
+            whereClauses.push("scope = ?");
+            params.push(options.scope);
+        }
+        if (options?.source) {
+            whereClauses.push("source = ?");
+            params.push(options.source);
+        }
+        if (options?.userId) {
+            whereClauses.push("user_id = ?");
+            params.push(options.userId);
+        }
+        else if (this.config.userId) {
+            whereClauses.push("user_id = ?");
+            params.push(this.config.userId);
+        }
+        const whereClause = whereClauses.length > 0 ? "WHERE " + whereClauses.join(" AND ") : "";
+        const sql = `
+      SELECT * FROM memory_items
+      ${whereClause}
+      ORDER BY ${orderBy} ${direction}
+      LIMIT ? OFFSET ?
+    `;
+        const rows = db.prepare(sql).all(...params, limit, offset);
+        let results = rows.map((row) => rowToMemory(row));
+        // Post-filter by tags if specified
+        if (options?.tags && options.tags.length > 0) {
+            const tagSet = new Set(options.tags);
+            results = results.filter((m) => m.tags.some((t) => tagSet.has(t)));
+        }
+        return results;
+    }
+    // ── Relations ──────────────────────────────────────────────────────────
+    async relate(fromId, toId, relation) {
+        const db = this.ensureConnected();
+        const id = randomUUID();
+        // Verify both memories exist
+        const fromExists = db.prepare("SELECT id FROM memory_items WHERE id = ?").get(fromId);
+        const toExists = db.prepare("SELECT id FROM memory_items WHERE id = ?").get(toId);
+        if (!fromExists)
+            throw new Error(`Source memory not found: ${fromId}`);
+        if (!toExists)
+            throw new Error(`Target memory not found: ${toId}`);
+        db.prepare(`
+      INSERT OR REPLACE INTO memory_relations (id, from_id, to_id, type, label, confidence, metadata, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
+    `).run(id, fromId, toId, relation.type, relation.label ?? null, relation.confidence ?? 1.0, JSON.stringify(relation.metadata ?? {}));
+    }
+    // ── Profile ────────────────────────────────────────────────────────────
+    async getProfile(userId) {
+        const db = this.ensureConnected();
+        const uid = userId ?? this.config.userId ?? "default";
+        const countRow = db.prepare("SELECT COUNT(*) as c FROM memory_items WHERE user_id = ?").get(uid);
+        if (countRow.c === 0)
+            return null;
+        const scopeRows = db.prepare("SELECT DISTINCT scope FROM memory_items WHERE user_id = ?").all(uid);
+        const firstRow = db.prepare("SELECT created_at FROM memory_items WHERE user_id = ? ORDER BY created_at ASC LIMIT 1").get(uid);
+        const lastRow = db.prepare("SELECT created_at FROM memory_items WHERE user_id = ? ORDER BY created_at DESC LIMIT 1").get(uid);
+        // Aggregate tags — parse JSON arrays and count
+        const allRows = db.prepare("SELECT tags, source FROM memory_items WHERE user_id = ?").all(uid);
+        const tagCounts = new Map();
+        const sourceCounts = new Map();
+        for (const row of allRows) {
+            try {
+                const tags = JSON.parse(row.tags);
+                for (const tag of tags) {
+                    tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+                }
+            }
+            catch { /* skip malformed */ }
+            if (row.source) {
+                sourceCounts.set(row.source, (sourceCounts.get(row.source) ?? 0) + 1);
+            }
+        }
+        const topTags = [...tagCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([tag, count]) => ({ tag, count }));
+        const topSources = [...sourceCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([source, count]) => ({ source, count }));
+        return {
+            userId: uid,
+            memoryCount: countRow.c,
+            scopes: scopeRows.map((r) => r.scope),
+            topTags,
+            topSources,
+            firstMemoryAt: firstRow?.created_at ?? null,
+            lastMemoryAt: lastRow?.created_at ?? null,
+        };
+    }
+    // ── Sync ───────────────────────────────────────────────────────────────
+    async sync(direction) {
+        // Local provider — no remote to sync with. Return no-op result.
+        return {
+            direction,
+            pushed: 0,
+            pulled: 0,
+            conflicts: 0,
+            errors: 0,
+            completedAt: new Date().toISOString(),
+        };
+    }
+}
+//# sourceMappingURL=localMemoryProvider.js.map

package/dist/providers/localMemoryProvider.js.map

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

package/dist/providers/memoryProvider.d.ts

@@ -0,0 +1,187 @@
+/**
+ * MemoryProvider — Abstract interface for NodeBench's Ambient Intelligence Layer.
+ *
+ * Defines the contract that all memory providers (local SQLite, Supermemory,
+ * Zep, Graphiti, custom) must implement. Enables multi-provider memory
+ * with unified recall, relation graphs, user profiles, and bidirectional sync.
+ *
+ * Design principles:
+ *   - Every provider is independently usable (store/recall/relate)
+ *   - Sync is optional — local-first providers may no-op
+ *   - Relations form an entity graph across memories
+ *   - Profiles aggregate user-level context from memories
+ */
+export type ProviderType = "supermemory" | "local" | "zep" | "graphiti" | "custom";
+export interface ProviderConfig {
+    /** Provider-specific API key or token */
+    apiKey?: string;
+    /** Base URL for remote providers */
+    baseUrl?: string;
+    /** User ID scope (isolates memories per user) */
+    userId?: string;
+    /** Additional provider-specific settings */
+    options?: Record<string, unknown>;
+}
+export interface MemoryInput {
+    /** Raw content to store */
+    content: string;
+    /** Optional structured metadata */
+    metadata?: Record<string, unknown>;
+    /** Categorization scope (e.g. "project", "entity", "decision", "conversation") */
+    scope?: string;
+    /** Tags for filtering and grouping */
+    tags?: string[];
+    /** Source identifier (e.g. tool name, agent ID, session ID) */
+    source?: string;
+    /** ISO 8601 timestamp override (defaults to now) */
+    timestamp?: string;
+    /** Optional user ID (defaults to provider config userId) */
+    userId?: string;
+}
+export interface Memory {
+    /** Unique memory ID (provider-generated) */
+    id: string;
+    /** Raw content */
+    content: string;
+    /** Structured metadata */
+    metadata: Record<string, unknown>;
+    /** Categorization scope */
+    scope: string;
+    /** Tags */
+    tags: string[];
+    /** Source identifier */
+    source: string;
+    /** User ID that owns this memory */
+    userId: string;
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+    /** ISO 8601 last-update timestamp */
+    updatedAt: string;
+    /** Relevance score (0-1, set during recall) */
+    relevanceScore?: number;
+}
+export type RelationType = "related_to" | "caused_by" | "supports" | "contradicts" | "follows" | "references" | "part_of" | "derived_from";
+export interface MemoryRelation {
+    /** Relation type */
+    type: RelationType;
+    /** Optional human-readable label */
+    label?: string;
+    /** Confidence score (0-1) */
+    confidence?: number;
+    /** Additional relation metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface StoredRelation extends MemoryRelation {
+    /** Unique relation ID */
+    id: string;
+    /** Source memory ID */
+    fromId: string;
+    /** Target memory ID */
+    toId: string;
+    /** ISO 8601 creation timestamp */
+    createdAt: string;
+}
+export interface RecallOptions {
+    /** Maximum results to return (default: 10) */
+    limit?: number;
+    /** Filter by scope */
+    scope?: string;
+    /** Filter by tags (any match) */
+    tags?: string[];
+    /** Filter by source */
+    source?: string;
+    /** Filter by user ID */
+    userId?: string;
+    /** Minimum relevance score (0-1) for semantic search */
+    minScore?: number;
+    /** ISO 8601 — only memories after this date */
+    after?: string;
+    /** ISO 8601 — only memories before this date */
+    before?: string;
+}
+export interface ListOptions {
+    /** Maximum results (default: 50) */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Filter by scope */
+    scope?: string;
+    /** Filter by tags (any match) */
+    tags?: string[];
+    /** Filter by source */
+    source?: string;
+    /** Filter by user ID */
+    userId?: string;
+    /** Sort order */
+    orderBy?: "createdAt" | "updatedAt" | "relevanceScore";
+    /** Sort direction */
+    orderDirection?: "asc" | "desc";
+}
+export interface UserProfile {
+    /** User ID */
+    userId: string;
+    /** Total memory count for this user */
+    memoryCount: number;
+    /** Scopes used by this user */
+    scopes: string[];
+    /** Most used tags */
+    topTags: Array<{
+        tag: string;
+        count: number;
+    }>;
+    /** Most active sources */
+    topSources: Array<{
+        source: string;
+        count: number;
+    }>;
+    /** ISO 8601 timestamp of earliest memory */
+    firstMemoryAt: string | null;
+    /** ISO 8601 timestamp of most recent memory */
+    lastMemoryAt: string | null;
+}
+export interface SyncResult {
+    /** Sync direction that was executed */
+    direction: "push" | "pull" | "both";
+    /** Number of memories pushed to remote */
+    pushed: number;
+    /** Number of memories pulled from remote */
+    pulled: number;
+    /** Number of conflicts detected */
+    conflicts: number;
+    /** Number of errors during sync */
+    errors: number;
+    /** ISO 8601 timestamp of sync completion */
+    completedAt: string;
+    /** Error details if any */
+    errorDetails?: string[];
+}
+export interface MemoryProvider {
+    /** Human-readable provider name (e.g. "local-sqlite", "supermemory") */
+    readonly name: string;
+    /** Provider type for registry classification */
+    readonly type: ProviderType;
+    /** Initialize connection to the provider backend */
+    connect(config: ProviderConfig): Promise<void>;
+    /** Gracefully disconnect from the provider backend */
+    disconnect(): Promise<void>;
+    /** Check if the provider is currently connected and operational */
+    isConnected(): boolean;
+    /** Store a new memory. Returns the generated memory ID. */
+    store(memory: MemoryInput): Promise<string>;
+    /** Update an existing memory by ID. */
+    update(id: string, memory: MemoryInput): Promise<void>;
+    /** Delete a memory by ID. */
+    delete(id: string): Promise<void>;
+    /** Semantic/keyword recall — search memories by natural language query. */
+    recall(query: string, options?: RecallOptions): Promise<Memory[]>;
+    /** Get a single memory by ID. Returns null if not found. */
+    get(id: string): Promise<Memory | null>;
+    /** List memories with filtering and pagination. */
+    list(options?: ListOptions): Promise<Memory[]>;
+    /** Create a directed relation between two memories. */
+    relate(fromId: string, toId: string, relation: MemoryRelation): Promise<void>;
+    /** Get aggregated profile for a user. Uses provider config userId if omitted. */
+    getProfile(userId?: string): Promise<UserProfile | null>;
+    /** Synchronize memories with a remote backend. */
+    sync(direction: "push" | "pull" | "both"): Promise<SyncResult>;
+}

package/dist/providers/memoryProvider.js

@@ -0,0 +1,15 @@
+/**
+ * MemoryProvider — Abstract interface for NodeBench's Ambient Intelligence Layer.
+ *
+ * Defines the contract that all memory providers (local SQLite, Supermemory,
+ * Zep, Graphiti, custom) must implement. Enables multi-provider memory
+ * with unified recall, relation graphs, user profiles, and bidirectional sync.
+ *
+ * Design principles:
+ *   - Every provider is independently usable (store/recall/relate)
+ *   - Sync is optional — local-first providers may no-op
+ *   - Relations form an entity graph across memories
+ *   - Profiles aggregate user-level context from memories
+ */
+export {};
+//# sourceMappingURL=memoryProvider.js.map

package/dist/providers/memoryProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryProvider.js","sourceRoot":"","sources":["../../src/providers/memoryProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}