@psiclawops/hypermem 0.5.0 → 0.5.1

package/dist/index.js

@@ -0,0 +1,1072 @@
+/**
+ * hypermem — Agent-Centric Memory & Context Composition Engine
+ *
+ * @module @psiclawops/hypermem
+ *
+ * Architecture:
+ *   L1: Redis       — hot session working memory
+ *   L2: messages.db — per-agent conversation log (rotatable)
+ *   L3: vectors.db  — per-agent semantic search index (reconstructable)
+ *   L4: library.db  — fleet-wide structured knowledge (crown jewel)
+ */
+export { ENGINE_VERSION, MIN_NODE_VERSION, MIN_REDIS_VERSION, SQLITE_VEC_VERSION, MAIN_SCHEMA_VERSION, LIBRARY_SCHEMA_VERSION_EXPORT, HYPERMEM_COMPAT_VERSION, SCHEMA_COMPAT } from './version.js';
+export { DatabaseManager } from './db.js';
+export { MessageStore } from './message-store.js';
+export { FactStore } from './fact-store.js';
+export { KnowledgeStore } from './knowledge-store.js';
+export { TopicStore } from './topic-store.js';
+export { EpisodeStore } from './episode-store.js';
+export { PreferenceStore } from './preference-store.js';
+export { FleetStore } from './fleet-store.js';
+export { SystemStore } from './system-store.js';
+export { WorkStore } from './work-store.js';
+export { DesiredStateStore } from './desired-state-store.js';
+export { evictStaleContent, DEFAULT_EVICTION_CONFIG } from './image-eviction.js';
+export { KnowledgeGraph } from './knowledge-graph.js';
+export { RateLimiter, createRateLimitedEmbedder } from './rate-limiter.js';
+export { CacheLayer } from './cache.js';
+export { Compositor, applyToolGradientToWindow, canPersistReshapedHistory } from './compositor.js';
+export { TRIGGER_REGISTRY, TRIGGER_REGISTRY_VERSION, TRIGGER_REGISTRY_HASH, DEFAULT_TRIGGERS, matchTriggers, } from './trigger-registry.js';
+export { ensureCompactionFenceSchema, updateCompactionFence, getCompactionFence, getCompactionEligibility, getCompactableMessages, } from './compaction-fence.js';
+export { verifyPreservation, verifyPreservationFromVectors, } from './preservation-gate.js';
+export { toProviderFormat, fromProviderFormat, userMessageToNeutral, toolResultsToNeutral, normalizeToolCallId, generateToolCallId, detectProvider, repairToolCallPairs, } from './provider-translator.js';
+export { migrate, SCHEMA_VERSION } from './schema.js';
+export { migrateLibrary, LIBRARY_SCHEMA_VERSION } from './library-schema.js';
+export { VectorStore, generateEmbeddings } from './vector-store.js';
+export { hybridSearch, buildFtsQuery } from './hybrid-retrieval.js';
+export { DocChunkStore } from './doc-chunk-store.js';
+export { WorkspaceSeeder, seedWorkspace } from './seed.js';
+export { chunkMarkdown, chunkFile, inferCollection, hashContent, ACA_COLLECTIONS } from './doc-chunker.js';
+export { crossAgentQuery, canAccess, visibilityFilter, defaultOrgRegistry, buildOrgRegistryFromDb, loadOrgRegistryFromDb, } from './cross-agent.js';
+export { BackgroundIndexer, createIndexer } from './background-indexer.js';
+export { runDreamingPromoter, runDreamingPassForFleet, resolveAgentWorkspacePath, DEFAULT_DREAMER_CONFIG, } from './dreaming-promoter.js';
+export { TopicSynthesizer } from './topic-synthesizer.js';
+export { WikiPageEmitter } from './wiki-page-emitter.js';
+export { lintKnowledge } from './knowledge-lint.js';
+export { buildSpawnContext } from './spawn-context.js';
+export { runNoiseSweep, runToolDecay } from './proactive-pass.js';
+export { classifyContentType, signalWeight, isSignalBearing, SIGNAL_WEIGHT } from './content-type-classifier.js';
+export { detectTopicShift, stripMessageMetadata } from './topic-detector.js';
+export { SessionTopicMap } from './session-topic-map.js';
+export { getActiveFOS, matchMOD, renderFOS, renderMOD, recordOutputMetrics, } from './fos-mod.js';
+import { DatabaseManager } from './db.js';
+import { MessageStore } from './message-store.js';
+import { FactStore } from './fact-store.js';
+import { KnowledgeStore } from './knowledge-store.js';
+import { TopicStore } from './topic-store.js';
+import { EpisodeStore } from './episode-store.js';
+import { PreferenceStore } from './preference-store.js';
+import { FleetStore } from './fleet-store.js';
+import { SystemStore } from './system-store.js';
+import { WorkStore } from './work-store.js';
+import { KnowledgeGraph } from './knowledge-graph.js';
+import { DesiredStateStore } from './desired-state-store.js';
+import { CacheLayer } from './cache.js';
+import { Compositor } from './compositor.js';
+import { VectorStore } from './vector-store.js';
+import { userMessageToNeutral, fromProviderFormat } from './provider-translator.js';
+import { stripMessageMetadata } from './topic-detector.js';
+import { DocChunkStore } from './doc-chunk-store.js';
+import { WorkspaceSeeder } from './seed.js';
+import { crossAgentQuery, buildOrgRegistryFromDb } from './cross-agent.js';
+import path from 'node:path';
+import os from 'node:os';
+const DEFAULT_CONFIG = {
+    enabled: true,
+    dataDir: path.join(process.env.HOME || os.homedir(), '.openclaw', 'hypermem'),
+    cache: {
+        keyPrefix: 'hm:',
+        sessionTTL: 14400, // 4 hours — system/identity/meta slots
+        historyTTL: 604800, // 7 days — extended for ClawCanvas display
+    },
+    compositor: {
+        // TUNE-010 (2026-04-02): Raised from 65000 → 90000.
+        // TUNE-008 dropped to 65k as a tool-loop overflow band-aid. The real fix
+        // (tool-loop pass-through guard in assemble()) means tool turns don't
+        // re-run composition, so 90k is safe — leaves ~30k headroom for in-flight
+        // tool results on a 120k window. Budget is better spent on context quality.
+        defaultTokenBudget: 90000,
+        maxHistoryMessages: 1000,
+        maxFacts: 28,
+        maxCrossSessionContext: 6000,
+        maxRecentToolPairs: 3,
+        maxProseToolPairs: 10,
+        warmHistoryBudgetFraction: 0.4,
+    },
+    indexer: {
+        enabled: true,
+        factExtractionMode: 'tiered',
+        topicDormantAfter: '24h',
+        topicClosedAfter: '7d',
+        factDecayRate: 0.01,
+        episodeSignificanceThreshold: 0.5,
+        periodicInterval: 300000,
+        batchSize: 128,
+        maxMessagesPerTick: 500,
+    },
+    embedding: {
+        ollamaUrl: 'http://localhost:11434',
+        model: 'nomic-embed-text',
+        dimensions: 768,
+        timeout: 10000,
+        batchSize: 32,
+    },
+};
+/**
+ * hypermem — the main API facade.
+ *
+ * Usage:
+ *   const hm = await hypermem.create({ dataDir: '~/.openclaw/hypermem' });
+ *   await hm.record('forge', 'agent:forge:webchat:main', userMsg);
+ *   const result = await hm.compose({ agentId: 'forge', sessionKey: '...', ... });
+ */
+export class HyperMem {
+    dbManager;
+    cache;
+    compositor;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.dbManager = new DatabaseManager({ dataDir: config.dataDir });
+        this.cache = new CacheLayer(config.cache);
+        this.compositor = new Compositor({
+            cache: this.cache,
+            vectorStore: null, // Set after create() when vector DB is available
+            libraryDb: null, // Set after create() when library DB is available
+        }, config.compositor);
+    }
+    /**
+     * Get the active vector store, if initialized.
+     * Used by the plugin to wire embeddings into the background indexer.
+     */
+    getVectorStore() {
+        return this.compositor.vectorStore;
+    }
+    /**
+     * Create and initialize a hypermem instance.
+     */
+    static async create(config) {
+        const merged = {
+            ...DEFAULT_CONFIG,
+            ...config,
+            cache: { ...DEFAULT_CONFIG.cache, ...config?.cache },
+            compositor: { ...DEFAULT_CONFIG.compositor, ...config?.compositor },
+            indexer: { ...DEFAULT_CONFIG.indexer, ...config?.indexer },
+            embedding: {
+                ...DEFAULT_CONFIG.embedding,
+                ...config?.embedding,
+            },
+        };
+        const hm = new HyperMem(merged);
+        const cacheOk = await hm.cache.connect();
+        if (cacheOk) {
+            console.log('[hypermem] Cache connected');
+        }
+        else {
+            console.warn('[hypermem] Cache unavailable — running in SQLite-only mode');
+        }
+        // ── Vector store init ─────────────────────────────────────
+        // Attempt to wire up sqlite-vec + nomic-embed-text for semantic recall.
+        // Non-fatal: if sqlite-vec isn't available or Ollama is down,
+        // hybridSearch() continues in FTS5-only mode.
+        // The vector store is shared (not per-agent) — facts/episodes from all agents
+        // are indexed together, keyed by (source_table, source_id).
+        try {
+            const vectorDb = hm.dbManager.getSharedVectorDb();
+            if (vectorDb) {
+                const vs = new VectorStore(vectorDb, merged.embedding, hm.dbManager.getLibraryDb());
+                vs.ensureTables();
+                hm.compositor.setVectorStore(vs);
+                const embeddingDesc = merged.embedding.provider === 'openai'
+                    ? `${merged.embedding.openaiBaseUrl?.includes('openrouter') ? 'openrouter' : 'openai'}/${merged.embedding.model ?? 'text-embedding-3-small'}`
+                    : `ollama/${merged.embedding.model ?? 'nomic-embed-text'}`;
+                console.log(`[hypermem] Vector store initialized (sqlite-vec + ${embeddingDesc})`);
+            }
+            else {
+                console.warn('[hypermem] sqlite-vec unavailable — semantic recall in FTS5-only mode');
+            }
+        }
+        catch (err) {
+            console.warn('[hypermem] Vector store init failed (non-fatal):', err.message);
+        }
+        return hm;
+    }
+    // ─── Core API (L2: Message DB) ──────────────────────────────
+    /**
+     * Record a user message.
+     */
+    async recordUserMessage(agentId, sessionKey, content, opts) {
+        const db = this.dbManager.getMessageDb(agentId);
+        this.dbManager.ensureAgent(agentId);
+        const store = new MessageStore(db);
+        const conversation = store.getOrCreateConversation(agentId, sessionKey, {
+            channelType: opts?.channelType,
+            channelId: opts?.channelId,
+            provider: opts?.provider,
+            model: opts?.model,
+        });
+        const neutral = userMessageToNeutral(stripMessageMetadata(content));
+        const stored = store.recordMessage(conversation.id, agentId, neutral, {
+            tokenCount: opts?.tokenCount,
+            isHeartbeat: opts?.isHeartbeat,
+        });
+        await this.cache.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
+        await this.cache.touchSession(agentId, sessionKey);
+        return stored;
+    }
+    /**
+     * Record an assistant response.
+     */
+    async recordAssistantMessage(agentId, sessionKey, message, opts) {
+        const db = this.dbManager.getMessageDb(agentId);
+        const store = new MessageStore(db);
+        const conversation = store.getConversation(sessionKey);
+        if (!conversation) {
+            throw new Error(`No conversation found for session ${sessionKey}`);
+        }
+        const stored = store.recordMessage(conversation.id, agentId, message, {
+            tokenCount: opts?.tokenCount,
+        });
+        await this.cache.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
+        await this.cache.touchSession(agentId, sessionKey);
+        return stored;
+    }
+    /**
+     * Record a raw provider response, converting to neutral format.
+     */
+    async recordProviderResponse(agentId, sessionKey, response, provider, opts) {
+        const neutral = fromProviderFormat(response, provider);
+        return this.recordAssistantMessage(agentId, sessionKey, neutral, opts);
+    }
+    /**
+     * Compose context for an LLM call.
+     */
+    async compose(request) {
+        const db = this.dbManager.getMessageDb(request.agentId);
+        const libraryDb = this.dbManager.getLibraryDb();
+        return this.compositor.compose(request, db, libraryDb);
+    }
+    /**
+     * Warm a session from SQLite into Redis.
+     */
+    async warm(agentId, sessionKey, opts) {
+        const db = this.dbManager.getMessageDb(agentId);
+        const libraryDb = this.dbManager.getLibraryDb();
+        await this.compositor.warmSession(agentId, sessionKey, db, { ...opts, libraryDb });
+    }
+    /**
+     * Recompute the Redis hot history view from SQLite and re-apply tool gradient.
+     */
+    async refreshRedisGradient(agentId, sessionKey, tokenBudget) {
+        const db = this.dbManager.getMessageDb(agentId);
+        await this.compositor.refreshRedisGradient(agentId, sessionKey, db, tokenBudget);
+    }
+    /**
+     * Full-text search across all messages for an agent.
+     */
+    search(agentId, query, limit = 20) {
+        const db = this.dbManager.getMessageDb(agentId);
+        const store = new MessageStore(db);
+        return store.searchMessages(agentId, query, limit);
+    }
+    /**
+     * Get or create a conversation.
+     */
+    getOrCreateConversation(agentId, sessionKey, opts) {
+        const db = this.dbManager.getMessageDb(agentId);
+        this.dbManager.ensureAgent(agentId);
+        const store = new MessageStore(db);
+        return store.getOrCreateConversation(agentId, sessionKey, opts);
+    }
+    /**
+     * List all agents with databases.
+     */
+    listAgents() {
+        return this.dbManager.listAgents();
+    }
+    // ─── Facts (L4: Library) ────────────────────────────────────
+    /**
+     * Add a fact.
+     */
+    addFact(agentId, content, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FactStore(db);
+        return store.addFact(agentId, content, opts);
+    }
+    /**
+     * Get active facts for an agent.
+     */
+    getActiveFacts(agentId, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FactStore(db);
+        return store.getActiveFacts(agentId, opts);
+    }
+    // ─── Knowledge (L4: Library) ────────────────────────────────
+    /**
+     * Add/update knowledge.
+     */
+    upsertKnowledge(agentId, domain, key, content, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new KnowledgeStore(db);
+        return store.upsert(agentId, domain, key, content, opts);
+    }
+    /**
+     * Get active knowledge, optionally filtered by domain.
+     */
+    getKnowledge(agentId, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new KnowledgeStore(db);
+        return store.getActive(agentId, opts);
+    }
+    // ─── Topics (L4: Library) ───────────────────────────────────
+    /**
+     * Create a topic.
+     */
+    createTopic(agentId, name, description) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new TopicStore(db);
+        return store.create(agentId, name, description);
+    }
+    /**
+     * Get active topics.
+     */
+    getActiveTopics(agentId, limit = 20) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new TopicStore(db);
+        return store.getActive(agentId, limit);
+    }
+    // ─── Episodes (L4: Library) ─────────────────────────────────
+    /**
+     * Record an episode.
+     */
+    recordEpisode(agentId, eventType, summary, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new EpisodeStore(db);
+        return store.record(agentId, eventType, summary, opts);
+    }
+    /**
+     * Get recent episodes.
+     */
+    getRecentEpisodes(agentId, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new EpisodeStore(db);
+        return store.getRecent(agentId, opts);
+    }
+    // ─── Preferences (L4: Library) ──────────────────────────────
+    /**
+     * Set a preference.
+     */
+    setPreference(subject, key, value, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new PreferenceStore(db);
+        return store.set(subject, key, value, opts);
+    }
+    /**
+     * Get a preference.
+     */
+    getPreference(subject, key, domain) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new PreferenceStore(db);
+        return store.get(subject, key, domain);
+    }
+    /**
+     * Get all preferences for a subject.
+     */
+    getPreferences(subject, domain) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new PreferenceStore(db);
+        return store.getForSubject(subject, domain);
+    }
+    // ─── Fleet Registry (L4: Library) ───────────────────────────
+    /**
+     * Register or update a fleet agent. Invalidates cache.
+     */
+    upsertFleetAgent(id, data) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        const result = store.upsertAgent(id, data);
+        // Invalidate cache — fire and forget
+        this.cache.invalidateFleetAgent(id).catch(() => { });
+        return result;
+    }
+    /**
+     * Get a fleet agent. Cache-aside: check Redis first, fall back to SQLite.
+     */
+    async getFleetAgentCached(id) {
+        // Try cache first
+        const cached = await this.cache.getCachedFleetAgent(id);
+        if (cached)
+            return cached;
+        // Fall back to SQLite
+        const agent = this.getFleetAgent(id);
+        if (agent) {
+            // Warm cache — fire and forget
+            this.cache.cacheFleetAgent(id, agent).catch(() => { });
+        }
+        return agent;
+    }
+    /**
+     * Get a fleet agent (synchronous, SQLite only).
+     */
+    getFleetAgent(id) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        return store.getAgent(id);
+    }
+    /**
+     * List fleet agents.
+     */
+    listFleetAgents(opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        return store.listAgents(opts);
+    }
+    /**
+     * Register or update a fleet org.
+     */
+    upsertFleetOrg(id, data) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        return store.upsertOrg(id, data);
+    }
+    /**
+     * List fleet orgs.
+     */
+    listFleetOrgs() {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        return store.listOrgs();
+    }
+    // ─── Agent Capabilities (L4: Library) ────────────────────────
+    /**
+     * Register or update a capability for an agent.
+     */
+    upsertCapability(agentId, cap) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        return store.upsertCapability(agentId, cap);
+    }
+    /**
+     * Bulk-sync capabilities of a given type for an agent.
+     * Marks capabilities not in the list as 'removed'.
+     */
+    syncCapabilities(agentId, capType, caps) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        store.syncCapabilities(agentId, capType, caps);
+    }
+    /**
+     * Get capabilities for an agent, optionally filtered by type.
+     */
+    getAgentCapabilities(agentId, capType) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        return store.getAgentCapabilities(agentId, capType);
+    }
+    /**
+     * Find agents that have a specific capability.
+     */
+    findAgentsByCapability(capType, name) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new FleetStore(db);
+        return store.findByCapability(capType, name);
+    }
+    // ─── System Registry (L4: Library) ──────────────────────────
+    /**
+     * Set a system state value.
+     */
+    setSystemState(category, key, value, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new SystemStore(db);
+        return store.set(category, key, value, opts);
+    }
+    /**
+     * Get a system state value.
+     */
+    getSystemState(category, key) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new SystemStore(db);
+        return store.get(category, key);
+    }
+    /**
+     * Get all state in a category.
+     */
+    getSystemCategory(category) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new SystemStore(db);
+        return store.getCategory(category);
+    }
+    // ─── Work Items (L4: Library) ───────────────────────────────
+    /**
+     * Create a work item.
+     */
+    createWorkItem(data) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new WorkStore(db);
+        return store.create(data);
+    }
+    /**
+     * Update work item status.
+     */
+    updateWorkStatus(id, status, agentId, comment) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new WorkStore(db);
+        return store.updateStatus(id, status, agentId, comment);
+    }
+    /**
+     * Get active work for an agent.
+     */
+    getAgentWork(agentId, status) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new WorkStore(db);
+        return store.getAgentWork(agentId, status);
+    }
+    /**
+     * Get the fleet kanban board.
+     */
+    getFleetKanban(opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new WorkStore(db);
+        return store.getKanban(opts);
+    }
+    /**
+     * Get work item stats.
+     */
+    getWorkStats(opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new WorkStore(db);
+        return store.getStats(opts);
+    }
+    /**
+     * Get blocked work items.
+     */
+    getBlockedWork() {
+        const db = this.dbManager.getLibraryDb();
+        const store = new WorkStore(db);
+        return store.getBlocked();
+    }
+    // ─── Agent Desired State (L4: Library) ──────────────────────
+    /**
+     * Set desired configuration for an agent.
+     */
+    setDesiredState(agentId, configKey, desiredValue, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        const result = store.setDesired(agentId, configKey, desiredValue, opts);
+        // Invalidate cache — desired state change affects fleet view
+        this.cache.invalidateFleetAgent(agentId).catch(() => { });
+        return result;
+    }
+    /**
+     * Report actual runtime value for drift detection. Invalidates cache.
+     */
+    reportActualState(agentId, configKey, actualValue) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        const result = store.reportActual(agentId, configKey, actualValue);
+        this.cache.invalidateFleetAgent(agentId).catch(() => { });
+        return result;
+    }
+    /**
+     * Bulk report actual state (e.g., on session startup / heartbeat). Invalidates cache.
+     */
+    reportActualStateBulk(agentId, actuals) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        const result = store.reportActualBulk(agentId, actuals);
+        this.cache.invalidateFleetAgent(agentId).catch(() => { });
+        return result;
+    }
+    /**
+     * Get all desired state for an agent.
+     */
+    getDesiredState(agentId) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        return store.getAgentState(agentId);
+    }
+    /**
+     * Get desired state as a flat config map.
+     */
+    getDesiredConfig(agentId) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        return store.getAgentConfig(agentId);
+    }
+    /**
+     * Get all drifted entries across the fleet.
+     */
+    getDriftedState() {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        return store.getDrifted();
+    }
+    /**
+     * Get fleet-wide view of a specific config key.
+     */
+    getFleetConfigKey(configKey) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        return store.getFleetConfig(configKey);
+    }
+    /**
+     * Get config change history.
+     */
+    getConfigHistory(agentId, configKey, limit) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        return store.getHistory(agentId, configKey, limit);
+    }
+    /**
+     * Get fleet drift summary.
+     */
+    getDriftSummary() {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DesiredStateStore(db);
+        return store.getDriftSummary();
+    }
+    // ─── Knowledge Graph (L4: Library) ──────────────────────────
+    /**
+     * Add a directed link between two entities.
+     */
+    addKnowledgeLink(fromType, fromId, toType, toId, linkType) {
+        const db = this.dbManager.getLibraryDb();
+        const graph = new KnowledgeGraph(db);
+        return graph.addLink(fromType, fromId, toType, toId, linkType);
+    }
+    /**
+     * Remove a specific link.
+     */
+    removeKnowledgeLink(fromType, fromId, toType, toId, linkType) {
+        const db = this.dbManager.getLibraryDb();
+        const graph = new KnowledgeGraph(db);
+        return graph.removeLink(fromType, fromId, toType, toId, linkType);
+    }
+    /**
+     * Get all links for an entity (both directions).
+     */
+    getEntityLinks(type, id) {
+        const db = this.dbManager.getLibraryDb();
+        const graph = new KnowledgeGraph(db);
+        return graph.getLinks(type, id);
+    }
+    /**
+     * Traverse the knowledge graph from a starting entity.
+     * BFS with bounded depth and result count.
+     */
+    traverseGraph(startType, startId, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const graph = new KnowledgeGraph(db);
+        return graph.traverse(startType, startId, opts);
+    }
+    /**
+     * Find the shortest path between two entities.
+     */
+    findGraphPath(fromType, fromId, toType, toId, maxDepth) {
+        const db = this.dbManager.getLibraryDb();
+        const graph = new KnowledgeGraph(db);
+        return graph.findPath(fromType, fromId, toType, toId, maxDepth);
+    }
+    /**
+     * Get the most connected entities.
+     */
+    getMostConnectedEntities(opts) {
+        const db = this.dbManager.getLibraryDb();
+        const graph = new KnowledgeGraph(db);
+        return graph.getMostConnected(opts);
+    }
+    /**
+     * Get knowledge graph statistics.
+     */
+    getGraphStats() {
+        const db = this.dbManager.getLibraryDb();
+        const graph = new KnowledgeGraph(db);
+        return {
+            totalLinks: graph.getTotalLinks(),
+            byType: graph.getLinkStats(),
+        };
+    }
+    // ─── Vector / Semantic Search (L3: Vectors DB) ──────────────
+    /**
+     * Semantic search across an agent's indexed memory.
+     */
+    async semanticSearch(agentId, query, opts) {
+        const db = this.dbManager.getVectorDb(agentId);
+        if (!db) {
+            console.warn('[hypermem] Semantic search unavailable — sqlite-vec not loaded');
+            return [];
+        }
+        const libraryDb = this.dbManager.getLibraryDb();
+        const vs = new VectorStore(db, this.config.embedding, libraryDb);
+        return vs.search(query, opts);
+    }
+    /**
+     * Index all un-indexed content for an agent.
+     */
+    async indexAgent(agentId) {
+        const db = this.dbManager.getVectorDb(agentId);
+        if (!db)
+            return { indexed: 0, skipped: 0, tombstoned: 0 };
+        const libraryDb = this.dbManager.getLibraryDb();
+        const vs = new VectorStore(db, this.config.embedding, libraryDb);
+        vs.ensureTables();
+        const result = await vs.indexAll(agentId);
+        // Tombstone superseded facts/knowledge so they don't surface in recall
+        const tombstoned = vs.tombstoneSuperseded();
+        return { ...result, tombstoned };
+    }
+    /**
+     * Get vector index statistics.
+     */
+    getVectorStats(agentId) {
+        const db = this.dbManager.getVectorDb(agentId);
+        if (!db)
+            return null;
+        const libraryDb = this.dbManager.getLibraryDb();
+        const vs = new VectorStore(db, this.config.embedding, libraryDb);
+        return vs.getStats();
+    }
+    /**
+     * Prune orphaned vector entries.
+     */
+    pruneVectorOrphans(agentId) {
+        const db = this.dbManager.getVectorDb(agentId);
+        if (!db)
+            return 0;
+        const libraryDb = this.dbManager.getLibraryDb();
+        const vs = new VectorStore(db, this.config.embedding, libraryDb);
+        return vs.pruneOrphans();
+    }
+    // ─── Session Cursor (dual-read: Redis → SQLite fallback) ──────
+    /**
+     * Get the session cursor for an agent+session.
+     * Reads from Redis first; falls back to SQLite if Redis returns null
+     * (e.g. after eviction or restart). This is the P1.3 durability guarantee.
+     */
+    async getSessionCursor(agentId, sessionKey) {
+        // Try Redis first (hot path)
+        const redisCursor = await this.cache.getCursor(agentId, sessionKey);
+        if (redisCursor)
+            return redisCursor;
+        // Fallback to SQLite
+        const db = this.dbManager.getMessageDb(agentId);
+        if (!db)
+            return null;
+        const row = db.prepare(`
+      SELECT cursor_last_sent_id, cursor_last_sent_index, cursor_last_sent_at,
+             cursor_window_size, cursor_token_count
+      FROM conversations
+      WHERE session_key = ? AND cursor_last_sent_id IS NOT NULL
+    `).get(sessionKey);
+        if (!row || row.cursor_last_sent_id == null)
+            return null;
+        const cursor = {
+            lastSentId: row.cursor_last_sent_id,
+            lastSentIndex: row.cursor_last_sent_index,
+            lastSentAt: row.cursor_last_sent_at,
+            windowSize: row.cursor_window_size,
+            tokenCount: row.cursor_token_count,
+        };
+        // Re-warm Redis so subsequent reads are fast
+        try {
+            await this.cache.setCursor(agentId, sessionKey, cursor);
+        }
+        catch {
+            // Best-effort re-warm
+        }
+        return cursor;
+    }
+    // ─── Message Rotation (L2: Messages) ────────────────────────
+    /**
+     * Get the size of an agent's active messages.db in bytes.
+     */
+    getMessageDbSize(agentId) {
+        return this.dbManager.getMessageDbSize(agentId);
+    }
+    /**
+     * Check if an agent's message database needs rotation.
+     */
+    shouldRotate(agentId, opts) {
+        return this.dbManager.shouldRotate(agentId, opts);
+    }
+    /**
+     * Rotate an agent's message database.
+     * Returns the path to the rotated file, or null if no active DB exists.
+     */
+    rotateMessageDb(agentId) {
+        return this.dbManager.rotateMessageDb(agentId);
+    }
+    /**
+     * List rotated message DB files for an agent.
+     */
+    listRotatedDbs(agentId) {
+        return this.dbManager.listRotatedDbs(agentId);
+    }
+    /**
+     * Check and auto-rotate all agents' message databases.
+     * Call on heartbeat/startup.
+     * Returns agents that were rotated.
+     */
+    autoRotate(opts) {
+        const agents = this.dbManager.listAgents();
+        const rotated = [];
+        for (const agentId of agents) {
+            const check = this.shouldRotate(agentId, opts);
+            if (check) {
+                const rotatedPath = this.rotateMessageDb(agentId);
+                if (rotatedPath) {
+                    rotated.push({
+                        agentId,
+                        reason: `${check.reason}: ${check.current} > ${check.threshold}`,
+                        rotatedTo: rotatedPath,
+                    });
+                }
+            }
+        }
+        return rotated;
+    }
+    // ─── Session Registry (L4: Library) ─────────────────────────
+    /**
+     * Register a session start.
+     */
+    registerSession(sessionKey, agentId, opts) {
+        const db = this.dbManager.getLibraryDb();
+        const now = new Date().toISOString();
+        const existing = db
+            .prepare('SELECT id FROM session_registry WHERE id = ?')
+            .get(sessionKey);
+        if (existing) {
+            db.prepare('UPDATE session_registry SET status = ?, started_at = ? WHERE id = ?')
+                .run('active', now, sessionKey);
+        }
+        else {
+            db.prepare(`INSERT INTO session_registry (id, agent_id, channel, channel_type, started_at, status)
+         VALUES (?, ?, ?, ?, ?, 'active')`).run(sessionKey, agentId, opts?.channel || null, opts?.channelType || null, now);
+        }
+        db.prepare('INSERT INTO session_events (session_id, event_type, timestamp, payload) VALUES (?, ?, ?, ?)').run(sessionKey, 'start', now, JSON.stringify({ channel: opts?.channel, channelType: opts?.channelType }));
+    }
+    /**
+     * Record a session event.
+     */
+    recordSessionEvent(sessionKey, eventType, payload) {
+        const db = this.dbManager.getLibraryDb();
+        db.prepare('INSERT INTO session_events (session_id, event_type, timestamp, payload) VALUES (?, ?, ?, ?)').run(sessionKey, eventType, new Date().toISOString(), payload ? JSON.stringify(payload) : null);
+        if (eventType === 'decision') {
+            db.prepare('UPDATE session_registry SET decisions_made = decisions_made + 1 WHERE id = ?').run(sessionKey);
+        }
+        else if (eventType === 'fact_extracted') {
+            db.prepare('UPDATE session_registry SET facts_extracted = facts_extracted + 1 WHERE id = ?').run(sessionKey);
+        }
+    }
+    /**
+     * Close a session.
+     */
+    closeSession(sessionKey, summary) {
+        const db = this.dbManager.getLibraryDb();
+        const now = new Date().toISOString();
+        db.prepare('UPDATE session_registry SET status = ?, ended_at = ?, summary = ? WHERE id = ?').run('completed', now, summary || null, sessionKey);
+        db.prepare('INSERT INTO session_events (session_id, event_type, timestamp) VALUES (?, ?, ?)').run(sessionKey, 'completion', now);
+    }
+    /**
+     * Query sessions.
+     */
+    querySessions(opts) {
+        const db = this.dbManager.getLibraryDb();
+        const conditions = [];
+        const params = [];
+        if (opts?.agentId) {
+            conditions.push('agent_id = ?');
+            params.push(opts.agentId);
+        }
+        if (opts?.status) {
+            conditions.push('status = ?');
+            params.push(opts.status);
+        }
+        if (opts?.since) {
+            conditions.push('started_at >= ?');
+            params.push(opts.since);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+        return db
+            .prepare(`SELECT * FROM session_registry ${where} ORDER BY started_at DESC LIMIT ?`)
+            .all(...params, opts?.limit || 50);
+    }
+    /**
+     * Get session events.
+     */
+    getSessionEvents(sessionKey, limit = 50) {
+        const db = this.dbManager.getLibraryDb();
+        return db
+            .prepare('SELECT * FROM session_events WHERE session_id = ? ORDER BY timestamp DESC LIMIT ?')
+            .all(sessionKey, limit);
+    }
+    // ─── Cross-Agent Queries ─────────────────────────────────────
+    /**
+     * Query another agent's memory with visibility-scoped access.
+     */
+    queryAgent(requesterId, targetAgentId, opts, registry) {
+        return crossAgentQuery(this.dbManager, {
+            requesterId,
+            targetAgentId,
+            memoryType: opts?.memoryType || 'facts',
+            domain: opts?.domain,
+            limit: opts?.limit,
+        }, registry || buildOrgRegistryFromDb(this.dbManager.getLibraryDb()));
+    }
+    /**
+     * Query fleet-wide visible memory.
+     */
+    queryFleet(requesterId, opts, registry) {
+        const reg = registry || buildOrgRegistryFromDb(this.dbManager.getLibraryDb());
+        const results = [];
+        // Query all agents from the fleet registry
+        const libraryDb = this.dbManager.getLibraryDb();
+        const agents = libraryDb
+            .prepare("SELECT id FROM fleet_agents WHERE status = 'active'")
+            .all();
+        for (const agent of agents) {
+            if (agent.id === requesterId)
+                continue;
+            try {
+                const agentResults = this.queryAgent(requesterId, agent.id, opts, reg);
+                results.push(...agentResults);
+            }
+            catch {
+                // Skip agents we can't query (not in registry)
+            }
+        }
+        return results;
+    }
+    // ─── Document Chunks (L4: Library) ──────────────────────────
+    /**
+     * Index chunks from a parsed set of DocChunk objects.
+     * Atomic: replaces all chunks for the source in one transaction.
+     */
+    indexDocChunks(chunks) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DocChunkStore(db);
+        return store.indexChunks(chunks);
+    }
+    /**
+     * Query doc chunks by collection with optional keyword/scope/agent filters.
+     */
+    queryDocChunks(query) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DocChunkStore(db);
+        return store.queryChunks(query);
+    }
+    /**
+     * Seed all ACA files from a workspace directory into the doc chunk index.
+     * Idempotent: skips files whose source hash hasn't changed.
+     * Force re-index with opts.force = true.
+     */
+    async seedWorkspace(workspaceDir, opts = {}) {
+        const db = this.dbManager.getLibraryDb();
+        const seeder = new WorkspaceSeeder(db);
+        return seeder.seedWorkspace(workspaceDir, opts);
+    }
+    /**
+     * Seed a single file into the doc chunk index.
+     */
+    seedFile(filePath, collection, opts = {}) {
+        const db = this.dbManager.getLibraryDb();
+        const seeder = new WorkspaceSeeder(db);
+        return seeder.seedFile(filePath, collection, opts);
+    }
+    /**
+     * Get stats about the current doc chunk index.
+     */
+    getDocIndexStats() {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DocChunkStore(db);
+        return store.getStats();
+    }
+    /**
+     * List indexed sources (what files have been seeded and their hashes).
+     */
+    listDocSources(opts) {
+        const db = this.dbManager.getLibraryDb();
+        const store = new DocChunkStore(db);
+        return store.listSources(opts);
+    }
+    // ─── Fleet Cache Hydration ──────────────────────────────────
+    /**
+     * Hydrate the Redis fleet cache from library.db.
+     * Call on gateway startup to warm the cache for dashboard queries.
+     *
+     * Populates:
+     *  - Per-agent profiles (fleet registry + capabilities + desired state)
+     *  - Fleet summary (counts, drift status)
+     */
+    async hydrateFleetCache() {
+        if (!this.cache.isConnected)
+            return { agents: 0, summary: false };
+        const db = this.dbManager.getLibraryDb();
+        const fleetStore = new FleetStore(db);
+        const desiredStore = new DesiredStateStore(db);
+        const agents = fleetStore.listAgents();
+        let hydrated = 0;
+        for (const agent of agents) {
+            try {
+                // Build a composite profile for each agent
+                const capabilities = fleetStore.getAgentCapabilities(agent.id);
+                const desiredState = desiredStore.getAgentState(agent.id);
+                const desiredConfig = desiredStore.getAgentConfig(agent.id);
+                const composite = {
+                    ...agent,
+                    capabilities: capabilities.map(c => ({ capType: c.capType, name: c.name, version: c.version })),
+                    desiredState: desiredState.map(d => ({
+                        configKey: d.configKey,
+                        desiredValue: d.desiredValue,
+                        actualValue: d.actualValue,
+                        driftStatus: d.driftStatus,
+                    })),
+                    desiredConfig,
+                };
+                await this.cache.cacheFleetAgent(agent.id, composite);
+                hydrated++;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                console.warn(`[hypermem] Failed to cache agent ${agent.id}: ${message}`);
+            }
+        }
+        // Cache fleet summary
+        try {
+            const driftSummary = desiredStore.getDriftSummary();
+            const summary = {
+                totalAgents: agents.length,
+                activeAgents: agents.filter(a => a.status === 'active').length,
+                tiers: {
+                    council: agents.filter(a => a.tier === 'council').length,
+                    director: agents.filter(a => a.tier === 'director').length,
+                    specialist: agents.filter(a => a.tier === 'specialist').length,
+                },
+                drift: driftSummary,
+                hydratedAt: new Date().toISOString(),
+            };
+            await this.cache.cacheFleetSummary(summary);
+        }
+        catch {
+            return { agents: hydrated, summary: false };
+        }
+        return { agents: hydrated, summary: true };
+    }
+    // ─── Lifecycle ───────────────────────────────────────────────
+    /**
+     * Clean shutdown.
+     */
+    async close() {
+        await this.cache.disconnect();
+        this.dbManager.close();
+    }
+}
+export default HyperMem;
+export { SessionFlusher, flushSession } from './session-flusher.js';
+export { importVault, watchVault, parseObsidianNote, parseFrontmatter, extractWikilinks, extractTags, cleanObsidianMarkdown } from './obsidian-watcher.js';
+export { exportToVault } from './obsidian-exporter.js';
+export { collectMetrics, formatMetricsSummary } from './metrics-dashboard.js';
+export { getProfile, mergeProfile, PROFILES, lightProfile, standardProfile, fullProfile, extendedProfile, minimalProfile, richProfile } from './profiles.js';
+export { renderStarterFOS, resolveOutputTier } from './fos-mod.js';
+export { repairToolPairs } from './repair-tool-pairs.js';
+//# sourceMappingURL=index.js.map