@claude-flow/memory 3.0.0-alpha.9 → 3.0.1

package/dist/tiered-memory.js

@@ -0,0 +1,350 @@
+/**
+ * Tier-aware store with Zep/Graphiti-style temporal validity, durable when
+ * given a SQLite handle.
+ *
+ * This is the store backing `agentdb_hierarchical-store` / `-recall` when
+ * agentdb's native HierarchicalMemory is unavailable (previously an inline
+ * stub in controller-registry.ts). It is promoted to a first-class module
+ * so temporal knowledge semantics live in one tested place:
+ *
+ * - Facts may carry a validity window (`validFrom` / `validUntil`).
+ * - Conflicting facts are INVALIDATED, not overwritten: `supersedes`
+ *   stamps the old entry with `validUntil = now` + `supersededBy = <newId>`
+ *   and archives it — the history stays queryable.
+ * - `recall()` filters invalid entries by default; `includeExpired: true`
+ *   is the audit escape hatch.
+ * - Entries without temporal fields behave exactly as before (always valid).
+ *
+ * Durability (#2887): agentdb dropped its `HierarchicalMemory` export at
+ * 3.0.0-alpha.17, so this store — not the native controller — is what every
+ * `agentdb_hierarchical-store` call actually lands in. Purely in-memory, that
+ * made every such write a silent no-op that still reported success. Pass a
+ * better-sqlite3-compatible handle and the store writes through to a
+ * `tiered_memory` table and rehydrates from it on construction; without a
+ * handle it stays volatile and says so via {@link TieredMemoryStore.isDurable}.
+ *
+ * API shape is kept duck-type compatible with the previous stub so the CLI
+ * memory-bridge keeps working unchanged:
+ *   store(key, value, tier)   recall(query, topK)   getTierStats()
+ *
+ * IMPORTANT: this class must NOT expose both `getStats` and `promote` —
+ * that pair is the bridge's detection signal for the REAL agentdb
+ * HierarchicalMemory API.
+ *
+ * @module @claude-flow/memory/tiered-memory
+ */
+const TABLE_DDL = `
+CREATE TABLE IF NOT EXISTS tiered_memory (
+  id TEXT PRIMARY KEY,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  tier TEXT NOT NULL,
+  ts INTEGER NOT NULL,
+  valid_from TEXT,
+  valid_until TEXT,
+  superseded_by TEXT,
+  archived INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_tiered_memory_key ON tiered_memory(key);
+CREATE INDEX IF NOT EXISTS idx_tiered_memory_tier ON tiered_memory(tier, archived);
+`;
+function rowToEntry(row) {
+    const entry = {
+        id: row.id,
+        key: row.key,
+        value: row.value,
+        tier: row.tier,
+        ts: Number(row.ts),
+    };
+    if (row.valid_from)
+        entry.validFrom = row.valid_from;
+    if (row.valid_until)
+        entry.validUntil = row.valid_until;
+    if (row.superseded_by)
+        entry.supersededBy = row.superseded_by;
+    return entry;
+}
+const VALID_TIERS = ['working', 'episodic', 'semantic'];
+const MAX_PER_TIER = 5000;
+const MAX_ARCHIVED = 5000;
+const MAX_VALUE_LENGTH = 100_000;
+const MAX_QUERY_LENGTH = 10_000;
+let idCounter = 0;
+function nextId() {
+    idCounter = (idCounter + 1) % Number.MAX_SAFE_INTEGER;
+    return `tm_${Date.now().toString(36)}_${idCounter.toString(36)}`;
+}
+/**
+ * Returns true when the entry is valid at `nowMs`.
+ * Entries without temporal fields are always valid (legacy behavior).
+ * Unparseable timestamps are ignored (treated as absent) rather than
+ * silently hiding the entry.
+ */
+export function isTemporallyValid(entry, nowMs = Date.now()) {
+    if (entry.validFrom) {
+        const from = Date.parse(entry.validFrom);
+        if (!Number.isNaN(from) && from > nowMs)
+            return false; // not yet valid
+    }
+    if (entry.validUntil) {
+        const until = Date.parse(entry.validUntil);
+        if (!Number.isNaN(until) && until <= nowMs)
+            return false; // expired/superseded
+    }
+    return true;
+}
+/**
+ * Tier-aware in-memory store with temporal validity and per-tier size
+ * limits to prevent unbounded memory growth.
+ */
+export class TieredMemoryStore {
+    tiers = {
+        working: new Map(),
+        episodic: new Map(),
+        semantic: new Map(),
+    };
+    /**
+     * Superseded entries are moved here so a same-key re-store cannot
+     * clobber the historical fact. Bounded FIFO.
+     */
+    archived = [];
+    db = null;
+    /**
+     * @param options.db better-sqlite3-compatible handle. When supplied the
+     *   store writes through to `tiered_memory` and rehydrates from it, so
+     *   entries survive the process. Without it the store is volatile and
+     *   {@link isDurable} returns false — callers must treat a write as lost
+     *   on exit rather than reporting success (#2887).
+     */
+    constructor(options) {
+        const db = options?.db ?? null;
+        if (!db)
+            return;
+        try {
+            db.exec(TABLE_DDL);
+            this.db = db;
+            this.hydrate();
+        }
+        catch {
+            // Schema creation failed — stay volatile and report it honestly via
+            // isDurable() rather than pretending the handle works.
+            this.db = null;
+        }
+    }
+    /** True when writes are persisted to the backing table. */
+    isDurable() {
+        return this.db !== null;
+    }
+    /** Durability mode, for surfacing to MCP callers. */
+    getPersistence() {
+        return this.db ? 'sqlite' : 'volatile';
+    }
+    /**
+     * Actual row count in the backing table (not the in-memory maps), so
+     * health checks can detect a claimed-write / empty-table mismatch.
+     * Returns null when volatile — there is no table to count.
+     */
+    countPersisted() {
+        if (!this.db)
+            return null;
+        try {
+            const row = this.db.prepare('SELECT COUNT(*) AS n FROM tiered_memory').get();
+            return Number(row?.n ?? 0);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Load persisted rows back into the tier maps and the archive. */
+    hydrate() {
+        if (!this.db)
+            return;
+        const rows = this.db
+            .prepare('SELECT * FROM tiered_memory ORDER BY ts ASC')
+            .all();
+        for (const row of rows) {
+            const entry = rowToEntry(row);
+            if (row.archived) {
+                this.archived.push(entry);
+                if (this.archived.length > MAX_ARCHIVED)
+                    this.archived.shift();
+                continue;
+            }
+            const map = this.tiers[entry.tier] ?? this.tiers.working;
+            if (map.size >= MAX_PER_TIER)
+                continue;
+            map.set(entry.key, entry);
+        }
+    }
+    /**
+     * Write-through. Throws on failure so a store that cannot be persisted
+     * fails loudly instead of reporting success for a lost write.
+     */
+    persist(entry, archived) {
+        if (!this.db)
+            return;
+        this.db
+            .prepare(`INSERT INTO tiered_memory (id, key, value, tier, ts, valid_from, valid_until, superseded_by, archived)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(id) DO UPDATE SET
+           key = excluded.key, value = excluded.value, tier = excluded.tier, ts = excluded.ts,
+           valid_from = excluded.valid_from, valid_until = excluded.valid_until,
+           superseded_by = excluded.superseded_by, archived = excluded.archived`)
+            .run(entry.id, entry.key, entry.value, entry.tier, entry.ts, entry.validFrom ?? null, entry.validUntil ?? null, entry.supersededBy ?? null, archived ? 1 : 0);
+    }
+    /** Drop a persisted row (used by eviction and remove()). */
+    unpersist(id) {
+        if (!this.db)
+            return;
+        try {
+            this.db.prepare('DELETE FROM tiered_memory WHERE id = ?').run(id);
+        }
+        catch {
+            // A failed eviction leaves a stale row; harmless next to losing a write.
+        }
+    }
+    /**
+     * Store an entry. Same-key stores within a tier overwrite (legacy
+     * behavior); use `options.supersedes` to invalidate-and-keep instead.
+     */
+    store(key, value, tier = 'working', options) {
+        const tierName = VALID_TIERS.includes(tier) ? tier : 'working';
+        const t = this.tiers[tierName];
+        const id = nextId();
+        let superseded = null;
+        if (options?.supersedes) {
+            superseded = this.supersede(options.supersedes, id);
+        }
+        // Evict oldest if at capacity
+        if (t.size >= MAX_PER_TIER) {
+            const oldestKey = t.keys().next().value;
+            if (oldestKey !== undefined) {
+                const evicted = t.get(oldestKey);
+                t.delete(oldestKey);
+                if (evicted)
+                    this.unpersist(evicted.id);
+            }
+        }
+        const entry = {
+            id,
+            key,
+            value: value.substring(0, MAX_VALUE_LENGTH),
+            tier: tierName,
+            ts: Date.now(),
+        };
+        if (options?.validFrom)
+            entry.validFrom = options.validFrom;
+        if (options?.validUntil)
+            entry.validUntil = options.validUntil;
+        // Persist BEFORE publishing to the in-memory map: a throw here must not
+        // leave a value visible in-process that never reached disk (#2887).
+        const replaced = t.get(key);
+        this.persist(entry, false);
+        if (replaced && replaced.id !== entry.id)
+            this.unpersist(replaced.id);
+        t.set(key, entry);
+        return {
+            id, key, tier: tierName, superseded,
+            durable: this.db !== null,
+            persistence: this.getPersistence(),
+        };
+    }
+    /**
+     * Invalidate an existing entry (matched by id first, then by key) by
+     * stamping `validUntil = now` + `supersededBy = newId` and moving it to
+     * the archive. The entry is NOT deleted — `recall(..., { includeExpired:
+     * true })` still returns it.
+     */
+    supersede(idOrKey, newId) {
+        const found = this.findActive(idOrKey);
+        if (!found)
+            return null;
+        const { map, entry } = found;
+        const now = new Date().toISOString();
+        entry.validUntil = now;
+        entry.supersededBy = newId;
+        map.delete(entry.key);
+        this.persist(entry, true);
+        this.archived.push(entry);
+        if (this.archived.length > MAX_ARCHIVED) {
+            const dropped = this.archived.shift();
+            if (dropped)
+                this.unpersist(dropped.id);
+        }
+        return { id: entry.id, key: entry.key, validUntil: now };
+    }
+    /**
+     * Substring recall across tiers, newest first. By default only
+     * temporally-valid entries are returned; pass `{ includeExpired: true }`
+     * to audit superseded / expired / future-dated facts too.
+     */
+    recall(query, topK = 5, options) {
+        const safeTopK = Math.min(Math.max(1, topK), 100);
+        const q = query.toLowerCase().substring(0, MAX_QUERY_LENGTH);
+        const includeExpired = options?.includeExpired === true;
+        const now = Date.now();
+        const results = [];
+        const consider = (entry) => {
+            if (!entry.key.toLowerCase().includes(q) && !entry.value.toLowerCase().includes(q)) {
+                return false;
+            }
+            if (!includeExpired && !isTemporallyValid(entry, now))
+                return false;
+            results.push(entry);
+            return true;
+        };
+        outer: for (const map of Object.values(this.tiers)) {
+            for (const entry of map.values()) {
+                consider(entry);
+                if (results.length >= safeTopK * 3)
+                    break outer; // early exit for large stores
+            }
+        }
+        if (includeExpired && results.length < safeTopK * 3) {
+            for (const entry of this.archived) {
+                consider(entry);
+                if (results.length >= safeTopK * 3)
+                    break;
+            }
+        }
+        return results.sort((a, b) => b.ts - a.ts).slice(0, safeTopK);
+    }
+    /** Hard-delete an active entry by key (used by hierarchical-delete). */
+    remove(key) {
+        for (const map of Object.values(this.tiers)) {
+            const entry = map.get(key);
+            if (!entry)
+                continue;
+            map.delete(key);
+            this.unpersist(entry.id);
+            return true;
+        }
+        return false;
+    }
+    /** Per-tier active counts plus the superseded-archive size. */
+    getTierStats() {
+        const stats = {};
+        for (const [name, map] of Object.entries(this.tiers)) {
+            stats[name] = map.size;
+        }
+        stats.superseded = this.archived.length;
+        return stats;
+    }
+    findActive(idOrKey) {
+        // Prefer id match (exact provenance), fall back to key match.
+        for (const map of Object.values(this.tiers)) {
+            for (const entry of map.values()) {
+                if (entry.id === idOrKey)
+                    return { map, entry };
+            }
+        }
+        for (const map of Object.values(this.tiers)) {
+            const entry = map.get(idOrKey);
+            if (entry)
+                return { map, entry };
+        }
+        return null;
+    }
+}
+export default TieredMemoryStore;
+//# sourceMappingURL=tiered-memory.js.map

package/dist/tiered-memory.js.map

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

package/dist/tiered-memory.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for TieredMemoryStore temporal validity (Zep/Graphiti-style).
+ *
+ * Covers: supersede flow (invalidate, not delete), expired filtering,
+ * the includeExpired escape hatch, and backward compatibility for legacy
+ * entries without temporal fields.
+ */
+export {};
+//# sourceMappingURL=tiered-memory.test.d.ts.map

package/dist/tiered-memory.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiered-memory.test.d.ts","sourceRoot":"","sources":["../src/tiered-memory.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/tiered-memory.test.js

@@ -0,0 +1,220 @@
+/**
+ * Tests for TieredMemoryStore temporal validity (Zep/Graphiti-style).
+ *
+ * Covers: supersede flow (invalidate, not delete), expired filtering,
+ * the includeExpired escape hatch, and backward compatibility for legacy
+ * entries without temporal fields.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { TieredMemoryStore, isTemporallyValid } from './tiered-memory.js';
+describe('TieredMemoryStore — legacy behavior (backward compatibility)', () => {
+    let store;
+    beforeEach(() => {
+        store = new TieredMemoryStore();
+    });
+    it('stores and recalls entries without temporal fields exactly as before', () => {
+        store.store('auth-pattern', 'JWT with refresh tokens', 'semantic');
+        store.store('scratch', 'temp note', 'working');
+        const results = store.recall('jwt', 5);
+        expect(results).toHaveLength(1);
+        expect(results[0].key).toBe('auth-pattern');
+        expect(results[0].tier).toBe('semantic');
+        expect(results[0].validFrom).toBeUndefined();
+        expect(results[0].validUntil).toBeUndefined();
+        expect(results[0].supersededBy).toBeUndefined();
+    });
+    it('same-key store within a tier overwrites (legacy semantics)', () => {
+        store.store('k1', 'first value', 'working');
+        store.store('k1', 'second value', 'working');
+        const results = store.recall('value', 10);
+        expect(results).toHaveLength(1);
+        expect(results[0].value).toBe('second value');
+    });
+    it('defaults invalid tiers to working', () => {
+        store.store('k1', 'v1', 'nonsense-tier');
+        expect(store.getTierStats().working).toBe(1);
+    });
+    it('reports per-tier stats plus superseded archive size', () => {
+        store.store('a', 'v', 'working');
+        store.store('b', 'v', 'episodic');
+        const stats = store.getTierStats();
+        expect(stats.working).toBe(1);
+        expect(stats.episodic).toBe(1);
+        expect(stats.semantic).toBe(0);
+        expect(stats.superseded).toBe(0);
+    });
+    it('remove() hard-deletes an active entry by key', () => {
+        store.store('gone', 'delete me', 'working');
+        expect(store.remove('gone')).toBe(true);
+        expect(store.recall('delete me', 5)).toHaveLength(0);
+        expect(store.remove('gone')).toBe(false);
+    });
+});
+describe('TieredMemoryStore — supersede flow', () => {
+    let store;
+    beforeEach(() => {
+        store = new TieredMemoryStore();
+    });
+    it('invalidates (not deletes) the superseded entry and links supersededBy', () => {
+        const oldFact = store.store('ceo', 'The CEO is Alice', 'semantic');
+        const newFact = store.store('ceo-2026', 'The CEO is Bob', 'semantic', {
+            supersedes: oldFact.id,
+        });
+        expect(newFact.superseded).not.toBeNull();
+        expect(newFact.superseded.id).toBe(oldFact.id);
+        expect(newFact.superseded.validUntil).toBeTruthy();
+        // Default recall: only the new fact is visible
+        const current = store.recall('CEO', 10);
+        expect(current).toHaveLength(1);
+        expect(current[0].key).toBe('ceo-2026');
+        // Escape hatch: both facts visible, old one carries the invalidation stamp
+        const audit = store.recall('CEO', 10, { includeExpired: true });
+        expect(audit).toHaveLength(2);
+        const old = audit.find((e) => e.key === 'ceo');
+        expect(old).toBeDefined();
+        expect(old.supersededBy).toBe(newFact.id);
+        expect(Date.parse(old.validUntil)).toBeLessThanOrEqual(Date.now());
+    });
+    it('resolves supersedes by key when no id matches', () => {
+        store.store('policy', 'Old policy text', 'semantic');
+        const result = store.store('policy-v2', 'New policy text', 'semantic', {
+            supersedes: 'policy',
+        });
+        expect(result.superseded).not.toBeNull();
+        expect(result.superseded.key).toBe('policy');
+        expect(store.recall('policy text', 10)).toHaveLength(1);
+        expect(store.recall('policy text', 10, { includeExpired: true })).toHaveLength(2);
+    });
+    it('superseding with the SAME key preserves the old fact in the archive', () => {
+        const oldFact = store.store('config', 'timeout=30', 'semantic');
+        store.store('config', 'timeout=60', 'semantic', { supersedes: oldFact.id });
+        const current = store.recall('timeout', 10);
+        expect(current).toHaveLength(1);
+        expect(current[0].value).toBe('timeout=60');
+        const audit = store.recall('timeout', 10, { includeExpired: true });
+        expect(audit).toHaveLength(2);
+        expect(audit.map((e) => e.value).sort()).toEqual(['timeout=30', 'timeout=60']);
+    });
+    it('returns null superseded when the target does not exist', () => {
+        const result = store.store('k', 'v', 'working', { supersedes: 'no-such-entry' });
+        expect(result.superseded).toBeNull();
+    });
+});
+describe('TieredMemoryStore — validity-window filtering', () => {
+    let store;
+    beforeEach(() => {
+        store = new TieredMemoryStore();
+    });
+    it('filters entries whose validUntil is in the past by default', () => {
+        const past = new Date(Date.now() - 60_000).toISOString();
+        store.store('expired-fact', 'promo code SAVE20', 'semantic', { validUntil: past });
+        store.store('live-fact', 'promo code SAVE30', 'semantic');
+        const results = store.recall('promo code', 10);
+        expect(results).toHaveLength(1);
+        expect(results[0].key).toBe('live-fact');
+    });
+    it('includeExpired returns expired entries too (audit escape hatch)', () => {
+        const past = new Date(Date.now() - 60_000).toISOString();
+        store.store('expired-fact', 'promo code SAVE20', 'semantic', { validUntil: past });
+        store.store('live-fact', 'promo code SAVE30', 'semantic');
+        const results = store.recall('promo code', 10, { includeExpired: true });
+        expect(results).toHaveLength(2);
+    });
+    it('keeps entries whose validUntil is in the future', () => {
+        const future = new Date(Date.now() + 3_600_000).toISOString();
+        store.store('ttl-fact', 'valid for one hour', 'working', { validUntil: future });
+        expect(store.recall('one hour', 5)).toHaveLength(1);
+    });
+    it('hides not-yet-valid entries (validFrom in the future) by default', () => {
+        const future = new Date(Date.now() + 3_600_000).toISOString();
+        store.store('scheduled-fact', 'new pricing takes effect', 'semantic', { validFrom: future });
+        expect(store.recall('pricing', 5)).toHaveLength(0);
+        expect(store.recall('pricing', 5, { includeExpired: true })).toHaveLength(1);
+    });
+    it('treats unparseable timestamps as absent instead of hiding the entry', () => {
+        store.store('weird', 'garbage timestamp entry', 'working', { validUntil: 'not-a-date' });
+        expect(store.recall('garbage', 5)).toHaveLength(1);
+    });
+});
+describe('isTemporallyValid', () => {
+    const now = Date.parse('2026-07-03T12:00:00Z');
+    it('entries without fields are always valid', () => {
+        expect(isTemporallyValid({}, now)).toBe(true);
+    });
+    it('respects validFrom / validUntil boundaries', () => {
+        expect(isTemporallyValid({ validFrom: '2026-07-03T13:00:00Z' }, now)).toBe(false);
+        expect(isTemporallyValid({ validFrom: '2026-07-03T11:00:00Z' }, now)).toBe(true);
+        expect(isTemporallyValid({ validUntil: '2026-07-03T11:00:00Z' }, now)).toBe(false);
+        expect(isTemporallyValid({ validUntil: '2026-07-03T13:00:00Z' }, now)).toBe(true);
+        // validUntil exactly now → expired (window is half-open)
+        expect(isTemporallyValid({ validUntil: '2026-07-03T12:00:00Z' }, now)).toBe(false);
+    });
+});
+describe('TieredMemoryStore — durability (#2887)', () => {
+    const dbs = [];
+    const dirs = [];
+    function freshDbPath() {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tiered-durability-'));
+        dirs.push(dir);
+        return path.join(dir, 'agentdb-memory.db');
+    }
+    function open(dbPath) {
+        const db = new Database(dbPath);
+        dbs.push(db);
+        return db;
+    }
+    afterEach(() => {
+        for (const db of dbs.splice(0)) {
+            try {
+                db.close();
+            }
+            catch { /* already closed */ }
+        }
+        for (const dir of dirs.splice(0))
+            fs.rmSync(dir, { recursive: true, force: true });
+    });
+    it('a successful store is queryable on disk, not just in the maps', () => {
+        const dbPath = freshDbPath();
+        const store = new TieredMemoryStore({ db: open(dbPath) });
+        const result = store.store('durable-key', 'DURABLE_VALUE', 'semantic');
+        expect(result.durable).toBe(true);
+        expect(result.persistence).toBe('sqlite');
+        // Read through an INDEPENDENT connection — proves the row is committed,
+        // not merely sitting in the writer's in-memory maps.
+        const rows = open(dbPath)
+            .prepare('SELECT key, value, tier FROM tiered_memory WHERE key = ?')
+            .all('durable-key');
+        expect(rows).toEqual([{ key: 'durable-key', value: 'DURABLE_VALUE', tier: 'semantic' }]);
+    });
+    it('rehydrates persisted entries into a brand-new store instance', () => {
+        const dbPath = freshDbPath();
+        new TieredMemoryStore({ db: open(dbPath) }).store('survives', 'ACROSS_INSTANCES', 'working');
+        const reopened = new TieredMemoryStore({ db: open(dbPath) });
+        expect(reopened.recall('ACROSS_INSTANCES')).toHaveLength(1);
+        expect(reopened.countPersisted()).toBe(1);
+    });
+    it('reports durable:false — never a bare success — when there is no backing db', () => {
+        const store = new TieredMemoryStore();
+        const result = store.store('volatile-key', 'LOST_ON_EXIT');
+        expect(store.isDurable()).toBe(false);
+        expect(result.durable).toBe(false);
+        expect(result.persistence).toBe('volatile');
+        // No table exists to count, so health checks can't be told a row landed.
+        expect(store.countPersisted()).toBeNull();
+    });
+    it('superseded entries stay auditable on disk, and removal deletes the row', () => {
+        const dbPath = freshDbPath();
+        const store = new TieredMemoryStore({ db: open(dbPath) });
+        const first = store.store('fact', 'v1', 'semantic');
+        store.store('fact', 'v2', 'semantic', { supersedes: first.id });
+        expect(store.countPersisted()).toBe(2);
+        expect(store.recall('fact', 5, { includeExpired: true })).toHaveLength(2);
+        expect(store.remove('fact')).toBe(true);
+        expect(open(dbPath).prepare('SELECT COUNT(*) AS n FROM tiered_memory WHERE archived = 0').get()).toEqual({ n: 0 });
+    });
+});
+//# sourceMappingURL=tiered-memory.test.js.map

package/dist/tiered-memory.test.js.map

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

package/dist/types.d.ts

@@ -360,6 +360,12 @@ export interface MigrationConfig {
     namespaceMapping?: Record<string, string>;
     /** Type mapping */
     typeMapping?: Record<string, MemoryType>;
+    /**
+     * Max concurrent single-entry embedding calls per migration batch when
+     * no batch embedding generator is available (default: 8). Set to 1 to
+     * restore fully sequential embedding.
+     */
+    embeddingConcurrency?: number;
 }
 /**
  * Migration progress
@@ -453,6 +459,17 @@ export interface LearningPattern {
  * Embedding generator function type
  */
 export type EmbeddingGenerator = (content: string) => Promise<Float32Array>;
+/**
+ * Batch embedding generator function type.
+ *
+ * Implementations that can run a single padded forward pass over many
+ * texts (e.g. transformers.js `tokenizer(texts[])` + one model call)
+ * should be exposed through this type — it is dramatically cheaper than
+ * N sequential single-text inferences in import/migration hot paths.
+ *
+ * Contract: MUST return one embedding per input text, in input order.
+ */
+export type BatchEmbeddingGenerator = (contents: string[]) => Promise<Float32Array[]>;
 /**
  * Generates a unique memory ID
  */