@swarmdo/cli 1.4.8

package/vendor/memory/dist/agentdb-adapter.js

@@ -0,0 +1,1050 @@
+/**
+ * V3 AgentDB Adapter
+ *
+ * Unified memory backend implementation using AgentDB with HNSW indexing
+ * for 150x-12,500x faster vector search. Implements IMemoryBackend interface.
+ *
+ * @module v3/memory/agentdb-adapter
+ */
+import { EventEmitter } from 'node:events';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createDefaultEntry, } from './types.js';
+import { HNSWIndex } from './hnsw-index.js';
+import { CacheManager } from './cache-manager.js';
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+    dimensions: 1536,
+    maxEntries: 1000000,
+    cacheEnabled: true,
+    cacheSize: 10000,
+    cacheTtl: 300000, // 5 minutes
+    hnswM: 16,
+    hnswEfConstruction: 200,
+    defaultNamespace: 'default',
+    persistenceEnabled: false,
+};
+/**
+ * AgentDB Memory Backend Adapter
+ *
+ * Provides unified memory storage with:
+ * - HNSW-based vector search (150x-12,500x faster than brute force)
+ * - LRU caching with TTL support
+ * - Namespace-based organization
+ * - Full-text and metadata filtering
+ * - Event-driven architecture
+ */
+export class AgentDBAdapter extends EventEmitter {
+    config;
+    entries = new Map();
+    index;
+    cache;
+    namespaceIndex = new Map();
+    keyIndex = new Map(); // namespace:key -> id
+    tagIndex = new Map();
+    initialized = false;
+    // Performance tracking
+    stats = {
+        queryCount: 0,
+        totalQueryTime: 0,
+        searchCount: 0,
+        totalSearchTime: 0,
+        writeCount: 0,
+        totalWriteTime: 0,
+    };
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        // Initialize HNSW index
+        this.index = new HNSWIndex({
+            dimensions: this.config.dimensions,
+            M: this.config.hnswM,
+            efConstruction: this.config.hnswEfConstruction,
+            maxElements: this.config.maxEntries,
+            metric: 'cosine',
+        });
+        // Initialize cache
+        this.cache = new CacheManager({
+            maxSize: this.config.cacheSize,
+            ttl: this.config.cacheTtl,
+            lruEnabled: true,
+        });
+        // Forward events
+        this.index.on('point:added', (data) => this.emit('index:added', data));
+        this.cache.on('cache:hit', (data) => this.emit('cache:hit', data));
+        this.cache.on('cache:miss', (data) => this.emit('cache:miss', data));
+    }
+    /**
+     * Initialize the adapter
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Load persisted data if enabled
+        if (this.config.persistenceEnabled && this.config.persistencePath) {
+            await this.loadFromDisk();
+        }
+        this.initialized = true;
+        this.emit('initialized');
+    }
+    /**
+     * Shutdown the adapter
+     */
+    async shutdown() {
+        if (!this.initialized)
+            return;
+        // Persist data if enabled
+        if (this.config.persistenceEnabled && this.config.persistencePath) {
+            await this.saveToDisk();
+        }
+        this.cache.shutdown();
+        this.initialized = false;
+        this.emit('shutdown');
+    }
+    /**
+     * Store a memory entry
+     */
+    async store(entry) {
+        const startTime = performance.now();
+        // Generate embedding if content provided but no embedding
+        if (entry.content && !entry.embedding && this.config.embeddingGenerator) {
+            entry.embedding = await this.config.embeddingGenerator(entry.content);
+        }
+        // Store in main storage
+        this.entries.set(entry.id, entry);
+        // Update namespace index
+        const namespace = entry.namespace || this.config.defaultNamespace;
+        if (!this.namespaceIndex.has(namespace)) {
+            this.namespaceIndex.set(namespace, new Set());
+        }
+        this.namespaceIndex.get(namespace).add(entry.id);
+        // Update key index
+        const keyIndexKey = `${namespace}:${entry.key}`;
+        this.keyIndex.set(keyIndexKey, entry.id);
+        // Update tag index
+        for (const tag of entry.tags) {
+            if (!this.tagIndex.has(tag)) {
+                this.tagIndex.set(tag, new Set());
+            }
+            this.tagIndex.get(tag).add(entry.id);
+        }
+        // Index embedding if available
+        if (entry.embedding) {
+            await this.index.addPoint(entry.id, entry.embedding);
+        }
+        // Update cache
+        if (this.config.cacheEnabled) {
+            this.cache.set(entry.id, entry);
+        }
+        const duration = performance.now() - startTime;
+        this.stats.writeCount++;
+        this.stats.totalWriteTime += duration;
+        this.emit('entry:stored', { id: entry.id, duration });
+    }
+    /**
+     * Get a memory entry by ID
+     */
+    async get(id) {
+        // Check cache first
+        if (this.config.cacheEnabled) {
+            const cached = this.cache.get(id);
+            if (cached) {
+                this.updateAccessStats(cached);
+                return cached;
+            }
+        }
+        const entry = this.entries.get(id);
+        if (entry) {
+            this.updateAccessStats(entry);
+            if (this.config.cacheEnabled) {
+                this.cache.set(id, entry);
+            }
+        }
+        return entry || null;
+    }
+    /**
+     * Get a memory entry by key within a namespace
+     */
+    async getByKey(namespace, key) {
+        const keyIndexKey = `${namespace}:${key}`;
+        const id = this.keyIndex.get(keyIndexKey);
+        if (!id)
+            return null;
+        return this.get(id);
+    }
+    /**
+     * Update a memory entry
+     */
+    async update(id, update) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return null;
+        // Apply updates
+        if (update.content !== undefined) {
+            entry.content = update.content;
+            // Regenerate embedding if content changed
+            if (this.config.embeddingGenerator) {
+                entry.embedding = await this.config.embeddingGenerator(entry.content);
+                // Re-index
+                await this.index.removePoint(id);
+                await this.index.addPoint(id, entry.embedding);
+            }
+        }
+        if (update.tags !== undefined) {
+            // Update tag index
+            for (const oldTag of entry.tags) {
+                this.tagIndex.get(oldTag)?.delete(id);
+            }
+            entry.tags = update.tags;
+            for (const newTag of update.tags) {
+                if (!this.tagIndex.has(newTag)) {
+                    this.tagIndex.set(newTag, new Set());
+                }
+                this.tagIndex.get(newTag).add(id);
+            }
+        }
+        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++;
+        // Update cache
+        if (this.config.cacheEnabled) {
+            this.cache.set(id, entry);
+        }
+        this.emit('entry:updated', { id });
+        return entry;
+    }
+    /**
+     * Delete a memory entry
+     */
+    async delete(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return false;
+        // Remove from main storage
+        this.entries.delete(id);
+        // Remove from namespace index
+        this.namespaceIndex.get(entry.namespace)?.delete(id);
+        // Remove from key index
+        const keyIndexKey = `${entry.namespace}:${entry.key}`;
+        this.keyIndex.delete(keyIndexKey);
+        // Remove from tag index
+        for (const tag of entry.tags) {
+            this.tagIndex.get(tag)?.delete(id);
+        }
+        // Remove from vector index
+        if (entry.embedding) {
+            await this.index.removePoint(id);
+        }
+        // Remove from cache
+        if (this.config.cacheEnabled) {
+            this.cache.delete(id);
+        }
+        this.emit('entry:deleted', { id });
+        return true;
+    }
+    /**
+     * Query memory entries with filters
+     */
+    async query(query) {
+        const startTime = performance.now();
+        let results = [];
+        switch (query.type) {
+            case 'exact':
+                if (query.key && query.namespace) {
+                    const entry = await this.getByKey(query.namespace, query.key);
+                    if (entry)
+                        results = [entry];
+                }
+                break;
+            case 'prefix':
+                results = this.queryByPrefix(query);
+                break;
+            case 'tag':
+                results = this.queryByTags(query);
+                break;
+            case 'semantic':
+            case 'hybrid':
+                results = await this.querySemanticWithFilters(query);
+                break;
+            default:
+                results = this.queryWithFilters(query);
+        }
+        // Apply common filters
+        results = this.applyFilters(results, query);
+        // Apply pagination
+        const offset = query.offset || 0;
+        results = results.slice(offset, offset + query.limit);
+        const duration = performance.now() - startTime;
+        this.stats.queryCount++;
+        this.stats.totalQueryTime += duration;
+        return results;
+    }
+    /**
+     * Semantic vector search
+     */
+    async search(embedding, options) {
+        const startTime = performance.now();
+        const indexResults = await this.index.search(embedding, options.k, options.ef);
+        const results = [];
+        for (const { id, distance } of indexResults) {
+            const entry = this.entries.get(id);
+            if (!entry)
+                continue;
+            // Apply threshold filter
+            const score = 1 - distance; // Convert distance to similarity
+            if (options.threshold && score < options.threshold)
+                continue;
+            // Apply additional filters if provided
+            if (options.filters) {
+                const filtered = this.applyFilters([entry], options.filters);
+                if (filtered.length === 0)
+                    continue;
+            }
+            results.push({ entry, score, distance });
+        }
+        const duration = performance.now() - startTime;
+        this.stats.searchCount++;
+        this.stats.totalSearchTime += duration;
+        return results;
+    }
+    /**
+     * Bulk insert entries (OPTIMIZED: 2-3x faster with batched operations)
+     *
+     * Performance improvements:
+     * - Parallel embedding generation
+     * - Batched index updates
+     * - Deferred cache population
+     * - Single event emission
+     */
+    async bulkInsert(entries, options) {
+        const startTime = performance.now();
+        const batchSize = options?.batchSize || 100;
+        // Phase 1: Generate embeddings in parallel batches
+        if (this.config.embeddingGenerator) {
+            const needsEmbedding = entries.filter(e => e.content && !e.embedding);
+            for (let i = 0; i < needsEmbedding.length; i += batchSize) {
+                const batch = needsEmbedding.slice(i, i + batchSize);
+                await Promise.all(batch.map(async (entry) => {
+                    entry.embedding = await this.config.embeddingGenerator(entry.content);
+                }));
+            }
+        }
+        // Phase 2: Store all entries (skip individual cache updates)
+        const embeddings = [];
+        for (const entry of entries) {
+            // Store in main storage
+            this.entries.set(entry.id, entry);
+            // Update namespace index
+            const namespace = entry.namespace || this.config.defaultNamespace;
+            if (!this.namespaceIndex.has(namespace)) {
+                this.namespaceIndex.set(namespace, new Set());
+            }
+            this.namespaceIndex.get(namespace).add(entry.id);
+            // Update key index
+            const keyIndexKey = `${namespace}:${entry.key}`;
+            this.keyIndex.set(keyIndexKey, entry.id);
+            // Update tag index
+            for (const tag of entry.tags) {
+                if (!this.tagIndex.has(tag)) {
+                    this.tagIndex.set(tag, new Set());
+                }
+                this.tagIndex.get(tag).add(entry.id);
+            }
+            // Collect embeddings for batch indexing
+            if (entry.embedding) {
+                embeddings.push({ id: entry.id, embedding: entry.embedding });
+            }
+        }
+        // Phase 3: Batch index embeddings
+        for (let i = 0; i < embeddings.length; i += batchSize) {
+            const batch = embeddings.slice(i, i + batchSize);
+            await Promise.all(batch.map(({ id, embedding }) => this.index.addPoint(id, embedding)));
+        }
+        // Phase 4: Batch cache update (only populate hot entries)
+        if (this.config.cacheEnabled && entries.length <= this.config.cacheSize) {
+            for (const entry of entries) {
+                this.cache.set(entry.id, entry);
+            }
+        }
+        const duration = performance.now() - startTime;
+        this.stats.writeCount += entries.length;
+        this.stats.totalWriteTime += duration;
+        this.emit('bulk:inserted', { count: entries.length, duration, avgPerEntry: duration / entries.length });
+    }
+    /**
+     * Bulk delete entries (OPTIMIZED: parallel deletion)
+     */
+    async bulkDelete(ids) {
+        const startTime = performance.now();
+        let deleted = 0;
+        // Batch delete from cache first (fast)
+        if (this.config.cacheEnabled) {
+            for (const id of ids) {
+                this.cache.delete(id);
+            }
+        }
+        // Process deletions in parallel batches
+        const batchSize = 100;
+        for (let i = 0; i < ids.length; i += batchSize) {
+            const batch = ids.slice(i, i + batchSize);
+            const results = await Promise.all(batch.map(async (id) => {
+                const entry = this.entries.get(id);
+                if (!entry)
+                    return false;
+                // Remove from main storage
+                this.entries.delete(id);
+                // Remove from namespace index
+                this.namespaceIndex.get(entry.namespace)?.delete(id);
+                // Remove from key index
+                const keyIndexKey = `${entry.namespace}:${entry.key}`;
+                this.keyIndex.delete(keyIndexKey);
+                // Remove from tag index
+                for (const tag of entry.tags) {
+                    this.tagIndex.get(tag)?.delete(id);
+                }
+                // Remove from vector index
+                if (entry.embedding) {
+                    await this.index.removePoint(id);
+                }
+                return true;
+            }));
+            deleted += results.filter(Boolean).length;
+        }
+        const duration = performance.now() - startTime;
+        this.emit('bulk:deleted', { count: deleted, duration });
+        return deleted;
+    }
+    /**
+     * Bulk get entries by IDs (OPTIMIZED: parallel fetch with cache)
+     */
+    async bulkGet(ids) {
+        const results = new Map();
+        const uncached = [];
+        // Check cache first
+        if (this.config.cacheEnabled) {
+            for (const id of ids) {
+                const cached = this.cache.get(id);
+                if (cached) {
+                    results.set(id, cached);
+                }
+                else {
+                    uncached.push(id);
+                }
+            }
+        }
+        else {
+            uncached.push(...ids);
+        }
+        // Fetch uncached entries
+        for (const id of uncached) {
+            const entry = this.entries.get(id) || null;
+            results.set(id, entry);
+            if (entry && this.config.cacheEnabled) {
+                this.cache.set(id, entry);
+            }
+        }
+        return results;
+    }
+    /**
+     * Bulk update entries (OPTIMIZED: batched updates)
+     */
+    async bulkUpdate(updates) {
+        const results = new Map();
+        // Process updates in parallel
+        await Promise.all(updates.map(async ({ id, update }) => {
+            const updated = await this.update(id, update);
+            results.set(id, updated);
+        }));
+        return results;
+    }
+    /**
+     * Get entry count
+     */
+    async count(namespace) {
+        if (namespace) {
+            return this.namespaceIndex.get(namespace)?.size || 0;
+        }
+        return this.entries.size;
+    }
+    /**
+     * List all namespaces
+     */
+    async listNamespaces() {
+        return Array.from(this.namespaceIndex.keys());
+    }
+    /**
+     * Clear all entries in a namespace
+     */
+    async clearNamespace(namespace) {
+        const ids = this.namespaceIndex.get(namespace);
+        if (!ids)
+            return 0;
+        let deleted = 0;
+        for (const id of ids) {
+            if (await this.delete(id)) {
+                deleted++;
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Get backend statistics
+     */
+    async getStats() {
+        const entriesByNamespace = {};
+        for (const [namespace, ids] of this.namespaceIndex) {
+            entriesByNamespace[namespace] = ids.size;
+        }
+        const entriesByType = {
+            episodic: 0,
+            semantic: 0,
+            procedural: 0,
+            working: 0,
+            cache: 0,
+        };
+        for (const entry of this.entries.values()) {
+            entriesByType[entry.type]++;
+        }
+        return {
+            totalEntries: this.entries.size,
+            entriesByNamespace,
+            entriesByType,
+            memoryUsage: this.estimateMemoryUsage(),
+            hnswStats: this.index.getStats(),
+            cacheStats: this.cache.getStats(),
+            avgQueryTime: this.stats.queryCount > 0
+                ? this.stats.totalQueryTime / this.stats.queryCount
+                : 0,
+            avgSearchTime: this.stats.searchCount > 0
+                ? this.stats.totalSearchTime / this.stats.searchCount
+                : 0,
+        };
+    }
+    /**
+     * Perform health check
+     */
+    async healthCheck() {
+        const issues = [];
+        const recommendations = [];
+        // Check storage health
+        const storageHealth = this.checkStorageHealth(issues, recommendations);
+        // Check index health
+        const indexHealth = this.checkIndexHealth(issues, recommendations);
+        // Check cache health
+        const cacheHealth = this.checkCacheHealth(issues, recommendations);
+        // Determine overall status
+        let status = 'healthy';
+        if (storageHealth.status === 'unhealthy' ||
+            indexHealth.status === 'unhealthy' ||
+            cacheHealth.status === 'unhealthy') {
+            status = 'unhealthy';
+        }
+        else if (storageHealth.status === 'degraded' ||
+            indexHealth.status === 'degraded' ||
+            cacheHealth.status === 'degraded') {
+            status = 'degraded';
+        }
+        return {
+            status,
+            components: {
+                storage: storageHealth,
+                index: indexHealth,
+                cache: cacheHealth,
+            },
+            timestamp: Date.now(),
+            issues,
+            recommendations,
+        };
+    }
+    // ===== Convenience Methods =====
+    /**
+     * Store a new entry from input
+     */
+    async storeEntry(input) {
+        const entry = createDefaultEntry(input);
+        await this.store(entry);
+        return entry;
+    }
+    /**
+     * Semantic search by content string.
+     *
+     * ADR-125 Phase 5 — degrades gracefully when the embedding generator is
+     * unavailable. Instead of throwing, emits `health:embedder` with
+     * `status: 'degraded'` and falls back to {@link searchKeyword} so the
+     * memory subsystem remains usable when `@swarmdo/embeddings` is
+     * unreachable (per ADR-124's lazy/degrade posture).
+     */
+    async semanticSearch(content, k = 10, threshold) {
+        if (!this.config.embeddingGenerator) {
+            this.emit('health:embedder', { status: 'degraded', reason: 'no-generator' });
+            return this.searchKeyword(content, { k, threshold });
+        }
+        try {
+            const embedding = await this.config.embeddingGenerator(content);
+            return this.search(embedding, { k, threshold });
+        }
+        catch (err) {
+            this.emit('health:embedder', {
+                status: 'degraded',
+                reason: err instanceof Error ? err.message : String(err),
+            });
+            return this.searchKeyword(content, { k, threshold });
+        }
+    }
+    /**
+     * Keyword search — in-memory token-overlap ranking against the
+     * `entries` map. Used as a fallback when the embedder is unavailable
+     * and as the "sparse" arm of the hybridSearch controller.
+     *
+     * Falls back to the SqlJs / SQLite backend FTS5 path when a backend is
+     * wired that exposes a `searchKeyword` method. The AgentDBAdapter itself
+     * keeps the implementation cheap and dependency-free.
+     *
+     * @internal ADR-125 Phase 5
+     */
+    async searchKeyword(query, options = { k: 10 }) {
+        const k = options.k ?? 10;
+        const tokens = tokenize(query);
+        if (tokens.size === 0)
+            return [];
+        const scored = [];
+        for (const entry of this.entries.values()) {
+            const entryTokens = tokenize(entry.content);
+            let overlap = 0;
+            for (const t of tokens)
+                if (entryTokens.has(t))
+                    overlap += 1;
+            if (overlap === 0)
+                continue;
+            // Simple token-overlap ratio in [0,1]. Adequate for fallback ranking.
+            const score = overlap / Math.max(tokens.size, 1);
+            if (options.threshold && score < options.threshold)
+                continue;
+            // Apply additional filters if provided
+            if (options.filters) {
+                const filtered = this.applyFilters([entry], options.filters);
+                if (filtered.length === 0)
+                    continue;
+            }
+            scored.push({ entry, score, distance: 1 - score });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, k);
+    }
+    // ===== Private Methods =====
+    queryByPrefix(query) {
+        const results = [];
+        const prefix = query.keyPrefix || '';
+        const namespace = query.namespace || this.config.defaultNamespace;
+        for (const [key, id] of this.keyIndex) {
+            if (key.startsWith(`${namespace}:${prefix}`)) {
+                const entry = this.entries.get(id);
+                if (entry)
+                    results.push(entry);
+            }
+        }
+        return results;
+    }
+    queryByTags(query) {
+        if (!query.tags || query.tags.length === 0) {
+            return Array.from(this.entries.values());
+        }
+        // Get intersection of entries for all tags
+        let matchingIds = null;
+        for (const tag of query.tags) {
+            const tagIds = this.tagIndex.get(tag);
+            if (!tagIds) {
+                return []; // Tag doesn't exist
+            }
+            if (matchingIds === null) {
+                matchingIds = new Set(tagIds);
+            }
+            else {
+                // Intersect with previous results
+                for (const id of matchingIds) {
+                    if (!tagIds.has(id)) {
+                        matchingIds.delete(id);
+                    }
+                }
+            }
+        }
+        if (!matchingIds)
+            return [];
+        const results = [];
+        for (const id of matchingIds) {
+            const entry = this.entries.get(id);
+            if (entry)
+                results.push(entry);
+        }
+        return results;
+    }
+    async querySemanticWithFilters(query) {
+        if (!query.content && !query.embedding) {
+            return this.queryWithFilters(query);
+        }
+        let embedding = query.embedding;
+        if (!embedding && query.content && this.config.embeddingGenerator) {
+            embedding = await this.config.embeddingGenerator(query.content);
+        }
+        if (!embedding) {
+            return this.queryWithFilters(query);
+        }
+        const searchResults = await this.search(embedding, {
+            k: query.limit * 2, // Over-fetch for filtering
+            threshold: query.threshold,
+            filters: query,
+        });
+        return searchResults.map((r) => r.entry);
+    }
+    queryWithFilters(query) {
+        let entries = [];
+        // Start with namespace filter if provided
+        if (query.namespace) {
+            const namespaceIds = this.namespaceIndex.get(query.namespace);
+            if (!namespaceIds)
+                return [];
+            for (const id of namespaceIds) {
+                const entry = this.entries.get(id);
+                if (entry)
+                    entries.push(entry);
+            }
+        }
+        else {
+            entries = Array.from(this.entries.values());
+        }
+        return entries;
+    }
+    applyFilters(entries, query) {
+        return entries.filter((entry) => {
+            // Namespace filter
+            if (query.namespace && entry.namespace !== query.namespace) {
+                return false;
+            }
+            // Memory type filter
+            if (query.memoryType && entry.type !== query.memoryType) {
+                return false;
+            }
+            // Access level filter
+            if (query.accessLevel && entry.accessLevel !== query.accessLevel) {
+                return false;
+            }
+            // Owner filter
+            if (query.ownerId && entry.ownerId !== query.ownerId) {
+                return false;
+            }
+            // Tags filter
+            if (query.tags && query.tags.length > 0) {
+                if (!query.tags.every((tag) => entry.tags.includes(tag))) {
+                    return false;
+                }
+            }
+            // Time range filters
+            if (query.createdAfter && entry.createdAt < query.createdAfter) {
+                return false;
+            }
+            if (query.createdBefore && entry.createdAt > query.createdBefore) {
+                return false;
+            }
+            if (query.updatedAfter && entry.updatedAt < query.updatedAfter) {
+                return false;
+            }
+            if (query.updatedBefore && entry.updatedAt > query.updatedBefore) {
+                return false;
+            }
+            // Expiration filter
+            if (!query.includeExpired && entry.expiresAt) {
+                if (entry.expiresAt < Date.now()) {
+                    return false;
+                }
+            }
+            // Metadata filters
+            if (query.metadata) {
+                for (const [key, value] of Object.entries(query.metadata)) {
+                    if (entry.metadata[key] !== value) {
+                        return false;
+                    }
+                }
+            }
+            return true;
+        });
+    }
+    updateAccessStats(entry) {
+        entry.accessCount++;
+        entry.lastAccessedAt = Date.now();
+    }
+    estimateMemoryUsage() {
+        let total = 0;
+        // Estimate entry storage
+        for (const entry of this.entries.values()) {
+            total += this.estimateEntrySize(entry);
+        }
+        // Add index memory
+        total += this.index.getStats().memoryUsage;
+        // Add cache memory
+        total += this.cache.getStats().memoryUsage;
+        return total;
+    }
+    estimateEntrySize(entry) {
+        let size = 0;
+        // Base object overhead
+        size += 100;
+        // String fields
+        size += (entry.id.length + entry.key.length + entry.content.length) * 2;
+        // Embedding (Float32Array)
+        if (entry.embedding) {
+            size += entry.embedding.length * 4;
+        }
+        // Tags and references
+        size += entry.tags.join('').length * 2;
+        size += entry.references.join('').length * 2;
+        // Metadata (rough estimate)
+        size += JSON.stringify(entry.metadata).length * 2;
+        return size;
+    }
+    checkStorageHealth(issues, recommendations) {
+        const utilizationPercent = (this.entries.size / this.config.maxEntries) * 100;
+        if (utilizationPercent > 95) {
+            issues.push('Storage utilization critical (>95%)');
+            recommendations.push('Increase maxEntries or cleanup old data');
+            return { status: 'unhealthy', latency: 0, message: 'Storage near capacity' };
+        }
+        if (utilizationPercent > 80) {
+            issues.push('Storage utilization high (>80%)');
+            recommendations.push('Consider cleanup or capacity increase');
+            return { status: 'degraded', latency: 0, message: 'Storage utilization high' };
+        }
+        return { status: 'healthy', latency: 0 };
+    }
+    checkIndexHealth(issues, recommendations) {
+        const stats = this.index.getStats();
+        if (stats.avgSearchTime > 10) {
+            issues.push('Index search time degraded (>10ms)');
+            recommendations.push('Consider rebuilding index or increasing ef');
+            return { status: 'degraded', latency: stats.avgSearchTime };
+        }
+        return { status: 'healthy', latency: stats.avgSearchTime };
+    }
+    checkCacheHealth(issues, recommendations) {
+        const stats = this.cache.getStats();
+        if (stats.hitRate < 0.5) {
+            issues.push('Cache hit rate low (<50%)');
+            recommendations.push('Consider increasing cache size');
+            return {
+                status: 'degraded',
+                latency: 0,
+                message: `Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`,
+            };
+        }
+        return { status: 'healthy', latency: 0 };
+    }
+    /**
+     * Path to the HNSW snapshot sidecar.
+     * Convention: `<persistencePath>.hnsw`
+     */
+    getHnswSidecarPath() {
+        if (!this.config.persistencePath)
+            return null;
+        return `${this.config.persistencePath}.hnsw`;
+    }
+    /**
+     * Path to the in-memory Maps (entries/namespaceIndex/keyIndex/tagIndex) sidecar.
+     * Convention: `<persistencePath>.meta.json`
+     */
+    getMetaSidecarPath() {
+        if (!this.config.persistencePath)
+            return null;
+        return `${this.config.persistencePath}.meta.json`;
+    }
+    /**
+     * Persist a snapshot of the in-memory state to disk.
+     *
+     * Writes two sidecar files alongside `persistencePath`:
+     * - `<persistencePath>.hnsw`        — binary HNSW snapshot via {@link HNSWIndex.serialize}
+     * - `<persistencePath>.meta.json`   — entries + indices in stable JSON
+     *
+     * Public so {@link MemoryService} can trigger periodic snapshots (ADR-125 Phase 3).
+     */
+    async saveSnapshot() {
+        await this.saveToDisk();
+    }
+    /**
+     * ADR-125 Phase 3 — real persistence implementation.
+     *
+     * Loads two sidecar files alongside `persistencePath` (when both exist):
+     * - `<persistencePath>.hnsw`        — binary HNSW snapshot
+     * - `<persistencePath>.meta.json`   — entries + namespaceIndex + keyIndex + tagIndex
+     *
+     * Emits `persistence:loaded` with `{ status: 'restored' | 'fresh' | 'corrupt' }`.
+     * Falls back to a fresh state on any deserialize / IO error so callers don't throw.
+     */
+    async loadFromDisk() {
+        const hnswPath = this.getHnswSidecarPath();
+        const metaPath = this.getMetaSidecarPath();
+        if (!hnswPath || !metaPath) {
+            this.emit('persistence:loaded', { status: 'fresh', reason: 'no-path' });
+            return;
+        }
+        let hnswExists = false;
+        let metaExists = false;
+        try {
+            hnswExists = fs.existsSync(hnswPath);
+        }
+        catch { /* ignore */ }
+        try {
+            metaExists = fs.existsSync(metaPath);
+        }
+        catch { /* ignore */ }
+        if (!hnswExists || !metaExists) {
+            this.emit('persistence:loaded', { status: 'fresh', reason: 'no-sidecar' });
+            return;
+        }
+        try {
+            const metaRaw = fs.readFileSync(metaPath, 'utf-8');
+            const meta = JSON.parse(metaRaw);
+            // Restore entries (rehydrate Float32Array embeddings if present)
+            this.entries.clear();
+            this.namespaceIndex.clear();
+            this.keyIndex.clear();
+            this.tagIndex.clear();
+            for (const persisted of meta.entries) {
+                const entry = {
+                    ...persisted,
+                    embedding: persisted.embedding
+                        ? Float32Array.from(persisted.embedding)
+                        : undefined,
+                };
+                this.entries.set(entry.id, entry);
+            }
+            for (const [ns, ids] of Object.entries(meta.namespaceIndex)) {
+                this.namespaceIndex.set(ns, new Set(ids));
+            }
+            for (const [key, id] of Object.entries(meta.keyIndex)) {
+                this.keyIndex.set(key, id);
+            }
+            for (const [tag, ids] of Object.entries(meta.tagIndex)) {
+                this.tagIndex.set(tag, new Set(ids));
+            }
+            // Restore HNSW
+            const hnswBuf = fs.readFileSync(hnswPath);
+            const restored = HNSWIndex.deserialize(hnswBuf);
+            // Swap pointers — preserves forwarded events because we only re-listen
+            // when the adapter is reconstructed (which happens on a fresh instance).
+            this.index = restored;
+            // Re-forward HNSW events
+            this.index.on('point:added', (data) => this.emit('index:added', data));
+            this.emit('persistence:loaded', { status: 'restored', count: this.entries.size });
+        }
+        catch (err) {
+            // Corrupt sidecar — start fresh, leave existing files in place for
+            // operator inspection.
+            this.entries.clear();
+            this.namespaceIndex.clear();
+            this.keyIndex.clear();
+            this.tagIndex.clear();
+            this.emit('persistence:loaded', {
+                status: 'corrupt',
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * ADR-125 Phase 3 — real snapshot implementation.
+     *
+     * Writes both sidecars atomically via a temp-file-and-rename dance so a
+     * crash mid-write doesn't leave half-baked state on disk.
+     */
+    async saveToDisk() {
+        const hnswPath = this.getHnswSidecarPath();
+        const metaPath = this.getMetaSidecarPath();
+        if (!hnswPath || !metaPath) {
+            this.emit('persistence:saved', { status: 'skipped', reason: 'no-path' });
+            return;
+        }
+        try {
+            // Ensure parent dir exists
+            const dir = path.dirname(hnswPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Build stable JSON representation
+            const meta = this.buildPersistedMeta();
+            const metaText = JSON.stringify(meta);
+            // Build HNSW snapshot
+            const hnswBuf = this.index.serialize();
+            // Atomic write via temp + rename
+            const hnswTmp = `${hnswPath}.tmp`;
+            const metaTmp = `${metaPath}.tmp`;
+            fs.writeFileSync(hnswTmp, hnswBuf);
+            fs.writeFileSync(metaTmp, metaText);
+            fs.renameSync(hnswTmp, hnswPath);
+            fs.renameSync(metaTmp, metaPath);
+            this.emit('persistence:saved', {
+                status: 'ok',
+                bytes: hnswBuf.length + Buffer.byteLength(metaText, 'utf-8'),
+            });
+        }
+        catch (err) {
+            this.emit('persistence:saved', {
+                status: 'failed',
+                reason: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Build a stable, diff-friendly JSON representation of the in-memory Maps.
+     * Keys are sorted; embeddings are serialized as plain number arrays.
+     */
+    buildPersistedMeta() {
+        const entriesArr = [...this.entries.values()].sort((a, b) => a.id.localeCompare(b.id));
+        const persistedEntries = entriesArr.map((e) => ({
+            ...e,
+            embedding: e.embedding ? Array.from(e.embedding) : undefined,
+        }));
+        const namespaceIndex = {};
+        for (const ns of [...this.namespaceIndex.keys()].sort()) {
+            namespaceIndex[ns] = [...this.namespaceIndex.get(ns)].sort();
+        }
+        const keyIndex = {};
+        for (const k of [...this.keyIndex.keys()].sort()) {
+            keyIndex[k] = this.keyIndex.get(k);
+        }
+        const tagIndex = {};
+        for (const t of [...this.tagIndex.keys()].sort()) {
+            tagIndex[t] = [...this.tagIndex.get(t)].sort();
+        }
+        return { version: 1, entries: persistedEntries, namespaceIndex, keyIndex, tagIndex };
+    }
+}
+// ADR-125 Phase 5 — minimal tokenizer for the in-memory keyword fallback.
+// Mirrors the shape used in `smart-retrieval.ts` but is duplicated here so the
+// adapter has no dependency on the retrieval layer.
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'any', 'can',
+    'her', 'was', 'one', 'our', 'out', 'day', 'get', 'has', 'him', 'his',
+    'how', 'man', 'new', 'now', 'old', 'see', 'two', 'way', 'who', 'boy',
+    'did', 'its', 'let', 'put', 'say', 'she', 'too', 'use', 'with', 'this',
+    'that', 'have', 'from', 'they', 'will', 'been', 'were', 'what', 'when',
+    'your',
+]);
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter((t) => t.length > 2 && !STOPWORDS.has(t)));
+}
+export default AgentDBAdapter;
+//# sourceMappingURL=agentdb-adapter.js.map