amalfa 0.0.0-reserved → 1.0.1

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/CHANGELOG.md.old

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to the **PolyVis** project 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).
+
+## [Unreleased] - 2025-12-31
+### Added
+- **UI:** Implemented "Terminal Brutalist" design system (High-Contrast / Low-Noise).
+- **UI:** Added "Vision Helper" (`window.__AGENT_THEME__`) for programmatic theme detection by agents.
+- **UI:** Added "Style Auditor" (`window.runStyleAudit()`) for runtime CSS integrity checks.
+- **UI:** Added "Hollow" vs "Full" node visualization states in `sigma.js` renderer.
+- **UI:** Added "Agent Activity" indicator color (`--ansi-orange` / `#FF8C00`).
+- **Arch:** Added "FAFCAS" Protocol (Feature Alignment / Frequency Correction / Amplitude Scaling) for normalized embeddings.
+- **Docs:** Added `CHANGELOG.md` as a primary context source.
+
+### Changed
+- **UI:** Replaced generic color palette with strict **ANSI Standard** variables (`basecoat-css`).
+- **UI:** Enforced `border-radius: 0px` global reset.
+- **UI:** Refactored Home Page to "Vertical Monolith" layout (5:8 Aspect Ratio).
+- **UI:** Updated Navbar Brand to use `--ansi-cyan` (System Identity).
+- **UI:** Implemented "Semantic Inversion" for hover states (High Contrast).
+- **Arch:** Initiated migration from `fastembed` to `model2vec` (Pending Benchmark results).
+- **Arch:** Deprecated "Context Engineering" in favor of "Constraint Stacking" for Agent prompts.
+
+### Fixed
+- **Code:** Resolved all Biome linting issues (`noExplicitAny`, `noStaticOnlyClass`).
+- **Code:** Eliminated strict TypeScript errors across the codebase.
+- **Code:** Refactored static-only classes to `export const` objects for better tree-shaking and simplicity.
+- **Code:** Strong typing for Database Query results (removed `any` casting).
+
+### Removed
+- **UI:** Removed all shadows, gradients, and non-monospace fonts.
+- **UI:** Removed "Soft" interaction states (transitions/fades) in favor of "Hard" inversions.
+
+## [1.0.0] - 2025-12-29
+### Added
+- **Core:** Initial release of the "Hollow Node" architecture.
+- **Runtime:** Validated **Bun** + **SQLite** (`bun:sqlite`) substrate.
+- **Visor:** Canvas-based Graph rendering via `sigma.js`.
+- **Agent:** MCP Server implementation with `search_documents` and `read_node` tools.
+- **Pipeline:** "Semantic Harvester" python bridge for initial ingestion.

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,371 @@
 
 **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
+{
+  "sources": ["./docs", "./notes"],
+  "database": ".amalfa/resonance.db",
+  "embeddings": {
+    "model": "BAAI/bge-small-en-v1.5",
+    "dimensions": 384
+  },
+  "watch": {
+    "enabled": true,
+    "debounce": 1000
+  },
+  "excludePatterns": ["node_modules", ".git", ".amalfa"]
+}
+```
+
+**New in v1.0.1:** Multi-source support! Use `sources` array to scan multiple directories. Single `source` string still works (auto-migrates).
+
+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 [--force]`
+
+Initialize knowledge graph from markdown files with pre-flight validation.
+
+```bash
+amalfa init          # With validation
+amalfa init --force  # Override warnings (use with caution)
+```
+
+**What it does:**
+- **Pre-flight validation** (v1.0.1): Checks for large files, symlinks, circular references
+- Scans your source directories for `.md` files
+- Generates vector embeddings (384 dimensions)
+- Extracts WikiLinks (`[[links]]`) and semantic tags
+- Creates edges between related documents
+- Stores metadata in SQLite (content in filesystem - "hollow nodes")
+
+**Pre-Flight Protection** (v1.0.1):
+- Blocks files >10MB (prevents memory issues)
+- Detects symlink loops (prevents infinite recursion)
+- Warns about small files (<50 bytes) and large corpora (10K+ files)
+- Generates `.amalfa-pre-flight.log` with actionable recommendations
+- Use `--force` to override warnings (errors still block)
+
+**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)
+
+**v1.0.1 Enhancement:** Schema v6 fully implements hollow nodes - content is never stored in the database, only metadata and embeddings. This reduces database size dramatically (~350MB saved for 70K documents) and maintains the filesystem as the single source of truth.
+
+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
+- ✅ Smaller databases, faster writes (v1.0.1)
+
+### 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 (schema v6 - hollow nodes)
+├── amalfa.config.json       # Configuration (optional)
+├── .amalfa-daemon.pid       # Daemon process ID (if running)
+├── .amalfa-daemon.log       # Daemon logs
+└── .amalfa-pre-flight.log   # Validation report (generated by init)
+```
+
+## 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.