amalfa 1.4.0 → 1.4.3

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.4.3] - 2026-01-16
+### Documentation
+- Bump to 1.4.3
+
+## [1.4.2] - 2026-01-16
+### Documentation
+- Created `docs/USER-MANUAL.md` as the definitive guide for configuration and operations.
+- Refactored `README.md` to be a lighter landing page.
+
+## [1.4.1] - 2026-01-16
+### Documentation
+- Updated README.md with Tiered Maintenance Strategy and Sub-Agent documentation.
+
 ## [1.4.0] - 2026-01-16
 
 ### Added

package/README.md

@@ -34,7 +34,9 @@ Built with **Bun + SQLite + FastEmbed**.
 
 **Current state:** AI agents lose context between sessions. Knowledge resets. Same problems get re-solved.
 
-**Amalfa solves this:** Agents write structured reflections (briefs → work → debriefs → playbooks). Amalfa indexes this as a queryable knowledge graph with semantic search.
+**Amalfa solves this:** Agents write structured reflections (Write Brief → Do Work → Write Debrief → Update Playbooks). Amalfa indexes this as a queryable knowledge graph with semantic search.
+
+👉 **Deep Dive:** [Why Structured Reflection Beats Infinite Context](docs/WHY-STRUCTURED-REFLECTION.md)
 
 **Result:** Agents can query "What did we learn about authentication?" and get ranked, relevant past work—even across different agents and sessions.
 
@@ -77,25 +79,14 @@ MCP Server (AI agents)
 
 **Distinguisher**: Unlike traditional systems where the database *is* the truth, AMALFA inverts this. Your prose is permanent, the index is disposable.
 
-### When to Re-Ingest
-
-Just delete `.amalfa/` and re-run ingestion:
+### Troubleshooting & Maintenance
 
-```bash
-rm -rf .amalfa/
-bun run scripts/cli/ingest.ts
-```
+Amalfa employs a tiered maintenance strategy. For standard issues, run `amalfa doctor`. For data updates, run `amalfa init`.
 
-**Common scenarios**:
-- After upgrading AMALFA versions
-- When experiencing search issues
-- When changing embedding models
-- After adding/modifying many documents
-- Anytime you want a clean slate
+👉 **Full Guide:** [User Manual - Maintenance & Troubleshooting](docs/USER-MANUAL.md#6-maintenance--troubleshooting)
 
-**Speed**: 308 nodes in <1 second. Re-ingestion is fast enough to be casual.
 
-### Brief-Debrief-Playbook Pattern
+### Write Brief → Do Work → Write Debrief → Update Playbooks Pattern
 
 ```
 Brief (task spec)
@@ -131,25 +122,62 @@ Amalfa **automatically** adds:
 
 **Agents don't maintain metadata manually.** Amalfa handles it via git-audited auto-augmentation.
 
-### Latent Space Tagging
+---
 
-**Innovation:** Tags emerge from vector clustering, not predefined taxonomy.
+## Sub-Agents & Discovery
 
-```python
-# Cluster documents in embedding space
-clusters = cluster(all_docs, min_size=3)
+Amalfa orchestrates specialized sub-agents (Vector, Reranker, Sonar) to provide intelligence.
 
-# Generate labels from cluster content
-for cluster in clusters:
-    label = generate_label(cluster.docs)  # e.g., "auth-state-patterns"
-    for doc in cluster:
-        doc.add_tag(f"latent:{label}", confidence_score)
-```
+*   **Vector Daemon**: Handles embeddings.
+*   **Reranker Daemon**: Re-scores search results for precision.
+*   **Sonar Agent**: Performs reasoning and deep research using local LLMs (Ollama) or Cloud APIs.
+
+👉 **Full Guide:** [User Manual - Services & Sub-Agents](docs/USER-MANUAL.md#5-services--sub-agents)
 
-**Result:** Self-organizing knowledge base that adapts as it grows.
 
 ---
 
+## Architecture
+
+### Technology Stack
+
+- **Runtime:** Bun (fast, TypeScript-native)
+- **Database:** SQLite with WAL mode (local-first, portable)
+- **Embeddings:** FastEmbed (`bge-small-en-v1.5`, 384 dims)
+- **Reranking:** Xenova Transformers (`bge-reranker-base`)
+- **Protocol:** Model Context Protocol (MCP)
+
+### Project Structure
+
+```
+amalfa/
+├── src/
+│   ├── mcp/           # MCP server implementation
+│   ├── resonance/     # Database layer (SQLite wrapper)
+│   ├── core/          # Graph processing (EdgeWeaver, VectorEngine)
+│   └── utils/         # Logging, validation, lifecycle
+├── scripts/
+│   ├── cli/           # Command-line tools
+│   └── pipeline/      # Data ingestion pipeline
+├── docs/
+│   ├── VISION-AGENT-LEARNING.md        # Core vision
+│   ├── AGENT-METADATA-PATTERNS.md      # Auto-augmentation design
+│   └── SETUP.md                        # NPM publishing guide
+├── briefs/            # Task specifications
+├── debriefs/          # Reflective documents
+└── playbooks/         # Codified patterns
+```
+
+### Key Patterns
+
+1.  **Hollow Nodes:** Node metadata in SQLite, content on filesystem
+2.  **FAFCAS Protocol:** Embedding normalization that enables scalar product searches (10x faster than cosine similarity)
+3.  **Micro-Daemon Mesh:**
+    *   **Vector Daemon (3010)**: Embeddings
+    *   **Reranker Daemon (3011)**: Relevance Scoring
+    *   **Sonar Agent (3012)**: Reasoning loop
+4.  **ServiceLifecycle:** Unified daemon management pattern
+
 ## Quick Start
 
 ### Installation
@@ -206,91 +234,19 @@ bun install
 
 ---
 
-## Architecture
-
-### Technology Stack
 
-- **Runtime:** Bun (fast, TypeScript-native)
-- **Database:** SQLite with WAL mode (local-first, portable)
-- **Embeddings:** FastEmbed (`all-MiniLM-L6-v2`, 384 dims)
-- **Search:** Vector similarity + full-text (FTS5)
-- **Protocol:** Model Context Protocol (MCP)
-
-### Project Structure
-
-```
-amalfa/
-├── src/
-│   ├── mcp/           # MCP server implementation
-│   ├── resonance/     # Database layer (SQLite wrapper)
-│   ├── core/          # Graph processing (EdgeWeaver, VectorEngine)
-│   └── utils/         # Logging, validation, lifecycle
-├── scripts/
-│   ├── cli/           # Command-line tools
-│   └── pipeline/      # Data ingestion pipeline
-├── docs/
-│   ├── VISION-AGENT-LEARNING.md        # Core vision
-│   ├── AGENT-METADATA-PATTERNS.md      # Auto-augmentation design
-│   └── SETUP.md                        # NPM publishing guide
-├── briefs/            # Task specifications
-├── debriefs/          # Reflective documents
-└── playbooks/         # Codified patterns
-```
-
-### Key Patterns
-
-1. **Hollow Nodes:** Node metadata in SQLite, content on filesystem
-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:
-
-![AMALFA Workflow](https://raw.githubusercontent.com/pjsvis/amalfa/main/docs/workflow.png)
-
-**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.
-
-**TL;DR:**
-
-Agents generate knowledge through structured reflection. Amalfa provides semantic infrastructure to make this knowledge:
-
-- **Queryable** (vector search + graph traversal)
-- **Persistent** (across sessions and agents)
-- **Self-organizing** (latent space clustering)
-- **Auditable** (git-based workflow)
-
-**The goal:** Enable agents to maintain institutional memory without human bottlenecks.
-
----
 
 ## Implementation Status
 
-### ✅ Core Functionality (v1.0 - Released)
+### ✅ Core Functionality (v1.4.0 - Released)
 
 - ✅ **MCP Server** - stdio transport, tools, resources
 - ✅ **Vector Search** - FastEmbed embeddings (384-dim), semantic search
+- ✅ **Reranking** - BGE-M3 cross-encoder for high precision
 - ✅ **Database** - SQLite with hollow nodes, FAFCAS protocol
 - ✅ **Ingestion Pipeline** - Markdown → nodes + embeddings
-- ✅ **CLI** - init, serve, stats, doctor, servers, daemon, vector
-- ✅ **Service Management** - Vector daemon, file watcher, lifecycle
+- ✅ **CLI** - init, serve, stats, doctor, servers, daemon, vector, reranker
+- ✅ **Service Management** - Vector/Reranker daemons, file watcher, Sonar agent
 - ✅ **Pre-flight Validation** - Check markdown before ingestion
 
 ### 🚧 Phase 1: Auto-Augmentation (In Progress)

package/package.json

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