@vheins/local-memory-mcp 0.1.0 → 0.1.2

package/.kiro/specs/memory-mcp-optimization/.config.kiro

@@ -0,0 +1 @@
+{"specId": "a9aa2a01-bac5-484c-8b95-7f5536bca00e", "workflowType": "requirements-first", "specType": "feature"}

package/.vscode/tasks.json

@@ -0,0 +1,27 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Start Dashboard",
+      "type": "shell",
+      "command": "npm",
+      "args": ["run", "dashboard"],
+      "options": {
+        "cwd": "/home/vheins/Projects/local-memory-mcp"
+      },
+      "group": "build",
+      "presentation": {
+        "echo": true,
+        "reveal": "silent",
+        "focus": false,
+        "panel": "shared",
+        "showReuseMessage": true,
+        "clear": false
+      },
+      "isBackground": true,
+      "runOptions": {
+        "runOn": "folderOpen"
+      }
+    }
+  ]
+}

package/README.md

@@ -15,13 +15,149 @@ This project implements a local memory service using Node.js and SQLite with vec
 - **MCP Protocol**: Full implementation of MCP resources, tools, and prompts
 - **Web Dashboard**: Browser-based UI for visualizing and managing memories
 
+## Quick Start (npx)
+
+The easiest way to use this MCP server is via npx - no installation required:
+
+```bash
+npx @vheins/local-memory-mcp
+```
+
 ## Installation
 
+### Local Development
+
 ```bash
 npm install
 npm run build
 ```
 
+### Global Install
+
+```bash
+npm install -g @vheins/local-memory-mcp
+mcp-memory-local
+```
+
+## MCP Client Configuration
+
+This server works with any MCP-compatible client. Add it to your configuration:
+
+### OpenCode
+
+```json
+{
+  "mcpServers": {
+    "local-memory": {
+      "command": "npx",
+      "args": ["@vheins/local-memory-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop (claude.ai)
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "local-memory": {
+      "command": "npx",
+      "args": ["@vheins/local-memory-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Settings → Features → Models → "Edit JSON"
+
+```json
+{
+  "mcpServers": {
+    "local-memory": {
+      "command": "npx",
+      "args": ["@vheins/local-memory-mcp"]
+    }
+  }
+}
+```
+
+### Kiro Antigravity
+
+Add to your MCP configuration file:
+
+```json
+{
+  "servers": {
+    "local-memory": {
+      "command": "npx",
+      "args": ["@vheins/local-memory-mcp"]
+    }
+  }
+}
+```
+
+### Trae
+
+Settings → Integrations → MCP → Add Server
+
+```json
+{
+  "command": "npx",
+  "args": ["@vheins/local-memory-mcp"]
+}
+```
+
+### Gemini CLI
+
+```bash
+gemini mcp add local-memory -- npx @vheins/local-memory-mcp
+```
+
+### Codex
+
+```json
+{
+  "mcp_servers": {
+    "local-memory": {
+      "command": "npx",
+      "args": ["@vheins/local-memory-mcp"]
+    }
+  }
+}
+```
+
+### VS Code (with MCP extension)
+
+```json
+{
+  "mcpServers": {
+    "local-memory": {
+      "command": "npx",
+      "args": ["@vheins/local-memory-mcp"]
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+For any other MCP-compatible client, use:
+
+- **Command**: `npx`
+- **Args**: `["@vheins/local-memory-mcp"]`
+
+Or build from source:
+
+- **Command**: `node`
+- **Args**: `["/path/to/dist/server.js"]`
+
 ## Usage
 
 ### MCP Server

package/package.json

@@ -1,13 +1,9 @@
 {
 	"name": "@vheins/local-memory-mcp",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "MCP Local Memory Service for coding copilot agents",
 	"type": "module",
 	"main": "dist/server.js",
-	"bin": {
-		"mcp-memory-local": "./dist/server.js",
-		"mcp-memory-dashboard": "./dist/dashboard/server.js"
-	},
 	"scripts": {
 		"build": "tsc && mkdir -p dist/dashboard/public && rsync -a --delete src/dashboard/public/ dist/dashboard/public/",
 		"dev": "tsc --watch",

package/DASHBOARD.md

@@ -1,129 +0,0 @@
-# MCP Memory Dashboard
-
-A web-based dashboard for managing and visualizing MCP Local Memory data.
-
-## Features
-
-- **Live Connection Status**: Real-time monitoring of MCP server connection
-- **Repository Scoping**: View memories filtered by repository
-- **Summary Statistics**: Quick overview of total memories, by type, and unused entries
-- **Visual Charts**: 
-  - Memory distribution by type (pie chart)
-  - Top 10 memories by importance (bar chart)
-- **Memory Management**:
-  - Browse all memories with sortable columns
-  - Filter by type (decision, mistake, code_fact, pattern)
-  - View detailed memory information
-  - Edit memory content and importance
-  - Delete memories with confirmation
-- **Operations-First Design**: Clear, data-dense interface optimized for daily use
-
-## Quick Start
-
-1. **Build the project**:
-   ```bash
-   npm run build
-   ```
-
-2. **Start the dashboard**:
-   ```bash
-   npm run dashboard
-   ```
-
-3. **Access the dashboard**:
-   Open your browser to `http://localhost:3456`
-
-## Architecture
-
-The dashboard is a thin presentation layer that:
-
-- Spawns the MCP server as a subprocess
-- Communicates via JSON-RPC (stdin/stdout)
-- Uses MCP tools exclusively (no direct database access):
-  - `memory.search` - List and filter memories
-  - `memory.update` - Edit memories
-  - `memory.delete` - Remove memories
-  - Resources API - Read individual memory details
-
-## Safety Features
-
-- **Confirmation Required**: All destructive actions require explicit confirmation
-- **Type "DELETE" Verification**: Memory deletion requires typing "DELETE" to proceed
-- **Read-Only Fields**: Repository scope and type cannot be changed
-- **Connection Monitoring**: Dashboard disables actions when MCP is offline
-
-## API Endpoints
-
-The dashboard server exposes these REST endpoints:
-
-- `GET /api/health` - Check MCP connection status
-- `GET /api/repos` - List all repositories
-- `GET /api/stats` - Get statistics (total, by type, top memories)
-- `GET /api/memories` - List memories with filtering and sorting
-- `GET /api/memories/:id` - Get memory detail
-- `PUT /api/memories/:id` - Update memory (content, importance)
-- `DELETE /api/memories/:id` - Delete memory
-
-## Configuration
-
-- **Port**: Set `PORT` environment variable (default: 3456)
-- **MCP Server**: Automatically spawned from `dist/server.js`
-
-## Known Limitations
-
-1. ~~**Memory Search Constraints**~~: RESOLVED - Dashboard now uses direct database access for listing all memories, bypassing the MCP search limitation.
-
-2. ~~**Unused Memory Tracking**~~: RESOLVED - The SQLite schema now includes `hit_count`, `recall_count`, and `last_used_at` columns for full usage tracking.
-
-3. **Chart.js CDN**: Charts use Chart.js from CDN, which may be blocked in some environments. The dashboard shows a graceful fallback message when unavailable: "Chart.js not available. Install locally for visualizations."
-
-## Similarity Search
-
-The system now uses **ultra-lightweight text-based similarity** instead of heavy ML models:
-- Normalized token vectors with term frequency
-- Cosine similarity for matching
-- No GPU dependencies or model servers required
-- Zero startup cost and minimal memory overhead
-- Query latency < 20ms for typical memory counts
-
-This approach provides:
-- Typo tolerance through normalized text
-- Basic semantic grouping
-- Deterministic and predictable behavior
-- Perfect for 100-2,000 memories
-
-## Acceptance Criteria Compliance
-
-This dashboard satisfies all acceptance criteria:
-
-✅ **AC-A1-A2**: MCP connection status and handling  
-✅ **AC-B1-B3**: Memory listing with repo scoping and sorting  
-✅ **AC-C1-C2**: Detail view with read-only fields  
-✅ **AC-D1-D3**: Memory editing with constraints and feedback  
-✅ **AC-E1-E3**: Soft delete with confirmation  
-✅ **AC-F1-F2**: Accurate statistics and unused detection  
-✅ **AC-G1-G2**: Chart rendering and consistency  
-✅ **AC-H1-H2**: No direct DB access, explicit mutations  
-✅ **AC-I1-I2**: No accidental actions, clear errors  
-✅ **AC-J1**: Fast load time for reasonable memory counts  
-
-## Development
-
-The dashboard consists of:
-
-- **Backend**: Express server (`src/dashboard/server.ts`)
-  - MCP client implementation
-  - REST API endpoints
-  - Static file serving
-  
-- **Frontend**: Single-page app (`src/dashboard/public/index.html`)
-  - Vanilla JavaScript (no framework overhead)
-  - Chart.js for visualizations
-  - Operations-focused UX
-
-## Notes
-
-- This dashboard does NOT modify MCP schemas or storage
-- All data operations go through official MCP tools
-- The MCP server is a subprocess, not a library import
-- If MCP server stops, dashboard enters degraded state

package/HYBRID_SEARCH.md

@@ -1,204 +0,0 @@
-# Hybrid Similarity + Vector Search
-
-## Overview
-
-The MCP Local Memory system implements a **hybrid search strategy** that combines:
-
-1. **Lightweight text similarity** (primary, mandatory)
-2. **Vector/semantic search** (secondary, optional boost)
-
-This approach provides precision through deterministic similarity while improving recall with semantic understanding.
-
-## Architecture
-
-### Search Pipeline
-
-```
-memory.search(query, repo)
-  ↓
-1. Repo filter (HARD)
-  ↓
-2. Lightweight similarity scoring (MANDATORY)
-  ↓
-3. Candidate pruning (top K × 3)
-  ↓
-4. OPTIONAL vector similarity re-rank
-  ↓
-5. Final ranking & threshold
-  ↓
-6. Return memory IDs
-```
-
-**Key Principle:** Vector search is NEVER step 1. It only re-ranks candidates identified by similarity.
-
-## Scoring Formula
-
-### Hybrid Mode (with vector search)
-```
-FinalScore = (SimilarityScore × 0.6) + (VectorScore × 0.3) + (ImportanceBoost × 0.1)
-```
-
-Where:
-- `SimilarityScore` ∈ [0.0 – 1.0] from text-based cosine similarity
-- `VectorScore` ∈ [0.0 – 1.0] from semantic embedding similarity
-- `ImportanceBoost` = importance / 5
-
-### Fallback Mode (similarity-only)
-```
-FinalScore = (SimilarityScore × 0.85) + (ImportanceBoost × 0.15)
-```
-
-When vector search is unavailable or fails, weights are redistributed to maintain ranking quality.
-
-## Implementation Details
-
-### Text-Based Similarity (Tier 1)
-
-**Always computed**, provides:
-- Fast filtering
-- Typo tolerance
-- Deterministic results
-
-Algorithm:
-1. Normalize text (lowercase, strip punctuation)
-2. Remove stopwords
-3. Build term frequency (TF) vector
-4. Compute cosine similarity
-
-### Vector Search (Tier 2)
-
-**Optional boost**, provides:
-- Paraphrase matching
-- Semantic recall
-- Abstract concept linking
-
-Rules:
-- Runs ONLY on top-K candidates from similarity
-- NEVER expands search universe
-- NEVER overrides similarity completely
-- Gracefully degrades if unavailable
-
-## Failsafe Behavior
-
-```typescript
-try {
-  const vectorResults = await vectors.search(query, candidates.length);
-  // Use hybrid ranking
-} catch (error) {
-  console.error("Vector search failed, using similarity-only");
-  // Automatically fall back to similarity-only ranking
-}
-```
-
-The system behaves identically from the caller's perspective - no errors propagate.
-
-## Storage
-
-### Similarity Vectors
-- Computed on-the-fly
-- No storage required
-- Cached in memory (optional)
-
-### Vector Embeddings (Optional)
-```sql
-CREATE TABLE IF NOT EXISTS memory_vectors (
-  memory_id TEXT PRIMARY KEY,
-  vector TEXT NOT NULL,         -- JSON array of floats
-  updated_at TEXT NOT NULL,
-  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
-);
-```
-
-Methods:
-- `upsertVectorEmbedding(memoryId, vector)` - Store embedding
-- `getVectorEmbedding(memoryId)` - Retrieve embedding
-
-## Dashboard Observability
-
-### Debug View (Future Enhancement)
-When search results are displayed, the dashboard can show:
-- **SimilarityScore**: Text-based match quality
-- **VectorScore**: Semantic match quality (if used)
-- **FinalScore**: Combined ranking score
-
-### Aggregate Metrics
-- Recall rate per search mode
-- Percentage of searches using vector boost
-- Performance comparison: similarity vs hybrid
-
-## Configuration
-
-### Weight Tuning
-```typescript
-const HYBRID_WEIGHTS = {
-  similarity: 0.6,  // Primary signal
-  vector: 0.3,      // Secondary boost
-  importance: 0.1   // Tiebreaker
-};
-```
-
-Weights must sum to 1.0. Adjust based on:
-- Recall rate metrics
-- Query patterns
-- Memory content characteristics
-
-### Quality Rules
-If recall_rate decreases after enabling vector boost:
-1. Reduce vector weight
-2. Or disable vector for that repo
-3. Monitor and iterate
-
-**Vector is an assistant, not an authority.**
-
-## Performance Expectations
-
-- **Similarity Search**: <20ms for <1k memories
-- **Vector Search**: Depends on implementation (embeddings, model)
-- **Hybrid Overhead**: Negligible if vector is fast
-- **Startup Cost**: ~0 (no model loading required for similarity)
-
-## Example Usage
-
-### With Vector Search Available
-```typescript
-// Returns memories ranked by hybrid score
-const results = await handleMemorySearch({
-  query: "authentication middleware",
-  repo: "backend-api",
-  limit: 10
-}, db, vectors);
-
-// Results use: 60% similarity + 30% vector + 10% importance
-```
-
-### With Vector Search Unavailable
-```typescript
-// Automatically falls back to similarity-only
-const results = await handleMemorySearch({
-  query: "authentication middleware",
-  repo: "backend-api",
-  limit: 10
-}, db, stubVectors); // Stub returns empty []
-
-// Results use: 85% similarity + 15% importance
-```
-
-## Philosophy
-
-This hybrid strategy:
-- ✅ Preserves precision (similarity as filter)
-- ✅ Improves recall (vector as booster)
-- ✅ Avoids overfitting to ML (deterministic-first)
-- ✅ Gracefully degrades (no hard dependencies)
-
-It is the correct balance for MCP Local Memory: **boring, predictable, fast** with optional semantic enhancement.
-
-## Activation Message
-
-When the system is running with hybrid search enabled:
-
-**"Hybrid similarity + vector search active. Deterministic-first strategy enabled."**
-
-When vector search is not available:
-
-**"Similarity-only search active. Vector search unavailable (graceful degradation)."**

package/IMPLEMENTATION.md

@@ -1,159 +0,0 @@
-# Implementation Summary
-
-## MCP Local Memory Server - COMPLETE ✅
-
-**Status:** Fully implemented and tested according to all documentation specifications.
-
-### What Was Built
-
-A complete MCP (Model Context Protocol) server that provides long-term memory capabilities for coding copilot agents. The implementation strictly follows the documented architecture in the `docs/` folder.
-
-### Architecture Components
-
-#### 1. MCP Server Core
-- **server.ts**: JSON-RPC protocol handler with stdin/stdout communication
-- **capabilities.ts**: MCP contract definition (resources, tools, prompts)
-- **router.ts**: Method dispatcher routing requests to appropriate handlers
-
-#### 2. Storage Layer
-- **storage/sqlite.ts**: SQLite database with proper schema and migrations
-  - `memories` table: All memory entries with repo scoping
-  - `memory_summary` table: Antigravity summaries per repo
-  - Indexes on repo, type, and importance
-- **storage/vectors.stub.ts**: Vector search stub ready for embedding integration
-
-#### 3. Tools (MCP Tools)
-- **memory.store**: Store new memory entries with strict validation
-- **memory.search**: Semantic search with keyword fallback
-- **memory.update**: Update existing memory entries
-- **memory.summarize**: Create/update antigravity summaries
-
-#### 4. Resources (MCP Resources)
-- **memory://index**: Recent memory entries metadata
-- **memory://{id}**: Individual memory entry
-- **memory://summary/{repo}**: Project-level summary
-
-#### 5. Prompts (MCP Prompts)
-- **memory-agent-core**: Core behavioral contract for agents
-- **memory-index-policy**: Memory discipline enforcement
-- **tool-usage-guidelines**: Tool usage best practices
-
-#### 6. Utilities
-- **utils/git-scope.ts**: Git repository scope resolver
-- **utils/normalize.ts**: Text normalization for search
-
-### Key Features Implemented
-
-✅ **Git Scope Isolation**: Memories are strictly scoped per repository
-✅ **Strict Validation**: Zod schemas enforce data quality
-✅ **Memory Types**: code_fact, decision, mistake, pattern
-✅ **Importance Scoring**: 1-5 importance levels
-✅ **Semantic Search Stub**: Ready for vector embedding integration
-✅ **Keyword Fallback**: Works without vector embeddings
-✅ **Antigravity Summaries**: Project-level context anchoring
-✅ **MCP Protocol Compliant**: Full MCP 2024-11-05 protocol support
-
-### Testing
-
-All behavioral contracts from `TEST-scenarios.md` validated:
-
-✅ Store architectural decisions
-✅ Store mistakes to avoid repetition
-✅ Store code patterns
-✅ Cross-repo isolation (no memory leakage)
-✅ Semantic search with typo tolerance
-✅ Fallback to keyword search when vector unavailable
-✅ Project summaries for antigravity behavior
-
-### Code Quality
-
-✅ **Code Review**: Completed with minor redundancies removed
-✅ **Security Scan**: No vulnerabilities found (CodeQL)
-✅ **Build**: TypeScript compiles without errors
-✅ **Tests**: All test scenarios pass
-
-### Design Compliance
-
-The implementation follows all specifications:
-- ✅ PRD (Product Requirements Document)
-- ✅ SPEC-heuristics (Auto-Memory rules)
-- ✅ SPEC-server (MCP contract)
-- ✅ SPEC-skeleton (Server structure)
-- ✅ SPEC-git-scope (Scope resolution)
-- ✅ SPEC-tool-schema (Tool validation)
-- ✅ SPEC-sqlite-schema (Database schema)
-- ✅ SPEC-vector-search (Vector layer)
-- ✅ TEST-scenarios (Behavioral tests)
-- ✅ PROMPT-agent (Agent behavior)
-
-### Usage Example
-
-```bash
-# Build
-npm install
-npm run build
-
-# Run server
-node dist/server.js
-
-# Store a memory (via JSON-RPC)
-{
-  "jsonrpc":"2.0",
-  "id":1,
-  "method":"tools/call",
-  "params":{
-    "name":"memory.store",
-    "arguments":{
-      "type":"decision",
-      "content":"Use React Query for all data fetching",
-      "importance":5,
-      "scope":{"repo":"frontend-app"}
-    }
-  }
-}
-
-# Search memories
-{
-  "jsonrpc":"2.0",
-  "id":2,
-  "method":"tools/call",
-  "params":{
-    "name":"memory.search",
-    "arguments":{
-      "query":"data fetching",
-      "repo":"frontend-app",
-      "limit":5
-    }
-  }
-}
-```
-
-### Next Steps (Future Enhancements)
-
-The implementation is production-ready but can be extended:
-
-1. **Vector Embeddings**: Replace stub with real embedding model
-   - Ollama integration
-   - llama.cpp integration
-   - OpenAI embeddings (with privacy controls)
-
-2. **Enhanced Search**: Improve ranking algorithm
-   - Temporal decay
-   - Usage frequency
-   - Cross-reference scoring
-
-3. **Memory Management**: Add lifecycle management
-   - Archival policies
-   - Memory consolidation
-   - Duplicate detection
-
-4. **Monitoring**: Add observability
-   - Memory growth tracking
-   - Search performance metrics
-   - Agent usage patterns
-
-### Conclusion
-
-**MCP Local Memory loaded. Documentation verified. Ready to execute.**
-
-The implementation is complete, tested, secure, and ready for production use. All documented behavioral contracts are satisfied. The server provides a solid foundation for long-term agent memory with clear extension points for future enhancements.