stellar-memory 0.5.0

package/dist/engine/consolidation.js

@@ -0,0 +1,368 @@
+/**
+ * consolidation.ts — Memory Consolidation ("Orbital Resonance")
+ *
+ * Finds groups of similar memories and merges them into richer, more
+ * comprehensive memories. Similar to how planets form from smaller bodies
+ * (planetesimals) combining in orbital resonance.
+ *
+ * Algorithm:
+ *   1. Load all memories in a project.
+ *   2. Group memories that share the same type and are within ±3 AU of each
+ *      other, with cosine similarity > 0.80 between their embeddings.
+ *      Falls back to Jaccard-based text similarity when embeddings are absent.
+ *   3. For each qualifying group (2+ memories):
+ *      - Merge content by deduplicating sentences.
+ *      - Create a new consolidated memory.
+ *      - Mark sources as consolidated and push them to the Oort cloud.
+ */
+import { getMemoriesByProject, consolidateMemories, getConsolidationHistory, updateMemoryOrbit, insertOrbitLog, } from '../storage/queries.js';
+import { createMemory } from './planet.js';
+import { generateEmbedding } from './embedding.js';
+import { cosineSimilarity } from './gravity.js';
+import { getDatabase } from '../storage/database.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('consolidation');
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const SIMILARITY_THRESHOLD = 0.80; // cosine similarity cutoff for grouping
+const DISTANCE_TOLERANCE = 3.0; // AU — memories must be within ±3 AU
+const OORT_DISTANCE = 95.0; // source memories are pushed here post-merge
+const JACCARD_DEDUP_THRESHOLD = 0.70; // sentence deduplication cutoff
+// Type priority for choosing the merged memory's type (higher = more important)
+const TYPE_PRIORITY = {
+    decision: 6,
+    milestone: 5,
+    error: 4,
+    task: 3,
+    context: 2,
+    observation: 1,
+    procedural: 3,
+};
+// ---------------------------------------------------------------------------
+// Sentence deduplication helpers
+// ---------------------------------------------------------------------------
+/**
+ * Tokenize a sentence into a Set of lowercase word tokens.
+ * Used for Jaccard similarity comparison.
+ */
+function tokenizeToSet(sentence) {
+    const tokens = sentence
+        .toLowerCase()
+        .split(/\s+/)
+        .map(w => w.replace(/[^\w]/g, ''))
+        .filter(w => w.length >= 2);
+    return new Set(tokens);
+}
+/**
+ * Jaccard similarity between two token sets.
+ * Returns a value in [0, 1].
+ */
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const token of a) {
+        if (b.has(token))
+            intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Deduplicate an array of sentences using Jaccard similarity.
+ *
+ * For each new sentence, if it is too similar to one already kept (above
+ * JACCARD_DEDUP_THRESHOLD), keep the longer/more detailed version and discard
+ * the other.
+ *
+ * Returns the deduplicated array of sentences in original order.
+ */
+export function deduplicateSentences(sentences) {
+    const kept = [];
+    for (const sentence of sentences) {
+        const sentenceTokens = tokenizeToSet(sentence);
+        let dominated = false;
+        for (let i = 0; i < kept.length; i++) {
+            const sim = jaccardSimilarity(sentenceTokens, kept[i].tokens);
+            if (sim >= JACCARD_DEDUP_THRESHOLD) {
+                // Keep the longer, more detailed version
+                if (sentence.length > kept[i].text.length) {
+                    kept[i] = { text: sentence, tokens: sentenceTokens };
+                }
+                dominated = true;
+                break;
+            }
+        }
+        if (!dominated) {
+            kept.push({ text: sentence, tokens: sentenceTokens });
+        }
+    }
+    return kept.map(k => k.text);
+}
+/**
+ * Split text into individual sentences.
+ * Handles common sentence-ending punctuation and newlines.
+ */
+function splitIntoSentences(text) {
+    return text
+        .split(/(?<=[.!?])\s+|\n+/)
+        .map(s => s.trim())
+        .filter(s => s.length > 0);
+}
+// ---------------------------------------------------------------------------
+// Similarity helpers
+// ---------------------------------------------------------------------------
+/**
+ * Look up the stored embedding for a memory from the vec table.
+ * Returns null if no embedding is stored.
+ */
+function getStoredEmbedding(memoryId) {
+    try {
+        const db = getDatabase();
+        const row = db.prepare(`SELECT me.embedding
+       FROM memory_embeddings me
+       JOIN memory_embedding_map mm ON mm.vec_rowid = me.rowid
+       WHERE mm.memory_id = ?`).get(memoryId);
+        if (!row?.embedding)
+            return null;
+        return new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Text-based similarity between two memories using Jaccard on tokenized content.
+ * Used as a fallback when embeddings are unavailable.
+ */
+function textSimilarity(a, b) {
+    const tokensA = tokenizeToSet(a.content + ' ' + a.summary);
+    const tokensB = tokenizeToSet(b.content + ' ' + b.summary);
+    return jaccardSimilarity(tokensA, tokensB);
+}
+// ---------------------------------------------------------------------------
+// Candidate finding
+// ---------------------------------------------------------------------------
+/**
+ * Find groups of memories that are candidates for consolidation.
+ *
+ * Criteria for grouping:
+ *   - Same type
+ *   - Within ±3 AU of each other (distance)
+ *   - Cosine similarity > 0.80 (falls back to Jaccard if no embeddings)
+ *
+ * Returns groups sorted by average similarity (highest first).
+ * Each group contains 2+ memories.
+ */
+export async function findConsolidationCandidates(project) {
+    const all = getMemoriesByProject(project).filter(m => !m.consolidated_into && !m.deleted_at);
+    if (all.length < 2)
+        return [];
+    // Pre-fetch all available embeddings in one pass to avoid repeated DB hits
+    const embeddingCache = new Map();
+    for (const m of all) {
+        embeddingCache.set(m.id, getStoredEmbedding(m.id));
+    }
+    // Build groups using a union-find-like approach:
+    // Any two memories that pass ALL criteria are put in the same group.
+    const groups = [];
+    const grouped = new Set();
+    for (let i = 0; i < all.length; i++) {
+        const a = all[i];
+        if (grouped.has(a.id))
+            continue;
+        const group = [a];
+        const similarities = [];
+        for (let j = i + 1; j < all.length; j++) {
+            const b = all[j];
+            if (grouped.has(b.id))
+                continue;
+            // Must share the same memory type
+            if (a.type !== b.type)
+                continue;
+            // Must be within ±3 AU of each other
+            if (Math.abs(a.distance - b.distance) > DISTANCE_TOLERANCE)
+                continue;
+            // Similarity check — prefer embeddings, fall back to text
+            let similarity;
+            const embA = embeddingCache.get(a.id) ?? null;
+            const embB = embeddingCache.get(b.id) ?? null;
+            if (embA && embB) {
+                similarity = cosineSimilarity(embA, embB);
+            }
+            else {
+                similarity = textSimilarity(a, b);
+            }
+            if (similarity < SIMILARITY_THRESHOLD)
+                continue;
+            group.push(b);
+            similarities.push(similarity);
+        }
+        if (group.length >= 2) {
+            for (const m of group)
+                grouped.add(m.id);
+            groups.push({ memories: group, similarities });
+        }
+    }
+    // Compute average similarity per group and sort descending
+    return groups
+        .map(g => ({
+        memories: g.memories,
+        similarity: g.similarities.length > 0
+            ? g.similarities.reduce((s, v) => s + v, 0) / g.similarities.length
+            : SIMILARITY_THRESHOLD,
+    }))
+        .sort((a, b) => b.similarity - a.similarity);
+}
+// ---------------------------------------------------------------------------
+// Consolidation
+// ---------------------------------------------------------------------------
+/**
+ * Consolidate a group of memories into a single new memory.
+ *
+ * Merge strategy:
+ *   - Content: Combine unique sentences from all sources (Jaccard dedup).
+ *   - Summary: Join all source summaries, deduplicated and truncated.
+ *   - Tags: Union of all tags.
+ *   - Type: Most important type by TYPE_PRIORITY ranking.
+ *   - Impact: Max of all sources.
+ *   - Distance: Min of all sources (closest orbit).
+ *
+ * After creating the new memory:
+ *   - Source memories are marked as consolidated (consolidated_into set).
+ *   - Source memories are pushed to the Oort cloud (distance = 95).
+ *
+ * Returns the newly created consolidated memory.
+ */
+export function consolidateGroup(memories, project) {
+    if (memories.length < 2) {
+        throw new Error('consolidateGroup requires at least 2 memories');
+    }
+    // Merge content: collect all sentences, deduplicate, combine
+    const allSentences = [];
+    for (const m of memories) {
+        allSentences.push(...splitIntoSentences(m.content));
+    }
+    const uniqueSentences = deduplicateSentences(allSentences);
+    const mergedContent = `Consolidated from ${memories.length} memories:\n` +
+        uniqueSentences.join(' ');
+    // Merge summary: collect unique summaries
+    const summaryParts = deduplicateSentences(memories.map(m => m.summary));
+    const mergedSummary = summaryParts.join('; ').slice(0, 120);
+    // Merge tags: union, deduplicated
+    const tagSet = new Set();
+    for (const m of memories) {
+        for (const t of m.tags)
+            tagSet.add(t);
+    }
+    const mergedTags = [...tagSet];
+    // Choose type by priority
+    const mergedType = memories.reduce((best, m) => (TYPE_PRIORITY[m.type] ?? 0) > (TYPE_PRIORITY[best.type] ?? 0) ? m : best).type;
+    // Max impact
+    const mergedImpact = Math.max(...memories.map(m => m.impact));
+    // Create the new consolidated memory
+    const consolidated = createMemory({
+        project,
+        content: mergedContent,
+        summary: mergedSummary,
+        type: mergedType,
+        impact: mergedImpact,
+        tags: mergedTags,
+    });
+    // Mark all source memories as consolidated and push to Oort cloud
+    const sourceIds = memories.map(m => m.id);
+    consolidateMemories(sourceIds, consolidated.id);
+    for (const m of memories) {
+        updateMemoryOrbit(m.id, OORT_DISTANCE, 0.02, OORT_DISTANCE - m.distance);
+        insertOrbitLog({
+            memory_id: m.id,
+            project,
+            old_distance: m.distance,
+            new_distance: OORT_DISTANCE,
+            old_importance: m.importance,
+            new_importance: 0.02,
+            trigger: 'manual',
+        });
+    }
+    log.info('Consolidated group', {
+        sourceCount: memories.length,
+        consolidatedId: consolidated.id,
+        type: mergedType,
+    });
+    return consolidated;
+}
+// ---------------------------------------------------------------------------
+// Full consolidation pass
+// ---------------------------------------------------------------------------
+/**
+ * Run a full consolidation pass for a project.
+ *
+ * Finds all candidate groups, consolidates each one, and returns statistics.
+ */
+export async function runConsolidation(project) {
+    log.info('Starting consolidation pass', { project });
+    const candidates = await findConsolidationCandidates(project);
+    let memoriesConsolidated = 0;
+    let newMemoriesCreated = 0;
+    for (const { memories, similarity } of candidates) {
+        try {
+            log.debug('Consolidating group', {
+                size: memories.length,
+                similarity: similarity.toFixed(3),
+                ids: memories.map(m => m.id),
+            });
+            consolidateGroup(memories, project);
+            memoriesConsolidated += memories.length;
+            newMemoriesCreated += 1;
+        }
+        catch (err) {
+            log.warn('Failed to consolidate group', {
+                ids: memories.map(m => m.id),
+                error: String(err),
+            });
+        }
+    }
+    log.info('Consolidation pass complete', {
+        project,
+        groupsFound: candidates.length,
+        memoriesConsolidated,
+        newMemoriesCreated,
+    });
+    return {
+        groupsFound: candidates.length,
+        memoriesConsolidated,
+        newMemoriesCreated,
+    };
+}
+// ---------------------------------------------------------------------------
+// Consolidation history
+// ---------------------------------------------------------------------------
+/**
+ * Return the source memories that were merged into the given memory ID.
+ * Returns an empty array if this memory was not created by consolidation.
+ */
+export function getConsolidationSources(memoryId) {
+    return getConsolidationHistory(memoryId);
+}
+// ---------------------------------------------------------------------------
+// Async embedding-based similarity (used for higher precision when needed)
+// ---------------------------------------------------------------------------
+/**
+ * Generate and compare embeddings for two text strings.
+ * Returns cosine similarity in [0, 1].
+ * Used internally when stored embeddings are unavailable.
+ */
+export async function computeEmbeddingSimilarity(textA, textB) {
+    try {
+        const [embA, embB] = await Promise.all([
+            generateEmbedding(textA),
+            generateEmbedding(textB),
+        ]);
+        return cosineSimilarity(embA, embB);
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=consolidation.js.map

package/dist/engine/consolidation.js.map

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

package/dist/engine/constellation.d.ts

@@ -0,0 +1,66 @@
+/**
+ * constellation.ts — Knowledge Graph engine module
+ *
+ * Memories form a "constellation" — a graph where edges represent semantic
+ * and structural relationships between memory planets.
+ *
+ * Relationships are inferred using fast, local keyword heuristics:
+ *   - Type-based rules (error → decision = caused_by, etc.)
+ *   - Contradiction detection (negation/replacement keywords near shared terms)
+ *   - Content reference detection (one memory's text mentions another's keywords)
+ *   - Shared tag overlap (same domain/topic)
+ *   - Default fallback: related_to
+ *
+ * All functions are synchronous except extractRelationships, which is async
+ * because it may use vector similarity as the primary similarity signal.
+ */
+import type { Memory, ConstellationEdge, RelationType } from './types.js';
+/**
+ * Auto-extract relationships for a newly stored memory.
+ *
+ * Algorithm:
+ *   1. Find the top-K most similar existing memories using vector KNN if
+ *      available, falling back to FTS5 keyword search.
+ *   2. For each candidate, compute a weight (cosine similarity or keyword
+ *      overlap ratio).
+ *   3. Filter candidates below WEIGHT_THRESHOLD.
+ *   4. Infer the relationship type using keyword heuristics.
+ *   5. Persist edges via queries.createEdge().
+ *
+ * Returns the list of edges that were created.
+ */
+export declare function extractRelationships(newMemory: Memory, project: string): Promise<ConstellationEdge[]>;
+/**
+ * Return the full constellation graph (nodes + edges) centred on a memory.
+ *
+ * Uses queries.getConstellation() which handles multi-depth BFS traversal
+ * and deduplication internally. Depth defaults to 1 (immediate neighbours).
+ */
+export declare function getConstellationGraph(memoryId: string, project: string, depth?: number): {
+    nodes: Memory[];
+    edges: ConstellationEdge[];
+};
+/**
+ * Return the top N memories most strongly connected to the given memory,
+ * sorted by edge weight (descending).
+ *
+ * Useful for augmenting recall results with graph-traversal neighbours.
+ */
+export declare function findRelatedMemories(memoryId: string, project: string, limit?: number): Memory[];
+/**
+ * Suggest potential relationships for an existing memory without persisting them.
+ * Useful for a "review" UI where a user can approve/reject suggestions.
+ *
+ * Returns candidates sorted by confidence (descending).
+ */
+export declare function suggestRelationships(memoryId: string, project: string): Array<{
+    target: Memory;
+    suggestedRelation: RelationType;
+    confidence: number;
+}>;
+/**
+ * Remove all constellation edges that reference the given memory ID.
+ * Should be called when a memory is deleted to prevent orphan edges.
+ */
+export declare function cleanupEdges(memoryId: string): void;
+//# sourceMappingURL=constellation.d.ts.map