amalfa 1.0.11 → 1.0.13

package/README.md

@@ -186,12 +186,52 @@ amalfa/
 ### Key Patterns
 
 1. **Hollow Nodes:** Node metadata in SQLite, content on filesystem
-2. **FAFCAS Protocol:** Fast Approximate Fuzzy Cosine Similarity search
+2. **FAFCAS Protocol:** Embedding normalization that enables scalar product searches (10x faster than cosine similarity)
 3. **Git-Based Auditing:** All agent augmentations are git commits
 4. **ServiceLifecycle:** Unified daemon management pattern
 
 ---
 
+## Example Workflow
+
+AMALFA follows a **Brief → Work → Debrief → Playbook** cycle:
+
+```dot
+digraph workflow {
+  rankdir=LR;
+  node [shape=box, style=filled];
+  
+  // Nodes
+  brief [label="Brief\n(Task Spec)", fillcolor=lightyellow];
+  work [label="Work\n(Implementation)", fillcolor=lightblue];
+  debrief [label="Debrief\n(Lessons Learned)", fillcolor=lightgreen];
+  playbook [label="Playbook\n(Codified Pattern)", fillcolor=orange];
+  db [label="AMALFA\nKnowledge Graph", shape=cylinder, fillcolor=lightgray];
+  
+  // Flow
+  brief -> work [label="guides"];
+  work -> debrief [label="captures"];
+  debrief -> playbook [label="abstracts to"];
+  playbook -> db [label="indexed as"];
+  db -> brief [label="informs\nnext task", style=dashed];
+  
+  // Semantic layer
+  db -> db [label="semantic search\nvector embeddings\ngraph traversal", style=dotted];
+}
+```
+
+**Example:**
+
+1. **Brief:** "Implement user authentication with JWT tokens"
+2. **Work:** Agent implements the feature, commits code
+3. **Debrief:** Document what worked (JWT refresh tokens), what didn't (session storage), lessons learned
+4. **Playbook:** Extract reusable pattern: "Authentication with stateless JWT tokens"
+5. **Query:** Later, "How should we handle auth?" → AMALFA retrieves the playbook via semantic search
+
+**The magic:** Each document is embedded as a vector (384 dimensions), enabling semantic search across all accumulated knowledge.
+
+---
+
 ## Vision
 
 See [VISION-AGENT-LEARNING.md](docs/VISION-AGENT-LEARNING.md) for the full vision.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.11",
+	"version": "1.0.13",
 	"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",

package/src/cli.ts

@@ -3,7 +3,7 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 
-const VERSION = "1.0.11";
+const VERSION = "1.0.13";
 
 // Database path loaded from config (lazy loaded per command)
 let DB_PATH: string | null = null;
@@ -26,6 +26,7 @@ Commands:
   doctor             Check installation and configuration
   setup-mcp          Generate MCP configuration JSON
   daemon <action>    Manage file watcher (start|stop|status|restart)
+  vector <action>    Manage vector daemon (start|stop|status|restart)
   servers [--dot]    Show status of all AMALFA services (--dot for graph)
 
 Options:
@@ -267,6 +268,28 @@ async function cmdDaemon() {
 	});
 }
 
+async function cmdVector() {
+	const action = args[1] || "status";
+	const validActions = ["start", "stop", "status", "restart"];
+
+	if (!validActions.includes(action)) {
+		console.error(`❌ Invalid action: ${action}`);
+		console.error("\nUsage: amalfa vector <start|stop|status|restart>");
+		process.exit(1);
+	}
+
+	// Run vector daemon with the specified action
+	const vectorPath = join(import.meta.dir, "resonance/services/vector-daemon.ts");
+	const proc = spawn("bun", ["run", vectorPath, action], {
+		stdio: "inherit",
+		cwd: process.cwd(),
+	});
+
+	proc.on("exit", (code) => {
+		process.exit(code ?? 0);
+	});
+}
+
 async function cmdSetupMcp() {
 	const { resolve } = await import("node:path");
 	
@@ -321,7 +344,7 @@ async function cmdServers() {
 	
 	const SERVICES = [
 		{ name: "MCP Server", pidFile: ".mcp.pid", port: "stdio", id: "mcp", cmd: "amalfa serve" },
-		{ name: "Vector Daemon", pidFile: ".vector-daemon.pid", port: "3010", id: "vector", cmd: "(auto-start)" },
+		{ name: "Vector Daemon", pidFile: ".vector-daemon.pid", port: "3010", id: "vector", cmd: "amalfa vector start" },
 		{ name: "File Watcher", pidFile: ".amalfa-daemon.pid", port: "-", id: "watcher", cmd: "amalfa daemon start" },
 	];
 
@@ -435,7 +458,7 @@ async function cmdServers() {
 	}
 
 	console.log("─".repeat(95));
-	console.log("\n💡 Commands: amalfa serve | amalfa daemon start | amalfa stats\n");
+	console.log("\n💡 Commands: amalfa serve | amalfa vector start | amalfa daemon start\n");
 }
 
 async function cmdDoctor() {
@@ -539,6 +562,10 @@ async function main() {
 		await cmdDaemon();
 		break;
 
+	case "vector":
+		await cmdVector();
+		break;
+
 	case "setup-mcp":
 		await cmdSetupMcp();
 		break;