amalfa 1.0.28 → 1.0.30

package/README.md

@@ -388,3 +388,9 @@ Amalfa evolved from patterns discovered in the [PolyVis](https://github.com/pjsv
 ---
 
 **Built with ❤️ by developers frustrated with context loss.**
+
+---
+
+## Acknowledgments
+
+AMALFA leverages the powerful [Graphology](https://graphology.github.io/) library for in-memory graph analysis. Graphology is published on Zenodo with a DOI ([10.5281/zenodo.5681257](https://doi.org/10.5281/zenodo.5681257)).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.28",
+	"version": "1.0.30",
 	"description": "Local-first knowledge graph engine for AI agents. Transforms markdown into searchable memory with MCP protocol.",
 	"license": "MIT",
 	"homepage": "https://github.com/pjsvis/amalfa#readme",
@@ -62,8 +62,10 @@
 		"publish": "npm publish"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "1.25.0",
+		"@modelcontextprotocol/sdk": "1.25.2",
 		"fastembed": "2.0.0",
+		"graphology": "^0.26.0",
+		"graphology-library": "^0.8.0",
 		"pino": "^10.1.0"
 	}
 }

package/src/core/GraphEngine.ts

@@ -0,0 +1,252 @@
+import type { Database } from "bun:sqlite";
+import { MultiDirectedGraph } from "graphology";
+import { bidirectional as shortestPath } from "graphology-shortest-path/unweighted";
+import communitiesLouvain from "graphology-communities-louvain";
+import pagerank from "graphology-metrics/centrality/pagerank";
+import betweenness from "graphology-metrics/centrality/betweenness";
+import { connectedComponents } from "graphology-components";
+import { getLogger } from "@src/utils/Logger";
+
+const log = getLogger("GraphEngine");
+
+export interface GraphNode {
+	id: string;
+	type?: string;
+	title?: string;
+	domain?: string;
+	layer?: string;
+	date?: string;
+}
+
+export interface GraphEdge {
+	source: string;
+	target: string;
+	type?: string;
+}
+
+/**
+ * GraphEngine - In-memory graph management using Graphology.
+ * Provides fast traversal and analysis without database overhead.
+ *
+ * CITATION:
+ * Graphology is published on Zenodo with a DOI (10.5281/zenodo.5681257).
+ * Academic users are encouraged to cite it accordingly.
+ */
+export class GraphEngine {
+	private graph: MultiDirectedGraph;
+
+	constructor() {
+		this.graph = new MultiDirectedGraph({ allowSelfLoops: true });
+	}
+
+	/**
+	 * Load the graph from ResonanceDB (SQLite)
+	 * Uses "hollow nodes" - only structural metadata, no embeddings.
+	 */
+	async load(db: Database): Promise<void> {
+		log.info("Loading graph into memory...");
+		const start = Date.now();
+
+		this.graph.clear();
+
+		// 1. Load Nodes
+		const nodes = db
+			.query("SELECT id, type, title, domain, layer, date FROM nodes")
+			.all() as GraphNode[];
+		for (const node of nodes) {
+			this.graph.addNode(node.id, {
+				type: node.type,
+				title: node.title,
+				domain: node.domain,
+				layer: node.layer,
+				date: node.date,
+			});
+		}
+
+		// 2. Load Edges
+		const edges = db
+			.query("SELECT source, target, type FROM edges")
+			.all() as GraphEdge[];
+		for (const edge of edges) {
+			try {
+				if (
+					this.graph.hasNode(edge.source) &&
+					this.graph.hasNode(edge.target)
+				) {
+					this.graph.addEdge(edge.source, edge.target, {
+						type: edge.type,
+					});
+				}
+			} catch (err) {
+				log.debug(
+					{ source: edge.source, target: edge.target, error: err },
+					"Failed to add edge",
+				);
+			}
+		}
+
+		log.info(
+			{
+				nodes: this.graph.order,
+				edges: this.graph.size,
+				elapsedMs: Date.now() - start,
+			},
+			"Graph loaded successfully",
+		);
+	}
+
+	/**
+	 * Get neighbors of a node
+	 */
+	getNeighbors(nodeId: string): string[] {
+		if (!this.graph.hasNode(nodeId)) return [];
+		return this.graph.neighbors(nodeId);
+	}
+
+	/**
+	 * Get attributes of a specific node
+	 */
+	getNodeAttributes(nodeId: string): GraphNode | null {
+		if (!this.graph.hasNode(nodeId)) return null;
+		return this.graph.getNodeAttributes(nodeId) as GraphNode;
+	}
+
+	/**
+	 * Find shortest path between two nodes
+	 */
+	findShortestPath(sourceId: string, targetId: string): string[] | null {
+		if (!this.graph.hasNode(sourceId) || !this.graph.hasNode(targetId)) {
+			return null;
+		}
+		return shortestPath(this.graph, sourceId, targetId);
+	}
+
+	/**
+	 * Run Louvain community detection
+	 */
+	detectCommunities(): Record<string, number> {
+		return communitiesLouvain(this.graph);
+	}
+
+	/**
+	 * Get PageRank for all nodes
+	 */
+	getPagerank(): Record<string, number> {
+		return pagerank(this.graph);
+	}
+
+	/**
+	 * Get Betweenness Centrality for all nodes
+	 */
+	getBetweenness(): Record<string, number> {
+		return betweenness(this.graph);
+	}
+
+	/**
+	 * Get connected components
+	 */
+	getComponents(): string[][] {
+		return connectedComponents(this.graph);
+	}
+
+	/**
+	 * Get a summary of all metrics
+	 */
+	getMetrics() {
+		const pr = this.getPagerank();
+		const bc = this.getBetweenness();
+		const communities = this.detectCommunities();
+
+		return {
+			pagerank: pr,
+			betweenness: bc,
+			communities: communities,
+			components: this.getComponents().length,
+			stats: this.getStats(),
+		};
+	}
+
+	/**
+	 * Calculate Adamic-Adar index for two nodes.
+	 * Higher score = more likely to have a logical relationship based on specific shared neighbors.
+	 * AA(u, v) = Sum of (1 / log(degree(w))) for each shared neighbor w.
+	 */
+	getAdamicAdar(nodeA: string, nodeB: string): number {
+		if (!this.graph.hasNode(nodeA) || !this.graph.hasNode(nodeB)) return 0;
+		if (nodeA === nodeB) return 0;
+
+		const neighborsA = new Set(this.graph.neighbors(nodeA));
+		const neighborsB = this.graph.neighbors(nodeB);
+		let score = 0;
+
+		for (const neighbor of neighborsB) {
+			if (neighborsA.has(neighbor)) {
+				const degree = this.graph.degree(neighbor);
+				// degree > 1 because it's a shared neighbor (connected to at least A and B)
+				if (degree > 1) {
+					score += 1 / Math.log(degree);
+				}
+			}
+		}
+
+		return score;
+	}
+
+	/**
+	 * Find structural candidates for new edges using Adamic-Adar.
+	 * Identifies nodes that are not linked but share many specific neighbors.
+	 */
+	findStructuralCandidates(
+		limit = 10,
+	): { source: string; target: string; score: number }[] {
+		const candidates: { source: string; target: string; score: number }[] = [];
+		const nodes = this.graph.nodes();
+		const seen = new Set<string>();
+
+		for (const u of nodes) {
+			const neighborsU = new Set(this.graph.neighbors(u));
+			const twoHopPotential = new Set<string>();
+
+			// Find nodes v that share at least one neighbor w with u
+			for (const w of neighborsU) {
+				for (const v of this.graph.neighbors(w)) {
+					if (v !== u && !neighborsU.has(v)) {
+						twoHopPotential.add(v);
+					}
+				}
+			}
+
+			for (const v of twoHopPotential) {
+				const pairId = [u, v].sort().join("|");
+				if (seen.has(pairId)) continue;
+				seen.add(pairId);
+
+				const score = this.getAdamicAdar(u, v);
+				if (score > 0) {
+					candidates.push({ source: u, target: v, score });
+				}
+			}
+		}
+
+		return candidates.sort((a, b) => b.score - a.score).slice(0, limit);
+	}
+
+	/**
+	 * Get graph statistics
+	 */
+	getStats() {
+		return {
+			nodes: this.graph.order,
+			edges: this.graph.size,
+			density:
+				this.graph.size / (this.graph.order * (this.graph.order - 1) || 1),
+		};
+	}
+
+	/**
+	 * Export for external tools (e.g. visualization)
+	 */
+	getInternalGraph(): MultiDirectedGraph {
+		return this.graph;
+	}
+}

package/src/core/GraphGardener.ts

@@ -0,0 +1,244 @@
+import type { ResonanceDB } from "@src/resonance/db";
+import { getLogger } from "@src/utils/Logger";
+import type { GraphEngine } from "./GraphEngine";
+import type { VectorEngine } from "./VectorEngine";
+
+const log = getLogger("GraphGardener");
+
+export interface BridgeSuggestion {
+	sourceId: string;
+	targetId: string;
+	reason: string;
+	similarity: number;
+}
+
+export interface ClusterInsight {
+	clusterId: number;
+	nodes: string[];
+	suggestedTag?: string;
+}
+
+/**
+ * GraphGardener - Semantic Graph Optimization
+ * Exploits the duality of Vector Search (Semantic) and Graphology (Structural)
+ * to find missing links and optimize knowledge topology.
+ */
+export class GraphGardener {
+	constructor(
+		private db: ResonanceDB,
+		private graph: GraphEngine,
+		private vector: VectorEngine,
+	) {}
+
+	/**
+	 * findGaps: Finds nodes that are semantically similar but structurally distant.
+	 * These are "hidden relationships" that should probably be links or shared tags.
+	 */
+	async findGaps(
+		limit = 10,
+		similarityThreshold = 0.82,
+	): Promise<BridgeSuggestion[]> {
+		log.info("Analyzing graph for semantic gaps...");
+		const candidates = this.db
+			.getRawDb()
+			.query(
+				"SELECT id, embedding FROM nodes WHERE embedding IS NOT NULL LIMIT 100",
+			)
+			.all() as { id: string; embedding: Uint8Array }[];
+
+		const suggestions: BridgeSuggestion[] = [];
+
+		for (const node of candidates) {
+			if (!node.embedding) continue;
+
+			// Convert blob to Float32Array for search
+			const queryFloats = new Float32Array(
+				node.embedding.buffer,
+				node.embedding.byteOffset,
+				node.embedding.byteLength / 4,
+			);
+
+			// 1. Get Vector Neighbors using stored embedding (FAFCAS Dot Product)
+			const semanticNeighbors = await this.vector.searchByVector(
+				queryFloats,
+				5,
+			);
+
+			// 2. Get Graph Neighbors
+			const graphNeighbors = new Set(this.graph.getNeighbors(node.id));
+
+			for (const sn of semanticNeighbors) {
+				if (sn.id === node.id) continue;
+				if (sn.score < similarityThreshold) continue;
+
+				// 3. If semantically close but NOT a graph neighbor -> Potential GAP
+				if (!graphNeighbors.has(sn.id)) {
+					// Check if inverse already in suggestions
+					if (
+						!suggestions.find(
+							(s) =>
+								(s.sourceId === node.id && s.targetId === sn.id) ||
+								(s.sourceId === sn.id && s.targetId === node.id),
+						)
+					) {
+						suggestions.push({
+							sourceId: node.id,
+							targetId: sn.id,
+							reason: "Semantic proximity without structural link",
+							similarity: sn.score,
+						});
+					}
+				}
+			}
+		}
+
+		return suggestions
+			.sort((a, b) => b.similarity - a.similarity)
+			.slice(0, limit);
+	}
+
+	/**
+	 * findStructuralGaps: Finds nodes that share significant structural context (Adamic-Adar)
+	 * but are not directly linked. This is pure topological link prediction.
+	 */
+	findStructuralGaps(limit = 10): BridgeSuggestion[] {
+		log.info("Analyzing graph for structural gaps (Adamic-Adar)...");
+		const candidates = this.graph.findStructuralCandidates(limit);
+
+		return candidates.map((c) => ({
+			sourceId: c.source,
+			targetId: c.target,
+			reason: `Structural Adamic-Adar overlap (score: ${c.score.toFixed(2)})`,
+			similarity: c.score,
+		}));
+	}
+
+	/**
+	 * analyzeCommunities: Provides insights into detected clusters.
+	 */
+	analyzeCommunities(): ClusterInsight[] {
+		const communities = this.graph.detectCommunities();
+		const clusters: Map<number, string[]> = new Map();
+
+		for (const [nodeId, clusterId] of Object.entries(communities)) {
+			if (!clusters.has(clusterId)) clusters.set(clusterId, []);
+			clusters.get(clusterId)?.push(nodeId);
+		}
+
+		return Array.from(clusters.entries()).map(([clusterId, nodes]) => ({
+			clusterId,
+			nodes,
+		}));
+	}
+
+	/**
+	 * summarizeCluster: Logic resides in agent calling LLM,
+	 * but helper to get representative nodes is useful.
+	 */
+	getClusterRepresentatives(nodes: string[], top = 3): string[] {
+		// Get highest PageRank nodes within this set
+		const pr = this.graph.getPagerank();
+		return nodes.sort((a, b) => (pr[b] || 0) - (pr[a] || 0)).slice(0, top);
+	}
+
+	/**
+	 * findRelated: Search for nodes related to a query.
+	 */
+	async findRelated(query: string, limit = 5) {
+		return await this.vector.search(query, limit);
+	}
+
+	/**
+	 * weaveTimeline: Proposes FOLLOWS/PRECEDES edges based on date metadata.
+	 */
+	weaveTimeline(): BridgeSuggestion[] {
+		const nodes = this.db
+			.getRawDb()
+			.query("SELECT id, date FROM nodes WHERE date IS NOT NULL")
+			.all() as { id: string; date: string }[];
+
+		if (nodes.length < 2) return [];
+
+		// Sort by date
+		nodes.sort((a, b) => a.date.localeCompare(b.date));
+
+		const clusters = this.analyzeCommunities();
+		const nodeToCluster = new Map<string, number>();
+		for (const c of clusters) {
+			for (const nodeId of c.nodes) {
+				nodeToCluster.set(nodeId, c.clusterId);
+			}
+		}
+
+		const suggestions: BridgeSuggestion[] = [];
+		const lastInCluster = new Map<number, { id: string; date: string }>();
+
+		for (const node of nodes) {
+			const clusterId = nodeToCluster.get(node.id);
+			if (clusterId === undefined) continue;
+
+			const last = lastInCluster.get(clusterId);
+			if (last) {
+				suggestions.push({
+					sourceId: last.id,
+					targetId: node.id,
+					reason: `Temporal sequence (${last.date} -> ${node.date}) in community ${clusterId}`,
+					similarity: 1.0,
+				});
+			}
+
+			lastInCluster.set(clusterId, node);
+		}
+
+		return suggestions;
+	}
+
+	/**
+	 * identifyHubs: Finds nodes with high betweenness or pagerank that lack tags.
+	 */
+	/**
+	 * resolveSource: Returns the absolute file path for a node ID.
+	 */
+	resolveSource(nodeId: string): string | null {
+		const row = this.db
+			.getRawDb()
+			.query("SELECT meta FROM nodes WHERE id = ?")
+			.get(nodeId) as { meta: string } | null;
+		if (row?.meta) {
+			try {
+				const meta = JSON.parse(row.meta);
+				return meta.source || null;
+			} catch {
+				return null;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * getContent: Reads the raw markdown content for a node.
+	 */
+	async getContent(nodeId: string): Promise<string | null> {
+		const sourcePath = this.resolveSource(nodeId);
+		if (!sourcePath) return null;
+		try {
+			return await Bun.file(sourcePath).text();
+		} catch {
+			return null;
+		}
+	}
+
+	identifyHubs(top = 5) {
+		const pr = this.graph.getPagerank();
+		const bc = this.graph.getBetweenness();
+
+		const nodes = Object.keys(pr).map((id) => ({
+			id,
+			pagerank: pr[id],
+			betweenness: bc[id],
+			score: (pr[id] || 0) + (bc[id] || 0),
+		}));
+
+		return nodes.sort((a, b) => b.score - a.score).slice(0, top);
+	}
+}

package/src/core/VectorEngine.ts

@@ -7,6 +7,7 @@ export interface SearchResult {
 	score: number;
 	content: string;
 	title?: string;
+	date?: string;
 }
 
 /**
@@ -191,7 +192,7 @@ export class VectorEngine {
 		// Note: Hollow Nodes have content=NULL, use meta.source to read from filesystem if needed
 		const results: SearchResult[] = [];
 		const contentStmt = this.db.prepare(
-			"SELECT title, content, meta FROM nodes WHERE id = ?",
+			"SELECT title, content, meta, date FROM nodes WHERE id = ?",
 		);
 
 		for (const item of topK) {
@@ -199,6 +200,7 @@ export class VectorEngine {
 				title: string;
 				content: string | null;
 				meta: string | null;
+				date: string | null;
 			};
 			if (row) {
 				// For hollow nodes, extract a preview from title or meta
@@ -217,6 +219,7 @@ export class VectorEngine {
 					score: item.score,
 					title: row.title,
 					content: content,
+					date: row.date || undefined,
 				});
 			}
 		}