amalfa 1.0.2 → 1.0.4

package/docs/MCP_SETUP.md

@@ -1,317 +0,0 @@
-# AMALFA MCP Server Setup
-
-**Guide to configuring AMALFA as an MCP server for Claude Desktop, Cursor, Windsurf, and other MCP clients.**
-
----
-
-## Prerequisites
-
-1. **Bun installed** (`v1.0+`)
-2. **AMALFA repository cloned** and dependencies installed:
-   ```bash
-   git clone https://github.com/pjsvis/amalfa.git
-   cd amalfa
-   bun install
-   ```
-3. **Database initialized** (see Data Preparation below)
-
----
-
-## Step 1: Prepare Your Data
-
-Before starting the MCP server, you need to:
-
-1. **Configure sources** in `amalfa.config.json`:
-   ```json
-   {
-     "sources": ["./docs", "./playbooks"],
-     "database": ".amalfa/resonance.db",
-     "embeddings": {
-       "model": "BAAI/bge-small-en-v1.5",
-       "dimensions": 384
-     }
-   }
-   ```
-
-2. **Ingest your markdown documents**:
-   ```bash
-   bun run scripts/cli/ingest.ts
-   ```
-   
-   This will:
-   - Parse all markdown files from your source directories
-   - Generate embeddings (first run downloads the model to `.amalfa/cache/`)
-   - Create the SQLite database at `.amalfa/resonance.db`
-
----
-
-## Step 2: Generate MCP Configuration
-
-Run the setup script to generate your machine-specific config:
-
-```bash
-bun run scripts/setup_mcp.ts
-```
-
-This will output configuration JSON like:
-
-```json
-{
-  "mcpServers": {
-    "amalfa": {
-      "command": "bun",
-      "args": [
-        "run",
-        "/absolute/path/to/amalfa/src/mcp/index.ts"
-      ],
-      "env": {
-        "PATH": "..."
-      }
-    }
-  }
-}
-```
-
-**Important:** The path is absolute and machine-specific. If you move the amalfa folder, run this script again.
-
----
-
-## Step 3: Configure Your MCP Client
-
-### Claude Desktop (macOS)
-
-1. **Open Claude Desktop config**:
-   ```bash
-   open ~/Library/Application\ Support/Claude/claude_desktop_config.json
-   ```
-   
-   Or create it if it doesn't exist:
-   ```bash
-   mkdir -p ~/Library/Application\ Support/Claude
-   touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
-   ```
-
-2. **Add the AMALFA server** to the `mcpServers` section:
-   ```json
-   {
-     "mcpServers": {
-       "amalfa": {
-         "command": "bun",
-         "args": [
-           "run",
-           "/Users/yourusername/path/to/amalfa/src/mcp/index.ts"
-         ],
-         "env": {
-           "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
-         }
-       }
-     }
-   }
-   ```
-   
-   **Note:** Use the exact JSON output from Step 2.
-
-3. **Restart Claude Desktop**
-
-4. **Verify connection**: In Claude Desktop, check the MCP icon/status—you should see "amalfa" listed as a connected server.
-
-### Cursor / Windsurf
-
-Check your IDE's MCP configuration documentation. The setup is similar—add the JSON block to the appropriate config file.
-
----
-
-## Step 4: Test the Connection
-
-### From Claude Desktop
-
-Ask Claude:
-
-```
-Search my knowledge base for "embeddings"
-```
-
-Claude should use the `search_documents` tool and return results from your markdown files.
-
-### From Command Line (Debug Mode)
-
-You can test the MCP server directly:
-
-```bash
-bun run src/mcp/index.ts
-```
-
-This starts the server in stdio mode. It will log to `.mcp.log`.
-
-Check the logs:
-```bash
-tail -f .amalfa/.mcp.log
-```
-
----
-
-## Available MCP Tools
-
-Once connected, your AI agent can use these tools:
-
-### 1. `search_documents`
-**Description:** Semantic search over your knowledge base  
-**Parameters:**
-- `query` (string, required): Search query
-- `limit` (number, optional): Max results (default: 20)
-
-**Example:**
-```
-Search for documents about "vector embeddings"
-```
-
-### 2. `read_node_content`
-**Description:** Read full markdown content of a specific document  
-**Parameters:**
-- `id` (string, required): Document ID from search results
-
-**Example:**
-```
-Read the full content of document "docs/embeddings.md"
-```
-
-### 3. `explore_links`
-**Description:** Find related documents (graph traversal)  
-**Parameters:**
-- `id` (string, required): Starting document ID
-- `relation` (string, optional): Relationship type
-
-**Example:**
-```
-Show me documents related to "playbooks/vector-search.md"
-```
-
-### 4. `list_directory_structure`
-**Description:** List all documents in the knowledge base  
-**Parameters:** None
-
-**Example:**
-```
-List all documents in my knowledge base
-```
-
-### 5. `inject_tags` (Experimental)
-**Description:** Add semantic tags to a document  
-**Parameters:**
-- `file_path` (string, required): Path to markdown file
-- `tags` (array, required): List of tags to add
-
----
-
-## Troubleshooting
-
-### "Server not connecting"
-
-1. **Check Bun is in PATH**:
-   ```bash
-   which bun
-   ```
-   
-2. **Verify database exists**:
-   ```bash
-   ls -la .amalfa/resonance.db
-   ```
-   
-   If missing, run ingestion again:
-   ```bash
-   bun run scripts/cli/ingest.ts
-   ```
-
-3. **Check server logs**:
-   ```bash
-   tail -n 50 .amalfa/.mcp.log
-   ```
-
-### "No results from search"
-
-1. **Verify database has data**:
-   ```bash
-   sqlite3 .amalfa/resonance.db "SELECT COUNT(*) FROM nodes;"
-   ```
-   
-   Should return a number > 0.
-
-2. **Check embeddings**:
-   ```bash
-   sqlite3 .amalfa/resonance.db "SELECT COUNT(*) FROM node_embeddings;"
-   ```
-
-3. **Re-run ingestion** if counts are 0:
-   ```bash
-   bun run scripts/cli/ingest.ts
-   ```
-
-### "Error: ENOENT: no such file or directory"
-
-The absolute path in your config is incorrect. Re-run:
-```bash
-bun run scripts/setup_mcp.ts
-```
-
-And update your MCP client config with the new path.
-
----
-
-## Advanced Configuration
-
-### Custom Database Path
-
-Edit `amalfa.config.json`:
-```json
-{
-  "database": ".amalfa/my-custom.db"
-}
-```
-
-Then re-ingest and restart the MCP server.
-
-### Multiple Source Directories
-
-```json
-{
-  "sources": [
-    "./docs",
-    "./playbooks",
-    "../other-project/docs"
-  ]
-}
-```
-
-### Environment Variables
-
-You can override config with environment variables in your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "amalfa": {
-      "command": "bun",
-      "args": ["run", "/path/to/amalfa/src/mcp/index.ts"],
-      "env": {
-        "AMALFA_DB": ".amalfa/custom.db",
-        "PATH": "..."
-      }
-    }
-  }
-}
-```
-
----
-
-## Next Steps
-
-- **[User Guide](./user-guide.md)** - Learn how to structure your markdown for best results
-- **[VISION-AGENT-LEARNING.md](./VISION-AGENT-LEARNING.md)** - Understand the brief-debrief-playbook pattern
-- **[Configuration Status](./docs/_current-config-status.md)** - Configuration reference
-
----
-
-## Support
-
-- **Issues:** https://github.com/pjsvis/amalfa/issues
-- **Discussions:** https://github.com/pjsvis/amalfa/discussions

package/docs/PERFORMANCE_BASELINES.md

@@ -1,88 +0,0 @@
-# Performance Baselines & Benchmarks
-
-> **Last Updated:** 2025-12-16
-> **Device:** Apple Silicon (M-series)
-> **Node/Bun:** Bun v1.3.4+
-
-## 1. Memory Footprint (Daemon)
-The Daemon run-time consists of the `Core Kernel`, `VectorEngine (WASM)`, and `Data Graph`.
-
-| Component | RAM Usage (RSS) | Scaling Nature | Notes |
-| :--- | :--- | :--- | :--- |
-| **AI Model (fastembed)** | **~252 MB** | 🛑 **Fixed** | Unavoidable one-time cost for local embedding. |
-| **Daemon Runtime** | **~60 MB** | 🛑 **Fixed** | Bun runtime + SQLite + Kernel overhead. |
-| **Graph Structure** | **~14 kB / node** | 🟢 **Variable** | Graphology in-memory graph representation. |
-| **Raw Data** | **~9 kB / node** | 🟢 **Variable** | Text content and metadata objects. |
-| **Vectors** | **~2 kB / node** | 🟢 **Variable** | Float32Arrays and normalized buffers. |
-
-### Total Daemon Footprint
-- **Empty State**: ~310 MB
-- **Current State (429 nodes)**: ~320 MB
-- **PROJECTED (10k nodes)**: ~560 MB
-
-## 2. Storage Footprint (Disk)
-Benchmarks from `public/resonance.db`.
-
-| Metric | Size / Count | Notes |
-| :--- | :--- | :--- |
-| **DB File Size** | 6.09 MB | SQLite WAL mode enabled. |
-| **Vector Data** | 1.42 MB | Blob storage. |
-| **Text Content** | 1.00 MB | Raw text in `content` column. |
-| **Node Count** | 429 | Including Experience & Persona domains. |
-
-## 3. How to Measure
-### Memory
-1. Ensure `graphology` is installed (temporarily): `bun add graphology`.
-2. Uncomment the graphology section in `scripts/profile_memory.ts`.
-3. Run: `bun run scripts/profile_memory.ts`.
-4. Revert: `bun remove graphology`.
-
-### Disk / DB Stats
-1. Run: `bun run scripts/assess_db_weight.ts`.
-
-## 4. Ingestion Baselines (Comparison)
-
-> **Baseline Source:** `_misc/ingestion-baseline.json` (2025-12-11)
-
-| Metric | Baseline (Dec 11) | Current (Dec 16) | Delta | Notes |
-| :--- | :--- | :--- | :--- | :--- |
-| **Persona Nodes** | 185 | 185 | **0** | Stable. Core lexicon. |
-| **Experience Nodes** | 128 | 244 | **+116** | Significant growth (new sessions/debriefs). |
-| **Total Nodes** | 313 | 429 | **+116** | ~37% Growth. |
-| **Total Edges** | 498 | 631 | **+133** | ~27% Growth. |
-| **Total Vectors** | 289 | 242 | **-47** | 📉 **Intentional Optimization** |
-
-### Insights
--   **Vector Efficiency**: Despite node growth (+37%), vector count dropped (-16%). This reflects the **"Narrative Vector Strategy"**, where only high-value content (Concepts, Playbooks) is vectorized, while structural nodes (Logs, raw fragments) are skipped.
--   **Graph Connectivity**: Edge growth (+27%) tracks closely with node growth, maintaining decent density.
-
-## 5. Speed Benchmarks (Dec 16)
-
-> **Environment**: Apple Silicon (M-series) | Bun v1.3.4
-
-| Operation | Latency | Notes |
-| :--- | :--- | :--- |
-| **Model Load (Cold)** | **~192 ms** | One-time initialization cost. |
-| **Vector Search** | **~71 ms** | Avg of 10 runs (Top-5 search). |
-| **SQL Insert (Raw)** | **~0.001 ms/row** | Batch prepared statement (Buffered). |
-| **SQL Insert (ORM)** | **~0.012 ms/row** | Drizzle ORM overhead (~12x slower than raw). |
-
-## 6. Vector Inclusion Rules (Audit)
-
-> **Policy:** "Everything in the folders noted in the settings file should be in the vector store."
-
-**Audit Results (Dec 16):**
-
-| Domain | Source | Status | Notes |
-| :--- | :--- | :--- | :--- |
-| **Experience** | `debriefs/` | ✅ **100% Vectorized** | Narrative content. |
-| **Experience** | `playbooks/` | ✅ **100% Vectorized** | Procedural knowledge. |
-| **Experience** | `briefs/` | ✅ **100% Vectorized** | Context setting. |
-| **Experience** | `docs/` | ✅ **100% Vectorized** | Project documentation. |
-| **Persona** | `lexicon.json` | ⚪ **Excluded** | *Optimization*: Concepts matched via Keywords/Graph. |
-| **Persona** | `cda.json` | ⚪ **Excluded** | *Optimization*: Directives matched via Keywords/Graph. |
-| **Experience** | `test-artifacts` | ⚪ **Excluded** | *Transient*: `test-doc-1` & `test-doc-2` (from test scripts). |
-
-**Conclusion:**
-The logic complies with the rule. All folder-based narrative content is vectorized. File-based structured data (Persona) is excluded to save memory, as it is efficiently retrievable via exact graph traversal. The only un-vectorized `document` nodes are confirmed test artifacts.
-

package/docs/QUICK_START_MCP.md

@@ -1,168 +0,0 @@
-# AMALFA MCP Quick Start
-
-**Get AMALFA running with Claude Desktop in 5 minutes.**
-
----
-
-## Current Status
-
-✅ **Database exists**: `.amalfa/resonance.db` (2.4 MB)  
-✅ **Dependencies installed**: `node_modules/` present  
-✅ **MCP server ready**: `src/mcp/index.ts`
-
----
-
-## Quick Setup (Claude Desktop)
-
-### 1. Generate your configuration
-
-```bash
-cd /Users/petersmith/Documents/GitHub/amalfa
-bun run scripts/setup_mcp.ts
-```
-
-Copy the JSON output (will look like this):
-
-```json
-{
-  "mcpServers": {
-    "amalfa": {
-      "command": "bun",
-      "args": [
-        "run",
-        "/Users/petersmith/Documents/GitHub/amalfa/src/mcp/index.ts"
-      ],
-      "env": {
-        "PATH": "..."
-      }
-    }
-  }
-}
-```
-
-### 2. Add to Claude Desktop
-
-**Open config file:**
-```bash
-open ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-**Paste the JSON** from step 1. If the file already has content, merge the `amalfa` entry into the existing `mcpServers` object.
-
-**Example final config:**
-```json
-{
-  "mcpServers": {
-    "amalfa": {
-      "command": "bun",
-      "args": [
-        "run",
-        "/Users/petersmith/Documents/GitHub/amalfa/src/mcp/index.ts"
-      ],
-      "env": {
-        "PATH": "/usr/local/bin:/usr/bin:/bin"
-      }
-    }
-  }
-}
-```
-
-### 3. Restart Claude Desktop
-
-Quit and relaunch Claude Desktop completely (Cmd+Q, then reopen).
-
-### 4. Test it
-
-In Claude Desktop, ask:
-
-```
-Search my knowledge base for "embeddings"
-```
-
-Claude should invoke the `search_documents` tool and return results from your markdown files.
-
----
-
-## What's in Your Database?
-
-Check what's indexed:
-
-```bash
-sqlite3 .amalfa/resonance.db "SELECT COUNT(*) FROM nodes;"
-sqlite3 .amalfa/resonance.db "SELECT COUNT(*) FROM node_embeddings;"
-sqlite3 .amalfa/resonance.db "SELECT id, type FROM nodes LIMIT 10;"
-```
-
----
-
-## Troubleshooting
-
-### "Server not connecting"
-
-1. **Verify Bun path in Claude config** matches your system:
-   ```bash
-   which bun
-   ```
-
-2. **Check server logs**:
-   ```bash
-   tail -f .amalfa/.mcp.log
-   ```
-
-3. **Test manually**:
-   ```bash
-   bun run src/mcp/index.ts
-   ```
-   Press Ctrl+C to stop. Check for errors in the startup output.
-
-### "No results from search"
-
-**Option A: Re-ingest from current config**
-
-Your `amalfa.config.json` currently points to:
-```json
-{
-  "sources": ["../polyvis/docs", "../polyvis/playbooks"]
-}
-```
-
-If you want to index **local** amalfa docs instead:
-
-1. **Edit** `amalfa.config.json`:
-   ```json
-   {
-     "sources": ["./docs", "./playbooks"],
-     "database": ".amalfa/resonance.db"
-   }
-   ```
-
-2. **Re-ingest**:
-   ```bash
-   bun run scripts/cli/ingest.ts
-   ```
-
-**Option B: Keep polyvis sources**
-
-If you want to keep searching polyvis content, ensure `../polyvis` exists and contains the docs/playbooks folders.
-
----
-
-## Next Steps
-
-- **[Full MCP Setup Guide](./MCP_SETUP.md)** - Advanced configuration, troubleshooting
-- **[User Guide](./user-guide.md)** - How to structure markdown for best results
-- **[Configuration Status](./docs/_current-config-status.md)** - All config files explained
-
----
-
-## Available Tools
-
-Once connected, Claude can use:
-
-- `search_documents` - Semantic search
-- `read_node_content` - Read full markdown file
-- `explore_links` - Graph traversal
-- `list_directory_structure` - List all documents
-- `inject_tags` - Add tags (experimental)
-
-See [MCP_SETUP.md](./MCP_SETUP.md) for details.