@monoes/memory 1.0.10 → 1.0.11

package/dist/sql-backend.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Unified SQL memory backend.
+ *
+ * One IMemoryBackend implementation over a pluggable SqlDriver, replacing the
+ * two near-parallel implementations (better-sqlite3 and sql.js) that together
+ * ran to ~1,780 lines. They had already drifted in ways users could observe:
+ * different schemas, different tag-filter semantics (ANY vs ALL for the same
+ * call), tag validation on one and not the other, and a crash on the sql.js
+ * side when reading a missing row. Sharing the logic removes that class of bug
+ * rather than testing for it after the fact.
+ *
+ * Driver differences (cursors, transactions, persistence, pragmas) live in
+ * sql-driver.ts; the canonical schema and the legacy-data migration live in
+ * sql-schema.ts. This file contains only behaviour.
+ *
+ * @module v1/memory/sql-backend
+ */
+import { EventEmitter } from 'node:events';
+import type { SqlDriver } from './sql-driver.js';
+import { type MigrationReport } from './sql-schema.js';
+import { IMemoryBackend, MemoryEntry, MemoryEntryUpdate, MemoryQuery, SearchOptions, SearchResult, BackendStats, HealthCheckResult, EmbeddingGenerator } from './types.js';
+export interface SqlBackendConfig {
+    /** Default namespace applied when an entry omits one. */
+    defaultNamespace: string;
+    /** Embedding generator, for callers that store text and want vectors. */
+    embeddingGenerator?: EmbeddingGenerator;
+    /** Soft cap used by healthCheck to report utilization. */
+    maxEntries: number;
+    verbose: boolean;
+}
+export declare class SqlBackend extends EventEmitter implements IMemoryBackend {
+    protected config: SqlBackendConfig;
+    protected driver: SqlDriver | null;
+    protected initialized: boolean;
+    /** Populated during initialize(); surfaced for diagnostics. */
+    migrationReport: MigrationReport | null;
+    private stats;
+    /** Debounce counter: the agent_reads purge is expensive, so it is amortised. */
+    private _readCount;
+    constructor(config?: Partial<SqlBackendConfig>);
+    /** Subclasses open their driver here. */
+    protected openDriver(): Promise<SqlDriver>;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    store(entry: MemoryEntry): Promise<void>;
+    /** Synchronous store body, shared by store() and bulkInsert(). */
+    private storeSync;
+    bulkInsert(entries: MemoryEntry[]): Promise<void>;
+    update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+    delete(id: string): Promise<boolean>;
+    bulkDelete(ids: string[]): Promise<number>;
+    clearNamespace(namespace: string): Promise<number>;
+    get(id: string, agentId?: string): Promise<MemoryEntry | null>;
+    /**
+     * Promote an entry to 'team' once 3+ distinct agents have read it within 24h.
+     * https://arxiv.org/abs/2505.18279
+     */
+    private checkAndPromoteEntry;
+    getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+    query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /**
+     * Semantic search — brute-force cosine over stored embeddings, namespace- and
+     * TTL-filtered in SQL. At second-brain scale (10^3–10^5 vectors of 384 dims)
+     * this is a few tens of ms; swap in an ANN index if a profiled workload
+     * outgrows it.
+     */
+    search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+    count(namespace?: string): Promise<number>;
+    listNamespaces(): Promise<string[]>;
+    getStats(): Promise<BackendStats>;
+    healthCheck(): Promise<HealthCheckResult>;
+    /** Flush to durable storage. No-op on write-through drivers. */
+    persist(): Promise<void>;
+    private static readonly TAG_RE;
+    private static readonly SRC_TAG_RE;
+    private static readonly MAX_TAG_LEN;
+    protected validateTags(tags: string[]): void;
+    protected ensureInitialized(): void;
+    private rowToEntry;
+}
+//# sourceMappingURL=sql-backend.d.ts.map

package/dist/sql-backend.d.ts.map

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

package/dist/sql-backend.js

@@ -0,0 +1,553 @@
+/**
+ * Unified SQL memory backend.
+ *
+ * One IMemoryBackend implementation over a pluggable SqlDriver, replacing the
+ * two near-parallel implementations (better-sqlite3 and sql.js) that together
+ * ran to ~1,780 lines. They had already drifted in ways users could observe:
+ * different schemas, different tag-filter semantics (ANY vs ALL for the same
+ * call), tag validation on one and not the other, and a crash on the sql.js
+ * side when reading a missing row. Sharing the logic removes that class of bug
+ * rather than testing for it after the fact.
+ *
+ * Driver differences (cursors, transactions, persistence, pragmas) live in
+ * sql-driver.ts; the canonical schema and the legacy-data migration live in
+ * sql-schema.ts. This file contains only behaviour.
+ *
+ * @module v1/memory/sql-backend
+ */
+import { EventEmitter } from 'node:events';
+import { cosineSimilarity } from './math-utils.js';
+import { initializeSchema } from './sql-schema.js';
+const DEFAULT_CONFIG = {
+    defaultNamespace: 'default',
+    maxEntries: 1_000_000,
+    verbose: false,
+};
+/** Cap on votes/rows pulled in one go, guarding against unbounded memory use. */
+const MAX_QUERY_LIMIT = 10_000;
+export class SqlBackend extends EventEmitter {
+    config;
+    driver = null;
+    initialized = false;
+    /** Populated during initialize(); surfaced for diagnostics. */
+    migrationReport = null;
+    stats = { queryCount: 0, totalQueryTime: 0, writeCount: 0, totalWriteTime: 0 };
+    /** Debounce counter: the agent_reads purge is expensive, so it is amortised. */
+    _readCount = 0;
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /** Subclasses open their driver here. */
+    async openDriver() {
+        throw new Error('SqlBackend.openDriver() must be implemented by a subclass');
+    }
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.driver = await this.openDriver();
+        // Enable FK enforcement — required for ON DELETE CASCADE to fire.
+        try {
+            this.driver.exec('PRAGMA foreign_keys = ON');
+        }
+        catch {
+            /* unsupported on this driver */
+        }
+        this.migrationReport = initializeSchema(this.driver);
+        if (this.config.verbose && this.migrationReport.legacyColumnFound) {
+            console.log(`[SqlBackend] migrated ${this.migrationReport.migrated} inline embedding(s); ` +
+                `${this.migrationReport.skipped} already present`);
+        }
+        this.initialized = true;
+        this.emit('initialized');
+    }
+    async shutdown() {
+        if (!this.initialized || !this.driver)
+            return;
+        await this.driver.persist();
+        try {
+            this.driver.pragma('optimize');
+        }
+        catch {
+            /* not supported everywhere */
+        }
+        this.driver.close();
+        this.driver = null;
+        this.initialized = false;
+        this.emit('shutdown');
+    }
+    // ===== Writes ============================================================
+    async store(entry) {
+        this.ensureInitialized();
+        const startTime = performance.now();
+        this.validateTags(entry.tags);
+        this.driver.transaction(() => this.storeSync(entry));
+        const duration = performance.now() - startTime;
+        this.stats.writeCount++;
+        this.stats.totalWriteTime += duration;
+        this.emit('entry:stored', { id: entry.id, duration });
+    }
+    /** Synchronous store body, shared by store() and bulkInsert(). */
+    storeSync(entry) {
+        const d = this.driver;
+        // Read any existing embedding BEFORE INSERT OR REPLACE fires the CASCADE
+        // that would delete it — an entry updated without a vector must keep the
+        // one it already had.
+        let embeddingToStore = entry.embedding;
+        if (!embeddingToStore) {
+            const existing = d.get('SELECT embedding FROM memory_embeddings WHERE entry_id = ?', [entry.id]);
+            const buf = existing?.embedding;
+            if (buf && buf.byteLength > 0) {
+                embeddingToStore = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+            }
+        }
+        d.run(`INSERT OR REPLACE INTO memory_entries (
+         id, key, content, type, namespace, tags, metadata, owner_id, access_level,
+         created_at, updated_at, expires_at, event_at, version, "references",
+         access_count, last_accessed_at
+       ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [
+            entry.id, entry.key, entry.content, entry.type, entry.namespace,
+            JSON.stringify(entry.tags), JSON.stringify(entry.metadata),
+            entry.ownerId || null, entry.accessLevel,
+            entry.createdAt, entry.updatedAt, entry.expiresAt || null, entry.eventAt ?? null,
+            entry.version, JSON.stringify(entry.references), entry.accessCount, entry.lastAccessedAt,
+        ]);
+        d.run('DELETE FROM memory_entry_tags WHERE entry_id = ?', [entry.id]);
+        for (const tag of entry.tags) {
+            d.run('INSERT OR IGNORE INTO memory_entry_tags (entry_id, tag) VALUES (?, ?)', [entry.id, tag]);
+        }
+        if (embeddingToStore) {
+            // Slice by byteOffset/byteLength: for copies under Node's 4KB pooling
+            // threshold, `.buffer` refers to the entire shared pool, so writing it
+            // whole silently stores unrelated memory.
+            const bytes = Buffer.from(embeddingToStore.buffer, embeddingToStore.byteOffset, embeddingToStore.byteLength);
+            d.run('INSERT OR REPLACE INTO memory_embeddings (entry_id, embedding) VALUES (?, ?)', [
+                entry.id,
+                bytes,
+            ]);
+        }
+    }
+    async bulkInsert(entries) {
+        this.ensureInitialized();
+        for (const e of entries)
+            this.validateTags(e.tags);
+        this.driver.transaction(() => {
+            for (const entry of entries)
+                this.storeSync(entry);
+        });
+        this.emit('bulk:inserted', { count: entries.length });
+    }
+    async update(id, update) {
+        this.ensureInitialized();
+        const entry = await this.get(id);
+        if (!entry)
+            return null;
+        if (update.content !== undefined)
+            entry.content = update.content;
+        if (update.tags !== undefined)
+            entry.tags = update.tags;
+        if (update.metadata !== undefined)
+            entry.metadata = { ...entry.metadata, ...update.metadata };
+        if (update.accessLevel !== undefined)
+            entry.accessLevel = update.accessLevel;
+        if (update.expiresAt !== undefined)
+            entry.expiresAt = update.expiresAt;
+        if (update.references !== undefined)
+            entry.references = update.references;
+        entry.updatedAt = Date.now();
+        entry.version++;
+        await this.store(entry);
+        this.emit('entry:updated', { id });
+        return entry;
+    }
+    async delete(id) {
+        this.ensureInitialized();
+        const d = this.driver;
+        // Explicit tag cleanup as well as the CASCADE — belt and braces, since FK
+        // enforcement is a pragma that not every driver honours.
+        d.run('DELETE FROM memory_entry_tags WHERE entry_id = ?', [id]);
+        d.run('DELETE FROM memory_embeddings WHERE entry_id = ?', [id]);
+        const changes = d.run('DELETE FROM memory_entries WHERE id = ?', [id]);
+        if (changes > 0) {
+            this.emit('entry:deleted', { id });
+            return true;
+        }
+        return false;
+    }
+    async bulkDelete(ids) {
+        this.ensureInitialized();
+        const d = this.driver;
+        const count = d.transaction(() => {
+            let deleted = 0;
+            for (const id of ids) {
+                d.run('DELETE FROM memory_entry_tags WHERE entry_id = ?', [id]);
+                d.run('DELETE FROM memory_embeddings WHERE entry_id = ?', [id]);
+                if (d.run('DELETE FROM memory_entries WHERE id = ?', [id]) > 0)
+                    deleted++;
+            }
+            return deleted;
+        });
+        this.emit('bulk:deleted', { count });
+        return count;
+    }
+    async clearNamespace(namespace) {
+        this.ensureInitialized();
+        const d = this.driver;
+        const count = d.transaction(() => {
+            d.run(`DELETE FROM memory_entry_tags
+          WHERE entry_id IN (SELECT id FROM memory_entries WHERE namespace = ?)`, [namespace]);
+            const changes = d.run('DELETE FROM memory_entries WHERE namespace = ?', [namespace]);
+            d.run('DELETE FROM memory_embeddings WHERE entry_id NOT IN (SELECT id FROM memory_entries)');
+            return changes;
+        });
+        this.emit('namespace:cleared', { namespace, count });
+        return count;
+    }
+    // ===== Reads =============================================================
+    async get(id, agentId) {
+        this.ensureInitialized();
+        const startTime = performance.now();
+        const row = this.driver.get('SELECT * FROM memory_entries WHERE id = ?', [id]);
+        if (!row)
+            return null;
+        // Collaborative memory promotion — https://arxiv.org/abs/2505.18279
+        const AGENT_ID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
+        if (agentId && AGENT_ID_RE.test(agentId)) {
+            try {
+                this.driver.run('INSERT OR IGNORE INTO agent_reads (entry_id, agent_id, read_at) VALUES (?, ?, ?)', [id, agentId, Date.now()]);
+                this._readCount++;
+                if (this._readCount % 1000 === 0)
+                    this.checkAndPromoteEntry(id);
+            }
+            catch {
+                /* non-critical */
+            }
+        }
+        const entry = this.rowToEntry(row);
+        this.emit('entry:retrieved', { id, duration: performance.now() - startTime });
+        return entry;
+    }
+    /**
+     * Promote an entry to 'team' once 3+ distinct agents have read it within 24h.
+     * https://arxiv.org/abs/2505.18279
+     */
+    checkAndPromoteEntry(entryId) {
+        const d = this.driver;
+        if (!d)
+            return;
+        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+        d.run('DELETE FROM agent_reads WHERE read_at <= ?', [cutoff]);
+        const row = d.get('SELECT COUNT(DISTINCT agent_id) as cnt FROM agent_reads WHERE entry_id = ? AND read_at > ?', [entryId, cutoff]);
+        if (Number(row?.cnt ?? 0) >= 3) {
+            d.run("UPDATE memory_entries SET access_level = 'team' WHERE id = ? AND access_level = 'private'", [
+                entryId,
+            ]);
+        }
+    }
+    async getByKey(namespace, key) {
+        this.ensureInitialized();
+        const startTime = performance.now();
+        const row = this.driver.get('SELECT * FROM memory_entries WHERE namespace = ? AND key = ?', [
+            namespace,
+            key,
+        ]);
+        if (!row)
+            return null;
+        const entry = this.rowToEntry(row);
+        this.emit('entry:retrieved', { namespace, key, duration: performance.now() - startTime });
+        return entry;
+    }
+    async query(query) {
+        this.ensureInitialized();
+        const startTime = performance.now();
+        let sql = 'SELECT * FROM memory_entries WHERE 1=1';
+        const params = [];
+        if (query.namespace) {
+            sql += ' AND namespace = ?';
+            params.push(query.namespace);
+        }
+        if (query.key) {
+            sql += ' AND key = ?';
+            params.push(query.key);
+        }
+        if (query.keyPrefix) {
+            sql += ' AND key LIKE ?';
+            params.push(`${query.keyPrefix}%`);
+        }
+        if (query.memoryType) {
+            sql += ' AND type = ?';
+            params.push(query.memoryType);
+        }
+        if (query.accessLevel) {
+            sql += ' AND access_level = ?';
+            params.push(query.accessLevel);
+        }
+        if (query.ownerId) {
+            sql += ' AND owner_id = ?';
+            params.push(query.ownerId);
+        }
+        if (query.createdAfter) {
+            sql += ' AND created_at >= ?';
+            params.push(query.createdAfter);
+        }
+        if (query.createdBefore) {
+            sql += ' AND created_at <= ?';
+            params.push(query.createdBefore);
+        }
+        if (query.updatedAfter) {
+            sql += ' AND updated_at >= ?';
+            params.push(query.updatedAfter);
+        }
+        if (query.updatedBefore) {
+            sql += ' AND updated_at <= ?';
+            params.push(query.updatedBefore);
+        }
+        // Bi-temporal event-time filters (arXiv:2501.13956 — Zep/Graphiti)
+        if (query.eventAfter) {
+            sql += ' AND event_at >= ?';
+            params.push(query.eventAfter);
+        }
+        if (query.eventBefore) {
+            sql += ' AND event_at <= ?';
+            params.push(query.eventBefore);
+        }
+        if (!query.includeExpired) {
+            sql += ' AND (expires_at IS NULL OR expires_at > ?)';
+            params.push(Date.now());
+        }
+        // MemoryQuery.tags is documented as "entries must have all specified tags"
+        // (types.ts). Counting distinct matches enforces that; an EXISTS(... IN ...)
+        // would be ANY-match, which is exactly the divergence that made the two old
+        // backends return different result sets for the same call.
+        if (query.tags && query.tags.length > 0) {
+            this.validateTags(query.tags);
+            const placeholders = query.tags.map(() => '?').join(', ');
+            sql += ` AND (
+        SELECT COUNT(DISTINCT t.tag) FROM memory_entry_tags t
+        WHERE t.entry_id = memory_entries.id AND t.tag IN (${placeholders})
+      ) = ?`;
+            params.push(...query.tags, query.tags.length);
+        }
+        const colMap = {
+            createdAt: 'created_at', updatedAt: 'updated_at',
+            lastAccessedAt: 'last_accessed_at', accessCount: 'access_count', key: 'key',
+        };
+        const orderCol = query.sortField && query.sortField !== 'score' && colMap[query.sortField]
+            ? colMap[query.sortField]
+            : 'created_at';
+        const orderDir = query.sortDirection === 'asc' ? 'ASC' : 'DESC';
+        sql += ` ORDER BY ${orderCol} ${orderDir} LIMIT ?`;
+        const effectiveLimit = Math.min(Math.max(1, query.limit ?? MAX_QUERY_LIMIT), MAX_QUERY_LIMIT);
+        params.push(effectiveLimit);
+        if (query.offset) {
+            sql += ' OFFSET ?';
+            params.push(query.offset);
+        }
+        const rows = this.driver.all(sql, params);
+        const results = rows.map((r) => this.rowToEntry(r));
+        const duration = performance.now() - startTime;
+        this.stats.queryCount++;
+        this.stats.totalQueryTime += duration;
+        this.emit('query:executed', { query, resultCount: results.length, duration });
+        return results;
+    }
+    /**
+     * Semantic search — brute-force cosine over stored embeddings, namespace- and
+     * TTL-filtered in SQL. At second-brain scale (10^3–10^5 vectors of 384 dims)
+     * this is a few tens of ms; swap in an ANN index if a profiled workload
+     * outgrows it.
+     */
+    async search(embedding, options) {
+        this.ensureInitialized();
+        const ns = options.filters?.namespace;
+        const rows = this.driver.iterate(`SELECT e.*, emb.embedding AS _emb
+         FROM memory_entries e
+         JOIN memory_embeddings emb ON emb.entry_id = e.id
+        WHERE (e.expires_at IS NULL OR e.expires_at = 0 OR e.expires_at > ?)
+        ${ns ? 'AND e.namespace = ?' : ''}`, ns ? [Date.now(), ns] : [Date.now()]);
+        const results = [];
+        for (const row of rows) {
+            const buf = row._emb;
+            if (!buf || buf.byteLength % 4 !== 0)
+                continue;
+            const vec = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+            if (vec.length !== embedding.length)
+                continue;
+            const similarity = cosineSimilarity(embedding, vec);
+            if (options.threshold !== undefined && similarity < options.threshold)
+                continue;
+            const clean = { ...row };
+            delete clean._emb;
+            results.push({ entry: this.rowToEntry(clean), score: similarity, distance: 1 - similarity });
+        }
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, options.k);
+    }
+    async count(namespace) {
+        this.ensureInitialized();
+        const row = namespace
+            ? this.driver.get('SELECT COUNT(*) as count FROM memory_entries WHERE namespace = ?', [namespace])
+            : this.driver.get('SELECT COUNT(*) as count FROM memory_entries');
+        return Number(row?.count ?? 0);
+    }
+    async listNamespaces() {
+        this.ensureInitialized();
+        return this.driver.all('SELECT DISTINCT namespace FROM memory_entries').map((r) => String(r.namespace));
+    }
+    // ===== Introspection =====================================================
+    async getStats() {
+        this.ensureInitialized();
+        const d = this.driver;
+        const entriesByNamespace = {};
+        for (const row of d.all('SELECT namespace, COUNT(*) as count FROM memory_entries GROUP BY namespace')) {
+            entriesByNamespace[String(row.namespace)] = Number(row.count);
+        }
+        const entriesByType = {
+            episodic: 0, semantic: 0, working: 0, cache: 0,
+        };
+        for (const row of d.all('SELECT type, COUNT(*) as count FROM memory_entries GROUP BY type')) {
+            entriesByType[String(row.type)] = Number(row.count);
+        }
+        // page_count/page_size are native-only; sql.js reports 0 rather than a
+        // fabricated figure.
+        let memoryUsage = 0;
+        const pageCount = d.pragma('page_count');
+        const pageSize = d.pragma('page_size');
+        if (typeof pageCount === 'number' && typeof pageSize === 'number') {
+            memoryUsage = pageCount * pageSize;
+        }
+        return {
+            totalEntries: await this.count(),
+            entriesByNamespace,
+            entriesByType,
+            memoryUsage,
+            avgQueryTime: this.stats.queryCount > 0 ? this.stats.totalQueryTime / this.stats.queryCount : 0,
+            avgSearchTime: 0,
+        };
+    }
+    async healthCheck() {
+        const issues = [];
+        const recommendations = [];
+        if (!this.initialized || !this.driver) {
+            return {
+                status: 'unhealthy',
+                components: {
+                    storage: { status: 'unhealthy', latency: 0, message: 'Not initialized' },
+                    index: { status: 'healthy', latency: 0 },
+                    cache: { status: 'healthy', latency: 0 },
+                },
+                timestamp: Date.now(),
+                issues: ['Backend not initialized'],
+                recommendations: ['Call initialize() before using'],
+            };
+        }
+        let storageHealth;
+        try {
+            const integrity = this.driver.pragma('integrity_check');
+            if (integrity === undefined || integrity === 'ok') {
+                // undefined means the driver cannot run the check, not that it failed.
+                storageHealth = { status: 'healthy', latency: 0 };
+            }
+            else {
+                issues.push('Database integrity check failed');
+                recommendations.push('Run VACUUM to repair database');
+                storageHealth = { status: 'unhealthy', latency: 0, message: 'Integrity check failed' };
+            }
+        }
+        catch (error) {
+            issues.push('Failed to check database integrity');
+            storageHealth = { status: 'unhealthy', latency: 0, message: String(error) };
+        }
+        const totalEntries = await this.count();
+        const utilizationPercent = (totalEntries / this.config.maxEntries) * 100;
+        if (utilizationPercent > 95) {
+            issues.push('Storage utilization critical (>95%)');
+            recommendations.push('Cleanup old data or increase maxEntries');
+            storageHealth = { status: 'unhealthy', latency: 0, message: 'Near capacity' };
+        }
+        else if (utilizationPercent > 80) {
+            issues.push('Storage utilization high (>80%)');
+            recommendations.push('Consider cleanup');
+            if (storageHealth.status === 'healthy') {
+                storageHealth = { status: 'degraded', latency: 0, message: 'High utilization' };
+            }
+        }
+        const status = storageHealth.status === 'unhealthy'
+            ? 'unhealthy'
+            : storageHealth.status === 'degraded'
+                ? 'degraded'
+                : 'healthy';
+        return {
+            status,
+            components: {
+                storage: storageHealth,
+                index: { status: 'healthy', latency: 0 },
+                cache: { status: 'healthy', latency: 0 },
+            },
+            timestamp: Date.now(),
+            issues,
+            recommendations,
+        };
+    }
+    /** Flush to durable storage. No-op on write-through drivers. */
+    async persist() {
+        if (!this.driver)
+            return;
+        await this.driver.persist();
+    }
+    // ===== Internals =========================================================
+    // Every tag write is parameterized, so this is shape sanity rather than
+    // injection defense. `src:<absolute path>` provenance tags are first-class in
+    // the knowledge pipeline and legitimately contain spaces, parentheses and
+    // unicode, so they only exclude control characters.
+    static TAG_RE = /^[a-zA-Z0-9_\-.:/~ ]+$/;
+    static SRC_TAG_RE = /^src:[^\x00-\x1f\x7f]+$/;
+    static MAX_TAG_LEN = 512;
+    validateTags(tags) {
+        for (const tag of tags) {
+            const ok = typeof tag === 'string' &&
+                tag.length <= SqlBackend.MAX_TAG_LEN &&
+                (tag.startsWith('src:') ? SqlBackend.SRC_TAG_RE.test(tag) : SqlBackend.TAG_RE.test(tag));
+            if (!ok)
+                throw new Error(`Invalid tag format: "${String(tag).slice(0, 80)}"`);
+        }
+    }
+    ensureInitialized() {
+        if (!this.initialized || !this.driver) {
+            throw new Error('Backend not initialized. Call initialize() first.');
+        }
+    }
+    rowToEntry(row) {
+        let embedding;
+        const embRow = this.driver.get('SELECT embedding FROM memory_embeddings WHERE entry_id = ?', [
+            String(row.id),
+        ]);
+        const buf = embRow?.embedding;
+        if (buf && buf.byteLength > 0) {
+            // Slice by byteOffset/byteLength — see storeSync for why `.buffer` alone
+            // can span unrelated pooled memory.
+            embedding = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+        }
+        return {
+            id: String(row.id),
+            key: String(row.key),
+            content: String(row.content),
+            embedding,
+            type: row.type,
+            namespace: String(row.namespace),
+            tags: JSON.parse(String(row.tags)),
+            metadata: JSON.parse(String(row.metadata)),
+            ownerId: row.owner_id ?? undefined,
+            accessLevel: row.access_level,
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+            expiresAt: row.expires_at ?? undefined,
+            eventAt: row.event_at ?? undefined,
+            version: Number(row.version),
+            references: JSON.parse(String(row.references)),
+            accessCount: Number(row.access_count),
+            lastAccessedAt: Number(row.last_accessed_at),
+        };
+    }
+}
+//# sourceMappingURL=sql-backend.js.map