@vinaes/succ 1.3.19

package/dist/lib/graph/community-detection.js

@@ -0,0 +1,218 @@
+/**
+ * Community Detection — Label Propagation Algorithm
+ *
+ * Automatically groups memories into thematic communities
+ * based on graph structure. Pure TypeScript, no external deps.
+ *
+ * Inspired by rahulnyk/knowledge_graph's Girvan-Newman approach,
+ * but using Label Propagation which is faster and simpler.
+ */
+import { getAllMemoryLinksForExport, getAllMemoriesForExport, updateMemoryTags, } from '../storage/index.js';
+// ============================================================================
+// Adjacency List
+// ============================================================================
+/**
+ * Build adjacency list from memory_links table.
+ * Returns undirected graph: each edge appears in both directions.
+ */
+export function buildAdjacencyList(links) {
+    const adj = new Map();
+    const addEdge = (from, to, weight) => {
+        const neighbors = adj.get(from) ?? [];
+        neighbors.push({ neighbor: to, weight });
+        adj.set(from, neighbors);
+    };
+    for (const link of links) {
+        addEdge(link.source_id, link.target_id, link.weight);
+        addEdge(link.target_id, link.source_id, link.weight);
+    }
+    return adj;
+}
+// ============================================================================
+// Label Propagation
+// ============================================================================
+/**
+ * Seeded random number generator (Mulberry32).
+ * Provides deterministic shuffling for reproducible results.
+ */
+function mulberry32(seed) {
+    return () => {
+        seed |= 0;
+        seed = (seed + 0x6d2b79f5) | 0;
+        let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Shuffle array in-place using Fisher-Yates with seeded RNG.
+ */
+function shuffleArray(arr, rng) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+}
+/**
+ * Label Propagation Algorithm.
+ *
+ * 1. Each node gets its own ID as label
+ * 2. Iteratively: each node adopts the most frequent weighted label of its neighbors
+ * 3. Converges when no labels change
+ *
+ * @returns Map of nodeId → communityId
+ */
+export function labelPropagation(adjacency, maxIterations = 100, seed = 42) {
+    const rng = mulberry32(seed);
+    // Initialize: each node is its own community
+    const labels = new Map();
+    const nodes = Array.from(adjacency.keys());
+    for (const node of nodes) {
+        labels.set(node, node);
+    }
+    for (let iter = 0; iter < maxIterations; iter++) {
+        let changed = false;
+        // Shuffle nodes for randomized order
+        shuffleArray(nodes, rng);
+        for (const node of nodes) {
+            const neighbors = adjacency.get(node);
+            if (!neighbors || neighbors.length === 0)
+                continue;
+            // Count weighted labels of neighbors
+            const labelWeights = new Map();
+            for (const { neighbor, weight } of neighbors) {
+                const neighborLabel = labels.get(neighbor);
+                labelWeights.set(neighborLabel, (labelWeights.get(neighborLabel) ?? 0) + weight);
+            }
+            // Find label with highest weight
+            let bestLabel = labels.get(node);
+            let bestWeight = -1;
+            for (const [label, weight] of labelWeights) {
+                if (weight > bestWeight || (weight === bestWeight && rng() > 0.5)) {
+                    bestLabel = label;
+                    bestWeight = weight;
+                }
+            }
+            if (bestLabel !== labels.get(node)) {
+                labels.set(node, bestLabel);
+                changed = true;
+            }
+        }
+        // Converged
+        if (!changed)
+            break;
+    }
+    return labels;
+}
+/**
+ * Renumber communities from 0..N for clean output.
+ */
+export function renumberCommunities(labels) {
+    const labelToId = new Map();
+    let nextId = 0;
+    const renumbered = new Map();
+    for (const [node, label] of labels) {
+        if (!labelToId.has(label)) {
+            labelToId.set(label, nextId++);
+        }
+        renumbered.set(node, labelToId.get(label));
+    }
+    return renumbered;
+}
+/**
+ * Detect communities in the memory graph.
+ * Updates memory tags with community:N assignments.
+ */
+export async function detectCommunities(options = {}) {
+    const { maxIterations = 100, minCommunitySize = 2, tagPrefix = 'community' } = options;
+    // Get all links via storage abstraction
+    const links = await getAllMemoryLinksForExport();
+    if (links.length === 0) {
+        return { communities: [], isolated: 0, iterations: 0 };
+    }
+    // Build adjacency list
+    const adjacency = buildAdjacencyList(links);
+    // Run Label Propagation
+    const rawLabels = labelPropagation(adjacency, maxIterations);
+    const labels = renumberCommunities(rawLabels);
+    // Group by community
+    const communityMap = new Map();
+    for (const [nodeId, communityId] of labels) {
+        const members = communityMap.get(communityId) ?? [];
+        members.push(nodeId);
+        communityMap.set(communityId, members);
+    }
+    // Build result, filtering by min size
+    const communities = [];
+    let isolated = 0;
+    for (const [id, members] of communityMap) {
+        if (members.length < minCommunitySize) {
+            isolated += members.length;
+        }
+        else {
+            communities.push({ id, size: members.length, members: members.sort((a, b) => a - b) });
+        }
+    }
+    communities.sort((a, b) => b.size - a.size);
+    // Update memory tags: remove old community tags, add new ones
+    const tagPattern = `${tagPrefix}:`;
+    const allMemories = await getAllMemoriesForExport();
+    const memoryTagMap = new Map();
+    for (const mem of allMemories) {
+        const tags = Array.isArray(mem.tags)
+            ? mem.tags
+            : typeof mem.tags === 'string'
+                ? (() => {
+                    try {
+                        return JSON.parse(mem.tags);
+                    }
+                    catch {
+                        return [];
+                    }
+                })()
+                : [];
+        memoryTagMap.set(mem.id, tags);
+    }
+    for (const memId of labels.keys()) {
+        let tags = memoryTagMap.get(memId) ?? [];
+        // Remove old community tags
+        tags = tags.filter((t) => !t.startsWith(tagPattern));
+        // Add new community tag (only if community is large enough)
+        const communityId = labels.get(memId);
+        if (communityId != null) {
+            const members = communityMap.get(communityId);
+            if (members && members.length >= minCommunitySize) {
+                tags.push(`${tagPrefix}:${communityId}`);
+            }
+        }
+        await updateMemoryTags(memId, tags);
+    }
+    return { communities, isolated, iterations: maxIterations };
+}
+/**
+ * Get community assignment for a specific memory from its tags.
+ */
+export async function getMemoryCommunity(memoryId, tagPrefix = 'community') {
+    const { getMemoryById } = await import('../storage/index.js');
+    const mem = await getMemoryById(memoryId);
+    if (!mem)
+        return null;
+    const tags = Array.isArray(mem.tags)
+        ? mem.tags
+        : typeof mem.tags === 'string'
+            ? (() => {
+                try {
+                    return JSON.parse(mem.tags);
+                }
+                catch {
+                    return [];
+                }
+            })()
+            : [];
+    const prefix = `${tagPrefix}:`;
+    const communityTag = tags.find((t) => t.startsWith(prefix));
+    if (!communityTag)
+        return null;
+    return parseInt(communityTag.slice(prefix.length), 10);
+}
+//# sourceMappingURL=community-detection.js.map

package/dist/lib/graph/community-detection.js.map

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

package/dist/lib/graph/contextual-proximity.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Contextual Proximity — co-occurrence linking
+ *
+ * Memories that share the same source (session, file, context) are related.
+ * Inspired by rahulnyk/knowledge_graph's contextual proximity approach:
+ * self-join by source → co-occurrence matrix → weighted edges.
+ */
+/**
+ * Normalize a source string to group similar sources together.
+ * - File paths → parent directory
+ * - Session IDs → keep as-is
+ * - Generic sources → keep as-is
+ */
+export declare function normalizeSource(source: string): string;
+/**
+ * Calculate co-occurrence matrix from memory sources.
+ * Returns pairs of memory IDs that share the same normalized source,
+ * with count = number of shared sources.
+ */
+export declare function calculateProximity(memories: Array<{
+    id: number;
+    source: string | null;
+}>): Array<{
+    node_1: number;
+    node_2: number;
+    count: number;
+    sources: string[];
+}>;
+/**
+ * Create proximity-based links from co-occurrence data.
+ * Skips pairs that already have any link between them.
+ */
+export declare function createProximityLinks(options?: {
+    minCooccurrence?: number;
+    dryRun?: boolean;
+}): Promise<{
+    created: number;
+    skipped: number;
+    total_pairs: number;
+}>;
+//# sourceMappingURL=contextual-proximity.d.ts.map

package/dist/lib/graph/contextual-proximity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextual-proximity.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/contextual-proximity.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgBtD;AAMD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GACrD,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA4C7E;AAMD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3D,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CA+CpE"}

package/dist/lib/graph/contextual-proximity.js

@@ -0,0 +1,125 @@
+/**
+ * Contextual Proximity — co-occurrence linking
+ *
+ * Memories that share the same source (session, file, context) are related.
+ * Inspired by rahulnyk/knowledge_graph's contextual proximity approach:
+ * self-join by source → co-occurrence matrix → weighted edges.
+ */
+import { getAllMemoriesForExport, getMemoryLinks, createMemoryLink } from '../storage/index.js';
+// ============================================================================
+// Source Normalization
+// ============================================================================
+/**
+ * Normalize a source string to group similar sources together.
+ * - File paths → parent directory
+ * - Session IDs → keep as-is
+ * - Generic sources → keep as-is
+ */
+export function normalizeSource(source) {
+    if (!source)
+        return '';
+    const trimmed = source.trim();
+    // File paths: normalize to directory
+    if (trimmed.includes('/') || trimmed.includes('\\')) {
+        const parts = trimmed.replace(/\\/g, '/').split('/');
+        // Remove filename, keep directory
+        if (parts.length > 1 && parts[parts.length - 1].includes('.')) {
+            return parts.slice(0, -1).join('/');
+        }
+        return trimmed.replace(/\\/g, '/');
+    }
+    return trimmed.toLowerCase();
+}
+// ============================================================================
+// Proximity Calculation
+// ============================================================================
+/**
+ * Calculate co-occurrence matrix from memory sources.
+ * Returns pairs of memory IDs that share the same normalized source,
+ * with count = number of shared sources.
+ */
+export function calculateProximity(memories) {
+    // Group memories by normalized source
+    const sourceGroups = new Map();
+    for (const mem of memories) {
+        if (!mem.source)
+            continue;
+        const normalized = normalizeSource(mem.source);
+        if (!normalized)
+            continue;
+        const group = sourceGroups.get(normalized) ?? [];
+        group.push(mem.id);
+        sourceGroups.set(normalized, group);
+    }
+    // Build co-occurrence pairs
+    const pairMap = new Map();
+    for (const [source, ids] of sourceGroups) {
+        if (ids.length < 2)
+            continue;
+        // Generate all pairs within this source group
+        for (let i = 0; i < ids.length; i++) {
+            for (let j = i + 1; j < ids.length; j++) {
+                const a = Math.min(ids[i], ids[j]);
+                const b = Math.max(ids[i], ids[j]);
+                const key = `${a}:${b}`;
+                const existing = pairMap.get(key);
+                if (existing) {
+                    existing.count++;
+                    if (!existing.sources.includes(source)) {
+                        existing.sources.push(source);
+                    }
+                }
+                else {
+                    pairMap.set(key, { node_1: a, node_2: b, count: 1, sources: [source] });
+                }
+            }
+        }
+    }
+    return Array.from(pairMap.values());
+}
+// ============================================================================
+// Link Creation
+// ============================================================================
+/**
+ * Create proximity-based links from co-occurrence data.
+ * Skips pairs that already have any link between them.
+ */
+export async function createProximityLinks(options = {}) {
+    const { minCooccurrence = 2, dryRun = false } = options;
+    // Get all non-invalidated memories with sources via storage
+    const allMemories = await getAllMemoriesForExport();
+    const memories = allMemories
+        .filter((m) => m.source && !m.invalidated_by)
+        .map((m) => ({ id: m.id, source: m.source }));
+    const pairs = calculateProximity(memories);
+    // Filter by min co-occurrence
+    const filtered = pairs.filter((p) => p.count >= minCooccurrence);
+    if (dryRun) {
+        return { created: 0, skipped: 0, total_pairs: filtered.length };
+    }
+    // Find max count for weight normalization
+    const maxCount = Math.max(1, ...filtered.map((p) => p.count));
+    let created = 0;
+    let skipped = 0;
+    for (const pair of filtered) {
+        // Check if any link already exists between these two memories
+        const linksA = await getMemoryLinks(pair.node_1);
+        const hasLink = linksA.outgoing?.some((l) => l.target_id === pair.node_2) ||
+            linksA.incoming?.some((l) => l.source_id === pair.node_2);
+        if (hasLink) {
+            skipped++;
+            continue;
+        }
+        // Normalized weight: count / maxCount
+        const weight = pair.count / maxCount;
+        const result = await createMemoryLink(pair.node_1, pair.node_2, 'related', weight);
+        if (result.created) {
+            created++;
+        }
+        else {
+            skipped++;
+        }
+    }
+    return { created, skipped, total_pairs: filtered.length };
+}
+//# sourceMappingURL=contextual-proximity.js.map

package/dist/lib/graph/contextual-proximity.js.map

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

package/dist/lib/graph/llm-relations.d.ts

@@ -0,0 +1,54 @@
+/**
+ * LLM Relation Extraction — classify link types using LLM
+ *
+ * Instead of blind "similar_to" links, uses LLM to determine
+ * the actual relationship between memories (caused_by, leads_to, etc.)
+ *
+ * Inspired by rahulnyk/knowledge_graph's approach of using LLM
+ * to extract ontological relationships from text.
+ */
+import { type LinkRelation } from '../storage/types.js';
+interface MemoryInfo {
+    id: number;
+    content: string;
+    type: string;
+    tags: string[];
+}
+interface ClassifyResult {
+    relation: LinkRelation;
+    confidence: number;
+}
+/**
+ * Classify the relation between two memories using LLM.
+ */
+export declare function classifyRelation(memoryA: MemoryInfo, memoryB: MemoryInfo): Promise<ClassifyResult>;
+/**
+ * Classify multiple pairs in a single LLM call (saves tokens).
+ */
+export declare function classifyRelationsBatch(pairs: Array<{
+    a: MemoryInfo;
+    b: MemoryInfo;
+    linkId: number;
+}>): Promise<Array<{
+    linkId: number;
+    relation: LinkRelation;
+    confidence: number;
+}>>;
+/**
+ * Enrich all existing similar_to links that haven't been LLM-enriched yet.
+ */
+export declare function enrichExistingLinks(options?: {
+    force?: boolean;
+    limit?: number;
+    batchSize?: number;
+}): Promise<{
+    enriched: number;
+    failed: number;
+    skipped: number;
+}>;
+/**
+ * Enrich links for a single memory (called async after auto-link).
+ */
+export declare function enrichMemoryLinks(memoryId: number): Promise<number>;
+export {};
+//# sourceMappingURL=llm-relations.d.ts.map

package/dist/lib/graph/llm-relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-relations.d.ts","sourceRoot":"","sources":["../../../src/lib/graph/llm-relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAkDxE,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,UAAU,cAAc;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,cAAc,CAAC,CAYzB;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,KAAK,CAAC;IAAE,CAAC,EAAE,UAAU,CAAC;IAAC,CAAC,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7D,OAAO,CAAC,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CA4BhF;AAMD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACpE,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAqGhE;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAczE"}