cozo-memory 1.1.6 → 1.1.7

package/dist/memory-activation.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryActivationService = void 0;
+class MemoryActivationService {
+    db;
+    config;
+    constructor(db, config = {}) {
+        this.db = db;
+        this.config = {
+            initialStrength: config.initialStrength ?? 1.0,
+            strengthIncrement: config.strengthIncrement ?? 1.0,
+            maxStrength: config.maxStrength ?? 20.0,
+            retentionThreshold: config.retentionThreshold ?? 0.15,
+            decayBase: config.decayBase ?? Math.E,
+            timeUnit: config.timeUnit ?? 'days',
+        };
+    }
+    /**
+     * Calculate activation score for an observation
+     * Formula: R = e^(-t/S)
+     */
+    calculateActivation(timeSinceAccess, strength) {
+        if (timeSinceAccess === 0)
+            return 1.0;
+        const exponent = -timeSinceAccess / strength;
+        const activation = Math.pow(this.config.decayBase, exponent);
+        return Math.max(0, Math.min(1, activation));
+    }
+    /**
+     * Get current memory strength for an observation
+     * S = initialStrength + (accessCount * strengthIncrement)
+     */
+    calculateStrength(accessCount) {
+        const strength = this.config.initialStrength +
+            (accessCount * this.config.strengthIncrement);
+        return Math.min(strength, this.config.maxStrength);
+    }
+    /**
+     * Convert timestamp to time units since last access
+     */
+    getTimeSinceAccess(lastAccessTime) {
+        const now = Date.now();
+        const diffMs = now - lastAccessTime;
+        if (this.config.timeUnit === 'hours') {
+            return diffMs / (1000 * 60 * 60);
+        }
+        else {
+            return diffMs / (1000 * 60 * 60 * 24);
+        }
+    }
+    /**
+     * Calculate activation scores for all observations
+     */
+    async calculateActivationScores(entityId) {
+        try {
+            // Query observations with access metadata
+            const query = entityId
+                ? `
+          ?[id, entity_id, text, metadata, created_at] := 
+            *observation{id, entity_id, text, metadata, created_at},
+            entity_id == $entity_id
+        `
+                : `
+          ?[id, entity_id, text, metadata, created_at] := 
+            *observation{id, entity_id, text, metadata, created_at}
+        `;
+            const result = await this.db.run(query, entityId ? { entity_id: entityId } : {});
+            const observations = result.rows;
+            const scores = [];
+            for (const [id, entity_id, text, metadata, created_at] of observations) {
+                // Extract access metadata
+                const accessCount = (metadata?.access_count || 0);
+                const lastAccessTime = (metadata?.last_access_time || created_at);
+                // Calculate activation
+                const timeSinceAccess = this.getTimeSinceAccess(lastAccessTime);
+                const strength = this.calculateStrength(accessCount);
+                const activation = this.calculateActivation(timeSinceAccess, strength);
+                // Determine retention
+                const shouldRetain = activation >= this.config.retentionThreshold;
+                const reason = shouldRetain
+                    ? `Active memory (activation: ${activation.toFixed(3)}, strength: ${strength.toFixed(1)})`
+                    : `Below threshold (activation: ${activation.toFixed(3)} < ${this.config.retentionThreshold})`;
+                scores.push({
+                    observationId: id,
+                    entityId: entity_id,
+                    activation,
+                    strength,
+                    timeSinceAccess,
+                    accessCount,
+                    shouldRetain,
+                    reason
+                });
+            }
+            return scores.sort((a, b) => b.activation - a.activation);
+        }
+        catch (error) {
+            console.error('[MemoryActivation] Error calculating activation scores:', error);
+            return [];
+        }
+    }
+    /**
+     * Update access metadata when an observation is retrieved
+     */
+    async recordAccess(observationId) {
+        try {
+            // Get current observation
+            const result = await this.db.run(`
+        ?[id, entity_id, text, metadata, created_at] := 
+          *observation{id, entity_id, text, metadata, created_at},
+          id == $id
+      `, { id: observationId });
+            if (result.rows.length === 0) {
+                console.warn(`[MemoryActivation] Observation ${observationId} not found`);
+                return;
+            }
+            const [id, entity_id, text, metadata, created_at] = result.rows[0];
+            const currentMetadata = (metadata || {});
+            // Update access metadata
+            const accessCount = (currentMetadata.access_count || 0) + 1;
+            const lastAccessTime = Date.now();
+            const updatedMetadata = {
+                ...currentMetadata,
+                access_count: accessCount,
+                last_access_time: lastAccessTime,
+            };
+            // Update observation with new metadata
+            await this.db.run(`
+        ?[id, entity_id, text, metadata, created_at] <- [
+          [$id, $entity_id, $text, $metadata, $created_at]
+        ]
+        :put observation {id, entity_id, text => metadata, created_at}
+      `, {
+                id,
+                entity_id,
+                text,
+                metadata: updatedMetadata,
+                created_at
+            });
+        }
+        catch (error) {
+            console.error('[MemoryActivation] Error recording access:', error);
+        }
+    }
+    /**
+     * Prune weak memories below activation threshold
+     */
+    async pruneWeakMemories(dryRun = true, entityId) {
+        try {
+            const scores = await this.calculateActivationScores(entityId);
+            const candidates = scores.filter(s => !s.shouldRetain);
+            if (dryRun) {
+                console.error(`[MemoryActivation] Dry run: ${candidates.length} observations below threshold`);
+                return {
+                    pruned: 0,
+                    preserved: scores.length,
+                    candidates,
+                };
+            }
+            // Actually delete weak memories
+            let pruned = 0;
+            for (const candidate of candidates) {
+                // Delete the observation
+                await this.db.run(`
+          ?[id, entity_id, text, metadata, created_at] := 
+            *observation{id, entity_id, text, metadata, created_at},
+            id == $id
+          :rm observation {id, entity_id, text => metadata, created_at}
+        `, { id: candidate.observationId });
+                pruned++;
+            }
+            return {
+                pruned,
+                preserved: scores.length - pruned,
+                candidates,
+            };
+        }
+        catch (error) {
+            console.error('[MemoryActivation] Error pruning weak memories:', error);
+            return { pruned: 0, preserved: 0, candidates: [] };
+        }
+    }
+    /**
+     * Get activation statistics
+     */
+    async getActivationStats(entityId) {
+        try {
+            const scores = await this.calculateActivationScores(entityId);
+            if (scores.length === 0) {
+                return {
+                    totalObservations: 0,
+                    averageActivation: 0,
+                    averageStrength: 0,
+                    belowThreshold: 0,
+                    aboveThreshold: 0,
+                    distribution: {
+                        veryWeak: 0,
+                        weak: 0,
+                        moderate: 0,
+                        strong: 0,
+                        veryStrong: 0,
+                    },
+                };
+            }
+            const totalActivation = scores.reduce((sum, s) => sum + s.activation, 0);
+            const totalStrength = scores.reduce((sum, s) => sum + s.strength, 0);
+            const distribution = {
+                veryWeak: scores.filter(s => s.activation < 0.1).length,
+                weak: scores.filter(s => s.activation >= 0.1 && s.activation < 0.3).length,
+                moderate: scores.filter(s => s.activation >= 0.3 && s.activation < 0.6).length,
+                strong: scores.filter(s => s.activation >= 0.6 && s.activation < 0.9).length,
+                veryStrong: scores.filter(s => s.activation >= 0.9).length,
+            };
+            return {
+                totalObservations: scores.length,
+                averageActivation: totalActivation / scores.length,
+                averageStrength: totalStrength / scores.length,
+                belowThreshold: scores.filter(s => !s.shouldRetain).length,
+                aboveThreshold: scores.filter(s => s.shouldRetain).length,
+                distribution,
+            };
+        }
+        catch (error) {
+            console.error('[MemoryActivation] Error getting activation stats:', error);
+            return {
+                totalObservations: 0,
+                averageActivation: 0,
+                averageStrength: 0,
+                belowThreshold: 0,
+                aboveThreshold: 0,
+                distribution: {
+                    veryWeak: 0,
+                    weak: 0,
+                    moderate: 0,
+                    strong: 0,
+                    veryStrong: 0,
+                },
+            };
+        }
+    }
+    /**
+     * Boost activation of related memories (priming effect)
+     */
+    async boostRelatedMemories(observationId, boostFactor = 0.5) {
+        try {
+            // Get the observation
+            const result = await this.db.run(`
+        ?[id, entity_id, text, metadata, created_at] := 
+          *observation{id, entity_id, text, metadata, created_at},
+          id == $id
+      `, { id: observationId });
+            if (result.rows.length === 0) {
+                console.warn(`[MemoryActivation] Observation ${observationId} not found`);
+                return 0;
+            }
+            const [id, entity_id] = result.rows[0];
+            // Get all observations for the same entity (excluding the current one)
+            const relatedResult = await this.db.run(`
+        ?[id, entity_id, text, metadata, created_at] := 
+          *observation{id, entity_id, text, metadata, created_at},
+          entity_id == $entity_id,
+          id != $id
+      `, { entity_id, id: observationId });
+            let boosted = 0;
+            for (const [relId, relEntityId, relText, relMetadata, relCreatedAt] of relatedResult.rows) {
+                const currentMetadata = (relMetadata || {});
+                // Simulate a partial access (priming effect)
+                const accessCount = (currentMetadata.access_count || 0) + boostFactor;
+                const updatedMetadata = {
+                    ...currentMetadata,
+                    access_count: accessCount,
+                };
+                // Update the related observation
+                await this.db.run(`
+          ?[id, entity_id, text, metadata, created_at] <- [
+            [$id, $entity_id, $text, $metadata, $created_at]
+          ]
+          :put observation {id, entity_id, text => metadata, created_at}
+        `, {
+                    id: relId,
+                    entity_id: relEntityId,
+                    text: relText,
+                    metadata: updatedMetadata,
+                    created_at: relCreatedAt
+                });
+                boosted++;
+            }
+            return boosted;
+        }
+        catch (error) {
+            console.error('[MemoryActivation] Error boosting related memories:', error);
+            return 0;
+        }
+    }
+}
+exports.MemoryActivationService = MemoryActivationService;

package/dist/query-aware-traversal.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Query-Aware Flow Diffusion for Graph Traversal
+ *
+ * Based on QAFD-RAG (ICLR 2026):
+ * - Dynamically weights edges based on query-node semantic alignment
+ * - Uses flow diffusion similar to Personalized PageRank
+ * - Provides statistical guarantees for subgraph retrieval
+ * - Training-free approach using cosine similarity
+ *
+ * Reference: "Query-Aware Flow Diffusion for Graph-Based RAG with Retrieval Guarantees"
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryAwareTraversal = void 0;
+/**
+ * Query-Aware Graph Traversal Service
+ *
+ * Implements flow diffusion with dynamic edge weighting based on query semantics.
+ */
+class QueryAwareTraversal {
+    db;
+    embeddingService;
+    constructor(db, embeddingService) {
+        this.db = db;
+        this.embeddingService = embeddingService;
+    }
+    /**
+     * Performs query-aware graph traversal from a start entity
+     *
+     * @param startEntityId - Starting entity ID
+     * @param query - Query string for semantic alignment
+     * @param options - Traversal options
+     * @returns Array of query-aware results
+     */
+    async traverse(startEntityId, query, options = {}) {
+        const { maxHops = 3, dampingFactor = 0.85, minScore = 0.1, topK = 20, relationTypes, convergenceThreshold = 0.001 } = options;
+        console.log('[QueryAwareTraversal] Starting traversal:', {
+            startEntityId,
+            query,
+            maxHops,
+            dampingFactor
+        });
+        try {
+            // Generate query embedding
+            const queryEmbedding = await this.embeddingService.embed(query);
+            // Build relation type filter
+            const relationFilter = relationTypes && relationTypes.length > 0
+                ? `is_in(relation_type, [${relationTypes.map(t => `"${t}"`).join(', ')}])`
+                : 'true';
+            // Query-Aware Flow Diffusion using Datalog
+            // This implements a simplified version of QAFD-RAG's flow diffusion
+            const datalogQuery = `
+        # Initialize: Start entity has score 1.0
+        flow[entity_id, hop, score] := 
+          entity_id = $start_id,
+          hop = 0,
+          score = 1.0
+
+        # Compute edge weights based on query-node semantic alignment
+        # weight = cosine_similarity(node_embedding, query_embedding)
+        edge_weight[from_id, to_id, weight, relation_type] := 
+          *relationship{
+            from_id,
+            to_id,
+            relation_type,
+            @ "NOW"
+          },
+          ${relationFilter},
+          *entity{
+            id: to_id,
+            embedding: to_emb,
+            @ "NOW"
+          },
+          # Cosine similarity between query and target node
+          similarity = cos_dist(to_emb, vec($query_emb)),
+          # Convert distance to similarity (1 - distance)
+          weight = 1.0 - similarity,
+          # Ensure positive weights
+          weight > 0.0
+
+        # Flow diffusion: propagate flow through weighted edges
+        # score_new = damping_factor * score_current * edge_weight
+        flow[to_id, hop_new, score_new] := 
+          flow[from_id, hop, score],
+          hop < $max_hops,
+          edge_weight[from_id, to_id, weight, _],
+          hop_new = hop + 1,
+          # Flow diffusion formula
+          score_new = $damping * score * weight,
+          score_new >= $min_score
+
+        # Join with entity data and aggregate scores
+        # Variables without aggregation (id, name, type, metadata) are grouping keys
+        ?[id, name, type, sum(flow_score), min(hop), metadata] := 
+          flow[id, hop, flow_score],
+          *entity{
+            id,
+            name,
+            type,
+            metadata,
+            @ "NOW"
+          }
+
+        :order -sum(flow_score)
+        :limit $top_k
+      `;
+            const result = await this.db.run(datalogQuery, {
+                start_id: startEntityId,
+                query_emb: queryEmbedding,
+                max_hops: maxHops,
+                damping: dampingFactor,
+                min_score: minScore,
+                top_k: topK
+            });
+            const results = result.rows.map((row) => ({
+                id: row[0],
+                entity_id: row[0],
+                name: row[1],
+                type: row[2],
+                score: row[3],
+                hops: row[4],
+                path_score: row[3],
+                metadata: row[5],
+                source: 'query_aware_traversal'
+            }));
+            console.log('[QueryAwareTraversal] Traversal completed:', {
+                resultsCount: results.length,
+                topScore: results[0]?.score || 0
+            });
+            return results;
+        }
+        catch (error) {
+            console.error('[QueryAwareTraversal] Error during traversal:', error);
+            throw error;
+        }
+    }
+    /**
+     * Performs query-aware traversal from multiple seed entities
+     *
+     * This is useful for starting from vector search results and expanding
+     * the graph in a query-aware manner.
+     *
+     * @param seedEntityIds - Array of starting entity IDs
+     * @param query - Query string for semantic alignment
+     * @param options - Traversal options
+     * @returns Array of query-aware results
+     */
+    async traverseFromSeeds(seedEntityIds, query, options = {}) {
+        const { maxHops = 3, dampingFactor = 0.85, minScore = 0.1, topK = 20, relationTypes, convergenceThreshold = 0.001 } = options;
+        console.log('[QueryAwareTraversal] Starting multi-seed traversal:', {
+            seedCount: seedEntityIds.length,
+            query,
+            maxHops
+        });
+        try {
+            // Generate query embedding
+            const queryEmbedding = await this.embeddingService.embed(query);
+            // Build relation type filter
+            const relationFilter = relationTypes && relationTypes.length > 0
+                ? `is_in(relation_type, [${relationTypes.map(t => `"${t}"`).join(', ')}])`
+                : 'true';
+            // Build seed list for Datalog
+            const seedList = seedEntityIds.map(id => `"${id}"`).join(', ');
+            const datalogQuery = `
+        # Initialize: All seed entities start with equal score
+        seeds[entity_id] := entity_id in [${seedList}]
+        
+        flow[entity_id, hop, score] := 
+          seeds[entity_id],
+          hop = 0,
+          score = 1.0 / to_float(${seedEntityIds.length})
+
+        # Compute query-aware edge weights
+        edge_weight[from_id, to_id, weight, relation_type] := 
+          *relationship{
+            from_id,
+            to_id,
+            relation_type,
+            @ "NOW"
+          },
+          ${relationFilter},
+          *entity{
+            id: to_id,
+            embedding: to_emb,
+            @ "NOW"
+          },
+          similarity = cos_dist(to_emb, vec($query_emb)),
+          weight = 1.0 - similarity,
+          weight > 0.0
+
+        # Flow diffusion with query-aware weighting
+        flow[to_id, hop_new, score_new] := 
+          flow[from_id, hop, score],
+          hop < $max_hops,
+          edge_weight[from_id, to_id, weight, _],
+          hop_new = hop + 1,
+          score_new = $damping * score * weight,
+          score_new >= $min_score
+
+        # Join with entity data and aggregate scores
+        ?[id, name, type, sum(flow_score), min(hop), metadata] := 
+          flow[id, hop, flow_score],
+          *entity{
+            id,
+            name,
+            type,
+            metadata,
+            @ "NOW"
+          }
+
+        :order -sum(flow_score)
+        :limit $top_k
+      `;
+            const result = await this.db.run(datalogQuery, {
+                query_emb: queryEmbedding,
+                max_hops: maxHops,
+                damping: dampingFactor,
+                min_score: minScore,
+                top_k: topK
+            });
+            const results = result.rows.map((row) => ({
+                id: row[0],
+                entity_id: row[0],
+                name: row[1],
+                type: row[2],
+                score: row[3],
+                hops: row[4],
+                path_score: row[3],
+                metadata: row[5],
+                source: 'query_aware_multi_seed'
+            }));
+            console.log('[QueryAwareTraversal] Multi-seed traversal completed:', {
+                resultsCount: results.length,
+                topScore: results[0]?.score || 0
+            });
+            return results;
+        }
+        catch (error) {
+            console.error('[QueryAwareTraversal] Error during multi-seed traversal:', error);
+            throw error;
+        }
+    }
+    /**
+     * Hybrid approach: Vector search + Query-Aware Traversal
+     *
+     * This combines the best of both worlds:
+     * 1. Find semantically relevant seed entities via vector search
+     * 2. Expand from seeds using query-aware graph traversal
+     *
+     * @param query - Query string
+     * @param options - Traversal options with additional vector search params
+     * @returns Array of query-aware results
+     */
+    async hybridSearch(query, options = {}) {
+        const { seedTopK = 5, ...traversalOptions } = options;
+        console.log('[QueryAwareTraversal] Starting hybrid search:', {
+            query,
+            seedTopK
+        });
+        try {
+            // Step 1: Vector search to find seed entities
+            const queryEmbedding = await this.embeddingService.embed(query);
+            const seedQuery = `
+        ?[id] := 
+          ~entity:semantic{
+            id | 
+            query: vec($embedding), 
+            k: $seed_k,
+            ef: 100
+          }
+      `;
+            const seedResult = await this.db.run(seedQuery, {
+                embedding: queryEmbedding,
+                seed_k: seedTopK
+            });
+            if (seedResult.rows.length === 0) {
+                console.log('[QueryAwareTraversal] No seed entities found');
+                return [];
+            }
+            const seedIds = seedResult.rows.map((row) => row[0]);
+            console.log('[QueryAwareTraversal] Found seed entities:', seedIds.length);
+            // Step 2: Query-aware traversal from seeds
+            return await this.traverseFromSeeds(seedIds, query, traversalOptions);
+        }
+        catch (error) {
+            console.error('[QueryAwareTraversal] Error during hybrid search:', error);
+            throw error;
+        }
+    }
+}
+exports.QueryAwareTraversal = QueryAwareTraversal;