amalfa 1.0.36 → 1.0.38

package/README.md

@@ -244,7 +244,13 @@ Agents generate knowledge through structured reflection. Amalfa provides semanti
 - [ ] Git-based auditing for augmentations
 - [ ] Automated file watcher updates
 
-### 📋 Phase 2: Latent Space Organization (Planned)
+### 🚧 Phase 2: Ember Service (Automated Enrichment)
+- ✅ **Analyzer** - Louvain community detection & heuristics
+- ✅ **Sidecar Generator** - Safe proposal mechanism (`.ember.json`)
+- ✅ **Squasher** - Robust metadata merging (preserves user content)
+- ✅ **CLI** - `amalfa ember scan/squash` commands
+
+### 📋 Phase 3: Latent Space Organization (Planned)
 
 - [ ] Document clustering (HDBSCAN)
 - [ ] Cluster label generation

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.36",
+	"version": "1.0.38",
 	"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",
@@ -45,9 +45,9 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.3.8",
 		"@types/bun": "1.3.4",
-		"only-allow": "^1.2.2",
-		"pino-pretty": "^13.1.3",
-		"typescript": "^5.9.3"
+		"only-allow": "1.2.2",
+		"pino-pretty": "13.1.3",
+		"typescript": "5.9.3"
 	},
 	"scripts": {
 		"precommit": "bun run scripts/maintenance/pre-commit.ts",
@@ -64,9 +64,13 @@
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "1.25.2",
+		"drizzle-kit": "0.31.8",
+		"drizzle-orm": "0.45.1",
 		"fastembed": "2.0.0",
-		"graphology": "^0.26.0",
-		"graphology-library": "^0.8.0",
-		"pino": "^10.1.0"
+		"graphology": "0.26.0",
+		"graphology-library": "0.8.0",
+		"gray-matter": "^4.0.3",
+		"hono": "4.11.3",
+		"pino": "10.1.0"
 	}
 }

package/src/cli.ts

@@ -50,6 +50,7 @@ Commands:
   daemon <action>    Manage file watcher (start|stop|status|restart)
   vector <action>    Manage vector daemon (start|stop|status|restart)
   sonar <action>     Manage Sonar AI agent (start|stop|status|restart)
+  ember <action>     Manage Ember enrichment service (scan|squash)
   scripts list       List available scripts and their descriptions
   servers [--dot]    Show status of all AMALFA services (--dot for graph)
 
@@ -821,6 +822,67 @@ async function cmdValidate() {
 	}
 }
 
+async function cmdEmber() {
+	const rawAction = args[1] || "help";
+	const action =
+		rawAction === "--help" || rawAction === "-h" ? "help" : rawAction;
+
+	if (action === "help") {
+		console.log(`
+EMBER - Automated Enrichment Service
+
+Usage:
+  amalfa ember scan [--dry-run]   Analyze files and generate sidecars
+  amalfa ember squash             Merge sidecars into markdown files
+  amalfa ember status             Show pending sidecars (TODO)
+`);
+		return;
+	}
+
+	const { ResonanceDB } = await import("./resonance/db");
+	const { EmberService } = await import("./ember/index");
+	const { loadConfig } = await import("./config/defaults");
+
+	// Check 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 appConfig = await loadConfig();
+
+	const emberConfig = {
+		enabled: true,
+		sources: appConfig.sources || ["./docs"],
+		minConfidence: 0.7,
+		backupDir: ".amalfa/backups",
+		excludePatterns: appConfig.excludePatterns || [],
+	};
+
+	const ember = new EmberService(db, emberConfig);
+
+	try {
+		if (action === "scan") {
+			const dryRun = args.includes("--dry-run");
+			await ember.runFullSweep(dryRun);
+		} else if (action === "squash") {
+			await ember.squashAll();
+		} else if (action === "status") {
+			console.log("Checking pending sidecars... (Not yet implemented)");
+		} else {
+			console.error(`❌ Unknown action: ${action}`);
+			process.exit(1);
+		}
+	} catch (e) {
+		console.error("❌ Ember command failed:", e);
+		process.exit(1);
+	} finally {
+		db.close();
+	}
+}
+
 async function cmdDoctor() {
 	console.log("🩺 AMALFA Health Check\n");
 
@@ -944,6 +1006,10 @@ async function main() {
 			await cmdSonar();
 			break;
 
+		case "ember":
+			await cmdEmber();
+			break;
+
 		case "scripts":
 			await cmdScripts();
 			break;

package/src/daemon/sonar-agent.ts

@@ -24,27 +24,14 @@ import { ServiceLifecycle } from "@src/utils/ServiceLifecycle";
 import { inferenceState } from "./sonar-inference";
 import {
 	handleBatchEnhancement,
-	handleChat,
-	handleContextExtraction,
 	handleGardenTask,
-	handleMetadataEnhancement,
 	handleResearchTask,
-	handleResultReranking,
-	handleSearchAnalysis,
 	handleSynthesisTask,
 	handleTimelineTask,
 	type SonarContext,
 } from "./sonar-logic";
 import { getTaskModel } from "./sonar-strategies";
-import type {
-	ChatRequest,
-	ChatSession,
-	MetadataEnhanceRequest,
-	SearchAnalyzeRequest,
-	SearchContextRequest,
-	SearchRerankRequest,
-	SonarTask,
-} from "./sonar-types";
+import type { ChatSession, SonarTask } from "./sonar-types";
 
 const args = process.argv.slice(2);
 const command = args[0] || "serve";
@@ -128,123 +115,18 @@ async function main() {
 	}
 }
 
+import { createSonarApp } from "./sonar-server";
+
 /**
- * Start Bun HTTP Server
+ * Start Bun HTTP Server via Hono
  */
 function startServer(port: number) {
-	const corsHeaders = {
-		"Access-Control-Allow-Origin": "*",
-		"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-		"Access-Control-Allow-Headers": "Content-Type",
-	};
-
 	const context: SonarContext = { db, graphEngine, gardener, chatSessions };
+	const app = createSonarApp(context);
 
 	Bun.serve({
 		port,
-		async fetch(req) {
-			if (req.method === "OPTIONS")
-				return new Response(null, { headers: corsHeaders });
-			const url = new URL(req.url);
-
-			// Health check
-			if (url.pathname === "/health") {
-				const cfg = await loadConfig();
-				const provider = cfg.sonar.cloud?.enabled ? "cloud" : "local";
-				const model = cfg.sonar.cloud?.enabled
-					? cfg.sonar.cloud.model
-					: inferenceState.ollamaModel || cfg.sonar.model;
-				return Response.json(
-					{
-						status: "ok",
-						ollama: inferenceState.ollamaAvailable,
-						provider,
-						model,
-					},
-					{ headers: corsHeaders },
-				);
-			}
-
-			// Chat endpoint
-			if (url.pathname === "/chat" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as ChatRequest;
-					const { sessionId, message, model } = body;
-					const result = await handleChat(sessionId, message, context, model);
-					return Response.json(result, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			// Metadata enhancement endpoint
-			if (url.pathname === "/metadata/enhance" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as MetadataEnhanceRequest;
-					const { docId } = body;
-					await handleMetadataEnhancement(docId, context);
-					return Response.json({ status: "success" }, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			// Graph Stats endpoint
-			if (url.pathname === "/graph/stats" && req.method === "GET") {
-				return Response.json(graphEngine.getStats(), { headers: corsHeaders });
-			}
-
-			// Search endpoints (analysis, rerank, context)
-			if (url.pathname === "/search/analyze" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as SearchAnalyzeRequest;
-					const { query } = body;
-					const result = await handleSearchAnalysis(query, context);
-					return Response.json(result, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			if (url.pathname === "/search/rerank" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as SearchRerankRequest;
-					const { results, query, intent } = body;
-					const result = await handleResultReranking(results, query, intent);
-					return Response.json(result, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			if (url.pathname === "/search/context" && req.method === "POST") {
-				try {
-					const body = (await req.json()) as SearchContextRequest;
-					const { result, query } = body;
-					const contextResult = await handleContextExtraction(result, query);
-					return Response.json(contextResult, { headers: corsHeaders });
-				} catch (error) {
-					return Response.json(
-						{ error: String(error) },
-						{ status: 500, headers: corsHeaders },
-					);
-				}
-			}
-
-			return new Response("Not Found", { status: 404, headers: corsHeaders });
-		},
+		fetch: app.fetch,
 	});
 
 	log.info(`Server started on port ${port}`);

package/src/daemon/sonar-server.ts

@@ -0,0 +1,133 @@
+import { loadConfig } from "@src/config/defaults";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { inferenceState } from "./sonar-inference";
+import {
+	handleChat,
+	handleContextExtraction,
+	handleMetadataEnhancement,
+	handleResultReranking,
+	handleSearchAnalysis,
+	type SonarContext,
+} from "./sonar-logic";
+import type {
+	ChatRequest,
+	MetadataEnhanceRequest,
+	SearchAnalyzeRequest,
+	SearchContextRequest,
+	SearchRerankRequest,
+} from "./sonar-types";
+
+/**
+ * Creates the Hono application for the Sonar Agent
+ */
+export function createSonarApp(context: SonarContext) {
+	const app = new Hono();
+
+	// Global Middleware
+	app.use(
+		"*",
+		cors({
+			origin: "*",
+			allowMethods: ["GET", "POST", "OPTIONS"],
+			allowHeaders: ["Content-Type"],
+		}),
+	);
+
+	/**
+	 * Health Check
+	 */
+	app.get("/health", async (c) => {
+		const cfg = await loadConfig();
+		const provider = cfg.sonar.cloud?.enabled ? "cloud" : "local";
+		const model = cfg.sonar.cloud?.enabled
+			? cfg.sonar.cloud.model
+			: inferenceState.ollamaModel || cfg.sonar.model;
+
+		return c.json({
+			status: "ok",
+			ollama: inferenceState.ollamaAvailable,
+			provider,
+			model,
+		});
+	});
+
+	/**
+	 * Chat Interface
+	 */
+	app.post("/chat", async (c) => {
+		try {
+			const body = await c.req.json<ChatRequest>();
+			const { sessionId, message, model } = body;
+			const result = await handleChat(sessionId, message, context, model);
+			return c.json(result);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Metadata Enhancement
+	 */
+	app.post("/metadata/enhance", async (c) => {
+		try {
+			const body = await c.req.json<MetadataEnhanceRequest>();
+			const { docId } = body;
+			await handleMetadataEnhancement(docId, context);
+			return c.json({ status: "success" });
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Graph Stats
+	 */
+	app.get("/graph/stats", (c) => {
+		return c.json(context.graphEngine.getStats());
+	});
+
+	/**
+	 * Search: Query Analysis
+	 */
+	app.post("/search/analyze", async (c) => {
+		try {
+			const body = await c.req.json<SearchAnalyzeRequest>();
+			const { query } = body;
+			const result = await handleSearchAnalysis(query, context);
+			return c.json(result);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Search: Reranking
+	 */
+	app.post("/search/rerank", async (c) => {
+		try {
+			const body = await c.req.json<SearchRerankRequest>();
+			const { results, query, intent } = body;
+			const result = await handleResultReranking(results, query, intent);
+			return c.json(result);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	/**
+	 * Search: Context Extraction
+	 */
+	app.post("/search/context", async (c) => {
+		try {
+			const body = await c.req.json<SearchContextRequest>();
+			const { result, query } = body;
+			const contextResult = await handleContextExtraction(result, query);
+			return c.json(contextResult);
+		} catch (error) {
+			return c.json({ error: String(error) }, 500);
+		}
+	});
+
+	return app;
+}

package/src/ember/README.md

@@ -0,0 +1,23 @@
+
+# Ember Service
+
+Automated enrichment service for the Amalfa Knowledge Graph.
+
+## Stability Clause
+
+> **Warning**
+> This module is responsible for modifying user data (markdown files). 
+> 
+> *   **Do not modify** `squasher.ts` without explicit regression testing.
+> *   **Do not change** the sidecar format without updating `types.ts` and `generator.ts`.
+> *   **Always use** `safe-dump` equivalent (e.g., `gray-matter`) when writing back files.
+
+## Architecture
+
+- **Analyzer**: Scans graph for enrichment opportunities.
+- **Generator**: Writes changes to `.ember.json` sidecar files.
+- **Squasher**: Merges sidecars into `.md` files safely.
+
+## Usage
+
+Included in the main Amalfa daemon. Can be triggered via CLI.

package/src/ember/analyzer.ts

@@ -0,0 +1,120 @@
+import { GraphEngine } from "@src/core/GraphEngine";
+import type { ResonanceDB } from "@src/resonance/db";
+import { getLogger } from "@src/utils/Logger";
+import type { EmberSidecar } from "./types";
+
+export class EmberAnalyzer {
+	private log = getLogger("EmberAnalyzer");
+	private graphEngine: GraphEngine;
+	private communities: Record<string, number> | null = null;
+	private isGraphLoaded = false;
+
+	constructor(private db: ResonanceDB) {
+		this.graphEngine = new GraphEngine();
+	}
+
+	/**
+	 * Pre-load graph data for batch analysis
+	 */
+	async prepare() {
+		this.log.info("Loading graph engine for analysis...");
+		await this.graphEngine.load(this.db.getRawDb());
+		this.communities = this.graphEngine.detectCommunities();
+		this.isGraphLoaded = true;
+		this.log.info("Graph engine ready.");
+	}
+
+	/**
+	 * Analyze a file and generate enrichment proposals
+	 */
+	async analyze(
+		filePath: string,
+		content: string,
+	): Promise<EmberSidecar | null> {
+		this.log.info(`Analyzing ${filePath}...`);
+
+		// Lazy load if not ready
+		if (!this.isGraphLoaded) {
+			await this.prepare();
+		}
+
+		// 1. Identify Node in Graph
+		const filename = filePath.split("/").pop() || "unknown";
+		const id = filename
+			.replace(/\.(md|ts|js)$/, "")
+			.toLowerCase()
+			.replace(/[^a-z0-9-]/g, "-");
+
+		const node = this.db.getNode(id);
+		if (!node) {
+			this.log.warn(`Node ${id} not found in graph. Skipping analysis.`);
+			return null;
+		}
+
+		const proposedTags: string[] = [];
+		const proposedLinks: string[] = [];
+
+		// 2. Community-based Tag Suggestion
+		if (this.communities && this.communities[id] !== undefined) {
+			const communityId = this.communities[id];
+			const communityNodes = Object.entries(this.communities)
+				.filter(([_, comm]) => comm === communityId)
+				.map(([nId]) => nId);
+
+			// Only analyze if community is large enough
+			if (communityNodes.length > 2) {
+				const tagFreq = new Map<string, number>();
+				let neighborCount = 0;
+
+				// Analyze neighbors specifically (stronger signal than whole community)
+				const neighbors = this.graphEngine.getNeighbors(id);
+
+				for (const neighborId of neighbors) {
+					const neighbor = this.db.getNode(neighborId);
+					const nTags = (neighbor?.meta?.tags as string[]) || [];
+
+					for (const tag of nTags) {
+						tagFreq.set(tag, (tagFreq.get(tag) || 0) + 1);
+					}
+					neighborCount++;
+				}
+
+				// Suggest tags present in > 50% of neighbors
+				if (neighborCount > 0) {
+					for (const [tag, count] of tagFreq.entries()) {
+						if (count / neighborCount >= 0.5) {
+							const currentTags = (node.meta?.tags as string[]) || [];
+							if (!currentTags.includes(tag) && !proposedTags.includes(tag)) {
+								proposedTags.push(tag);
+							}
+						}
+					}
+				}
+			}
+		}
+
+		// 3. Heuristics (Stub detection)
+		const tags = (node.meta?.tags as string[]) || [];
+		if (content.length < 100 && !tags.includes("stub")) {
+			proposedTags.push("stub");
+		}
+
+		// If no meaningful changes, return null
+		if (proposedTags.length === 0 && proposedLinks.length === 0) {
+			return null;
+		}
+
+		// 4. Construct Sidecar
+		const sidecar: EmberSidecar = {
+			targetFile: filePath,
+			generatedAt: new Date().toISOString(),
+			confidence: 0.8,
+			changes: {
+				tags: proposedTags.length > 0 ? { add: proposedTags } : undefined,
+				links: proposedLinks.length > 0 ? { add: proposedLinks } : undefined,
+			},
+		};
+
+		return sidecar;
+	}
+}

package/src/ember/generator.ts

@@ -0,0 +1,25 @@
+import { getLogger } from "@src/utils/Logger";
+import type { EmberSidecar } from "./types";
+
+export class EmberGenerator {
+	private log = getLogger("EmberGenerator");
+
+	/**
+	 * Write the sidecar file to disk
+	 */
+	async generate(sidecar: EmberSidecar): Promise<string> {
+		const sidecarPath = `${sidecar.targetFile}.ember.json`;
+
+		try {
+			await Bun.write(sidecarPath, JSON.stringify(sidecar, null, 2));
+			this.log.info(`Generated sidecar: ${sidecarPath}`);
+			return sidecarPath;
+		} catch (error) {
+			this.log.error(
+				{ err: error, file: sidecarPath },
+				"Failed to write sidecar",
+			);
+			throw error;
+		}
+	}
+}

package/src/ember/index.ts

@@ -0,0 +1,106 @@
+import { join } from "node:path";
+import type { ResonanceDB } from "@src/resonance/db";
+import { getLogger } from "@src/utils/Logger";
+import { Glob } from "bun";
+import { EmberAnalyzer } from "./analyzer";
+import { EmberGenerator } from "./generator";
+import { EmberSquasher } from "./squasher";
+import type { EmberConfig } from "./types";
+
+export class EmberService {
+	private analyzer: EmberAnalyzer;
+	private generator: EmberGenerator;
+	private squasher: EmberSquasher;
+	private log = getLogger("EmberService");
+
+	constructor(
+		db: ResonanceDB,
+		private config: EmberConfig,
+	) {
+		this.analyzer = new EmberAnalyzer(db);
+		this.generator = new EmberGenerator();
+		this.squasher = new EmberSquasher();
+	}
+
+	/**
+	 * Run a full sweep of all configured sources
+	 */
+	async runFullSweep(dryRun = false) {
+		this.log.info("Starting full Ember sweep...");
+
+		const files = await this.discoverFiles();
+		let enrichedCount = 0;
+
+		for (const file of files) {
+			const content = await Bun.file(file).text();
+			const sidecar = await this.analyzer.analyze(file, content);
+
+			if (sidecar) {
+				if (dryRun) {
+					this.log.info(`[Dry Run] Would generate sidecar for ${file}`);
+					console.log(JSON.stringify(sidecar, null, 2));
+				} else {
+					await this.generator.generate(sidecar);
+					enrichedCount++;
+				}
+			}
+		}
+
+		this.log.info(`Sweep complete. Enriched ${enrichedCount} files.`);
+		return enrichedCount;
+	}
+
+	/**
+	 * Squash all pending sidecars
+	 */
+	async squashAll() {
+		this.log.info("Squashing all pending sidecars...");
+		let count = 0;
+
+		// Simpler scan:
+		const sidecars = await this.findSidecars();
+		for (const sidecarPath of sidecars) {
+			await this.squasher.squash(sidecarPath);
+			count++;
+		}
+
+		this.log.info(`Squashed ${count} sidecars.`);
+		return count;
+	}
+
+	private async findSidecars(): Promise<string[]> {
+		const sidecars: string[] = [];
+		const glob = new Glob("**/*.ember.json");
+		// Scan sources
+		for (const source of this.config.sources) {
+			// Assuming source is like "./docs"
+			const sourcePath = join(process.cwd(), source);
+			for (const file of glob.scanSync({ cwd: sourcePath })) {
+				sidecars.push(join(sourcePath, file));
+			}
+		}
+		return sidecars;
+	}
+
+	private async discoverFiles(): Promise<string[]> {
+		const files: string[] = [];
+		const glob = new Glob("**/*.{md,mdx}"); // Only markdown for now
+
+		for (const source of this.config.sources) {
+			const sourcePath = join(process.cwd(), source);
+			try {
+				for (const file of glob.scanSync({ cwd: sourcePath })) {
+					const shouldExclude = this.config.excludePatterns.some((p) =>
+						file.includes(p),
+					);
+					if (!shouldExclude) {
+						files.push(join(sourcePath, file));
+					}
+				}
+			} catch (e) {
+				this.log.warn({ source: sourcePath, err: e }, "Failed to scan source");
+			}
+		}
+		return files;
+	}
+}

package/src/ember/squasher.ts

@@ -0,0 +1,71 @@
+import { unlink } from "node:fs/promises";
+import { getLogger } from "@src/utils/Logger";
+import matter from "gray-matter";
+import type { EmberSidecar } from "./types";
+
+export class EmberSquasher {
+	private log = getLogger("EmberSquasher");
+
+	/**
+	 * Apply the sidecar changes to the target file
+	 */
+	async squash(sidecarPath: string): Promise<void> {
+		try {
+			// 1. Read Sidecar
+			const sidecarContent = await Bun.file(sidecarPath).text();
+			const sidecar: EmberSidecar = JSON.parse(sidecarContent);
+
+			const targetPath = sidecar.targetFile;
+
+			// 2. Read Target File
+			const fileContent = await Bun.file(targetPath).text();
+
+			// 3. Parse with gray-matter
+			const parsed = matter(fileContent);
+			const data = parsed.data || {};
+
+			// 4. Apply Changes
+			if (sidecar.changes.tags) {
+				const currentTags = (
+					Array.isArray(data.tags) ? data.tags : []
+				) as string[];
+				const toAdd = sidecar.changes.tags.add || [];
+				const toRemove = sidecar.changes.tags.remove || [];
+
+				const newTags = new Set(currentTags);
+				for (const t of toAdd) {
+					newTags.add(t);
+				}
+				for (const t of toRemove) {
+					newTags.delete(t);
+				}
+
+				data.tags = Array.from(newTags);
+			}
+
+			if (sidecar.changes.frontmatter) {
+				Object.assign(data, sidecar.changes.frontmatter);
+			}
+
+			if (sidecar.changes.summary) {
+				data.summary = sidecar.changes.summary;
+			}
+
+			// 5. Reconstruct File
+			const newContent = matter.stringify(parsed.content, data);
+
+			// 6. Write Back
+			await Bun.write(targetPath, newContent);
+			this.log.info(`Squashed sidecar into ${targetPath}`);
+
+			// 7. Cleanup Sidecar
+			await unlink(sidecarPath);
+		} catch (error) {
+			this.log.error(
+				{ err: error, file: sidecarPath },
+				"Failed to squash sidecar",
+			);
+			throw error;
+		}
+	}
+}

package/src/ember/types.ts

@@ -0,0 +1,26 @@
+export interface EmberSidecar {
+	targetFile: string;
+	generatedAt: string;
+	confidence: number;
+	changes: {
+		tags?: {
+			add: string[];
+			remove?: string[];
+		};
+		frontmatter?: Record<string, unknown>;
+		summary?: string;
+		links?: {
+			add: string[]; // List of IDs or Titles to add to 'related'
+		};
+	};
+}
+
+export interface EmberConfig {
+	enabled: boolean;
+	sources: string[];
+	minConfidence: number;
+	backupDir: string;
+	excludePatterns: string[];
+}
+
+export type EnrichmentType = "tag" | "link" | "summary" | "metadata";

package/src/pipeline/AmalfaIngestor.ts

@@ -12,6 +12,7 @@ import { Embedder } from "@src/resonance/services/embedder";
 import { SimpleTokenizerService as TokenizerService } from "@src/resonance/services/simpleTokenizer";
 import { getLogger } from "@src/utils/Logger";
 import { Glob } from "bun";
+import matter from "gray-matter";
 
 export interface IngestionResult {
 	success: boolean;
@@ -236,11 +237,12 @@ export class AmalfaIngestor {
 		tokenizer: TokenizerService,
 	): Promise<void> {
 		try {
-			const content = await Bun.file(filePath).text();
+			const rawContent = await Bun.file(filePath).text();
 
-			// Parse frontmatter
-			const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
-			const frontmatter = fmMatch?.[1] ? this.parseFrontmatter(fmMatch[1]) : {};
+			// Parse frontmatter with gray-matter
+			const parsed = matter(rawContent);
+			const frontmatter = parsed.data || {};
+			const content = parsed.content;
 
 			// Generate ID from filename
 			const filename = filePath.split("/").pop() || "unknown";
@@ -251,7 +253,7 @@ export class AmalfaIngestor {
 
 			// Skip if content unchanged (hash check)
 			const hasher = new Bun.CryptoHasher("md5");
-			hasher.update(content.trim());
+			hasher.update(rawContent.trim());
 			const currentHash = hasher.digest("hex");
 			const storedHash = this.db.getNodeHash(id);
 
@@ -268,6 +270,8 @@ export class AmalfaIngestor {
 			// Extract semantic tokens
 			const tokens = tokenizer.extract(content);
 
+			// Insert node
+
 			// Insert node
 			const node: Node = {
 				id,
@@ -295,18 +299,4 @@ export class AmalfaIngestor {
 			this.log.warn({ err: e, file: filePath }, "⚠️  Failed to process file");
 		}
 	}
-
-	/**
-	 * Parse YAML-like frontmatter
-	 */
-	private parseFrontmatter(text: string): Record<string, unknown> {
-		const meta: Record<string, unknown> = {};
-		text.split("\n").forEach((line) => {
-			const [key, ...vals] = line.split(":");
-			if (key && vals.length) {
-				meta[key.trim()] = vals.join(":").trim();
-			}
-		});
-		return meta;
-	}
 }

package/src/resonance/DatabaseFactory.ts

@@ -13,7 +13,7 @@ import { Database } from "bun:sqlite";
 export const DatabaseFactory = {
 	/**
 	 * Connects specifically to the main Resonance Graph database.
-	 * @deprecated Use connect() with explicit path from config instead.
+	 * Kept for convenience and backward compatibility.
 	 */
 	connectToResonance(
 		dbPath: string = ".amalfa/resonance.db",

package/src/resonance/drizzle/README.md

@@ -0,0 +1,25 @@
+# Drizzle Schema Management
+
+## ⚠️ CRITICAL ARCHITECTURE RULE
+
+**Drizzle ORM is used HERE strictly for:**
+1.  **Schema Definition:** Single source of truth for table structures (`schema.ts`).
+2.  **Migrations:** Generating and running SQL migrations (`drizzle-kit`).
+
+**Drizzle ORM is NOT used for:**
+- **Runtime Queries:** Do NOT use Drizzle `db.select()` query builders in critical paths.
+- **Data Access:** All runtime data access uses `bun:sqlite` with raw parameterized SQL (`db.prepare()`).
+
+## Why?
+Our **FAFCAS** (Fast, Autonomous, Fractionally-Connected Agent System) architecture demands raw IO performance. We treat SQLite as a raw storage engine. The overhead of an ORM query builder—even a light one—is unnecessary.
+
+## ⛔ Agent Guardrail
+If you are an AI Agent reading this:
+- **DO NOT** refactor the existing `ResonanceDB` SQL queries to use Drizzle.
+- **DO NOT** introduce Drizzle usage into `GraphEngine` or `VectorEngine`.
+- **ONLY** modify this folder if the Database Schema (tables/columns) needs to change.
+
+## Workflow for Schema Changes
+1.  Edit `schema.ts`
+2.  Run `bunx drizzle-kit generate`
+3.  Run migrations (automated via scripts)

package/src/resonance/drizzle/migrations/0000_happy_thaddeus_ross.sql

@@ -0,0 +1,30 @@
+CREATE TABLE `edges` (
+	`source` text NOT NULL,
+	`target` text NOT NULL,
+	`type` text NOT NULL,
+	`confidence` real DEFAULT 1,
+	`veracity` real DEFAULT 1,
+	`context_source` text,
+	PRIMARY KEY(`source`, `target`, `type`)
+);
+--> statement-breakpoint
+CREATE INDEX `idx_edges_source` ON `edges` (`source`);--> statement-breakpoint
+CREATE INDEX `idx_edges_target` ON `edges` (`target`);--> statement-breakpoint
+CREATE TABLE `ember_state` (
+	`file_path` text PRIMARY KEY NOT NULL,
+	`last_analyzed` text,
+	`sidecar_created` integer,
+	`confidence` real
+);
+--> statement-breakpoint
+CREATE TABLE `nodes` (
+	`id` text PRIMARY KEY NOT NULL,
+	`type` text,
+	`title` text,
+	`domain` text,
+	`layer` text,
+	`embedding` blob,
+	`hash` text,
+	`meta` text,
+	`date` text
+);

package/src/resonance/drizzle/migrations/meta/0000_snapshot.json

@@ -0,0 +1,199 @@
+{
+	"version": "6",
+	"dialect": "sqlite",
+	"id": "577c9f07-f198-49d2-9fa3-f222a6ecee23",
+	"prevId": "00000000-0000-0000-0000-000000000000",
+	"tables": {
+		"edges": {
+			"name": "edges",
+			"columns": {
+				"source": {
+					"name": "source",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"target": {
+					"name": "target",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"type": {
+					"name": "type",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"confidence": {
+					"name": "confidence",
+					"type": "real",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false,
+					"default": 1
+				},
+				"veracity": {
+					"name": "veracity",
+					"type": "real",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false,
+					"default": 1
+				},
+				"context_source": {
+					"name": "context_source",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				}
+			},
+			"indexes": {
+				"idx_edges_source": {
+					"name": "idx_edges_source",
+					"columns": ["source"],
+					"isUnique": false
+				},
+				"idx_edges_target": {
+					"name": "idx_edges_target",
+					"columns": ["target"],
+					"isUnique": false
+				}
+			},
+			"foreignKeys": {},
+			"compositePrimaryKeys": {
+				"edges_source_target_type_pk": {
+					"columns": ["source", "target", "type"],
+					"name": "edges_source_target_type_pk"
+				}
+			},
+			"uniqueConstraints": {},
+			"checkConstraints": {}
+		},
+		"ember_state": {
+			"name": "ember_state",
+			"columns": {
+				"file_path": {
+					"name": "file_path",
+					"type": "text",
+					"primaryKey": true,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"last_analyzed": {
+					"name": "last_analyzed",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"sidecar_created": {
+					"name": "sidecar_created",
+					"type": "integer",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"confidence": {
+					"name": "confidence",
+					"type": "real",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				}
+			},
+			"indexes": {},
+			"foreignKeys": {},
+			"compositePrimaryKeys": {},
+			"uniqueConstraints": {},
+			"checkConstraints": {}
+		},
+		"nodes": {
+			"name": "nodes",
+			"columns": {
+				"id": {
+					"name": "id",
+					"type": "text",
+					"primaryKey": true,
+					"notNull": true,
+					"autoincrement": false
+				},
+				"type": {
+					"name": "type",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"title": {
+					"name": "title",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"domain": {
+					"name": "domain",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"layer": {
+					"name": "layer",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"embedding": {
+					"name": "embedding",
+					"type": "blob",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"hash": {
+					"name": "hash",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"meta": {
+					"name": "meta",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				},
+				"date": {
+					"name": "date",
+					"type": "text",
+					"primaryKey": false,
+					"notNull": false,
+					"autoincrement": false
+				}
+			},
+			"indexes": {},
+			"foreignKeys": {},
+			"compositePrimaryKeys": {},
+			"uniqueConstraints": {},
+			"checkConstraints": {}
+		}
+	},
+	"views": {},
+	"enums": {},
+	"_meta": {
+		"schemas": {},
+		"tables": {},
+		"columns": {}
+	},
+	"internal": {
+		"indexes": {}
+	}
+}

package/src/resonance/drizzle/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+	"version": "7",
+	"dialect": "sqlite",
+	"entries": [
+		{
+			"idx": 0,
+			"version": "6",
+			"when": 1767981411501,
+			"tag": "0000_happy_thaddeus_ross",
+			"breakpoints": true
+		}
+	]
+}

package/src/resonance/drizzle/schema.ts

@@ -0,0 +1,60 @@
+import {
+	blob,
+	index,
+	integer,
+	primaryKey,
+	real,
+	sqliteTable,
+	text,
+} from "drizzle-orm/sqlite-core";
+
+/**
+ * NODES Table
+ * Core entity storage. Now "Hollow" (no content).
+ */
+export const nodes = sqliteTable("nodes", {
+	id: text("id").primaryKey(),
+	type: text("type"),
+	title: text("title"),
+	domain: text("domain"),
+	layer: text("layer"),
+	// Embeddings are stored as raw BLOBs (Float32Array bytes)
+	embedding: blob("embedding"),
+	hash: text("hash"),
+	meta: text("meta"), // JSON string
+	date: text("date"), // ISO string or YYYY-MM-DD
+});
+
+/**
+ * EDGES Table
+ * Defines relationships between nodes.
+ */
+export const edges = sqliteTable(
+	"edges",
+	{
+		source: text("source").notNull(),
+		target: text("target").notNull(),
+		type: text("type").notNull(),
+		confidence: real("confidence").default(1.0),
+		veracity: real("veracity").default(1.0),
+		contextSource: text("context_source"),
+	},
+	(table) => ({
+		// Composite Primary Key
+		pk: primaryKey({ columns: [table.source, table.target, table.type] }),
+		// Indices for traversal speed
+		sourceIdx: index("idx_edges_source").on(table.source),
+		targetIdx: index("idx_edges_target").on(table.target),
+	}),
+);
+
+/**
+ * EMBER STATE Table (Pilot)
+ * Tracks the state of the Ember Service (automated enrichment).
+ */
+export const emberState = sqliteTable("ember_state", {
+	filePath: text("file_path").primaryKey(),
+	lastAnalyzed: text("last_analyzed"),
+	sidecarCreated: integer("sidecar_created", { mode: "boolean" }),
+	confidence: real("confidence"),
+});