amalfa 1.0.38 → 1.0.40

package/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Changelog
+
+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.0.40] - 2026-01-09
+
+### Added
+- **Ember Phase 2**: Integrated `EmberService` into the `AmalfaDaemon`.
+- **Optimization**: Changes to file content now trigger immediate sidecar generation (if applicable).
+- **Configuration**: Added `tests` to default `excludePatterns`.
+- **CLI**: Added `amalfa stop-all` (alias `kill`) to stop all running services.
+
+## [1.0.39] - 2026-01-09
+
+### Fixed
+- **Documentation**: Updated CHANGELOG.md to include recent Ember Service changes (missed in 1.0.38).
+- **Testing**: Fixed `analyzer.test.ts` to correctly pass file content, resolving pre-commit failures.
+- **Process**: Added Changelog version verification to `pre-commit` hook to prevent future ghost releases.
+
+## [1.0.38] - 2026-01-09
+
+### Added
+- **Ember Service**: Introduced the `amalfa ember` command suite for automated documentation enrichment.
+  - `amalfa ember scan`: Analyzes documents using graph communities to suggest missing tags (Sidecar generation).
+  - `amalfa ember squash`: Safely merges sidecar suggestions into markdown frontmatter using `gray-matter`.
+- **Graph Intelligence**: Integrated `GraphEngine` into Ember for community detection (Louvain) and neighbor-based tag recommendation.
+- **Stub Detection**: Added heuristics to automatically tag short content as `stub`.
+
+### Changed
+- **Ingestion Pipeline**: Upgraded `AmalfaIngestor` to use `gray-matter` for robust frontmatter parsing (replacing legacy regex).
+- **CLI**: Expanded `src/cli.ts` to include `ember` command handling.
+
+### Fixed
+- **Testing**: Resolved content read logic in `analyzer.test.ts`.
+
+## [1.0.37] - 2026-01-09
+
+### Added
+- **Drizzle Integration**: Added Drizzle ORM for schema management and migrations using `drizzle-kit`.
+- **Hono Migration**: Migrated Sonar Agent to Hono for robust routing and standard middleware support.
+- **Guardrails**: Added explicit "No ORM Runtime" policy for FAFCAS compliance (Drizzle for schema only).
+
+### Changed
+- **Dependency Pinning**: Pinned all dependencies in `package.json` to exact versions to prevent drift.
+- **Cleanup**: Removed stale deprecations and unused imports across the codebase.
+
+## [1.0.36] - 2026-01-09
+
+### Fixed
+- **Pre-commit Checks**: Resolved TypeScript regex match narrowing issues in `doc-consistency-check.ts`
+- **Biome Configuration**: Excluded lab/legacy scripts from linting to focus on core code quality
+- **Branch Protection**: Added local pre-commit hook to prevent direct commits to main branch
+
+### Added
+- **Documentation**: Comprehensive README files added throughout codebase (`src/`, `scripts/`, `src/cli/`, `src/config/`, `src/daemon/`, `src/resonance/services/`, `src/resonance/types/`, `src/types/`, `src/utils/`)
+- **Development Tooling**: Pre-commit hook script for local branch protection
+
+## [1.0.35] - 2026-01-09
+
+### Changed
+- **Version Bump**: Minor version increment for release preparation
+
+## [1.0.34] - 2026-01-09
+
+### Changed
+- **Code Quality**: Applied Biome formatting and lint fixes across the entire codebase to improve consistency and maintainability.
+
+## [1.0.32] - 2026-01-09
+
+### Fixed
+- **CLI**: `setup-mcp` now correctly includes the `--cwd` flag in the generated JSON config. This prevents `EROFS` (read-only file system) errors when the MCP server is launched by clients (like Claude Desktop or Antigravity) that might use a read-only root as the working directory. It forces the server to run in the user's project root where it has write permissions for logs and databases.
+
+## [1.0.31] - 2026-01-09
+
+### Fixed
+- **Publishing**: Included `tsconfig.json` in the published package files. This ensures that global installations (via `npm` or `bun`) can correctly resolve path aliases (e.g., `@src/`) when running the CLI or MCP server.
+- **CLI**: Improved CWD handling when running from system root.
+
+## [1.0.30] - 2026-01-09
+
+### Security
+- **Dependabot**: Updated `@modelcontextprotocol/sdk` to `1.25.2` to resolve ReDoS vulnerability (GHSA-8r9q-7v3j-jr4g).
+
+## [1.0.29] - 2026-01-09
+
+### Added
+- **Phase 5: Autonomous Research & Recursive Discovery (FAFCAS)**: Implemented a multi-step "Internal Monologue" research agent.
+  - **Discovery Loop**: Iterative SEARCH → READ → EXPLORE → ANALYZE cycles.
+  - **Topological Discovery**: Hub-aware entry points using PageRank and Betweenness Centrality.
+  - **EXPLORE Action**: Physical graph neighborhood traversal for non-semantic lead discovery.
+  - **Chain Verification**: Autonomous "AMALFA Auditor" that double-checks research findings for truthfulness.
+  - **Robust JSON Recovery**: Defensive parsing to handle non-compliant LLM outputs.
+- **Phase 4: Topological Intelligence**: Integrated structural link prediction into the gardening loop.
+  - **Adamic-Adar Index**: Implemented topological relationship scoring in `GraphEngine`.
+  - **Structural Gap Detection**: 2-hop shared neighbor analysis to find "missing links."
+- **Phase 3 (Chronos) Completion**: Advanced "Timeline Weaving" and temporal grounding verified.
+- **Cross-Corpus Readiness**: Infrastructure for multi-repo research initiated.
+
+### Changed
+- **Architectural Refactor**: decoupled `sonar-agent.ts` daemon from task logic.
+- **Modular Task Handlers**: Synthesis, Timeline, Garden, and Research logic moved to `sonar-logic.ts`.
+- **Bun-Native Async I/O**: Switched to `Bun.write` and `fs/promises` for all task processing and reporting.
+- **Strict Type Safety**: Replaced `any` assertions with explicit API request interfaces.
+
+## [1.0.28] - 2026-01-08
+
+### Added
+- **OpenRouter Cloud Integration**: New `sonar.cloud` config with `openrouter` provider for accessing cloud LLMs
+- **Dev-Cloud/Prod-Local Strategy**: Test with large cloud models, deploy with smaller local ones
+- **Model Strategy Guide**: New `docs/guides/model-strategy.md` documentation
+- **RAG Pipeline**: Vector search now augments chat context for grounded responses
+- **ENV API Key**: `OPENROUTER_API_KEY` read from `.env` for secure credential handling
+
+### Changed
+- **Tiered Model Strategy**: Research tasks use cloud config, quick tasks use local `qwen2.5:1.5b`
+- **Expanded Ingestion Sources**: Root markdown files now included in knowledge graph
+- **Model Priority**: Updated to prioritize `qwen2.5:1.5b` as default local model
+
+### Removed
+- Cleaned up unused Ollama models: `tinydolphin`, `tinyllama`, `phi3`, `functiongemma`, `nomic-embed-text`, `llama3.1:8b`, `mistral:7b-instruct`
+
+
+### Added
+- **Staleness Detection**: `amalfa stats` now warns (`⚠️ STALE`) if source files are newer than the database.
+- **JSON Mode (GBNF)**: Sonar Agent now enforces valid JSON output for `tinydolphin` compatibility.
+- **Phi3 Sub-Agent**: Robust daemon (`amalfa phi3`) managing local LLM interactions for chat and analysis.
+- **Search Intelligence**: New endpoints `/search/analyze`, `/search/rerank`, `/search/context`.
+- **Metadata Enhancement**: AI-powered document enrichment via `/metadata/enhance` connected to ResonanceDB.
+- **CLI Tooling**: 
+  - `amalfa phi3 chat` (Interactive chat with real-time feedback)
+  - `amalfa phi3 status` (Rich diagnostics)
+  - `amalfa enhance` (Batch/Single doc enhancement)
+- **FAFCAS Optimization**: Prioritized `tinydolphin` (1.1B) model for instant CPU inference.
+- **OH-104 Pinch Check**: Physical file verification after WAL checkpoint to prevent silent corruption
+- Test script `scripts/verify/test-hardening.ts` for validating resilience improvements
+
+### Changed
+- **Sonar Refactor**: Renamed "Phi3" sub-agent to "Sonar Agent" (daemon, CLI, config) for better naming.
+- **Default Model**: Switched from `phi3` to `tinydolphin` for vastly improved local performance.
+- Hardened ingestion pipeline with explicit file size checks after database checkpoints
+- Enhanced MCP gardening tool with tag deduplication logic
+
+## [1.0.19] - 2026-01-07
+
+### Fixed
+- Version reporting: CLI now reads version from `package.json` instead of hardcoded value, ensuring single source of truth
+- Added missing `validate-config` script to package.json for pre-publish checks
+
+### Documentation
+- Added pre-publish checklist to prevent release issues
+
+## [1.0.18] - 2026-01-07
+
+### Added
+- **Configurable notifications**: New `watch.notifications` config option to enable/disable desktop notifications from the daemon
+- Comprehensive documentation for notification settings in example config
+
+### Changed
+- **Cache consolidation**: Moved ML model cache from `.resonance/cache` to `.amalfa/cache` for cleaner project structure
+- All runtime artifacts now in single `.amalfa/` directory (database, logs, PIDs, cache)
+- Updated `.gitignore` and `.npmignore` to reflect new cache location
+
+### Fixed
+- Removed legacy `.resonance/` folder - single source of truth for runtime artifacts
+- Cache directory auto-creates on first use with proper error handling
+
+### Documentation
+- Added brief and debrief for cache consolidation implementation
+- Updated example config with notification settings
+- Clarified single `.amalfa/` directory structure in docs
+
+## [1.0.17] - 2026-01-07
+
+### Added
+- Added `briefs/` folder to watched sources
+- Comprehensive test suite improvements
+
+### Fixed
+- EdgeWeaver tests: Added `getRawDb()` mock for LouvainGate compatibility
+- DatabaseFactory tests: Corrected parameter order for `connectToResonance()`
+- Updated verify scripts with correct DatabaseFactory parameters
+
+### Removed
+- Removed unnecessary tests: `olmo_parsing.test.ts`, `schema.test.ts` (outdated after v6 migration)
+- Skipped daemon integration tests that require full infrastructure
+
+### Testing
+- All core tests passing: 18 pass, 5 skip, 0 fail
+- Database validation passing
+- Deterministic ingestion verified (tear down and rebuild test)
+
+## [1.0.16] - Previous Release
+
+Initial stable release with MCP server, daemon, and vector search capabilities.
+
+---
+
+**Note**: For full details on each release, see the git commit history and associated debrief documents.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "amalfa",
-	"version": "1.0.38",
+	"version": "1.0.40",
 	"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",
@@ -18,6 +18,7 @@
 		"src",
 		"tsconfig.json",
 		"README.md",
+		"CHANGELOG.md",
 		"LICENSE"
 	],
 	"keywords": [

package/src/cli.ts

@@ -53,6 +53,7 @@ Commands:
   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)
+  stop-all (kill)    Stop all running AMALFA services
 
 Options:
   --force            Override pre-flight warnings (errors still block)
@@ -738,6 +739,63 @@ async function cmdServers() {
 	);
 }
 
+async function cmdStopAll() {
+	console.log("🛑 Stopping ALL Amalfa Services...\n");
+
+	// We reuse the service definitions from cmdServers logic,
+	// but abstracted slightly or duplicated for simplicity since they are inside cmdServers
+	const { AMALFA_DIRS } = await import("./config/defaults");
+	const { join } = await import("node:path");
+	const { existsSync, readFileSync, unlinkSync } = await import("node:fs");
+
+	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).`);
+	}
+}
+
 async function cmdValidate() {
 	console.log("🛡️  AMALFA Database Validation\n");
 
@@ -1002,6 +1060,11 @@ async function main() {
 			await cmdServers();
 			break;
 
+		case "stop-all":
+		case "kill":
+			await cmdStopAll();
+			break;
+
 		case "sonar":
 			await cmdSonar();
 			break;

package/src/config/defaults.ts

@@ -44,6 +44,8 @@ export function initAmalfaDirs(): void {
 	}
 }
 
+import type { EmberConfig } from "@src/ember/types";
+
 export interface AmalfaConfig {
 	/** @deprecated Use sources array instead */
 	source?: string;
@@ -77,6 +79,8 @@ export interface AmalfaConfig {
 	sonar: SonarConfig;
 	/** @deprecated Use sonar instead */
 	phi3?: SonarConfig;
+	/** Ember automated enrichment configuration */
+	ember: EmberConfig;
 }
 
 export interface SonarConfig {
@@ -142,12 +146,18 @@ export const DEFAULT_CONFIG: AmalfaConfig = {
 		model: "BAAI/bge-small-en-v1.5",
 		dimensions: 384,
 	},
+	ember: {
+		enabled: true,
+		minConfidence: 0.8,
+		autoSquash: false,
+		backupDir: ".amalfa/backups/ember",
+	},
 	watch: {
 		enabled: true,
 		debounce: 1000,
 		notifications: true,
 	},
-	excludePatterns: ["node_modules", ".git", ".amalfa"],
+	excludePatterns: ["node_modules", ".git", ".amalfa", "tests"],
 	// Optional graph tuning (for advanced use)
 	graph: {
 		tuning: {
@@ -276,6 +286,10 @@ export async function loadConfig(): Promise<AmalfaConfig> {
 							},
 						},
 					} as SonarConfig,
+					ember: {
+						...DEFAULT_CONFIG.ember,
+						...(userConfig.ember || {}),
+					},
 				};
 
 				// Normalize: Convert legacy 'source' to 'sources' array

package/src/daemon/index.ts

@@ -12,6 +12,7 @@ import {
 	type AmalfaConfig,
 	loadConfig,
 } from "@src/config/defaults";
+import { EmberService } from "@src/ember";
 import { AmalfaIngestor } from "@src/pipeline/AmalfaIngestor";
 import { ResonanceDB } from "@src/resonance/db";
 import { getLogger } from "@src/utils/Logger";
@@ -157,6 +158,32 @@ function triggerIngestion(debounceMs: number) {
 			// For now, we'll re-run full ingestion (hash checking prevents duplicates)
 			await ingestor.ingest();
 
+			// --- EMBER INTEGRATION ---
+			if (config.ember?.enabled) {
+				log.info("🔥 Running Ember Analysis...");
+				const ember = new EmberService(db, config.ember);
+				let enrichedCount = 0;
+
+				// Analyze changed files only
+				// Note: Reading again from disk is safer than passing content from ingestor for now
+				for (const file of batch) {
+					try {
+						const content = await Bun.file(file).text();
+						const sidecar = await ember.analyze(file, content);
+						if (sidecar) {
+							await ember.generate(sidecar);
+							enrichedCount++;
+						}
+					} catch (err) {
+						log.warn({ file, err }, "Failed to analyze with Ember");
+					}
+				}
+				if (enrichedCount > 0) {
+					log.info({ enrichedCount }, "🔥 Ember enriched files");
+				}
+			}
+			// -------------------------
+
 			db.close();
 
 			log.info({ files: batchSize }, "✅ Update complete");

package/src/ember/index.ts

@@ -5,7 +5,7 @@ import { Glob } from "bun";
 import { EmberAnalyzer } from "./analyzer";
 import { EmberGenerator } from "./generator";
 import { EmberSquasher } from "./squasher";
-import type { EmberConfig } from "./types";
+import type { EmberConfig, EmberSidecar } from "./types";
 
 export class EmberService {
 	private analyzer: EmberAnalyzer;
@@ -50,6 +50,20 @@ export class EmberService {
 		return enrichedCount;
 	}
 
+	/**
+	 * Analyze a single file
+	 */
+	async analyze(filePath: string, content: string) {
+		return this.analyzer.analyze(filePath, content);
+	}
+
+	/**
+	 * Generate a sidecar file
+	 */
+	async generate(sidecar: EmberSidecar) {
+		return this.generator.generate(sidecar);
+	}
+
 	/**
 	 * Squash all pending sidecars
 	 */
@@ -71,8 +85,9 @@ export class EmberService {
 	private async findSidecars(): Promise<string[]> {
 		const sidecars: string[] = [];
 		const glob = new Glob("**/*.ember.json");
+		const sources = this.config.sources || ["./docs"];
 		// Scan sources
-		for (const source of this.config.sources) {
+		for (const source of sources) {
 			// Assuming source is like "./docs"
 			const sourcePath = join(process.cwd(), source);
 			for (const file of glob.scanSync({ cwd: sourcePath })) {
@@ -85,14 +100,14 @@ export class EmberService {
 	private async discoverFiles(): Promise<string[]> {
 		const files: string[] = [];
 		const glob = new Glob("**/*.{md,mdx}"); // Only markdown for now
+		const sources = this.config.sources || ["./docs"];
+		const excludes = this.config.excludePatterns || [];
 
-		for (const source of this.config.sources) {
+		for (const source of 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),
-					);
+					const shouldExclude = excludes.some((p) => file.includes(p));
 					if (!shouldExclude) {
 						files.push(join(sourcePath, file));
 					}

package/src/ember/types.ts

@@ -17,10 +17,11 @@ export interface EmberSidecar {
 
 export interface EmberConfig {
 	enabled: boolean;
-	sources: string[];
+	sources?: string[];
 	minConfidence: number;
 	backupDir: string;
-	excludePatterns: string[];
+	excludePatterns?: string[];
+	autoSquash?: boolean;
 }
 
 export type EnrichmentType = "tag" | "link" | "summary" | "metadata";