amalfa 0.0.0-reserved → 1.0.0

package/.biomeignore

@@ -0,0 +1,19 @@
+**/*-bak.html
+**/*.bak
+public/layout-test.html
+public/test
+public/js
+public/css/app.css
+node_modules
+dist
+.DS_Store
+**/*.py
+**/*.c
+**/*.cpp
+**/*.h
+**/*.hpp
+**/*.sh
+**/*.txt
+docs
+examples
+experiments

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Polyvis Project Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,25 +2,355 @@
 
 **A Memory Layer For Agents**
 
-🚧 **Coming Soon** 🚧
+A local-first knowledge graph engine that transforms your markdown files into a searchable memory layer for AI agents. Built for privacy, speed, and zero API costs.
 
-AMALFA is an MCP (Model Context Protocol) server that gives AI agents access to your project's knowledge graph.
+[![NPM Version](https://img.shields.io/npm/v/amalfa)](https://www.npmjs.com/package/amalfa)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Planned Features
+## Why AMALFA?
 
-- 🔍 Vector search over markdown documentation
-- 📊 Graph traversal (relationships between docs)
-- 🧠 Works with Claude Desktop, Cursor, Windsurf
-- ⚡ Built with Bun + SQLite + FastEmbed
-- 🔒 Local-first, privacy-focused
+AI agents need memory. AMALFA provides:
 
-## Status
+- **🔒 Privacy-first**: Your data never leaves your machine
+- **⚡️ Fast**: SQLite + vector embeddings for sub-second search
+- **💰 Zero cost**: No API calls, no subscriptions
+- **📝 Markdown native**: Your notes are the source of truth
+- **🔄 Real-time**: File watcher keeps your knowledge graph up-to-date
+- **🤖 Agent-ready**: MCP protocol integration with Claude Desktop
 
-Currently in development. Watch this space!
+## Quick Start
 
-**GitHub:** [Coming Soon]  
-**Author:** @polyvis
+### Installation
+
+```bash
+# Install globally
+bun add -g amalfa
+
+# Or use with bunx
+bunx amalfa --help
+```
+
+### Initialize Your Knowledge Graph
+
+```bash
+# 1. Navigate to your project with markdown files
+cd ~/Documents/my-notes
+
+# 2. Initialize AMALFA (creates .amalfa/resonance.db)
+amalfa init
+
+# 3. Start the file watcher (optional)
+amalfa daemon start
+
+# 4. Connect to Claude Desktop (see Configuration below)
+```
+
+## Configuration
+
+Create `amalfa.config.json` in your project root:
+
+```json
+{
+  "source": "./docs",
+  "database": ".amalfa/resonance.db",
+  "embeddings": {
+    "model": "BAAI/bge-small-en-v1.5",
+    "dimensions": 384
+  },
+  "watch": {
+    "enabled": true,
+    "debounce": 1000
+  },
+  "excludePatterns": ["node_modules", ".git", ".amalfa"]
+}
+```
+
+Or use TypeScript:
+
+```typescript
+// amalfa.config.ts
+export default {
+  source: "./docs",
+  database: ".amalfa/resonance.db",
+  // ... rest of config
+};
+```
+
+### Claude Desktop Integration
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "amalfa": {
+      "command": "amalfa",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, and you'll see AMALFA tools available in the conversation.
+
+## CLI Commands
+
+### `amalfa init`
+
+Initialize knowledge graph from markdown files.
+
+```bash
+amalfa init
+```
+
+**What it does:**
+- Scans your source directory for `.md` files
+- Generates vector embeddings (384 dimensions)
+- Extracts WikiLinks (`[[links]]`) and semantic tags
+- Creates edges between related documents
+- Stores everything in SQLite with WAL mode
+
+**Output:**
+```
+📚 Starting ingestion from: ./docs
+📁 Found 127 markdown files
+  100% (127/127)
+✅ Initialization complete!
+
+📊 Summary:
+  Files processed: 127
+  Nodes created: 127
+  Edges created: 243
+  Embeddings: 127
+  Duration: 8.42s
+```
+
+### `amalfa daemon <action>`
+
+Manage the file watcher daemon.
+
+```bash
+amalfa daemon start   # Start watching for changes
+amalfa daemon stop    # Stop the daemon
+amalfa daemon status  # Check if running
+amalfa daemon restart # Restart daemon
+```
+
+**Features:**
+- Watches source directory recursively
+- Debounced updates (1s default)
+- Hash-based change detection (only processes modified files)
+- Retry logic with exponential backoff
+- Native macOS notifications
+
+### `amalfa serve`
+
+Start MCP server for Claude Desktop (stdio transport).
+
+```bash
+amalfa serve
+```
+
+**Available Tools:**
+- `search_knowledge`: Semantic search across all documents
+- `get_node`: Retrieve specific document by ID
+- `get_neighbors`: Find related documents (graph traversal)
+
+See [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) for detailed tool schemas.
+
+### `amalfa stats`
+
+View knowledge graph statistics.
+
+```bash
+amalfa stats
+```
+
+### `amalfa doctor`
+
+Health check and diagnostics.
+
+```bash
+amalfa doctor
+```
+
+## Architecture
+
+### Philosophy: Markdown is Truth
+
+AMALFA implements the **"Hollow Nodes"** pattern:
+
+- **Markdown files** = Source of truth (version controlled, human-readable)
+- **SQLite database** = Ephemeral cache (can be regenerated anytime)
+
+This means:
+- ✅ You can delete `.amalfa/` and rebuild with `amalfa init`
+- ✅ Your markdown files remain the canonical source
+- ✅ Database changes are never written back to files
+- ✅ No lock-in, no vendor formats
+
+### Technology Stack
+
+- **Runtime**: Bun (fast, modern JavaScript runtime)
+- **Database**: SQLite with WAL mode
+- **Embeddings**: FastEmbed (local, no API calls)
+- **Vectors**: 384-dimensional (BAAI/bge-small-en-v1.5)
+- **Search**: Pure dot product (cosine similarity)
+- **Protocol**: Model Context Protocol (MCP)
+
+### File Structure
+
+```
+your-project/
+├── docs/                    # Your markdown files
+│   ├── README.md
+│   ├── architecture.md
+│   └── ...
+├── .amalfa/                 # AMALFA data (gitignored)
+│   └── resonance.db         # SQLite database (2-5 MB typical)
+├── amalfa.config.json       # Configuration (optional)
+└── .amalfa-daemon.pid       # Daemon process ID (if running)
+```
+
+## Features
+
+### Vector Search (FAFCAS Protocol)
+
+Fast, accurate search without a vector database:
+
+- L2-normalized embeddings (unit vectors)
+- Pure dot product = cosine similarity
+- 85%+ accuracy at <10ms per query
+- No chunking needed (markdown files are already chunk-sized)
+
+### Edge Weaving
+
+Automatic relationship detection:
+
+- **WikiLinks**: `[[Document Name]]` creates `CITES` edges
+- **Tags**: `[tag: Concept]` creates `TAGGED_AS` edges
+- **Metadata**: `<!-- tags: [RELATION: Target] -->` for explicit edges
+- **Louvain Gate**: Prevents graph pollution (community detection)
+
+### Incremental Updates
+
+The daemon watches for changes and only re-processes modified files:
+
+- MD5 hash tracking
+- Batch transactions (50 files)
+- Debounced (1s default)
+- Automatic retry on failure (3 attempts, exponential backoff)
+
+## Use Cases
+
+### Personal Knowledge Base
+
+```bash
+# Your notes directory
+cd ~/Documents/notes
+amalfa init
+amalfa daemon start
+
+# Now ask Claude: "What did I write about X?"
+# Claude uses AMALFA to search your notes
+```
+
+### Project Documentation
+
+```bash
+# Your project's docs
+cd ~/Code/my-project
+amalfa init
+
+# Ask Claude: "Explain the architecture"
+# Claude searches ./docs and provides context
+```
+
+### Research & Zettelkasten
+
+```bash
+# Zettelkasten notes
+cd ~/Zettelkasten
+amalfa init
+
+# Ask Claude: "Find connections between concept A and B"
+# Claude traverses the knowledge graph
+```
+
+## Troubleshooting
+
+### Daemon won't start
+
+Check logs:
+```bash
+tail -f .amalfa-daemon.log
+```
+
+Common issues:
+- Source directory doesn't exist
+- Database permissions
+- Port conflicts (if running multiple instances)
+
+### Database corruption
+
+Rebuild from markdown:
+```bash
+rm -rf .amalfa/
+amalfa init
+```
+
+Your markdown files are the source of truth, so this is always safe.
+
+### Slow initialization
+
+Large repositories (1000+ files) may take 2-5 minutes on first run. Subsequent updates are fast (hash checking prevents re-processing).
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/pjsvis/amalfa.git
+cd amalfa
+
+# Install dependencies
+bun install
+
+# Run CLI locally
+bun run src/cli.ts help
+
+# Run tests
+bun test
+
+# Type checking
+bun run tsc --noEmit
+```
+
+## Roadmap
+
+- [ ] v1.1: Web UI for graph visualization
+- [ ] v1.2: Multi-language embedding models
+- [ ] v1.3: PDF/DOCX support
+- [ ] v2.0: Distributed sync (private P2P)
+
+## Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Credits
+
+Built with:
+- [Bun](https://bun.sh) - Fast JavaScript runtime
+- [FastEmbed](https://github.com/qdrant/fastembed) - Local embeddings
+- [Model Context Protocol](https://modelcontextprotocol.io) - AI agent integration
 
 ---
 
-_This is a placeholder package to reserve the name. v1.0.0 coming soon._
+**AMALFA** = **A Memory Layer For Agents**
+
+Give your AI agents a memory. Keep your privacy. Own your data.
+
+**[GitHub](https://github.com/pjsvis/amalfa)** • **[NPM](https://www.npmjs.com/package/amalfa)** • **[Issues](https://github.com/pjsvis/amalfa/issues)**

package/README.old.md

@@ -0,0 +1,112 @@
+# Polyvis: A Neuro-Symbolic Graph Visualizer
+
+Polyvis is a lightweight, frontend-only web application for exploring and visualizing neuro-symbolic knowledge graphs. It renders conceptual relationships from a pre-built SQLite database, allowing users to navigate a "Neuro-Map" of interconnected ideas, principles, and directives.
+
+The application is built with HTML, CSS, and [Alpine.js](https://alpinejs.dev/), and uses [Bun](https://bun.sh/) as its JavaScript runtime and toolkit. The graph visualization is powered by [viz.js](https://github.com/mdaines/viz.js) and [Sigma.js](https://www.sigmajs.org/), and the in-browser database is handled by [sql.js](https://sql.js.org/).
+
+## Features
+
+- **Interactive Graph Visualization:** Explore the knowledge graph by searching for terms.
+- **Data-Driven Suggestions:** The search box provides a curated list of high-value terms guaranteed to produce rich, interesting graphs.
+- **In-Browser Database:** The entire graph dataset is loaded into the browser via sql.js, requiring no active backend server for querying.
+- **Alpine.js Reactivity:** Uses [Alpine.js](https://alpinejs.dev/) for a lightweight, reactive UI without a complex build step.
+- **Zero-Build Frontend:** Built with vanilla web technologies and Alpine.js for maximum simplicity and performance.
+- **Themable UI:** All design tokens (colors, dimensions) are centralized in `src/css/layers/theme.css` ("The Control Panel") for easy customization.
+- **Semantic Styling:** No magic numbers. All styles use semantic variables (e.g., `--surface-panel`, `--border-base`) for consistent theming.
+- **Efficient Search:** Two-tier search architecture (vector embeddings + grep) - no FTS or chunking needed.
+
+## Search Architecture
+
+Polyvis uses a **two-tier search system** that eliminates the need for full-text search (FTS) or document chunking:
+
+### 1. Vector Search (Semantic)
+- **Purpose:** Semantic similarity, concept discovery
+- **Accuracy:** 85% average best match across diverse queries
+- **Speed:** <10ms per query
+- **Use case:** "Find documents about CSS patterns" or "Show me graph weaving logic"
+
+### 2. Grep/Ripgrep (Literal)
+- **Purpose:** Exact phrase matches, symbol lookup
+- **Accuracy:** 100% (literal text matching)
+- **Speed:** <1ms
+- **Use case:** "Find exact phrase 'function fooBar'" or "Where is BentoBoxer imported?"
+
+### Why No Chunking?
+
+**Document corpus characteristics:**
+- 80% of documents are <5KB (~1,000 words) - already "chunk-sized"
+- Average document: 2.7KB (~550 words)
+- Largest document: 47KB (~9,500 words) - still within LLM context windows
+
+**Results without chunking:**
+- Vector search achieves 85% accuracy on whole documents
+- Documents are well-structured markdown with clear headers
+- Natural granularity matches search needs
+
+**Future strategy:** If large documents (>20KB) become problematic, split them into multiple markdown files at natural boundaries (H1/H2 headers) and commit to version control. This keeps source files as the source of truth, maintains git-friendly diffs, and requires no runtime infrastructure.
+
+**See:** `docs/BENTO_BOXING_DEPRECATION.md` for full analysis and decision rationale.
+
+## Design System (The Control Center)
+The application's visual design is strictly controlled by **`src/css/layers/theme.css`**. This file acts as a configuration panel for:
+-   **Dimensions:** Sidebar widths, header heights.
+-   **Colors:** Semantic mappings (e.g., `--surface-1`, `--brand`).
+-   **Spacing:** Global padding and gaps.
+
+**Protocol:** Always check and tweak `theme.css` before modifying component styles.
+
+## Prerequisites
+
+- [Bun.js](https://bun.sh/docs/installation) (v1.0 or later) - **MANDATORY**
+- A local web server for development (e.g., `bun x http-server`)
+
+## Getting Started
+
+Follow these steps to set up and run the project locally.
+
+### 1. Installation
+
+There are no external dependencies to install for the application itself, as it relies on vanilla JavaScript and CDN-hosted libraries.
+
+### 2. Development Workflow
+
+For detailed instructions on CSS development, database building, and running the app, please refer to the **[Development Workflow Playbook](playbooks/development-workflow-playbook.md)**.
+
+**Quick Start:**
+1.  **Dev Mode:** `bun run dev` (Starts server & CSS watcher)
+2.  **Build DB:** `bun run scripts/build_db.ts`
+
+## Project Structure
+
+### 3. Detailed Documentation
+For a deep dive on the codebase organization, please see **[Project Structure](docs/webdocs/project-structure.md)**.
+
+## Project Structure (High Level)
+
+```
+├── public/              # Web Root (HTML, Static Data)
+│   ├── explorer/        # Sigma.js Graph Explorer
+│   └── resonance.db     # SQLite Database (generated locally)
+│
+├── src/                 # Application Source Code
+│   ├── core/            # The Bento Box Kernel (Normalizer, Weaver)
+│   ├── config/          # Shared Configuration
+│   └── db/              # Database Schemas
+│
+├── scripts/             # Data Pipeline & Tooling
+│   ├── pipeline/        # ETL Scripts (Sync, Load)
+│   ├── cli/             # Command Line Tools (Harvest)
+│   └── verify/          # Integrity Checks
+│
+├── docs/                # Project Documentation
+├── playbooks/           # Operational Protocols
+├── polyvis.settings.json # Central Configuration
+└── README.md            # This file
+```
+
+## Contributing
+## Contribution Guidelines
+Please review `AGENTS.md` for our operational protocols, specifically:
+-   **EVP (Empirical Verification Protocol):** Use the browser to verify, don't guess.
+-   **GEP (Granular Execution Protocol):** One step at a time.
+ Please feel free to open issues or submit pull requests.

package/agents.config.json

@@ -0,0 +1,11 @@
+{
+	"nanocoder": {
+		"providers": [
+			{
+				"name": "ollama",
+				"models": ["llama3.1:8b"],
+				"baseUrl": "http://localhost:11434/v1"
+			}
+		]
+	}
+}

package/amalfa.config.example.ts

@@ -0,0 +1,100 @@
+/**
+ * AMALFA Configuration Example
+ * 
+ * Copy this file to your project root as:
+ * - amalfa.config.ts (TypeScript)
+ * - amalfa.config.js (JavaScript)
+ * - amalfa.config.json (JSON)
+ */
+
+export default {
+	/**
+	 * Source directory containing markdown files
+	 * Relative to project root
+	 * 
+	 * Examples:
+	 * - "./docs" - Standard documentation folder
+	 * - "./notes" - Personal notes
+	 * - "./content" - Content management
+	 * - "." - Current directory (scans all .md files)
+	 */
+	source: "./docs",
+
+	/**
+	 * Database file location
+	 * Relative to project root
+	 * 
+	 * The .amalfa directory is gitignored by default.
+	 * The database can be regenerated from markdown at any time.
+	 */
+	database: ".amalfa/resonance.db",
+
+	/**
+	 * Embedding configuration
+	 */
+	embeddings: {
+		/**
+		 * Embedding model to use
+		 * 
+		 * Options:
+		 * - "BAAI/bge-small-en-v1.5" (default) - Best balance (384 dims)
+		 * - "sentence-transformers/all-MiniLM-L6-v2" - Faster (384 dims)
+		 * - "BAAI/bge-base-en-v1.5" - More accurate (768 dims, slower)
+		 * 
+		 * Models are downloaded on first use to .resonance/cache/
+		 */
+		model: "BAAI/bge-small-en-v1.5",
+
+		/**
+		 * Vector dimensions
+		 * Must match the model's output size
+		 * 
+		 * Common dimensions:
+		 * - 384: Most small models
+		 * - 768: Most base models
+		 * - 1024: Large models
+		 */
+		dimensions: 384,
+	},
+
+	/**
+	 * File watcher configuration
+	 */
+	watch: {
+		/**
+		 * Enable file watching
+		 * Used by 'amalfa daemon' command
+		 */
+		enabled: true,
+
+		/**
+		 * Debounce delay in milliseconds
+		 * 
+		 * How long to wait after the last file change before
+		 * triggering re-ingestion. This prevents excessive
+		 * processing during rapid file edits.
+		 * 
+		 * Recommended:
+		 * - 1000ms (1 second) - Default, good for most cases
+		 * - 500ms - More responsive, slightly higher CPU
+		 * - 2000ms - Less responsive, lower CPU
+		 */
+		debounce: 1000,
+	},
+
+	/**
+	 * Patterns to exclude from ingestion
+	 * 
+	 * Files/directories matching these patterns are ignored.
+	 * Patterns are checked with String.includes(), not glob.
+	 * 
+	 * Common exclusions:
+	 * - "node_modules" - JavaScript dependencies
+	 * - ".git" - Git internals
+	 * - ".amalfa" - AMALFA data directory
+	 * - "vendor" - PHP dependencies
+	 * - "target" - Rust build artifacts
+	 * - "dist" - Build output
+	 */
+	excludePatterns: ["node_modules", ".git", ".amalfa"],
+};

package/biome.json

@@ -0,0 +1,49 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"includes": [
+			"src/**",
+			"scripts/**",
+			"tests/**",
+			"*.ts",
+			"*.js",
+			"*.json",
+			"*.css"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"css": {
+		"parser": {
+			"cssModules": true,
+			"tailwindDirectives": true
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}