helixmind 0.5.4

package/dist/spiral/cloud/web-enricher.js

@@ -0,0 +1,176 @@
+/**
+ * Web Knowledge Enricher — The Internet Layer.
+ *
+ * When the agent works on a topic, this module automatically:
+ * 1. Detects what topics need fresh knowledge
+ * 2. Searches the web for relevant docs, best practices, examples
+ * 3. Extracts and compresses the useful parts
+ * 4. Stores them in the spiral brain (as L2 Active nodes)
+ *
+ * The brain visualization shows new web knowledge arriving in real-time.
+ */
+import { detectTopics, needsEnrichment } from './topic-detector.js';
+import { webSearch, fetchPageContent } from './search-provider.js';
+import { extractKnowledge, formatForSpiral } from './content-extractor.js';
+import { logger } from '../../utils/logger.js';
+// Track recently searched topics to avoid redundant searches within a session
+const recentSearches = new Map();
+const SEARCH_COOLDOWN_MS = 10 * 60 * 1000; // 10 minutes
+/**
+ * Enrich the spiral brain with web knowledge about the current topic.
+ * Runs in the background (non-blocking).
+ *
+ * @param userMessage - The user's message to analyze
+ * @param spiralEngine - The spiral engine to store knowledge in
+ * @param options - Configuration options
+ */
+export async function enrichFromWeb(userMessage, spiralEngine, options = {}) {
+    const startTime = Date.now();
+    const { maxTopics = 2, maxPagesPerTopic = 2, minQuality = 0.4, signal, onKnowledgeFound, } = options;
+    const result = {
+        topics: [],
+        nodesStored: 0,
+        sourcesSearched: 0,
+        pagesFetched: 0,
+        duration_ms: 0,
+        newKnowledge: [],
+    };
+    // Check if enrichment is needed
+    if (!needsEnrichment(userMessage)) {
+        result.duration_ms = Date.now() - startTime;
+        return result;
+    }
+    // Detect topics
+    const allTopics = detectTopics(userMessage);
+    const topics = filterRecentTopics(allTopics).slice(0, maxTopics);
+    if (topics.length === 0) {
+        result.duration_ms = Date.now() - startTime;
+        return result;
+    }
+    result.topics = topics.map(t => t.query);
+    logger.debug(`Web enricher: researching ${topics.length} topics: ${result.topics.join(', ')}`);
+    // Check if spiral already has knowledge about these topics
+    const filteredTopics = await filterKnownTopics(topics, spiralEngine);
+    // Research each topic
+    for (const topic of filteredTopics) {
+        if (signal?.aborted)
+            break;
+        try {
+            // Mark as recently searched
+            recentSearches.set(normalizeQuery(topic.query), Date.now());
+            // Search the web
+            const searchResults = await webSearch(topic.query, maxPagesPerTopic + 2, signal);
+            result.sourcesSearched += searchResults.length;
+            if (searchResults.length === 0)
+                continue;
+            // Fetch and process top results
+            const pagesToFetch = searchResults.slice(0, maxPagesPerTopic);
+            for (const searchResult of pagesToFetch) {
+                if (signal?.aborted)
+                    break;
+                const pageContent = await fetchPageContent(searchResult.url, 8000, signal);
+                if (!pageContent)
+                    continue;
+                result.pagesFetched++;
+                // Extract knowledge
+                const knowledge = extractKnowledge(pageContent, searchResult.url, topic.query);
+                // Skip low quality
+                if (knowledge.quality < minQuality)
+                    continue;
+                // Format for spiral storage
+                const spiralContent = formatForSpiral(knowledge, topic.query);
+                // Store in spiral brain as L2 (Active) node
+                try {
+                    await spiralEngine.store(spiralContent, 'pattern', {
+                        tags: ['web_knowledge', topic.category, ...topic.query.split(/\s+/).slice(0, 3)],
+                        source: searchResult.url,
+                        web_topic: topic.query,
+                        quality: knowledge.quality,
+                    });
+                    result.nodesStored++;
+                    const knowledgeItem = {
+                        topic: topic.query,
+                        summary: knowledge.summary.slice(0, 150),
+                        source: searchResult.url,
+                        quality: knowledge.quality,
+                    };
+                    result.newKnowledge.push(knowledgeItem);
+                    // Notify for live brain visualization
+                    onKnowledgeFound?.(topic.query, knowledge.summary.slice(0, 150), searchResult.url);
+                    logger.debug(`Stored web knowledge: ${topic.query} from ${searchResult.url} (quality: ${knowledge.quality.toFixed(2)})`);
+                }
+                catch {
+                    // Storage error, skip
+                }
+            }
+        }
+        catch (err) {
+            logger.debug(`Web enricher error for "${topic.query}": ${err}`);
+        }
+    }
+    result.duration_ms = Date.now() - startTime;
+    logger.debug(`Web enricher complete: ${result.nodesStored} nodes stored in ${result.duration_ms}ms`);
+    return result;
+}
+/**
+ * Filter out topics that were recently searched.
+ */
+function filterRecentTopics(topics) {
+    const now = Date.now();
+    // Evict expired entries to prevent unbounded memory growth
+    for (const [key, timestamp] of recentSearches) {
+        if (now - timestamp >= SEARCH_COOLDOWN_MS) {
+            recentSearches.delete(key);
+        }
+    }
+    return topics.filter(t => {
+        const normalized = normalizeQuery(t.query);
+        const lastSearch = recentSearches.get(normalized);
+        if (lastSearch && now - lastSearch < SEARCH_COOLDOWN_MS) {
+            return false;
+        }
+        return true;
+    });
+}
+/**
+ * Filter out topics the spiral already has good knowledge about.
+ */
+async function filterKnownTopics(topics, spiralEngine) {
+    const filtered = [];
+    for (const topic of topics) {
+        try {
+            const existing = await spiralEngine.query(topic.query, undefined, [1, 2]);
+            // If we already have 3+ relevant nodes in L1/L2, skip this topic
+            const totalExisting = existing.level_1.length + existing.level_2.length;
+            // Check if any existing nodes are web knowledge
+            const hasWebKnowledge = [...existing.level_1, ...existing.level_2].some((n) => n.content?.includes('[Web Knowledge:'));
+            if (totalExisting < 3 || !hasWebKnowledge) {
+                filtered.push(topic);
+            }
+        }
+        catch {
+            // If query fails, include the topic
+            filtered.push(topic);
+        }
+    }
+    return filtered;
+}
+function normalizeQuery(query) {
+    return query.toLowerCase().trim().replace(/\s+/g, ' ');
+}
+/**
+ * Clear the recent searches cache (for testing or session reset).
+ */
+export function clearSearchCache() {
+    recentSearches.clear();
+}
+/**
+ * Get current cache stats.
+ */
+export function getSearchCacheStats() {
+    return {
+        size: recentSearches.size,
+        topics: Array.from(recentSearches.keys()),
+    };
+}
+//# sourceMappingURL=web-enricher.js.map

package/dist/spiral/cloud/web-enricher.js.map

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

package/dist/spiral/compression.d.ts

@@ -0,0 +1,54 @@
+import { NodeStore } from '../storage/nodes.js';
+import { VectorStore } from '../storage/vectors.js';
+interface CompactionResult {
+    compacted_nodes: number;
+    freed_tokens: number;
+    nodes_deleted: number;
+}
+export interface EvolutionResult {
+    promoted: number;
+    demoted: number;
+    archived: number;
+    summarized: number;
+}
+/**
+ * Handles context evolution as nodes move through 5 spiral levels.
+ * L1 Focus → L2 Active: relevance demotion, no content change
+ * L2 Active → L3 Reference: content summarized
+ * L3 Reference → L4 Archive: content heavily compressed
+ * L4 Archive → L5 Deep Archive: only metadata + short summary kept
+ * Archived nodes are NEVER deleted — they remain retrievable.
+ */
+export declare class CompressionService {
+    private nodes;
+    private vectors;
+    private l1Min;
+    private l2Min;
+    private l3Min;
+    private l4Min;
+    constructor(nodes: NodeStore, vectors: VectorStore, l1Min?: number, l2Min?: number, l3Min?: number, l4Min?: number);
+    /**
+     * Apply time-based decay to all nodes and re-level them.
+     */
+    applyDecay(decayRate: number): number;
+    /**
+     * Evolution: promote or demote nodes based on current relevance scores.
+     * Unlike compaction, evolution preserves ALL nodes — nothing is deleted.
+     */
+    evolve(): EvolutionResult;
+    /**
+     * Manual compaction: compress and demote old nodes.
+     * In 5-level system, aggressive mode pushes to L4/L5 instead of deleting.
+     */
+    compact(aggressive: boolean): CompactionResult;
+    /**
+     * Simple content summarization: truncate to ~200 chars.
+     */
+    summarizeContent(content: string): string;
+    /**
+     * Deep compression for archive levels: truncate to ~100 chars.
+     */
+    deepCompress(content: string): string;
+}
+export {};
+//# sourceMappingURL=compression.d.ts.map

package/dist/spiral/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/spiral/compression.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKpD,UAAU,gBAAgB;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAS;gBAEV,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,SAAM,EAAE,KAAK,SAAM,EAAE,KAAK,SAAM,EAAE,KAAK,SAAM;IAStG;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAoCrC;;;OAGG;IACH,MAAM,IAAI,eAAe;IA8CzB;;;OAGG;IACH,OAAO,CAAC,UAAU,EAAE,OAAO,GAAG,gBAAgB;IAgE9C;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAKzC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAItC"}

package/dist/spiral/compression.js

@@ -0,0 +1,175 @@
+import { logger } from '../utils/logger.js';
+import { estimateTokens } from '../utils/tokens.js';
+import { determineLevel } from './relevance.js';
+/**
+ * Handles context evolution as nodes move through 5 spiral levels.
+ * L1 Focus → L2 Active: relevance demotion, no content change
+ * L2 Active → L3 Reference: content summarized
+ * L3 Reference → L4 Archive: content heavily compressed
+ * L4 Archive → L5 Deep Archive: only metadata + short summary kept
+ * Archived nodes are NEVER deleted — they remain retrievable.
+ */
+export class CompressionService {
+    nodes;
+    vectors;
+    l1Min;
+    l2Min;
+    l3Min;
+    l4Min;
+    constructor(nodes, vectors, l1Min = 0.7, l2Min = 0.5, l3Min = 0.3, l4Min = 0.1) {
+        this.nodes = nodes;
+        this.vectors = vectors;
+        this.l1Min = l1Min;
+        this.l2Min = l2Min;
+        this.l3Min = l3Min;
+        this.l4Min = l4Min;
+    }
+    /**
+     * Apply time-based decay to all nodes and re-level them.
+     */
+    applyDecay(decayRate) {
+        const now = Date.now();
+        const allNodes = this.nodes.getAll();
+        const updates = [];
+        for (const node of allNodes) {
+            const hoursSinceAccess = (now - node.accessed_at) / (1000 * 60 * 60);
+            const decayFactor = Math.exp(-decayRate * hoursSinceAccess);
+            const newScore = Math.max(0.01, node.relevance_score * decayFactor);
+            const newLevel = determineLevel(newScore, this.l1Min, this.l2Min, this.l3Min, this.l4Min);
+            if (newScore !== node.relevance_score || newLevel !== node.level) {
+                updates.push({ id: node.id, score: newScore, level: newLevel });
+                // Summarize when demoting to L3+
+                if (newLevel >= 3 && node.level < 3 && !node.summary) {
+                    const summary = this.summarizeContent(node.content);
+                    this.nodes.updateSummary(node.id, summary);
+                }
+                // Deep compress when demoting to L4+
+                if (newLevel >= 4 && node.level < 4 && node.summary) {
+                    const deepSummary = this.deepCompress(node.summary);
+                    this.nodes.updateSummary(node.id, deepSummary);
+                }
+            }
+        }
+        if (updates.length > 0) {
+            this.nodes.bulkUpdateRelevance(updates);
+            logger.debug(`Decay applied to ${updates.length} nodes`);
+        }
+        return updates.length;
+    }
+    /**
+     * Evolution: promote or demote nodes based on current relevance scores.
+     * Unlike compaction, evolution preserves ALL nodes — nothing is deleted.
+     */
+    evolve() {
+        let promoted = 0;
+        let demoted = 0;
+        let archived = 0;
+        let summarized = 0;
+        const allNodes = this.nodes.getAll();
+        for (const node of allNodes) {
+            const targetLevel = determineLevel(node.relevance_score, this.l1Min, this.l2Min, this.l3Min, this.l4Min);
+            if (targetLevel === node.level)
+                continue;
+            // Promotion (moving to a higher-priority level)
+            if (targetLevel < node.level) {
+                this.nodes.updateLevel(node.id, targetLevel);
+                promoted++;
+                continue;
+            }
+            // Demotion (moving to a lower-priority level)
+            this.nodes.updateLevel(node.id, targetLevel);
+            demoted++;
+            // Summarize when entering L3 for the first time
+            if (targetLevel >= 3 && node.level < 3 && !node.summary) {
+                const summary = this.summarizeContent(node.content);
+                this.nodes.updateSummary(node.id, summary);
+                summarized++;
+            }
+            // Deep compress when entering L4/L5
+            if (targetLevel >= 4 && node.level < 4) {
+                const text = node.summary ?? node.content;
+                const deepSummary = this.deepCompress(text);
+                this.nodes.updateSummary(node.id, deepSummary);
+                archived++;
+            }
+        }
+        logger.info(`Evolution: ${promoted} promoted, ${demoted} demoted, ${archived} archived, ${summarized} summarized`);
+        return { promoted, demoted, archived, summarized };
+    }
+    /**
+     * Manual compaction: compress and demote old nodes.
+     * In 5-level system, aggressive mode pushes to L4/L5 instead of deleting.
+     */
+    compact(aggressive) {
+        let compacted = 0;
+        let freed = 0;
+        let deleted = 0;
+        const allNodes = this.nodes.getAll();
+        for (const node of allNodes) {
+            // Compress L2 Active nodes that are old
+            if (node.level === 2 && !node.summary) {
+                const hoursSince = (Date.now() - node.accessed_at) / (1000 * 60 * 60);
+                if (hoursSince > 24 || aggressive) {
+                    const summary = this.summarizeContent(node.content);
+                    const oldTokens = node.token_count;
+                    const newTokens = estimateTokens(summary);
+                    freed += oldTokens - newTokens;
+                    this.nodes.updateSummary(node.id, summary);
+                    this.nodes.updateLevel(node.id, 3);
+                    compacted++;
+                }
+            }
+            // Compress L3 Reference nodes to L4 Archive
+            if (node.level === 3) {
+                const hoursSince = (Date.now() - node.accessed_at) / (1000 * 60 * 60);
+                if (hoursSince > 72 || aggressive) {
+                    const text = node.summary ?? node.content;
+                    const deepSummary = this.deepCompress(text);
+                    const oldTokens = estimateTokens(text);
+                    const newTokens = estimateTokens(deepSummary);
+                    freed += oldTokens - newTokens;
+                    this.nodes.updateSummary(node.id, deepSummary);
+                    this.nodes.updateLevel(node.id, 4);
+                    compacted++;
+                }
+            }
+            // In aggressive mode, push L4 to L5 (deep archive) — but NEVER delete
+            if (aggressive && node.level === 4) {
+                const hoursSince = (Date.now() - node.accessed_at) / (1000 * 60 * 60);
+                if (hoursSince > 168) { // 7 days
+                    this.nodes.updateLevel(node.id, 5);
+                    compacted++;
+                }
+            }
+            // Only delete L5 nodes in aggressive mode after 30 days
+            if (aggressive && node.level === 5) {
+                const hoursSince = (Date.now() - node.accessed_at) / (1000 * 60 * 60);
+                if (hoursSince > 720) { // 30 days
+                    freed += node.token_count;
+                    this.vectors.delete(node.id);
+                    this.nodes.delete(node.id);
+                    deleted++;
+                }
+            }
+        }
+        logger.info(`Compaction: ${compacted} compressed, ${deleted} deleted, ${freed} tokens freed`);
+        return { compacted_nodes: compacted, freed_tokens: freed, nodes_deleted: deleted };
+    }
+    /**
+     * Simple content summarization: truncate to ~200 chars.
+     */
+    summarizeContent(content) {
+        if (content.length <= 200)
+            return content;
+        return content.slice(0, 197) + '...';
+    }
+    /**
+     * Deep compression for archive levels: truncate to ~100 chars.
+     */
+    deepCompress(content) {
+        if (content.length <= 100)
+            return content;
+        return content.slice(0, 97) + '...';
+    }
+}
+//# sourceMappingURL=compression.js.map

package/dist/spiral/compression.js.map

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

package/dist/spiral/embeddings.d.ts

@@ -0,0 +1,30 @@
+import type { EmbeddingStatus } from '../types.js';
+/**
+ * Manages local embedding generation using HuggingFace Transformers.js.
+ * Falls back gracefully if the model can't be loaded.
+ */
+export declare class EmbeddingService {
+    private pipeline;
+    private loading;
+    private _status;
+    private model;
+    private cache;
+    private static readonly MAX_CACHE;
+    constructor(model: string);
+    get status(): EmbeddingStatus;
+    /**
+     * Start loading the model eagerly. Call this at server startup.
+     */
+    initialize(): Promise<void>;
+    private loadModel;
+    /**
+     * Dispose the embedding model to free memory (ONNX sessions, WASM buffers).
+     */
+    dispose(): Promise<void>;
+    /**
+     * Generate embedding for a text string.
+     * Returns null if embeddings are not available.
+     */
+    embed(text: string): Promise<Float32Array | null>;
+}
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/spiral/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/spiral/embeddings.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAO;gBAE5B,KAAK,EAAE,MAAM;IAIzB,IAAI,MAAM,IAAI,eAAe,CAE5B;IAED;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAOnB,SAAS;IAsBvB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAY9B;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;CAkCxD"}

package/dist/spiral/embeddings.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { logger } from '../utils/logger.js';
+/**
+ * Manages local embedding generation using HuggingFace Transformers.js.
+ * Falls back gracefully if the model can't be loaded.
+ */
+export class EmbeddingService {
+    pipeline = null;
+    loading = null;
+    _status = 'loading';
+    model;
+    cache = new Map();
+    static MAX_CACHE = 128;
+    constructor(model) {
+        this.model = model;
+    }
+    get status() {
+        return this._status;
+    }
+    /**
+     * Start loading the model eagerly. Call this at server startup.
+     */
+    async initialize() {
+        if (this.loading)
+            return this.loading;
+        this.loading = this.loadModel();
+        return this.loading;
+    }
+    async loadModel() {
+        try {
+            logger.info(`Loading embedding model: ${this.model}`);
+            const startTime = Date.now();
+            const { pipeline } = await import('@huggingface/transformers');
+            const extractor = await pipeline('feature-extraction', this.model, {
+                dtype: 'q8',
+            });
+            this.pipeline = extractor;
+            this._status = 'loaded';
+            const elapsed = Date.now() - startTime;
+            logger.info(`Embedding model loaded in ${elapsed}ms`);
+        }
+        catch (err) {
+            logger.warn(`Failed to load embedding model: ${err}. Using keyword fallback.`);
+            this._status = 'fallback';
+            this.pipeline = null;
+        }
+    }
+    /**
+     * Dispose the embedding model to free memory (ONNX sessions, WASM buffers).
+     */
+    async dispose() {
+        if (this.pipeline) {
+            try {
+                await this.pipeline.dispose?.();
+            }
+            catch { /* ignore disposal errors */ }
+            this.pipeline = null;
+            this._status = 'fallback';
+        }
+        this.cache.clear();
+        this.loading = null;
+    }
+    /**
+     * Generate embedding for a text string.
+     * Returns null if embeddings are not available.
+     */
+    async embed(text) {
+        if (this._status === 'loading') {
+            await this.loading;
+        }
+        if (!this.pipeline) {
+            return null;
+        }
+        // LRU cache: same input text → return cached embedding
+        const key = createHash('sha256').update(text).digest('hex').slice(0, 16);
+        const cached = this.cache.get(key);
+        if (cached)
+            return new Float32Array(cached);
+        try {
+            const result = await this.pipeline(text, {
+                pooling: 'mean',
+                normalize: true,
+            });
+            const embedding = new Float32Array(result.data);
+            // Evict oldest entry if cache is full
+            if (this.cache.size >= EmbeddingService.MAX_CACHE) {
+                const oldest = this.cache.keys().next().value;
+                this.cache.delete(oldest);
+            }
+            this.cache.set(key, new Float32Array(embedding));
+            return embedding;
+        }
+        catch (err) {
+            logger.error(`Embedding generation failed: ${err}`);
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/spiral/embeddings.js.map

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