amalfa 1.0.1 → 1.0.2

package/docs/_current-config-status.md

@@ -0,0 +1,93 @@
+# Current Configuration Status
+
+**Last Updated:** 2026-01-06
+
+## Configuration Files (Single Source of Truth)
+
+### 1. AMALFA Core Configuration
+**File:** `amalfa.config.json` (root)
+**Purpose:** Main AMALFA system settings
+**Loaded by:** `src/config/defaults.ts`
+
+```json
+{
+  "sources": ["../polyvis/docs", "../polyvis/playbooks"],
+  "database": ".amalfa/multi-source-test.db",
+  "embeddings": {
+    "model": "BAAI/bge-small-en-v1.5",
+    "dimensions": 384
+  },
+  "watch": {
+    "enabled": true,
+    "debounce": 1000
+  },
+  "excludePatterns": ["node_modules", ".git", ".amalfa"]
+}
+```
+
+**Status:** ✅ Active, primary config for AMALFA operations
+
+### 2. Resonance Configuration (Legacy)
+**File:** `polyvis.settings.json` (root)
+**Purpose:** Resonance database and pipeline settings
+**Loaded by:** `src/resonance/config.ts`
+
+```json
+{
+  "paths": {
+    "database": { "resonance": "public/resonance.db" },
+    "docs": { ... },
+    "sources": {
+      "experience": [...],
+      "persona": { ... }
+    }
+  },
+  "graph": { "tuning": { ... } },
+  "schema": { "version": "1.0.0" }
+}
+```
+
+**Status:** 🔄 Legacy, used by resonance pipeline only
+
+### 3. Beads Issue Tracking
+**File:** `.beads/config.yaml`
+**Purpose:** Beads issue tracking system configuration
+**Loaded by:** Beads CLI (`bd` commands)
+
+**Status:** ✅ Active, separate system
+
+## Configuration Strategy
+
+### Current Approach (2026-01-06)
+- **AMALFA** and **Resonance** have separate configs
+- This is **intentional** - they serve different purposes:
+  - AMALFA: User-facing MCP server and CLI
+  - Resonance: Internal database/pipeline layer
+
+### Future Unification (v1.0+)
+- Consider consolidating if Resonance becomes AMALFA-exclusive
+- Keep separate if Resonance remains standalone library
+
+## Configuration Hierarchy
+
+```
+Project Root
+├── amalfa.config.json        ← AMALFA core (MCP, CLI, daemon)
+├── polyvis.settings.json     ← Resonance (database, pipeline)
+└── .beads/
+    └── config.yaml           ← Beads (issue tracking)
+```
+
+## Action Items
+
+- [x] Decide: Keep separate, deprecate polyvis.settings.json gradually (See CONFIG_UNIFICATION.md)
+- [x] Document: Which config controls what (See CONFIG_UNIFICATION.md)
+- [ ] Add deprecation warning when polyvis.settings.json is loaded
+- [ ] Migrate graph tuning to amalfa.config.json (optional)
+- [ ] Remove polyvis.settings.json in v2.0
+
+## Notes
+
+- No `_current-*` files existed prior to 2026-01-06
+- Configuration is stable but not unified
+- Each system has clear ownership of its config file

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"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",
@@ -10,7 +10,7 @@
 	"author": "Peter John Smith <729613+pjsvis@users.noreply.github.com>",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/pjsvis/amalfa"
+		"url": "git+https://github.com/pjsvis/amalfa.git"
 	},
 	"keywords": [
 		"mcp",
@@ -29,7 +29,7 @@
 		"pkm"
 	],
 	"bin": {
-		"amalfa": "./src/cli.ts"
+		"amalfa": "src/cli.ts"
 	},
 	"engines": {
 		"bun": "1.3.x",
@@ -48,6 +48,9 @@
 		"start": "bun run src/mcp/index.ts start",
 		"stop": "bun run src/mcp/index.ts stop",
 		"status": "bun run src/mcp/index.ts status",
+		"servers": "bun run scripts/cli/servers.ts",
+		"validate-config": "bun run scripts/validate-config.ts",
+		"release": "bun run scripts/release.ts",
 		"check": "biome check .",
 		"format": "biome format --write ."
 	},

package/polyvis.settings.json.bak

@@ -0,0 +1,38 @@
+{
+	"_comment": "⚠️  DEPRECATED: This file will be removed in v2.0. Use amalfa.config.json for user-facing settings. See docs/CONFIG_UNIFICATION.md",
+	"paths": {
+		"database": {
+			"resonance": "public/resonance.db"
+		},
+		"docs": {
+			"root": "docs",
+			"webdocs": "docs/webdocs",
+			"architecture": "docs/architecture",
+			"public": "public/docs"
+		},
+		"sources": {
+			"experience": [
+				{ "path": "debriefs", "name": "Debrief" },
+				{ "path": "playbooks", "name": "Playbook" },
+				{ "path": "briefs", "name": "Brief" },
+				{ "path": "docs", "name": "Docs" }
+			],
+			"persona": {
+				"lexicon": "scripts/fixtures/conceptual-lexicon-ref-v1.79.json",
+				"cda": "scripts/fixtures/cda-ref-v63.json"
+			}
+		}
+	},
+	"graph": {
+		"tuning": {
+			"louvain": {
+				"persona": 0.3,
+				"experience": 0.25
+			}
+		}
+	},
+
+	"schema": {
+		"version": "1.0.0"
+	}
+}

package/src/cli.ts

@@ -3,8 +3,10 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 
-const VERSION = "1.0.1";
-const DB_PATH = join(process.cwd(), ".amalfa/resonance.db");
+const VERSION = "1.0.2";
+
+// Database path loaded from config (lazy loaded per command)
+let DB_PATH: string | null = null;
 
 // Parse command line arguments
 const args = process.argv.slice(2);
@@ -22,6 +24,7 @@ Commands:
   serve              Start MCP server (stdio transport)
   stats              Show database statistics
   doctor             Check installation and configuration
+  setup-mcp          Generate MCP configuration JSON
   daemon <action>    Manage file watcher (start|stop|status|restart)
 
 Options:
@@ -44,10 +47,21 @@ function showVersion() {
 	console.log(`amalfa v${VERSION}`);
 }
 
+async function getDbPath(): Promise<string> {
+	if (DB_PATH) return DB_PATH;
+	
+	// Load from config
+	const { loadConfig } = await import("./config/defaults");
+	const config = await loadConfig();
+	DB_PATH = join(process.cwd(), config.database);
+	return DB_PATH;
+}
+
 async function checkDatabase(): Promise<boolean> {
-	if (!existsSync(DB_PATH)) {
+	const dbPath = await getDbPath();
+	if (!existsSync(dbPath)) {
 		console.error(`
-❌ Database not found at: ${DB_PATH}
+❌ Database not found at: ${dbPath}
 
 To initialize AMALFA:
 1. Create markdown files in ./docs/ (or your preferred location)
@@ -66,8 +80,9 @@ async function cmdServe() {
 		process.exit(1);
 	}
 
+	const dbPath = await getDbPath();
 	console.error("🚀 Starting AMALFA MCP Server...");
-	console.error(`📊 Database: ${DB_PATH}`);
+	console.error(`📊 Database: ${dbPath}`);
 	console.error("");
 
 	// Run MCP server (it handles stdio transport)
@@ -89,18 +104,19 @@ async function cmdStats() {
 	}
 
 	// Import database wrapper
+	const dbPath = await getDbPath();
 	const { ResonanceDB } = await import("./resonance/db");
-	const db = new ResonanceDB(DB_PATH);
+	const db = new ResonanceDB(dbPath);
 
 	try {
 		const stats = db.getStats();
-		const fileSize = statSync(DB_PATH).size;
+		const fileSize = statSync(dbPath).size;
 		const fileSizeMB = (fileSize / 1024 / 1024).toFixed(2);
 
-		console.log(`
+	console.log(`
 📊 AMALFA Database Statistics
 
-Database: ${DB_PATH}
+Database: ${dbPath}
 Size: ${fileSizeMB} MB
 
 Nodes: ${stats.nodes.toLocaleString()}
@@ -108,7 +124,7 @@ Edges: ${stats.edges.toLocaleString()}
 Embeddings: ${stats.vectors.toLocaleString()} (384-dim)
 
 Source: ./docs (markdown files)
-Last modified: ${new Date(statSync(DB_PATH).mtime).toISOString()}
+Last modified: ${new Date(statSync(dbPath).mtime).toISOString()}
 
 🔍 To search: Use with Claude Desktop or other MCP client
 📝 To update: Run 'amalfa daemon start' (coming soon)
@@ -250,6 +266,55 @@ async function cmdDaemon() {
 	});
 }
 
+async function cmdSetupMcp() {
+	const { resolve } = await import("node:path");
+	
+	const cwd = resolve(process.cwd());
+	const mcpScript = resolve(cwd, "src/mcp/index.ts");
+	
+	// Minimal PATH for MCP - only include essential directories
+	const bunPath = process.execPath.replace(/\/bun$/, ''); // Directory containing bun
+	const minimalPath = [
+		bunPath,
+		'/usr/local/bin',
+		'/usr/bin',
+		'/bin',
+		'/usr/sbin',
+		'/sbin',
+		'/opt/homebrew/bin',  // Apple Silicon Homebrew
+	].join(':');
+	
+	const config = {
+		mcpServers: {
+			amalfa: {
+				command: "bun",
+				args: ["run", mcpScript],
+				env: {
+					PATH: minimalPath,
+				},
+			},
+		},
+	};
+	
+	console.log("\n✅ AMALFA MCP Configuration");
+	console.log("=".repeat(60));
+	console.log(`📂 Installation: ${cwd}`);
+	console.log("=".repeat(60));
+	console.log("\n📋 Copy this JSON to your MCP client config:");
+	console.log("   Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json");
+	console.log("   Warp Preview: MCP settings\n");
+	console.log("=".repeat(60));
+	console.log();
+	
+	console.log(JSON.stringify(config, null, 2));
+	
+	console.log();
+	console.log("=".repeat(60));
+	console.log("💡 Tip: If you move this folder, run 'amalfa setup-mcp' again");
+	console.log("=".repeat(60));
+	console.log();
+}
+
 async function cmdDoctor() {
 	console.log("🩺 AMALFA Health Check\n");
 
@@ -258,12 +323,14 @@ async function cmdDoctor() {
 	// Check Bun runtime
 	console.log("✓ Bun runtime: OK");
 
-	// Check database
-	if (existsSync(DB_PATH)) {
-		const fileSizeMB = (statSync(DB_PATH).size / 1024 / 1024).toFixed(2);
-		console.log(`✓ Database found: ${DB_PATH} (${fileSizeMB} MB)`);
+	// 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: ${DB_PATH}`);
+		console.log(`✗ Database not found: ${dbPath}`);
+		console.log(`  Run: amalfa init`);
 		issues++;
 	}
 
@@ -276,12 +343,23 @@ async function cmdDoctor() {
 		issues++;
 	}
 
-	// Check source directories
-	const docsDir = join(process.cwd(), "docs");
-	if (existsSync(docsDir)) {
-		console.log(`✓ Source directory: ${docsDir}`);
-	} else {
-		console.log(`⚠ Source directory not found: ${docsDir} (optional)`);
+	// Check source directories from config
+	const { loadConfig } = await import("./config/defaults");
+	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)
@@ -338,6 +416,10 @@ async function main() {
 		await cmdDaemon();
 		break;
 
+	case "setup-mcp":
+		await cmdSetupMcp();
+		break;
+
 		case "version":
 		case "--version":
 		case "-v":

package/src/config/defaults.ts

@@ -17,6 +17,20 @@ export interface AmalfaConfig {
 		debounce: number;
 	};
 	excludePatterns: string[];
+	/** Graph analysis tuning parameters (optional) */
+	graph?: {
+		tuning?: {
+			louvain?: {
+				persona?: number;
+				experience?: number;
+			};
+		};
+	};
+	/** Persona fixture paths (optional, for legacy Resonance features) */
+	fixtures?: {
+		lexicon?: string;
+		cda?: string;
+	};
 }
 
 export const DEFAULT_CONFIG: AmalfaConfig = {
@@ -31,6 +45,20 @@ export const DEFAULT_CONFIG: AmalfaConfig = {
 		debounce: 1000,
 	},
 	excludePatterns: ["node_modules", ".git", ".amalfa"],
+	// Optional graph tuning (for advanced use)
+	graph: {
+		tuning: {
+			louvain: {
+				persona: 0.3,
+				experience: 0.25,
+			},
+		},
+	},
+	// Optional fixtures (for legacy Resonance features)
+	fixtures: {
+		lexicon: "scripts/fixtures/conceptual-lexicon-ref-v1.79.json",
+		cda: "scripts/fixtures/cda-ref-v63.json",
+	},
 };
 
 /**
@@ -58,19 +86,31 @@ export async function loadConfig(): Promise<AmalfaConfig> {
 					userConfig = imported.default || imported;
 				}
 
-				// Merge with defaults
-				const merged = {
-					...DEFAULT_CONFIG,
-					...userConfig,
-					embeddings: {
-						...DEFAULT_CONFIG.embeddings,
-						...(userConfig.embeddings || {}),
-					},
-					watch: {
-						...DEFAULT_CONFIG.watch,
-						...(userConfig.watch || {}),
+			// Merge with defaults
+			const merged = {
+				...DEFAULT_CONFIG,
+				...userConfig,
+				embeddings: {
+					...DEFAULT_CONFIG.embeddings,
+					...(userConfig.embeddings || {}),
+				},
+				watch: {
+					...DEFAULT_CONFIG.watch,
+					...(userConfig.watch || {}),
+				},
+				graph: {
+					...DEFAULT_CONFIG.graph,
+					...(userConfig.graph || {}),
+					tuning: {
+						...(DEFAULT_CONFIG.graph?.tuning || {}),
+						...(userConfig.graph?.tuning || {}),
 					},
-				};
+				},
+				fixtures: {
+					...DEFAULT_CONFIG.fixtures,
+					...(userConfig.fixtures || {}),
+				},
+			};
 
 				// Normalize: Convert legacy 'source' to 'sources' array
 				if (merged.source && !merged.sources) {

package/src/core/VectorEngine.ts

@@ -1,7 +1,5 @@
 import { Database } from "bun:sqlite";
-import { join } from "node:path";
 import { EmbeddingModel, FlagEmbedding } from "fastembed";
-import settings from "@/polyvis.settings.json";
 
 // Types
 export interface SearchResult {
@@ -89,9 +87,7 @@ export class VectorEngine {
 			console.warn(
 				"⚠️  DEPRECATED: VectorEngine string path constructor bypasses DatabaseFactory. Pass Database object instead. Will be removed in v2.0.",
 			);
-			const path =
-				dbOrPath || join(process.cwd(), settings.paths.database.resonance);
-			this.db = new Database(path);
+			this.db = new Database(dbOrPath);
 
 			// Apply Safeguards if we created it
 			this.db.run("PRAGMA journal_mode = WAL;");
@@ -192,22 +188,35 @@ export class VectorEngine {
 		const topK = scored.sort((a, b) => b.score - a.score).slice(0, limit);
 
 		// 5. Hydrate Content (for top K only)
+		// 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 FROM nodes WHERE id = ?",
+			"SELECT title, content, meta FROM nodes WHERE id = ?",
 		);
 
 		for (const item of topK) {
 			const row = contentStmt.get(item.id) as {
 				title: string;
-				content: string;
+				content: string | null;
+				meta: string | null;
 			};
 			if (row) {
+				// For hollow nodes, extract a preview from title or meta
+				let content = row.content || "";
+				if (!content && row.meta) {
+					try {
+						const meta = JSON.parse(row.meta);
+						// Provide source path as content placeholder for hollow nodes
+						content = `[Hollow Node: ${meta.source || "no source"}]`;
+					} catch {
+						content = "[Hollow Node: parse error]";
+					}
+				}
 				results.push({
 					id: item.id,
 					score: item.score,
-					title: row.title, // Add title
-					content: row.content,
+					title: row.title,
+					content: content,
 				});
 			}
 		}

package/src/mcp/index.ts

@@ -8,9 +8,10 @@ import {
 	ListToolsRequestSchema,
 	ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig } from "@src/config/defaults";
 import { VectorEngine } from "@src/core/VectorEngine";
 import { ResonanceDB } from "@src/resonance/db";
-import { EnvironmentVerifier } from "../utils/EnvironmentVerifier";
+import { DaemonManager } from "../utils/DaemonManager";
 import { getLogger } from "../utils/Logger";
 import { ServiceLifecycle } from "../utils/ServiceLifecycle";
 
@@ -29,18 +30,68 @@ const lifecycle = new ServiceLifecycle({
 
 // --- Server Logic ---
 
+// Database path from config (loaded once at startup)
+let DB_PATH: string;
+
 // Helper function to create fresh database connection per request
 function createConnection() {
-	const dbPath = join(import.meta.dir, "../../.amalfa/resonance.db");
-	const db = new ResonanceDB(dbPath);
+	const db = new ResonanceDB(DB_PATH);
 	const vectorEngine = new VectorEngine(db.getRawDb());
 	return { db, vectorEngine };
 }
 
 async function runServer() {
-	// 0. Verify Environment
-	// TODO: Update EnvironmentVerifier for AMALFA paths (not PolyVis)
-	// await EnvironmentVerifier.verifyOrExit();
+	// 0. Load configuration
+	const config = await loadConfig();
+	DB_PATH = join(process.cwd(), config.database);
+	log.info({ database: DB_PATH }, "📁 Database path loaded from config");
+
+	// 1. Start daemons if needed
+	const daemonManager = new DaemonManager();
+
+	// Check file watcher status
+	if (config.watch?.enabled) {
+		const watcherStatus = await daemonManager.checkFileWatcher();
+		if (!watcherStatus.running) {
+			log.info("🔄 Starting file watcher daemon...");
+			try {
+				await daemonManager.startFileWatcher();
+				log.info("✅ File watcher daemon started");
+			} catch (e) {
+				log.warn(
+					{ err: e },
+					"⚠️  Failed to start file watcher, continuing without it",
+				);
+			}
+		} else {
+			log.info(
+				{ pid: watcherStatus.pid },
+				"✅ File watcher daemon already running",
+			);
+		}
+	} else {
+		log.info("ℹ️  File watching disabled in config");
+	}
+
+	// Start vector daemon for fast embeddings
+	const vectorStatus = await daemonManager.checkVectorDaemon();
+	if (!vectorStatus.running) {
+		log.info("🔄 Starting vector daemon...");
+		try {
+			await daemonManager.startVectorDaemon();
+			log.info("✅ Vector daemon started");
+		} catch (e) {
+			log.warn(
+				{ err: e },
+				"⚠️  Failed to start vector daemon, searches will be slower",
+			);
+		}
+	} else {
+		log.info(
+			{ pid: vectorStatus.pid, port: vectorStatus.port },
+			"✅ Vector daemon already running",
+		);
+	}
 
 	log.info("🚀 AMALFA MCP Server Initializing...");
 
@@ -138,10 +189,14 @@ async function runServer() {
 					try {
 						const vectorResults = await vectorEngine.search(query, limit);
 						for (const r of vectorResults) {
+							// Handle hollow nodes: content may be placeholder text
+							const preview = r.content
+								? r.content.slice(0, 200).replace(/\n/g, " ")
+								: "[No preview available]";
 							candidates.set(r.id, {
 								id: r.id,
 								score: r.score,
-								preview: r.content.slice(0, 200).replace(/\n/g, " "),
+								preview: preview,
 								source: "vector",
 							});
 						}

package/src/resonance/DatabaseFactory.ts

@@ -1,5 +1,4 @@
 import { Database } from "bun:sqlite";
-import settings from "@/polyvis.settings.json";
 
 /**
  * 🏭 DATABASE FACTORY (The Enforcer)
@@ -14,10 +13,10 @@ import settings from "@/polyvis.settings.json";
 export const DatabaseFactory = {
 	/**
 	 * Connects specifically to the main Resonance Graph database.
-	 * Uses path from `polyvis.settings.json`.
+	 * @deprecated Use connect() with explicit path from config instead.
 	 */
-	connectToResonance(options: { readonly?: boolean } = {}): Database {
-		return DatabaseFactory.connect(settings.paths.database.resonance, options);
+	connectToResonance(dbPath: string = ".amalfa/resonance.db", options: { readonly?: boolean } = {}): Database {
+		return DatabaseFactory.connect(dbPath, options);
 	},
 	/**
 	 * Creates a fully configured, concurrent-safe SQLite connection.

package/src/resonance/db.ts

@@ -1,6 +1,5 @@
 import type { Database } from "bun:sqlite";
 import { getLogger } from "@src/utils/Logger";
-import settings from "@/polyvis.settings.json";
 import { DatabaseFactory } from "./DatabaseFactory";
 import { CURRENT_SCHEMA_VERSION, MIGRATIONS } from "./schema";
 
@@ -25,10 +24,11 @@ export class ResonanceDB {
 	private dbPath: string;
 
 	/**
-	 * Factory method to load the default Resonance Graph based on settings.
+	 * Factory method to load the default Resonance Graph.
+	 * @deprecated Use constructor with explicit path from config instead.
 	 */
-	static init(): ResonanceDB {
-		return new ResonanceDB(settings.paths.database.resonance);
+	static init(dbPath: string = ".amalfa/resonance.db"): ResonanceDB {
+		return new ResonanceDB(dbPath);
 	}
 
 	/**