@claude-flow/memory 3.0.0-alpha.21 → 3.0.0-alpha.23

package/dist/tiered-memory.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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
+ */
+/** Temporal options accepted by {@link TieredMemoryStore.store}. */
+export interface TemporalStoreOptions {
+    /** ISO-8601 timestamp from which the fact is valid (default: always). */
+    validFrom?: string;
+    /** ISO-8601 timestamp after which the fact is no longer valid. */
+    validUntil?: string;
+    /**
+     * Id (or key) of an existing entry this fact supersedes. The old entry
+     * is stamped `validUntil = now`, `supersededBy = <new id>` and archived —
+     * never deleted.
+     */
+    supersedes?: string;
+}
+/** Options accepted by {@link TieredMemoryStore.recall}. */
+export interface TieredRecallOptions {
+    /**
+     * Include entries whose validity window has closed (superseded or
+     * expired) and entries not yet valid. Audit escape hatch — default false.
+     */
+    includeExpired?: boolean;
+}
+/** A stored tiered-memory entry. */
+export interface TieredMemoryEntry {
+    id: string;
+    key: string;
+    value: string;
+    tier: string;
+    ts: number;
+    validFrom?: string;
+    validUntil?: string;
+    supersededBy?: string;
+}
+/** Result of a store operation. */
+export interface TieredStoreResult {
+    id: string;
+    key: string;
+    tier: string;
+    /** Set when `supersedes` matched an existing entry. */
+    superseded?: {
+        id: string;
+        key: string;
+        validUntil: string;
+    } | null;
+    /** True when the entry was written through to the backing SQLite table. */
+    durable: boolean;
+    /** Where the entry lives: a real table, or process memory only. */
+    persistence: TieredPersistence;
+}
+/** Durability mode of a {@link TieredMemoryStore}. */
+export type TieredPersistence = 'sqlite' | 'volatile';
+/**
+ * Minimal better-sqlite3-shaped handle. Only the calls this store makes are
+ * required, so any driver exposing the same synchronous surface works.
+ */
+export interface TieredMemoryDb {
+    exec(sql: string): unknown;
+    prepare(sql: string): {
+        run(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+        get(...params: unknown[]): unknown;
+    };
+}
+/**
+ * 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 declare function isTemporallyValid(entry: Pick<TieredMemoryEntry, 'validFrom' | 'validUntil'>, nowMs?: number): boolean;
+/**
+ * Tier-aware in-memory store with temporal validity and per-tier size
+ * limits to prevent unbounded memory growth.
+ */
+export declare class TieredMemoryStore {
+    private tiers;
+    /**
+     * Superseded entries are moved here so a same-key re-store cannot
+     * clobber the historical fact. Bounded FIFO.
+     */
+    private archived;
+    private db;
+    /**
+     * @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?: {
+        db?: TieredMemoryDb | null;
+    });
+    /** True when writes are persisted to the backing table. */
+    isDurable(): boolean;
+    /** Durability mode, for surfacing to MCP callers. */
+    getPersistence(): TieredPersistence;
+    /**
+     * 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(): number | null;
+    /** Load persisted rows back into the tier maps and the archive. */
+    private hydrate;
+    /**
+     * Write-through. Throws on failure so a store that cannot be persisted
+     * fails loudly instead of reporting success for a lost write.
+     */
+    private persist;
+    /** Drop a persisted row (used by eviction and remove()). */
+    private unpersist;
+    /**
+     * Store an entry. Same-key stores within a tier overwrite (legacy
+     * behavior); use `options.supersedes` to invalidate-and-keep instead.
+     */
+    store(key: string, value: string, tier?: string, options?: TemporalStoreOptions): TieredStoreResult;
+    /**
+     * 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: string, newId: string): TieredStoreResult['superseded'];
+    /**
+     * 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: string, topK?: number, options?: TieredRecallOptions): TieredMemoryEntry[];
+    /** Hard-delete an active entry by key (used by hierarchical-delete). */
+    remove(key: string): boolean;
+    /** Per-tier active counts plus the superseded-archive size. */
+    getTierStats(): Record<string, number>;
+    private findActive;
+}
+export default TieredMemoryStore;
+//# sourceMappingURL=tiered-memory.d.ts.map

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

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

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"}