@openweave/weave-graph 0.2.0 → 0.2.1

package/dist/cjs/compression.d.ts

@@ -0,0 +1,94 @@
+import { Node, Edge } from "./types";
+/**
+ * CompressionStats tracks metrics about graph compression
+ */
+export interface CompressionStats {
+    originalNodeCount: number;
+    originalEdgeCount: number;
+    compressedNodeCount: number;
+    compressedEdgeCount: number;
+    archivedNodeCount: number;
+    compressionRatio: number;
+    estimatedContextSize: number;
+}
+/**
+ * CompressionManager handles graph compression and context optimization
+ * Keeps high-value nodes in active memory, archives low-frequency nodes
+ */
+export declare class CompressionManager {
+    private archivedNodes;
+    private archivedEdges;
+    /**
+     * Calculate approximate size of a node in bytes (for context window estimation)
+     */
+    static estimateNodeSize(node: Node): number;
+    /**
+     * Calculate approximate size of an edge in bytes
+     */
+    static estimateEdgeSize(edge: Edge): number;
+    /**
+     * Calculate total estimated context window usage
+     */
+    static calculateContextSize(nodes: Node[], edges: Edge[]): number;
+    /**
+     * Calculate context window usage as a percentage (0-1)
+     * Assumes ~100KB max context for graph data (typical LLM context budget)
+     */
+    static calculateContextUsagePercentage(contextSize: number): number;
+    /**
+     * Identify nodes that should be archived (low frequency, old, not critical)
+     * Returns nodeIds sorted by priority for archival
+     */
+    static identifyArchiveCandidates(nodes: Node[], edges: Edge[], targetReductionPercentage?: number): string[];
+    /**
+     * Archive nodes and their dependent edges
+     */
+    archiveNodes(nodeIds: string[], nodes: Map<string, Node>, edges: Map<string, Edge>): void;
+    /**
+     * Restore archived nodes back to active graph
+     */
+    restoreNodes(nodeIds: string[]): Map<string, Node>;
+    /**
+     * Get archive statistics
+     */
+    getArchiveStats(): {
+        archivedNodeCount: number;
+        archivedEdgeCount: number;
+    };
+    /**
+     * Clear all archives
+     */
+    clearArchives(): void;
+}
+/**
+ * ErrorSuppression handles marking errors and their corrections
+ */
+export declare class ErrorSuppression {
+    /**
+     * Mark a node as suppressed (contains an error)
+     */
+    static suppressNode(node: Node): Node;
+    /**
+     * Check if a node is suppressed
+     */
+    static isSuppressed(node: Node): boolean;
+    /**
+     * Create a correction node linked to an error node
+     */
+    static createCorrection(errorNodeId: string, correctionLabel: string, correctionDescription?: string): {
+        correctionNode: Node;
+        correctionEdge: Edge;
+    };
+    /**
+     * Get all error nodes that have corrections
+     */
+    static findCorrectedErrors(nodes: Map<string, Node>, edges: Map<string, Edge>): Map<string, {
+        error: Node;
+        corrections: Node[];
+    }>;
+    /**
+     * Get uncorrected error nodes
+     */
+    static findUncorrectedErrors(nodes: Map<string, Node>, edges: Map<string, Edge>): Node[];
+}
+//# sourceMappingURL=compression.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/compression.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAsB,MAAM,SAAS,CAAC;AAIzD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,aAAa,CAAgC;IAErD;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAQ3C;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAM3C;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM;IAMjE;;;OAGG;IACH,MAAM,CAAC,+BAA+B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAKnE;;;OAGG;IACH,MAAM,CAAC,yBAAyB,CAC9B,KAAK,EAAE,IAAI,EAAE,EACb,KAAK,EAAE,IAAI,EAAE,EACb,yBAAyB,GAAE,MAAY,GACtC,MAAM,EAAE;IA8CX;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI;IAmBzF;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;IAYlD;;OAEG;IACH,eAAe,IAAI;QACjB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,iBAAiB,EAAE,MAAM,CAAC;KAC3B;IAOD;;OAEG;IACH,aAAa,IAAI,IAAI;CAItB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAcrC;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO;IAIxC;;OAEG;IACH,MAAM,CAAC,gBAAgB,CACrB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,EACvB,qBAAqB,CAAC,EAAE,MAAM,GAC7B;QAAE,cAAc,EAAE,IAAI,CAAC;QAAC,cAAc,EAAE,IAAI,CAAA;KAAE;IAUjD;;OAEG;IACH,MAAM,CAAC,mBAAmB,CACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EACxB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GACvB,GAAG,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,WAAW,EAAE,IAAI,EAAE,CAAA;KAAE,CAAC;IAuBpD;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,EAAE;CAYzF"}

package/dist/cjs/compression.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorSuppression = exports.CompressionManager = void 0;
+const types_1 = require("./types");
+const node_1 = require("./node");
+const edge_1 = require("./edge");
+/**
+ * CompressionManager handles graph compression and context optimization
+ * Keeps high-value nodes in active memory, archives low-frequency nodes
+ */
+class CompressionManager {
+    archivedNodes = new Map();
+    archivedEdges = new Map();
+    /**
+     * Calculate approximate size of a node in bytes (for context window estimation)
+     */
+    static estimateNodeSize(node) {
+        // Rough estimation: labels ~50 bytes + metadata ~100 bytes
+        const labelSize = node.label.length * 2;
+        const descSize = (node.description || "").length * 2;
+        const metadataSize = JSON.stringify(node.metadata || {}).length;
+        return 50 + labelSize + descSize + metadataSize;
+    }
+    /**
+     * Calculate approximate size of an edge in bytes
+     */
+    static estimateEdgeSize(edge) {
+        // Edge size: sourceId ~ 36 bytes + targetId ~ 36 bytes + type ~ 20 bytes + metadata
+        const metadataSize = JSON.stringify(edge.metadata || {}).length;
+        return 100 + metadataSize;
+    }
+    /**
+     * Calculate total estimated context window usage
+     */
+    static calculateContextSize(nodes, edges) {
+        const nodesSize = nodes.reduce((sum, node) => sum + this.estimateNodeSize(node), 0);
+        const edgesSize = edges.reduce((sum, edge) => sum + this.estimateEdgeSize(edge), 0);
+        return nodesSize + edgesSize;
+    }
+    /**
+     * Calculate context window usage as a percentage (0-1)
+     * Assumes ~100KB max context for graph data (typical LLM context budget)
+     */
+    static calculateContextUsagePercentage(contextSize) {
+        const MAX_CONTEXT_BYTES = 100_000; // ~100KB for graph data
+        return Math.min(contextSize / MAX_CONTEXT_BYTES, 1);
+    }
+    /**
+     * Identify nodes that should be archived (low frequency, old, not critical)
+     * Returns nodeIds sorted by priority for archival
+     */
+    static identifyArchiveCandidates(nodes, edges, targetReductionPercentage = 0.3) {
+        // Build a map of node importance
+        const nodeImportance = new Map();
+        // Initialize with frequency
+        for (const node of nodes) {
+            nodeImportance.set(node.id, node.frequency ?? 1);
+        }
+        // Increase importance of nodes with many connections
+        const connectionCount = new Map();
+        for (const edge of edges) {
+            connectionCount.set(edge.sourceId, (connectionCount.get(edge.sourceId) ?? 0) + 1);
+            connectionCount.set(edge.targetId, (connectionCount.get(edge.targetId) ?? 0) + 1);
+        }
+        for (const [nodeId, count] of connectionCount) {
+            const current = nodeImportance.get(nodeId) ?? 1;
+            nodeImportance.set(nodeId, current + count * 2);
+        }
+        // Mark ERROR nodes as candidates (they can be archived after corrections exist)
+        for (const node of nodes) {
+            if (node.type === types_1.NodeType.ERROR) {
+                nodeImportance.set(node.id, Math.max(0.1, (nodeImportance.get(node.id) ?? 1) - 5));
+            }
+        }
+        // Mark old nodes with low frequency as less important
+        const now = new Date();
+        for (const node of nodes) {
+            const ageHours = (now.getTime() - node.updatedAt.getTime()) / (1000 * 60 * 60);
+            if (ageHours > 24 && (node.frequency ?? 1) < 3) {
+                nodeImportance.set(node.id, (nodeImportance.get(node.id) ?? 1) * 0.5);
+            }
+        }
+        // Sort by importance and select bottom candidates
+        const sorted = Array.from(nodeImportance.entries())
+            .sort((a, b) => a[1] - b[1])
+            .map(([id]) => id);
+        const targetCount = Math.ceil(nodes.length * targetReductionPercentage);
+        return sorted.slice(0, targetCount);
+    }
+    /**
+     * Archive nodes and their dependent edges
+     */
+    archiveNodes(nodeIds, nodes, edges) {
+        const nodeIdSet = new Set(nodeIds);
+        // Archive nodes
+        for (const nodeId of nodeIds) {
+            const node = nodes.get(nodeId);
+            if (node) {
+                this.archivedNodes.set(nodeId, node);
+            }
+        }
+        // Archive edges connected to archived nodes
+        for (const [edgeId, edge] of edges) {
+            if (nodeIdSet.has(edge.sourceId) || nodeIdSet.has(edge.targetId)) {
+                this.archivedEdges.set(edgeId, edge);
+            }
+        }
+    }
+    /**
+     * Restore archived nodes back to active graph
+     */
+    restoreNodes(nodeIds) {
+        const restored = new Map();
+        for (const nodeId of nodeIds) {
+            const node = this.archivedNodes.get(nodeId);
+            if (node) {
+                restored.set(nodeId, node);
+                this.archivedNodes.delete(nodeId);
+            }
+        }
+        return restored;
+    }
+    /**
+     * Get archive statistics
+     */
+    getArchiveStats() {
+        return {
+            archivedNodeCount: this.archivedNodes.size,
+            archivedEdgeCount: this.archivedEdges.size,
+        };
+    }
+    /**
+     * Clear all archives
+     */
+    clearArchives() {
+        this.archivedNodes.clear();
+        this.archivedEdges.clear();
+    }
+}
+exports.CompressionManager = CompressionManager;
+/**
+ * ErrorSuppression handles marking errors and their corrections
+ */
+class ErrorSuppression {
+    /**
+     * Mark a node as suppressed (contains an error)
+     */
+    static suppressNode(node) {
+        if (node.type !== types_1.NodeType.ERROR) {
+            throw new Error("Only ERROR type nodes can be suppressed");
+        }
+        return {
+            ...node,
+            metadata: {
+                ...node.metadata,
+                suppressed: true,
+                suppressedAt: new Date().toISOString(),
+            },
+        };
+    }
+    /**
+     * Check if a node is suppressed
+     */
+    static isSuppressed(node) {
+        return node.metadata?.suppressed ?? false;
+    }
+    /**
+     * Create a correction node linked to an error node
+     */
+    static createCorrection(errorNodeId, correctionLabel, correctionDescription) {
+        const correctionNode = node_1.NodeBuilder.correction(correctionLabel, correctionDescription);
+        const correctionEdge = edge_1.EdgeBuilder.corrects(correctionNode.id, errorNodeId);
+        return {
+            correctionNode,
+            correctionEdge,
+        };
+    }
+    /**
+     * Get all error nodes that have corrections
+     */
+    static findCorrectedErrors(nodes, edges) {
+        const correctedErrors = new Map();
+        for (const [, edge] of edges) {
+            if (edge.type === types_1.EdgeType.CORRECTS) {
+                const correctionNode = nodes.get(edge.sourceId);
+                const errorNode = nodes.get(edge.targetId);
+                if (correctionNode && errorNode && errorNode.type === types_1.NodeType.ERROR) {
+                    if (!correctedErrors.has(errorNode.id)) {
+                        correctedErrors.set(errorNode.id, {
+                            error: errorNode,
+                            corrections: [],
+                        });
+                    }
+                    correctedErrors.get(errorNode.id).corrections.push(correctionNode);
+                }
+            }
+        }
+        return correctedErrors;
+    }
+    /**
+     * Get uncorrected error nodes
+     */
+    static findUncorrectedErrors(nodes, edges) {
+        const errorNodes = Array.from(nodes.values()).filter((n) => n.type === types_1.NodeType.ERROR);
+        const correctedErrorIds = new Set();
+        for (const [, edge] of edges) {
+            if (edge.type === types_1.EdgeType.CORRECTS) {
+                correctedErrorIds.add(edge.targetId);
+            }
+        }
+        return errorNodes.filter((n) => !correctedErrorIds.has(n.id));
+    }
+}
+exports.ErrorSuppression = ErrorSuppression;
+//# sourceMappingURL=compression.js.map

package/dist/cjs/compression.js.map

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

package/dist/cjs/edge.d.ts

@@ -0,0 +1,43 @@
+import { Edge, EdgeType } from "./types";
+/**
+ * EdgeBuilder utility for creating and managing graph edges
+ */
+export declare class EdgeBuilder {
+    /**
+     * Create a new edge between two nodes
+     */
+    static create(sourceId: string, targetId: string, type: EdgeType, weight?: number, metadata?: Record<string, unknown>): Edge;
+    /**
+     * Create a RELATES edge
+     */
+    static relates(sourceId: string, targetId: string, weight?: number): Edge;
+    /**
+     * Create a CAUSES edge
+     */
+    static causes(sourceId: string, targetId: string, weight?: number): Edge;
+    /**
+     * Create a CORRECTS edge (links CORRECTION to ERROR)
+     */
+    static corrects(correctionId: string, errorId: string, weight?: number): Edge;
+    /**
+     * Create an IMPLEMENTS edge (code → decision)
+     */
+    static implements(codeEntityId: string, decisionId: string, weight?: number): Edge;
+    /**
+     * Create a DEPENDS_ON edge
+     */
+    static dependsOn(sourceId: string, targetId: string, weight?: number): Edge;
+    /**
+     * Create a BLOCKS edge
+     */
+    static blocks(blockerId: string, blockedId: string, weight?: number): Edge;
+    /**
+     * Clone an edge with updated values
+     */
+    static clone(edge: Edge, updates?: Partial<Edge>): Edge;
+    /**
+     * Increase the weight (confidence) of an edge
+     */
+    static reinforceWeight(edge: Edge, factor?: number): Edge;
+}
+//# sourceMappingURL=edge.d.ts.map

package/dist/cjs/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/edge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGzC;;GAEG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,QAAQ,EACd,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,IAAI;IAaP;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,QAAQ,CACb,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,UAAU,CACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,SAAS,CACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAIP;;OAEG;IACH,MAAM,CAAC,KAAK,CACV,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GACtB,IAAI;IAQP;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,MAAY,GAAG,IAAI;CAO/D"}

package/dist/cjs/edge.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EdgeBuilder = void 0;
+const types_1 = require("./types");
+const crypto_1 = require("crypto");
+/**
+ * EdgeBuilder utility for creating and managing graph edges
+ */
+class EdgeBuilder {
+    /**
+     * Create a new edge between two nodes
+     */
+    static create(sourceId, targetId, type, weight, metadata) {
+        return {
+            id: (0, crypto_1.randomUUID)(),
+            sourceId,
+            targetId,
+            type,
+            weight: weight ?? 1.0,
+            metadata: metadata ?? {},
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+    }
+    /**
+     * Create a RELATES edge
+     */
+    static relates(sourceId, targetId, weight) {
+        return this.create(sourceId, targetId, types_1.EdgeType.RELATES, weight);
+    }
+    /**
+     * Create a CAUSES edge
+     */
+    static causes(sourceId, targetId, weight) {
+        return this.create(sourceId, targetId, types_1.EdgeType.CAUSES, weight);
+    }
+    /**
+     * Create a CORRECTS edge (links CORRECTION to ERROR)
+     */
+    static corrects(correctionId, errorId, weight) {
+        return this.create(correctionId, errorId, types_1.EdgeType.CORRECTS, weight);
+    }
+    /**
+     * Create an IMPLEMENTS edge (code → decision)
+     */
+    static implements(codeEntityId, decisionId, weight) {
+        return this.create(codeEntityId, decisionId, types_1.EdgeType.IMPLEMENTS, weight);
+    }
+    /**
+     * Create a DEPENDS_ON edge
+     */
+    static dependsOn(sourceId, targetId, weight) {
+        return this.create(sourceId, targetId, types_1.EdgeType.DEPENDS_ON, weight);
+    }
+    /**
+     * Create a BLOCKS edge
+     */
+    static blocks(blockerId, blockedId, weight) {
+        return this.create(blockerId, blockedId, types_1.EdgeType.BLOCKS, weight);
+    }
+    /**
+     * Clone an edge with updated values
+     */
+    static clone(edge, updates) {
+        return {
+            ...edge,
+            updatedAt: new Date(),
+            ...updates,
+        };
+    }
+    /**
+     * Increase the weight (confidence) of an edge
+     */
+    static reinforceWeight(edge, factor = 1.1) {
+        return {
+            ...edge,
+            weight: (edge.weight ?? 1.0) * factor,
+            updatedAt: new Date(),
+        };
+    }
+}
+exports.EdgeBuilder = EdgeBuilder;
+//# sourceMappingURL=edge.js.map

package/dist/cjs/edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../src/edge.ts"],"names":[],"mappings":";;;AAAA,mCAAyC;AACzC,mCAAoC;AAEpC;;GAEG;AACH,MAAa,WAAW;IACtB;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,QAAgB,EAChB,QAAgB,EAChB,IAAc,EACd,MAAe,EACf,QAAkC;QAElC,OAAO;YACL,EAAE,EAAE,IAAA,mBAAU,GAAE;YAChB,QAAQ;YACR,QAAQ;YACR,IAAI;YACJ,MAAM,EAAE,MAAM,IAAI,GAAG;YACrB,QAAQ,EAAE,QAAQ,IAAI,EAAE;YACxB,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAO,CACZ,QAAgB,EAChB,QAAgB,EAChB,MAAe;QAEf,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,gBAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,QAAgB,EAChB,QAAgB,EAChB,MAAe;QAEf,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,gBAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,QAAQ,CACb,YAAoB,EACpB,OAAe,EACf,MAAe;QAEf,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,EAAE,gBAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,UAAU,CACf,YAAoB,EACpB,UAAkB,EAClB,MAAe;QAEf,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,EAAE,gBAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC5E,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAS,CACd,QAAgB,EAChB,QAAgB,EAChB,MAAe;QAEf,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,gBAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM,CACX,SAAiB,EACjB,SAAiB,EACjB,MAAe;QAEf,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,gBAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CACV,IAAU,EACV,OAAuB;QAEvB,OAAO;YACL,GAAG,IAAI;YACP,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,GAAG,OAAO;SACX,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,IAAU,EAAE,SAAiB,GAAG;QACrD,OAAO;YACL,GAAG,IAAI;YACP,MAAM,EAAE,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM;YACrC,SAAS,EAAE,IAAI,IAAI,EAAE;SACtB,CAAC;IACJ,CAAC;CACF;AAjHD,kCAiHC"}

package/dist/cjs/hebbian-weights.d.ts

@@ -0,0 +1,100 @@
+import { Edge } from "./types.js";
+export interface HebbianOptions {
+    /** Amount added to edge.weight on co-activation. Default: 0.1 */
+    hebbianStrength?: number;
+    /** Multiplicative factor applied to all weights per decay cycle. Default: 0.99 */
+    decayRate?: number;
+    /** Edges whose weight falls below this are pruned. Default: 0.05 */
+    pruneThreshold?: number;
+    /** Hard ceiling on edge.weight after strengthening. Default: 5.0 */
+    maxWeight?: number;
+}
+/**
+ * Minimal structural interface that ContextGraphManager satisfies.
+ * HebbianWeights only needs these methods — no import of the full class.
+ */
+export interface HebbianGraph {
+    getEdge(edgeId: string): Edge | undefined;
+    updateEdge(edgeId: string, updates: Partial<Edge>): Edge | undefined;
+    getAllEdges(): Edge[];
+    deleteEdge(edgeId: string): boolean;
+}
+/**
+ * HebbianWeights — Hebbian learning + temporal decay for graph edges.
+ *
+ * Models three neuronal behaviours:
+ *
+ * 1. **Strengthen** (`strengthen`): When two nodes are co-activated (both
+ *    appear in the same query result), every edge connecting them gains
+ *    `hebbianStrength` weight — "neurons that fire together, wire together."
+ *
+ * 2. **Decay** (`decay`): Every edge weight is multiplied by `decayRate`
+ *    each cycle. Edges not reinforced by co-activation gradually weaken.
+ *
+ * 3. **Prune** (`prune`): Edges whose weight drops below `pruneThreshold`
+ *    are deleted, keeping the graph clean and preventing stale connections
+ *    from accumulating indefinitely.
+ *
+ * @example
+ * ```ts
+ * const hebb = new HebbianWeights({ hebbianStrength: 0.1, decayRate: 0.99 });
+ * graph.setHebbianWeights(hebb);
+ *
+ * // queryNodesByLabel() auto-strengthens edges between co-activated nodes
+ * graph.queryNodesByLabel("TypeScript");
+ *
+ * // Run decay once per session cycle
+ * hebb.decay(graph);
+ *
+ * // Prune weak edges
+ * hebb.prune(graph);
+ * ```
+ */
+export declare class HebbianWeights {
+    private readonly hebbianStrength;
+    private readonly decayRate;
+    private readonly pruneThreshold;
+    private readonly maxWeight;
+    constructor(options?: HebbianOptions);
+    /** Read-only view of the resolved configuration. */
+    get config(): Required<HebbianOptions>;
+    /**
+     * Strengthen a single edge by `hebbianStrength`, capped at `maxWeight`.
+     *
+     * Intended to be called for every edge that connects two nodes that were
+     * co-activated (both appeared in the same query result).
+     *
+     * @returns The updated edge, or `undefined` if the edge was not found.
+     */
+    strengthen(edgeId: string, graph: HebbianGraph): Edge | undefined;
+    /**
+     * Strengthen all edges that connect pairs of nodes within `nodeIds`.
+     *
+     * This is the batch form used by `ContextGraphManager` after a query:
+     * every edge whose `sourceId` AND `targetId` both appear in the result
+     * set gets strengthened once.
+     *
+     * @returns The list of edge ids that were strengthened.
+     */
+    strengthenCoActivated(nodeIds: string[], graph: HebbianGraph): string[];
+    /**
+     * Apply temporal decay to every edge in the graph.
+     *
+     * Each edge weight is multiplied by `decayRate` (< 1.0).
+     * Edges reinforced by recent co-activation decay slower relative
+     * to their higher baseline weight.
+     *
+     * @returns The number of edges decayed.
+     */
+    decay(graph: HebbianGraph): number;
+    /**
+     * Delete all edges whose weight has fallen below `pruneThreshold`.
+     *
+     * Can be called after `decay()` to clean up stale connections.
+     *
+     * @param minWeight Override the instance's `pruneThreshold` for this call.
+     * @returns The number of edges deleted.
+     */
+    prune(graph: HebbianGraph, minWeight?: number): number;
+}
+//# sourceMappingURL=hebbian-weights.d.ts.map

package/dist/cjs/hebbian-weights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hebbian-weights.d.ts","sourceRoot":"","sources":["../../src/hebbian-weights.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAMlC,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAC1C,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACrE,WAAW,IAAI,IAAI,EAAE,CAAC;IACtB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,GAAE,cAAmB;IAOxC,oDAAoD;IACpD,IAAI,MAAM,IAAI,QAAQ,CAAC,cAAc,CAAC,CAOrC;IAMD;;;;;;;OAOG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS;IAUjE;;;;;;;;OAQG;IACH,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE;IAoBvE;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM;IAkBlC;;;;;;;OAOG;IACH,KAAK,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;CAgBvD"}