amalfa 1.0.40 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to AMALFA will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-01-13
+
+### Added
+- **Scratchpad Protocol (Phase 7)**: Intercepts large MCP tool outputs (>4KB) and caches them to `.amalfa/cache/scratchpad/`, returning a reference with preview instead of full content. Reduces context window usage for verbose responses.
+  - New `scratchpad_read` and `scratchpad_list` MCP tools for retrieving cached content.
+  - Content-addressable storage with SHA256 deduplication.
+  - Configurable threshold, max age (24h), and cache size limit (50MB).
+
+## [1.1.0] - 2026-01-13
+
+### Added
+- **Graphology Workflows (Phase 6)**:
+  - Added Adamic-Adar ("Friend-of-a-Friend") link prediction strategy.
+  - Added PageRank ("Pillar Content") identification strategy.
+  - Added Louvain ("Global Context") community detection strategy.
+  - Added `amalfa enhance --strategy=<strategy>` CLI command to expose these analyses.
+- **Autonomous Research (Phase 5)**:
+  - **LouvainGate**: Configurable thresholds for super-node detection.
+  - **Pipeline History**: Added `history` table to track graph mutations.
+  - **CLI Promotion**: `amalfa stats --orphans` and `amalfa validate --graph` for advanced diagnostics.
+  - **Graph Features**: Exposed `GraphEngine.traverse()` (BFS) and `validateIntegrity()`.
+
+### Changed
+- **CLI Architecture**: Refactored monolithic `src/cli.ts` into modular command files (`src/cli/commands/*.ts`) for maintainability.
+- **Cleanup**: Deprecated legacy `tag-slug` syntax in EdgeWeaver.
+
 ## [1.0.40] - 2026-01-09
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.40",
+	"version": "1.2.0",
 	"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",
@@ -44,7 +44,7 @@
 		"bun": ">=1.0.0"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.3.8",
+		"@biomejs/biome": "^2.3.11",
 		"@types/bun": "1.3.4",
 		"only-allow": "1.2.2",
 		"pino-pretty": "13.1.3",

package/src/cli/commands/doctor.ts

@@ -0,0 +1,83 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "@src/config/defaults";
+import { getDbPath } from "../utils";
+
+export async function cmdDoctor(_args: string[]) {
+	console.log("🩺 AMALFA Health Check\n");
+
+	let issues = 0;
+
+	// Check Bun runtime
+	console.log("✓ Bun runtime: OK");
+
+	// Check config and database
+	const dbPath = await getDbPath();
+	if (existsSync(dbPath)) {
+		const fileSizeMB = (statSync(dbPath).size / 1024 / 1024).toFixed(2);
+		console.log(`✓ Database found: ${dbPath} (${fileSizeMB} MB)`);
+	} else {
+		console.log(`✗ Database not found: ${dbPath}`);
+		console.log(`  Run: amalfa init`);
+		issues++;
+	}
+
+	// Check .amalfa directory
+	const amalfaDir = join(process.cwd(), ".amalfa");
+	if (existsSync(amalfaDir)) {
+		console.log(`✓ AMALFA directory: ${amalfaDir}`);
+	} else {
+		console.log(`✗ AMALFA directory not found: ${amalfaDir}`);
+		issues++;
+	}
+
+	// Check source directories from config
+	const config = await loadConfig();
+	const sources = config.sources || ["./docs"];
+	let sourcesFound = 0;
+	for (const source of sources) {
+		const sourcePath = join(process.cwd(), source);
+		if (existsSync(sourcePath)) {
+			console.log(`✓ Source directory: ${sourcePath}`);
+			sourcesFound++;
+		} else {
+			console.log(`✗ Source directory not found: ${sourcePath}`);
+			issues++;
+		}
+	}
+	if (sourcesFound === 0) {
+		console.log(`  Configure sources in amalfa.config.json`);
+	}
+
+	// Check dependencies (FastEmbed)
+	try {
+		await import("fastembed");
+		console.log("✓ FastEmbed: OK");
+	} catch {
+		console.log("✗ FastEmbed not found (run: bun install)");
+		issues++;
+	}
+
+	// Check MCP SDK
+	try {
+		await import("@modelcontextprotocol/sdk/server/index.js");
+		console.log("✓ MCP SDK: OK");
+	} catch {
+		console.log("✗ MCP SDK not found (run: bun install)");
+		issues++;
+	}
+
+	console.log("");
+
+	if (issues === 0) {
+		console.log("✅ All checks passed! AMALFA is ready to use.");
+		console.log("\nNext steps:");
+		console.log("  amalfa serve    # Start MCP server");
+		console.log("  amalfa stats    # View database statistics");
+	} else {
+		console.log(
+			`❌ Found ${issues} issue(s). Please resolve them and try again.`,
+		);
+		process.exit(1);
+	}
+}

package/src/cli/commands/enhance.ts

@@ -0,0 +1,100 @@
+import { existsSync } from "node:fs";
+import { GraphEngine } from "@src/core/GraphEngine";
+import { ResonanceDB } from "@src/resonance/db";
+import { getDbPath } from "../utils";
+
+export async function cmdEnhance(args: string[]) {
+	// Parse args
+	const strategyArg = args.find((a) => a.startsWith("--strategy="));
+	const strategy = strategyArg ? strategyArg.split("=")[1] : "help";
+	const limitArg = args.find((a) => a.startsWith("--limit="));
+	const limitStr = limitArg ? limitArg.split("=")[1] : "10";
+	const limit = limitStr ? Number.parseInt(limitStr, 10) : 10;
+
+	if (strategy === "help" || !strategy) {
+		console.log(`
+Enhance your knowledge graph with structural analysis strategies.
+
+Usage:
+  amalfa enhance --strategy=[strategy] [--limit=N]
+
+Strategies:
+  adamic-adar   Find "Friend-of-a-Friend" connections (missing links)
+  pagerank      Identify "Pillar Content" (high authority nodes)
+  communities   List "Global Context" clusters (Louvain communities)
+
+Examples:
+  amalfa enhance --strategy=adamic-adar --limit=5
+  amalfa enhance --strategy=pagerank
+`);
+		return;
+	}
+
+	// Load DB
+	const dbPath = await getDbPath();
+	if (!existsSync(dbPath)) {
+		console.error("❌ Database not found. Run 'amalfa init' first.");
+		process.exit(1);
+	}
+
+	const db = new ResonanceDB(dbPath);
+	const graph = new GraphEngine();
+
+	try {
+		await graph.load(db.getRawDb());
+
+		if (strategy === "adamic-adar") {
+			console.log(`🔍 Finding structural gaps (Adamic-Adar)...`);
+			const candidates = graph.findStructuralCandidates(limit);
+
+			if (candidates.length === 0) {
+				console.log("✅ No significant structural gaps found.");
+			} else {
+				console.log("\nProposed Edges (based on shared neighbors):");
+				console.log("Score | Source <-> Target");
+				console.log("-".repeat(40));
+				for (const c of candidates) {
+					console.log(`${c.score.toFixed(2)}  | ${c.source} <-> ${c.target}`);
+				}
+			}
+		} else if (strategy === "pagerank") {
+			console.log(`🏛️  Identifying Pillar Content (PageRank)...`);
+			const pillars = graph.findPillars(limit);
+
+			console.log("\nTop Authority Nodes:");
+			console.log("Score  | Degree | ID");
+			console.log("-".repeat(40));
+			for (const p of pillars) {
+				console.log(
+					`${p.score.toFixed(4)} | ${p.degree.toString().padEnd(6)} | ${p.id}`,
+				);
+			}
+		} else if (strategy === "communities") {
+			console.log(`🌍 Identifying Global Context (Louvain)...`);
+			const communities = graph.getCommunities();
+			const clusterIds = Object.keys(communities)
+				.sort(
+					(a, b) =>
+						(communities[b]?.length || 0) - (communities[a]?.length || 0),
+				)
+				.slice(0, limit);
+
+			console.log("\nTop Communities:");
+			for (const id of clusterIds) {
+				const members = communities[id] || [];
+				console.log(`\nCluster ${id} (${members.length} nodes):`);
+				console.log(
+					members.slice(0, 5).join(", ") + (members.length > 5 ? "..." : ""),
+				);
+			}
+		} else {
+			console.error(`❌ Unknown strategy: ${strategy}`);
+			process.exit(1);
+		}
+	} catch (error) {
+		console.error("❌ Enhancement failed:", error);
+		process.exit(1);
+	} finally {
+		db.close();
+	}
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,130 @@
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "@src/config/defaults";
+import { AmalfaIngestor } from "@src/pipeline/AmalfaIngestor";
+import { PreFlightAnalyzer } from "@src/pipeline/PreFlightAnalyzer";
+import { ResonanceDB } from "@src/resonance/db";
+import { StatsTracker } from "@src/utils/StatsTracker";
+import pkg from "../../../package.json" with { type: "json" };
+
+const VERSION = pkg.version;
+
+export async function cmdInit(args: string[]) {
+	console.log("🚀 AMALFA Initialization\n");
+
+	// Check for --force flag
+	const forceMode = args.includes("--force");
+
+	// Load configuration
+	const config = await loadConfig();
+
+	const sources = config.sources || ["./docs"];
+	console.log(`📁 Sources: ${sources.join(", ")}`);
+	console.log(`💾 Database: ${config.database}`);
+	console.log(`🧠 Model: ${config.embeddings.model}\n`);
+
+	// Run pre-flight analysis
+	console.log("🔍 Running pre-flight analysis...\n");
+	const analyzer = new PreFlightAnalyzer(config);
+	const report = await analyzer.analyze();
+
+	// Display summary
+	console.log("📊 Pre-Flight Summary:");
+	console.log(`  Total files: ${report.totalFiles}`);
+	console.log(`  Valid files: ${report.validFiles}`);
+	console.log(`  Skipped files: ${report.skippedFiles}`);
+	console.log(
+		`  Total size: ${(report.totalSizeBytes / 1024 / 1024).toFixed(2)} MB`,
+	);
+	console.log(`  Estimated nodes: ${report.estimatedNodes}\n`);
+
+	if (report.hasErrors) {
+		console.error("❌ Pre-flight check failed with errors\n");
+		console.error("Errors detected:");
+		for (const issue of report.issues.filter((i) => i.severity === "error")) {
+			console.error(`  - ${issue.path}: ${issue.details}`);
+		}
+		console.error(
+			"\nSee .amalfa/logs/pre-flight.log for details and recommendations",
+		);
+		console.error("\nFix these issues and try again.");
+		process.exit(1);
+	}
+
+	if (report.hasWarnings && !forceMode) {
+		console.warn("⚠️  Pre-flight check completed with warnings\n");
+		console.warn("Warnings detected:");
+		for (const issue of report.issues.filter((i) => i.severity === "warning")) {
+			console.warn(`  - ${issue.path}: ${issue.details}`);
+		}
+		console.warn("\nSee .amalfa/logs/pre-flight.log for recommendations");
+		console.warn("\nTo proceed anyway, use: amalfa init --force");
+		process.exit(1);
+	}
+
+	if (report.validFiles === 0) {
+		console.error("\n❌ No valid markdown files found");
+		console.error("See .amalfa/logs/pre-flight.log for details");
+		process.exit(1);
+	}
+
+	if (forceMode && report.hasWarnings) {
+		console.warn("⚠️  Proceeding with --force despite warnings\n");
+	}
+
+	// Create .amalfa directory
+	const amalfaDir = join(process.cwd(), ".amalfa");
+	if (!existsSync(amalfaDir)) {
+		console.log(`📂 Creating directory: ${amalfaDir}`);
+		mkdirSync(amalfaDir, { recursive: true });
+	}
+
+	// Initialize database
+	const dbPath = join(process.cwd(), config.database);
+	console.log(`🗄️  Initializing database: ${dbPath}\n`);
+
+	try {
+		// Create/open database
+		const db = new ResonanceDB(dbPath);
+
+		// Run ingestion
+		const ingestor = new AmalfaIngestor(config, db);
+		const result = await ingestor.ingest();
+
+		db.close();
+
+		if (result.success) {
+			// Record database snapshot for tracking
+			const tracker = new StatsTracker();
+			const fileSize = statSync(dbPath).size;
+			const dbSizeMB = fileSize / 1024 / 1024;
+
+			await tracker.recordSnapshot({
+				timestamp: new Date().toISOString(),
+				nodes: result.stats.nodes,
+				edges: result.stats.edges,
+				embeddings: result.stats.vectors,
+				dbSizeMB,
+				version: VERSION,
+			});
+
+			console.log("\n✅ Initialization complete!");
+			console.log("\n📊 Summary:");
+			console.log(`  Files processed: ${result.stats.files}`);
+			console.log(`  Nodes created: ${result.stats.nodes}`);
+			console.log(`  Edges created: ${result.stats.edges}`);
+			console.log(`  Embeddings: ${result.stats.vectors}`);
+			console.log(`  Duration: ${result.stats.durationSec.toFixed(2)}s\n`);
+			console.log("📊 Snapshot saved to: .amalfa/stats-history.json\n");
+			console.log("Next steps:");
+			console.log("  amalfa serve     # Start MCP server");
+			console.log("  amalfa daemon    # Watch for file changes (coming soon)");
+		} else {
+			console.error("\n❌ Initialization failed");
+			process.exit(1);
+		}
+	} catch (error) {
+		console.error("\n❌ Initialization failed:", error);
+		process.exit(1);
+	}
+}

package/src/cli/commands/server.ts

@@ -0,0 +1,290 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { AMALFA_DIRS } from "@src/config/defaults";
+import { checkDatabase, getDbPath } from "../utils";
+
+export async function cmdServe(_args: string[]) {
+	// Check database exists
+	if (!(await checkDatabase())) {
+		process.exit(1);
+	}
+
+	const dbPath = await getDbPath();
+	console.error("🚀 Starting AMALFA MCP Server...");
+	console.error(`📊 Database: ${dbPath}`);
+	console.error("");
+
+	const serverPath = join(process.cwd(), "src/mcp/index.ts");
+	const proc = spawn("bun", ["run", serverPath, "serve"], {
+		stdio: "inherit",
+		cwd: process.cwd(),
+	});
+
+	proc.on("exit", (code) => {
+		process.exit(code ?? 0);
+	});
+}
+
+export async function cmdServers(args: string[]) {
+	const action = args[1];
+	// If action is provided and isn't a flag (like --dot), treat it as a lifecycle command
+	if (
+		action &&
+		!action.startsWith("-") &&
+		["start", "stop", "restart", "status"].includes(action)
+	) {
+		if (action === "status") {
+			// Just fall through to normal status display
+		} else {
+			await manageAllServers(action as "start" | "stop" | "restart");
+			return;
+		}
+	}
+
+	const showDot = args.includes("--dot");
+
+	const SERVICES = [
+		{
+			name: "MCP Server",
+			pidFile: join(AMALFA_DIRS.runtime, "mcp.pid"),
+			port: "stdio",
+			id: "mcp",
+			cmd: "amalfa serve",
+		},
+		{
+			name: "Vector Daemon",
+			pidFile: join(AMALFA_DIRS.runtime, "vector-daemon.pid"),
+			port: "3010",
+			id: "vector",
+			cmd: "amalfa vector start",
+		},
+		{
+			name: "File Watcher",
+			pidFile: join(AMALFA_DIRS.runtime, "daemon.pid"),
+			port: "-",
+			id: "watcher",
+			cmd: "amalfa daemon start",
+		},
+		{
+			name: "Sonar Agent",
+			pidFile: join(AMALFA_DIRS.runtime, "sonar.pid"),
+			port: "3012",
+			id: "sonar",
+			cmd: "amalfa sonar start",
+		},
+	];
+
+	async function isRunning(pid: number): Promise<boolean> {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	if (showDot) {
+		// Generate DOT diagram
+		const statuses = new Map<string, { status: string; pid: string }>();
+
+		for (const svc of SERVICES) {
+			let status = "stopped";
+			let pidStr = "-";
+
+			if (existsSync(svc.pidFile)) {
+				try {
+					const text = readFileSync(svc.pidFile, "utf-8");
+					const pid = Number.parseInt(text.trim(), 10);
+
+					if (!Number.isNaN(pid) && (await isRunning(pid))) {
+						status = "running";
+						pidStr = pid.toString();
+					} else {
+						status = "stale";
+						pidStr = `${pid}`;
+					}
+				} catch {
+					// Ignore
+				}
+			}
+
+			statuses.set(svc.id, { status, pid: pidStr });
+		}
+
+		console.log("digraph AMALFA {");
+		console.log("  rankdir=LR;");
+		console.log("  node [shape=box, style=filled];");
+		console.log("");
+		console.log("  // Nodes");
+
+		for (const svc of SERVICES) {
+			const st = statuses.get(svc.id);
+			const color =
+				st?.status === "running"
+					? "lightgreen"
+					: st?.status === "stale"
+						? "orange"
+						: "lightgray";
+			const label = `${svc.name}\\nPort: ${svc.port}\\nPID: ${st?.pid || "-"}`;
+			console.log(`  ${svc.id} [label="${label}", fillcolor=${color}];`);
+		}
+
+		console.log("");
+		console.log("  // Database");
+		console.log(
+			'  db [label="SQLite\\n.amalfa/resonance.db", shape=cylinder, fillcolor=lightyellow];',
+		);
+		console.log("");
+		console.log("  // Connections");
+		console.log('  mcp -> db [label="read/write"];');
+		console.log('  vector -> db [label="embeddings"];');
+		console.log('  watcher -> db [label="updates"];');
+		console.log('  mcp -> vector [label="query", style=dashed];');
+		console.log("}");
+		console.log("");
+		console.log("# Save to file: amalfa servers --dot > amalfa.dot");
+		console.log("# Render: dot -Tpng amalfa.dot -o amalfa.png");
+		return;
+	}
+
+	console.log("\n📡 AMALFA Service Status\n");
+	console.log("─".repeat(95));
+	console.log(
+		"SERVICE".padEnd(18) +
+			"COMMAND".padEnd(25) +
+			"PORT".padEnd(12) +
+			"STATUS".padEnd(15) +
+			"PID".padEnd(10),
+	);
+	console.log("─".repeat(95));
+
+	for (const svc of SERVICES) {
+		let status = "⚪️ STOPPED";
+		let pidStr = "-";
+
+		if (existsSync(svc.pidFile)) {
+			try {
+				const text = readFileSync(svc.pidFile, "utf-8");
+				const pid = Number.parseInt(text.trim(), 10);
+
+				if (!Number.isNaN(pid) && (await isRunning(pid))) {
+					status = "🟢 RUNNING";
+					pidStr = pid.toString();
+				} else {
+					status = "🔴 STALE";
+					pidStr = `${pid} (?)`;
+				}
+			} catch {
+				// Ignore read errors
+			}
+		}
+
+		console.log(
+			svc.name.padEnd(18) +
+				svc.cmd.padEnd(25) +
+				svc.port.padEnd(12) +
+				status.padEnd(15) +
+				pidStr.padEnd(10),
+		);
+	}
+
+	console.log("─".repeat(95));
+	console.log(
+		"\n💡 Commands: amalfa servers [start|stop|restart] | amalfa vector start | amalfa daemon start\n",
+	);
+}
+
+// Background services to manage via 'amalfa servers start/restart'
+const BACKGROUND_SERVICES = [
+	{
+		name: "Vector Daemon",
+		cmd: "amalfa",
+		args: ["vector", "start"],
+	},
+	{
+		name: "File Watcher",
+		cmd: "amalfa",
+		args: ["daemon", "start"],
+	},
+	{
+		name: "Sonar Agent",
+		cmd: "amalfa",
+		args: ["sonar", "start"],
+	},
+];
+
+async function manageAllServers(action: "start" | "stop" | "restart") {
+	if (action === "stop" || action === "restart") {
+		await cmdStopAll([]);
+	}
+
+	if (action === "start" || action === "restart") {
+		console.log("🚀 Starting background services...\n");
+
+		for (const svc of BACKGROUND_SERVICES) {
+			console.log(`▶️  Starting ${svc.name}...`);
+			const child = spawn(svc.cmd, svc.args, {
+				detached: true,
+				stdio: "ignore", // Daemons manage their own logs
+				cwd: process.cwd(),
+			});
+			child.unref();
+			// Brief pause to allow pid file creation / logging
+			await new Promise((resolve) => setTimeout(resolve, 500));
+		}
+		console.log("\n✅ All background services triggered.");
+		console.log("Run 'amalfa servers' to check status.");
+	}
+}
+
+export async function cmdStopAll(_args: string[]) {
+	console.log("🛑 Stopping ALL Amalfa Services...\n");
+
+	const SERVICES = [
+		{
+			name: "Vector Daemon",
+			pidFile: join(AMALFA_DIRS.runtime, "vector-daemon.pid"),
+		},
+		{ name: "File Watcher", pidFile: join(AMALFA_DIRS.runtime, "daemon.pid") },
+		{ name: "Sonar Agent", pidFile: join(AMALFA_DIRS.runtime, "sonar.pid") },
+		// MCP usually runs as stdio, but if we track a PID file for it:
+		{ name: "MCP Server", pidFile: join(AMALFA_DIRS.runtime, "mcp.pid") },
+	];
+
+	let stoppedCount = 0;
+
+	for (const svc of SERVICES) {
+		if (existsSync(svc.pidFile)) {
+			try {
+				const pidStr = readFileSync(svc.pidFile, "utf-8").trim();
+				const pid = Number.parseInt(pidStr, 10);
+
+				if (!Number.isNaN(pid)) {
+					// Check if running
+					try {
+						process.kill(pid, 0); // Check existence
+						process.kill(pid, "SIGTERM");
+						console.log(`✅ Sent SIGTERM to ${svc.name} (PID: ${pid})`);
+						stoppedCount++;
+					} catch {
+						// Not running, just stale
+						console.log(`🧹 Cleaning stale PID file for ${svc.name}`);
+					}
+				}
+			} catch (e) {
+				console.warn(`⚠️ Failed to stop ${svc.name}:`, e);
+			}
+			// Always clean up PID file
+			try {
+				unlinkSync(svc.pidFile);
+			} catch {}
+		}
+	}
+
+	if (stoppedCount === 0) {
+		console.log("✨ No active services found.");
+	} else {
+		console.log(`\n✅ Stopped ${stoppedCount} service(s).`);
+	}
+}