cf-memory-mcp 3.8.5 → 3.8.6

package/README.md

@@ -1,717 +1,143 @@
 # CF Memory MCP
 
-[![npm version](https://badge.fury.io/js/cf-memory-mcp.svg)](https://badge.fury.io/js/cf-memory-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Cloudflare-hosted MCP server for semantic code indexing, retrieval, and assistant memory.
 
-A **best-in-class MCP (Model Context Protocol)** server for AI memory storage using **Cloudflare infrastructure**. This package provides AI coding agents with intelligent memory management featuring **smart auto-features**, **intelligent search**, **memory collections**, **temporal intelligence**, **multi-agent collaboration**, **advanced analytics**, and a **real-time analytics dashboard** with interactive visualizations and business intelligence.
+**Live at [https://memcp.ai](https://memcp.ai)**
 
-## 🎯 Current Version: v3.2.1 (Tool Consolidation Release)
+## Key Features
 
-**🔧 Major Update: Tool Consolidation** - Reduced from 95+ tools to 20 essential tools (79% reduction) for improved usability and performance.
+- **110+ language support** - TypeScript, Python, Go, Rust, Java, C/C++, Ruby, PHP, Swift, Kotlin, Scala, and 100+ more including shaders (GLSL, HLSL, WGSL, Metal, CUDA)
+- **Hybrid retrieval** - 3-lane RRF (semantic + keyword + name matching) with cross-encoder reranking
+- **100% benchmark accuracy** - 32 queries across behavioral, conceptual, identifier, and negation categories
+- **Code graph navigation** - Track calls, imports, inheritance across 9 language families (TS/JS, Python, Go, Rust, Java/Kotlin/Scala, C/C++/C#, Ruby, PHP, Swift)
+- **21 MCP tools** - Indexing, retrieval, file exploration, code graph, freshness management, and persistent memory
+- **Self-healing freshness** - Results auto-flag stale chunks with a copy-pasteable `refresh_files` call; `refresh_stale` rebuilds the changed files in seconds; cache invalidates on write
+- **Self-debugging errors** - `retrieve_context` includes `empty_hint` on 0-result queries; `get_file_content` / `get_file_outline` return `{error, hint}` pointing to the next call instead of bare null; calling bridge-only tools server-side returns `bridge_required` install instructions
+- **Smart defaults** - Bridge auto-detects project_id from cwd, returns chunks pre-enriched with file imports + citation + source classification
+- **Contextual embeddings** - Qwen3 8K-context model with Anthropic-style chunk headers
 
-## 📊 Real-time Analytics Dashboard
+The active runtime is at [src-simplified/index.ts](src-simplified/index.ts). It exposes direct MCP over HTTP and a local stdio bridge for clients that want `npx cf-memory-mcp`.
 
-**NEW: Beautiful, high-performance analytics dashboard with interactive visualizations and business intelligence**
+## What Works
 
-🌐 **Live Dashboard**: [https://55a2aea1.cf-memory-dashboard-vue.pages.dev](https://55a2aea1.cf-memory-dashboard-vue.pages.dev)
+- Direct remote MCP on `/mcp`
+- Legacy compatibility on `/mcp/message`
+- Code indexing with `index_project` and `index_github`
+- Retrieval with `retrieve_context` (3-lane hybrid + cross-encoder rerank, returns `file_imports` + `source_kind` + `citation`)
+- Code relationship graph with `get_related_code` (calls, imports, extends, implements)
+- Project exploration with `list_files`, `list_projects`, `get_stats`, `get_file_outline`, `get_file_content`
+- **Staleness handling**: `find_stale_files`, `refresh_files`, `refresh_stale`. Results auto-tag stale chunks with a `stale_refresh_hint` showing the exact call to fix them.
+- Assistant memory tools (`store_memory`, `retrieve_memories`, `get_context_bootstrap`, `delete_memory`)
+- Session tracking with `start_session`, `end_session`
+- Structured entity storage with `store_entity`
+- Async indexing with Queues
+- Coordination and progress with Durable Objects
+- Diagnostics: `health_check` tool + `npx cf-memory-mcp --diagnose` + `CF_MEMORY_TRACE=1`
 
-### Key Features
-- **🔄 Real-time Updates** - Live data streaming with Server-Sent Events (SSE)
-- **📈 Interactive Charts** - Quality heatmaps, learning velocity gauges, performance radar charts
-- **🕸️ Network Visualization** - Memory relationship graphs with clustering and filtering
-- **📱 Mobile Responsive** - Optimized for desktop, tablet, and mobile devices
-- **🌙 Dark/Light Themes** - Automatic theme switching with user preferences
-- **📊 Export & Reports** - JSON/CSV export for business intelligence and presentations
-- **⚡ <2s Loading** - Enterprise-grade performance with global CDN
-- **🧪 Built-in Testing** - Comprehensive performance and functionality testing suite
+## Active Infra
 
-### Business Value
-- **Quality Tracking** - Monitor AI learning progress from 27% to 60%+ quality scores
-- **Performance Monitoring** - Real-time system health and optimization insights
-- **Decision Support** - Data-driven insights for strategic planning and resource allocation
-- **ROI Measurement** - Quantifiable metrics for AI investment returns
+- Workers
+- D1
+- Vectorize
+- Queues
+- Durable Objects
 
-### Quick Start
-```bash
-# Deploy dashboard (requires Cloudflare account)
-cd dashboard-vue
-npm run deploy:production
-
-# Or access the live demo
-open https://55a2aea1.cf-memory-dashboard-vue.pages.dev
-```
-
-📖 **Documentation**: [Dashboard README](./dashboard-vue/README.md) | [Executive Summary](./docs/dashboard-executive-summary.md)
-
-**🚀 NEW: Enhanced JSON + Cloudflare Vectorize Integration (v2.12.1) - Next-Level Semantic Search:**
-
-- 🎯 **Entity-Level Vectorization** - Individual JSON entities get their own vectors for granular semantic search
-- 🔍 **Multi-Level Search Architecture** - Search at memory level AND entity level simultaneously
-- 🤖 **Automatic Relationship Discovery** - AI-powered similarity-based relationship suggestions
-- 📊 **85-95% Search Accuracy** - Enterprise-grade semantic understanding of complex data structures
-- ⚡ **50-70% Faster Discovery** - Optimized performance with Cloudflare's edge infrastructure
-- 🔗 **Cross-Memory Entity Linking** - Connect similar entities across different JSON memories
-- 📈 **Entity Analytics** - Importance scoring and pattern analysis for JSON structures
-
-**🔥 Enhanced JSON Processing & Temporal Relationship Tracking (v2.12.0) - Graphiti-Inspired Features:**
-
-- 📊 **Enhanced JSON Processing** - Automatic entity extraction from structured JSON data with JSONPath tracking
-- 🕒 **Temporal Relationship Tracking** - Relationship versioning, validity status, and evolution history
-- 🔗 **Relationship Evolution** - Track how connections between memories change over time
-- 📝 **Source Type Support** - Handle text, JSON, and message format data with automatic processing
-- 🎯 **Entity Relationship Mapping** - Automatic relationship generation between JSON entities
-- 📈 **Relationship Analytics** - Evolution summaries and temporal pattern analysis
-- 🔧 **New MCP Tools** - update_memory_relationship, search_relationships_temporal, get_relationship_evolution
-- 🗄️ **Database Extensions** - Enhanced schema with memory_entities table and temporal indexes
-
-**🧠 Priority 4 - Context-Aware + Temporal Intelligence (v2.11.0) - AI-Enhanced Features:**
-
-- 🎯 **AI-Enhanced Contextual Suggestions** - Smart suggestions using semantic search and AI-powered relevance scoring
-- 🕒 **Advanced Temporal Intelligence** - Enhanced time-aware search with sophisticated temporal scoring algorithms
-- 🔄 **Context-Switching Optimization** - Automatic project detection and intelligent context switching
-- 📊 **Temporal Pattern Analytics** - Advanced pattern recognition with ML-powered predictions
-- 🤖 **AI-Powered Suggestion Text** - Intelligent suggestion generation using Cloudflare AI (Llama 3.1 8B)
-- 📈 **Enhanced Temporal Relevance** - Context-aware scoring with access patterns and importance weighting
-- 🧠 **Smart Context Detection** - AI-powered context extraction from conversation history
-- ⚡ **Semantic Context Matching** - Vector-based project context discovery with 95%+ confidence
-
-**🧠 AI/ML Intelligence Engine (v2.9.0) - Production AI Features:**
-
-- 🤖 **AI-Powered Content Expansion** - Real content enrichment using Llama 3.1 8B (replaces static text appending)
-- 🏷️ **Semantic Tag Generation** - Intelligent tagging with Cloudflare AI classification models
-- 📊 **Real Performance Monitoring** - Actual metrics from database analytics (replaces mock data)
-- ⚡ **Enhanced Analytics Dashboard** - Database-driven performance tracking and system health
-- 🎯 **Production AI Models** - BGE embeddings, DistilBERT sentiment, Llama classification
-- 🔧 **Improved Quality Scoring** - AI-powered analysis with >95% prediction confidence
-- 📈 **Performance Tracking** - Real-time operation monitoring with automatic metric collection
-
-**🚀 Cloudflare Vectorize Integration (v2.8.1) - Paid Tier Enhancement:**
-
-- 🎯 **Advanced Vector Search** - Cloudflare Vectorize for lightning-fast semantic search (50M queries/month)
-- 📊 **Vector Storage** - Dedicated vector database with 10M stored dimensions/month
-- 🔍 **Enhanced Similarity** - Superior semantic search performance vs D1-based embeddings
-- 🧩 **Memory Clustering** - AI-powered clustering analysis using vector similarity
-- 📈 **Paid Tier Optimization** - 33x more KV writes, 10x larger batches, 6x faster learning cycles
-- ⚡ **Performance Boost** - 50-70% response time reduction through optimized caching
-
-**⚡ KV Optimization Engine (v2.8.0) - Performance & Reliability:**
-
-- 🎯 **Intelligent Caching** - Optimized cache service with conditional writes and longer TTL values
-- 📊 **KV Usage Monitoring** - Real-time tracking to prevent daily limit breaches (1,000 writes/day)
-- 🗄️ **D1 Database Fallback** - Analytics data stored in D1 to reduce KV write frequency
-- 🔄 **Batched Operations** - Write queue batching to minimize KV operations
-- 📈 **Usage Analytics** - Trends, recommendations, and optimization insights
-- 🛡️ **Limit Protection** - Automatic prevention of KV limit exceeded errors
-
-**🧠 Memory Intelligence Engine (v2.7.0) - Autonomous Optimization:**
-
-- 🤖 **Automated Learning Loops** - Self-improving algorithms with A/B testing framework
-- 🎯 **Adaptive Thresholds** - Dynamic parameter optimization based on performance data
-- 🧪 **Learning Experiments** - Scientific approach to testing optimization strategies
-- 📊 **A/B Testing Framework** - Rigorous experimentation with statistical analysis
-- 🔄 **Autonomous Optimization** - System continuously improves itself without manual intervention
+This is the correct default stack for the current product. Queues fit per-file async indexing well, and Durable Objects fit progress and shared coordination.
 
-**Previous Features (Phase 2 Enhancements):**
+## Quick Start
 
-- 🚀 **Quality Auto-Improvement Engine** - AI-powered memory enhancement to boost quality scores from 27% to 60%+
-- 🔧 **Content Expansion** - Intelligent AI analysis to expand short memories with relevant context
-- 🏷️ **Smart Tag Enhancement** - Automatic tag suggestions and improvements for better organization
-- ⚖️ **Importance Recalculation** - Dynamic importance scoring based on content analysis and usage patterns
+### Local MCP Bridge
 
-**Previous Features (Phase 1 Enhancements):**
-
-- 📊 **Memory Analytics Dashboard** - Real-time statistics and performance insights
-- 🔍 **Advanced Search Filters** - Date range, importance, size, and boolean search
-- 🏥 **Memory Health Monitoring** - Orphan detection and quality scoring
-- 📈 **Performance Metrics** - Response time tracking and cache efficiency analysis
-- 📤 **Rich Export/Import** - Multiple formats including graph visualization
-
-**Total Tools Available: 50+** spanning memory management, relationships, temporal intelligence, collaboration, autonomous optimization, KV performance monitoring, and advanced vector search.
-
-## 🎯 Agent Tool Selection Solutions (v2.9.1)
-
-**NEW: Comprehensive guidance for AI agents to efficiently select from 31+ available MCP tools**
-
-With 31+ powerful MCP tools available, selecting the right tool for your task can be overwhelming. Our **Agent Tool Selection Solutions** provide structured guidance to help AI agents quickly identify optimal tools and workflows.
-
-### 📚 Documentation Suite
-
-- **[Intent-Based Tool Selection Guide](docs/AGENT_TOOL_SELECTION_GUIDE.md)** - Clear mappings from user intents to appropriate tools
-- **[Common Workflow Patterns](docs/AGENT_WORKFLOW_PATTERNS.md)** - 5 proven workflow templates for common agent tasks
-- **[Tool Categories & Organization](docs/TOOL_CATEGORIES.md)** - 31+ tools organized into 8 logical categories
-- **[Performance Tips & Best Practices](docs/PERFORMANCE_TIPS.md)** - Optimization guidelines for maximum efficiency
-
-### 🔧 Tool Categories (8 Categories, 31+ Tools)
-
-| Category | Tools | Best For |
-|----------|-------|----------|
-| **🔧 CORE** | 5 tools | Daily operations, simple tasks |
-| **📦 BATCH** | 3 tools | Bulk operations (>5 items) |
-| **🕸️ GRAPH** | 6 tools | Exploring connections, relationships |
-| **🧠 INTELLIGENCE** | 6 tools | AI-powered automation, quality improvement |
-| **🎯 CONTEXT** | 6 tools | Project management, relevant suggestions |
-| **🤝 COLLABORATION** | 6 tools | Team projects, multi-agent workflows |
-| **📊 ANALYTICS** | 7 tools | System monitoring, performance analysis |
-| **⏰ LIFECYCLE** | 7 tools | Data maintenance, system optimization |
-
-### ⚡ Quick Selection Guide
-
-```
-Need basic operations? → CORE tools
-Working with many items? → BATCH tools
-Exploring connections? → GRAPH tools
-Want AI assistance? → INTELLIGENCE tools
-Working on projects? → CONTEXT tools
-Collaborating with others? → COLLABORATION tools
-Monitoring system? → ANALYTICS tools
-Managing data lifecycle? → LIFECYCLE tools
-```
-
-### 🔄 Common Workflow Patterns
-
-1. **New Project Setup**: `create_project_context` → `project_onboarding` → `store_multiple_memories` → `build_automatic_relationships`
-2. **Research & Discovery**: `intelligent_search` → `get_related_memories` → `traverse_memory_graph` → `get_contextual_suggestions`
-3. **Quality Improvement**: `memory_health_check` → `improve_memory_quality` → `repair_and_enhance_tags` → `detect_duplicates`
-4. **Analytics & Insights**: `get_memory_stats` → `get_usage_analytics` → `analyze_temporal_relationships`
-5. **Collaboration Setup**: `register_agent` → `create_memory_space` → `grant_space_permission` → `add_memory_to_space`
-
-### 🤖 Smart Tool Recommendation (NEW!)
-
-**Get intelligent tool recommendations based on your intent:**
-
-```javascript
-// Example: Finding information
-await callTool('recommend_tools', {
-  user_intent: 'I want to find information about React performance optimization',
-  current_context: 'Working on a React project',
-  task_description: 'Need to improve the performance of my React application'
-});
-
-// Returns:
-// - Intent: "search_data" (66% confidence)
-// - Top tools: intelligent_search, store_memory, retrieve_memory
-// - Workflows: Quality Improvement, Analytics & Insights
-
-// Example: Storing project data
-await callTool('recommend_tools', {
-  user_intent: 'I want to store multiple memories about my new project',
-  current_context: 'Starting a new e-commerce project',
-  task_description: 'Need to save project requirements, team info, and technical decisions'
-});
-
-// Returns:
-// - Intent: "store_data" (95% confidence)
-// - Top tools: store_memory, retrieve_memory, unified_search
-// - Workflows: New Project Setup, Collaboration Setup
+```bash
+CF_MEMORY_API_KEY="your-key" npx cf-memory-mcp
 ```
 
-### 💡 Performance Tips
-
-- **Use batch tools for >5 operations** (10x performance improvement)
-- **Enable `semantic: true`** for AI-powered search capabilities
-- **Set project context** for better relevance and accuracy
-- **Use `get_contextual_suggestions`** when unsure what to do next
-- **Use `recommend_tools`** for intelligent tool selection guidance
-- **Leverage AI features** for automation and quality improvement
-
-## 🚀 Quick Start
+Test connectivity:
 
 ```bash
-# Run directly with npx (no installation required)
-npx cf-memory-mcp
-
-# Or install globally
-npm install -g cf-memory-mcp
-cf-memory-mcp
+CF_MEMORY_API_KEY="your-key" npx cf-memory-mcp --diagnose
 ```
 
-## ✨ Features
-
-### Core Features
-
-- **🌐 Completely Portable** - No local setup required, connects to deployed Cloudflare Worker
-- **⚡ Production Ready** - Uses Cloudflare D1 database and KV storage for reliability
-- **🔧 Zero Configuration** - Works out of the box with any MCP client
-- **🌍 Cross Platform** - Supports Windows, macOS, and Linux
-- **📦 NPX Compatible** - Run instantly without installation
-- **🔒 Secure** - Built on Cloudflare's secure infrastructure
-- **🚄 Fast** - Global edge deployment with KV caching
-
-### 🤖 Smart Auto-Features (v2.0.0)
-
-- **🔗 Auto-Relationship Detection** - Automatically suggests relationships between memories
-- **🔍 Duplicate Detection** - Identifies potential duplicates with merge strategies
-- **🏷️ Smart Tagging** - AI-powered tag suggestions based on content analysis
-- **⭐ Auto-Importance Scoring** - ML-based importance prediction with detailed reasoning
-
-### 🧠 Intelligent Search & Collections (v2.0.0)
-
-- **🎯 Intelligent Search** - Combines semantic + keyword + graph traversal with query expansion
-- **📚 Memory Collections** - Organize memories with auto-include criteria and sharing
-- **🚀 Project Onboarding** - Automated workflows for project setup and knowledge extraction
-- **🔄 Query Expansion** - Automatically includes synonyms and related terms
-
-### ⏰ Context-Aware & Temporal Intelligence (v2.2.0)
-
-- **🧠 Conversation Context** - Track and manage conversation-specific memory contexts
-- **⏰ Temporal Relevance** - Time-based memory scoring and decay management
-- **🔄 Memory Evolution** - Version control and evolution tracking for memories
-- **📊 Temporal Analytics** - Analyze how memories and relationships change over time
-- **🎯 Context Activation** - Smart memory activation based on conversation context
-- **📈 Predictive Relevance** - ML-powered predictions for memory importance over time
-
-### 🤝 Multi-Agent Collaboration (v2.3.0)
-
-- **👥 Agent Management** - Register and authenticate multiple AI agents
-- **🏠 Collaborative Spaces** - Shared memory workspaces with permission control
-- **🔐 Access Control** - Fine-grained permissions (read/write/admin) for agents
-- **🔄 Memory Synchronization** - Real-time sync between different instances
-- **⚡ Conflict Resolution** - Smart merge strategies for concurrent edits
-- **📊 Collaboration Analytics** - Track agent interactions and collaboration patterns
-
-### 🧠 Memory Intelligence Engine (v2.7.0)
-
-- **🤖 Automated Learning Loops** - Self-improving algorithms that continuously optimize system performance
-- **🎯 Adaptive Thresholds** - Dynamic parameter adjustment based on real-time performance data
-- **🧪 Learning Experiments** - Create and manage A/B tests for optimization strategies
-- **📊 A/B Testing Framework** - Scientific experimentation with statistical analysis and confidence scoring
-- **🔄 Improvement Cycles** - Autonomous optimization cycles that identify and apply performance enhancements
-- **📈 Predictive Analytics** - ML-powered predictions with >95% confidence targeting
-- **🎛️ Threshold Management** - Initialize and manage quality, relevance, importance, and relationship thresholds
-- **📋 Experiment Analysis** - Automated analysis of test results with optimization recommendations
-
-### 📤 Advanced Export/Import (v2.3.0)
-
-- **📋 Multi-Format Export** - JSON, XML, Markdown, CSV, GraphML formats
-- **🔄 Batch Operations** - Asynchronous export/import job processing
-- **🕸️ Graph Visualization** - Export memory networks for analysis tools
-- **📦 Rich Metadata** - Full preservation of relationships and collaboration data
-- **🔀 Conflict Handling** - Smart import strategies for existing memories
-
-### 📊 Phase 1 Enhancements (v2.5.0)
-
-- **📈 Memory Analytics Dashboard** - Real-time statistics, usage patterns, and performance metrics
-- **🔍 Advanced Search Filters** - Date range, importance score, content size, and boolean search operators
-- **🏥 Memory Health Monitoring** - Orphan detection, stale memory identification, and quality scoring
-- **📊 Performance Insights** - Response time tracking, cache efficiency, and database performance
-- **🎯 Quality Analysis** - Multi-factor quality scoring with improvement recommendations
+Useful environment variables:
 
-### Advanced Features
+- `CF_MEMORY_BASE_URL` — override the server URL (defaults to `https://memcp.ai`). Pre-migration `workers.dev` URLs are auto-rewritten to memcp.ai.
+- `CF_MEMORY_TRACE=1` — verbose request/response logging to `/tmp/cf-memory-mcp.log` (rotates at 5MB)
+- `CF_MEMORY_PROGRESS=true` — stream per-file indexing progress via SSE to stderr during `index_project`
+- `CF_MEMORY_AUTO_WATCH=true` — watch the project directory and auto-reindex on file change
+- `CF_MEMORY_WATCH_PATH=/path/to/project` — explicit project root (defaults to bridge's `cwd`)
+- `CF_MEMORY_PROJECT_NAME=my-project` — display name when auto-watch indexes the project
 
-- **🧠 Semantic Search** - AI-powered vector search using Cloudflare AI Workers
-- **🕸️ Knowledge Graph** - Store and traverse relationships between memories
-- **📦 Batch Operations** - Efficiently process multiple memories at once
-- **🔍 Graph Traversal** - Find paths and connections between related memories
-- **🎯 Smart Filtering** - Advanced search with tags, importance, and similarity
+### Recommended workflow for active development
 
-## 🛠️ Usage
-
-### With MCP Clients
-
-Add to your MCP client configuration:
-
-```json
-{
-  "mcpServers": {
-    "cf-memory": {
-      "command": "npx",
-      "args": ["cf-memory-mcp"]
-    }
-  }
-}
+```text
+1. retrieve_context("how does X work")           ← finds chunks with file_imports + citation
+2. (if stale_count > 0): refresh_stale(project)  ← re-embeds edited files
+3. retrieve_context(...)                          ← fresh results
+4. get_related_code(name=X)                       ← navigate the call graph
+5. get_file_content(file_path)                    ← read whole file if needed
 ```
 
-### With Augment
+The bridge auto-detects the project from `cwd` so `project_id` is optional in step 1.
 
-Add to your `augment-config.json`:
+### Direct Remote MCP
 
-```json
-{
-  "mcpServers": {
-    "cf-memory": {
-      "command": "npx",
-      "args": ["cf-memory-mcp"]
-    }
-  }
-}
-```
-
-### With Claude Desktop
+- Base URL: [https://memcp.ai](https://memcp.ai)
+- MCP endpoint: [https://memcp.ai/mcp](https://memcp.ai/mcp)
+- Health check: [https://memcp.ai/health](https://memcp.ai/health)
 
-Add to your Claude Desktop MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "cf-memory": {
-      "command": "npx",
-      "args": ["cf-memory-mcp"]
+```bash
+curl -X POST https://memcp.ai/mcp \
+  -H 'content-type: application/json' \
+  -H 'x-api-key: your-key' \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2025-03-26",
+      "capabilities": {},
+      "clientInfo": { "name": "example", "version": "1.0.0" }
     }
-  }
-}
+  }'
 ```
 
-## 🔧 Available Tools (v3.2.0 - Consolidated)
-
-The CF Memory MCP server provides **20 essential tools** (consolidated from 95+ tools for improved usability):
-
-### Core Memory Operations (5 tools)
-
-#### `store_memory`
-Store a new memory with optional metadata and tags.
-
-**Parameters:**
-- `content` (string, required) - The memory content
-- `tags` (array, optional) - Tags for categorization
-- `importance_score` (number, optional) - Importance score 0-10
-- `metadata` (object, optional) - Additional metadata
-
-#### `retrieve_memory`
-Retrieve a specific memory by ID.
-
-**Parameters:**
-- `id` (string, required) - The unique memory ID
-
-#### `update_memory`
-Update an existing memory.
-
-**Parameters:**
-- `id` (string, required) - Memory ID to update
-- `content` (string, optional) - New content
-- `tags` (array, optional) - New tags
-- `importance_score` (number, optional) - New importance score
-- `metadata` (object, optional) - New metadata
+### Incremental Local Indexing
 
-#### `delete_memory`
-Delete a memory and its relationships.
-
-**Parameters:**
-- `id` (string, required) - Memory ID to delete
-
-#### `unified_search`
-Unified search interface consolidating all search modes: basic, intelligent, temporal, and vectorize.
-
-**Parameters:**
-- `query` (string, optional) - Full-text or semantic search query
-- `mode` (string, optional) - Search mode: 'basic', 'intelligent', 'temporal', 'vectorize'
-- `tags` (array, optional) - Filter by specific tags
-- `limit` (number, optional) - Maximum results (default: 10)
-- `semantic` (boolean, optional) - Use AI-powered semantic search
-- `time_context` (string, optional) - Temporal context: 'today', 'last_week', 'last_month'
-
-### Analytics & System (3 tools)
-
-#### `unified_analytics`
-Unified analytics interface for memory, usage, patterns, system, and collaboration analytics.
-
-**Parameters:**
-- `scope` (string, optional) - Analytics scope: 'memory', 'usage', 'patterns', 'system', 'collaboration'
-- `time_range` (string, optional) - Time range: 'day', 'week', 'month'
-- `analysis_type` (string, optional) - Analysis depth: 'basic', 'comprehensive', 'learning'
-
-#### `get_system_health_report`
-Generate comprehensive system health report with actionable insights.
-
-**Parameters:**
-- `report_type` (string, optional) - Report type: 'summary', 'detailed', 'diagnostic'
-- `time_range` (string, optional) - Time range: 'day', 'week', 'month'
-- `include_recommendations` (boolean, optional) - Include optimization recommendations
-
-#### `get_cleanup_suggestions`
-Get AI-powered cleanup suggestions for memory optimization.
-
-**Parameters:**
-- `suggestion_types` (array, optional) - Types: 'duplicates', 'low_quality', 'orphaned', 'outdated'
-- `limit` (number, optional) - Maximum suggestions
-
-### Unified Management Tools (6 tools)
-
-#### `unified_relationships`
-Manage memory relationships: create, update, list, delete.
-
-**Parameters:**
-- `action` (string, required) - Action: 'create', 'update', 'list', 'delete'
-- `source_memory_id` (string, conditional) - Source memory ID (for create)
-- `target_memory_id` (string, conditional) - Target memory ID (for create)
-- `relationship_type` (string, conditional) - Relationship type
-- `relationship_id` (string, conditional) - Relationship ID (for update/delete)
-- `strength` (number, optional) - Relationship strength 0-1
-
-#### `unified_collections`
-Manage memory collections: create, add, remove, get memories.
-
-**Parameters:**
-- `action` (string, required) - Action: 'create', 'add', 'remove', 'get_memories', 'list'
-- `name` (string, conditional) - Collection name (for create)
-- `collection_id` (string, conditional) - Collection ID
-- `memory_id` (string, conditional) - Memory ID (for add/remove)
-
-#### `unified_optimization`
-Run optimization operations: recommendations, comprehensive optimization.
-
-**Parameters:**
-- `action` (string, required) - Action: 'get_recommendations', 'run_comprehensive'
-- `optimization_scope` (string, optional) - Scope: 'quality', 'relationships', 'performance', 'comprehensive'
-- `dry_run` (boolean, optional) - Preview changes without applying
-
-#### `unified_batch_jobs`
-Manage batch processing jobs: create, status, cancel, results.
-
-**Parameters:**
-- `action` (string, required) - Action: 'create', 'status', 'cancel', 'results'
-- `job_type` (string, conditional) - Job type (for create): 'quality_improvement', 'relationship_building', 'export', 'import'
-- `job_id` (string, conditional) - Job ID (for status/cancel/results)
-
-#### `unified_system_alerts`
-Manage system alerts: list, configure, resolve.
-
-**Parameters:**
-- `action` (string, required) - Action: 'list', 'configure', 'resolve'
-- `alert_id` (string, conditional) - Alert ID (for resolve)
-- `alert_types` (array, optional) - Alert types to configure
-- `thresholds` (object, optional) - Custom thresholds
-
-#### `unified_agent_handoff`
-Manage agent handoff: get context, enable handoff, cleanup.
-
-**Parameters:**
-- `action` (string, required) - Action: 'get_context', 'enable_handoff', 'cleanup'
-- `session_id` (string, optional) - Session ID
-
-### Project Intelligence (1 tool)
-
-#### `get_complete_project_intelligence`
-Unified project intelligence combining scanning, briefing, and handoff summary.
-
-**Parameters:**
-- `project_path` (string, optional) - Path to project root
-- `project_name` (string, optional) - Project name
-- `briefing_type` (string, optional) - Briefing type: 'full', 'quick', 'technical', 'deployment', 'onboarding'
-- `include_components` (array, optional) - Components: 'scan', 'briefing', 'handoff', 'list'
-
-### Multi-Agent Collaboration (3 tools)
-
-#### `register_agent`
-Register a new agent in the system for collaboration.
-
-**Parameters:**
-- `name` (string, required) - Agent name
-- `type` (string, required) - Agent type: 'ai_agent', 'human_user', 'system'
-- `description` (string, optional) - Agent description
-- `capabilities` (array, optional) - Agent capabilities
-
-#### `create_memory_space`
-Create a collaborative memory space for multi-agent sharing.
-
-**Parameters:**
-- `name` (string, required) - Memory space name
-- `owner_agent_id` (string, required) - Agent ID who owns this space
-- `space_type` (string, optional) - Type: 'private', 'collaborative', 'public'
-- `access_policy` (string, optional) - Policy: 'open', 'invite_only', 'restricted'
-
-#### `get_agent_spaces`
-Get all memory spaces accessible to an agent.
-
-**Parameters:**
-- `agent_id` (string, required) - Agent ID to get spaces for
-
-### Export/Import (2 tools)
-
-#### `create_export_job`
-Create an export job for memories.
-
-**Parameters:**
-- `format` (string, required) - Export format: 'json', 'xml', 'markdown', 'csv', 'graphml'
-- `initiated_by` (string, required) - Agent ID initiating export
-- `memory_ids` (array, optional) - Specific memory IDs to export
-- `include_relationships` (boolean, optional) - Include memory relationships
-
-#### `create_import_job`
-Create an import job for memories.
-
-**Parameters:**
-- `format` (string, required) - Import format
-- `file_content` (string, required) - File content to import
-- `initiated_by` (string, required) - Agent ID initiating import
-- `conflict_resolution` (string, optional) - How to handle existing memories: 'skip', 'overwrite', 'merge'
-
----
-
-### Tool Consolidation Summary (v3.2.0)
-
-| Category | Tools | Description |
-|----------|-------|-------------|
-| Core CRUD | 5 | store, retrieve, update, delete, unified_search |
-| Analytics | 3 | unified_analytics, health_report, cleanup_suggestions |
-| Unified Management | 6 | relationships, collections, optimization, batch_jobs, alerts, handoff |
-| Project Intelligence | 1 | get_complete_project_intelligence |
-| Collaboration | 3 | register_agent, create_memory_space, get_agent_spaces |
-| Export/Import | 2 | create_export_job, create_import_job |
-| **Total** | **20** | Reduced from 95+ tools (79% reduction) |
-
-## 🌐 Architecture
-
-```
-┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
-│   MCP Client    │    │  cf-memory-mcp   │    │  Cloudflare Worker  │
-│   (Augment,     │◄──►│   (npm package)  │◄──►│   (Production API)  │
-│   Claude, etc.) │    │                  │    │                     │
-└─────────────────┘    └──────────────────┘    └─────────────────────┘
-                                                          │
-                                                          ▼
-                                               ┌─────────────────────┐
-                                               │  Cloudflare D1 DB   │
-                                               │  + KV Storage       │
-                                               │  + Vectorize (Paid) │
-                                               │  + AI Workers       │
-                                               └─────────────────────┘
+```bash
+CF_MEMORY_API_KEY="your-key" cf-memory-index /path/to/project
+CF_MEMORY_API_KEY="your-key" cf-memory-watch /path/to/project
 ```
 
-### Hybrid D1+Vectorize Architecture
-
-The system uses a sophisticated hybrid approach:
-
-- **D1 Database**: Primary storage for all memory content, metadata, relationships, and tags
-- **Vectorize**: High-performance vector similarity search with 50M queries/month capacity
-- **Hybrid Search**: Vectorize finds similar vectors → D1 enriches with full memory data
-- **Fallback System**: Automatic fallback to D1-based search if Vectorize is unavailable
-- **Data Sync**: Both databases stay synchronized for all memory operations
+The indexer keeps a local hash cache and uploads only changed files.
 
-📖 **[Detailed Architecture Documentation](docs/vectorize-architecture.md)** - Complete technical overview with diagrams, data flows, and performance characteristics.
-
-## 🔧 Command Line Options
+## Local Validation
 
 ```bash
-# Start the MCP server
-npx cf-memory-mcp
-
-# Show version
-npx cf-memory-mcp --version
-
-# Show help
-npx cf-memory-mcp --help
-
-# Enable debug logging
-DEBUG=1 npx cf-memory-mcp
+npm run validate:simplified
 ```
 
-## 🌍 Environment Variables
-
-- `DEBUG=1` - Enable debug logging
-- `MCP_DEBUG=1` - Enable MCP-specific debug logging
-
-## 🧠 NEW: Assistant Memory Features (v4.0.0)
-
-**AI Assistant Memory Management** - Long-term memory for AI assistants with session tracking, context bootstrapping, and entity relationships.
-
-### Assistant Memory Tools
-
-| Tool | Description |
-|------|-------------|
-| `store_memory` | Store facts, preferences, or important context |
-| `retrieve_memories` | Semantic search over memories |
-| `get_context_bootstrap` | Get memories to pre-load on session start |
-| `start_session` | Begin a conversation session |
-| `end_session` | End session, extract key facts |
-| `store_entity` | Store structured entities (people, projects, etc.) |
-
-### Memory Types
-- **fact** - General knowledge about the user
-- **preference** - User preferences and settings
-- **task** - Active or completed tasks
-- **entity** - Structured data about people, projects, companies
-- **session_summary** - Summarized conversation sessions
-
-### Example Usage
-
-```typescript
-// Store a memory
-const result = await store_memory({
-  content: "John is building a RAG pipeline with 4x H100 GPUs",
-  type: "fact",
-  importance: 0.9,
-  confidence: 1.0,
-  source: "user_explicit",
-  tags: ["hardware", "rag", "work"]
-});
-
-// Retrieve relevant memories
-const memories = await retrieve_memories({
-  query: "what hardware is John using?",
-  limit: 5,
-  min_importance: 0.7
-});
-
-// Bootstrap context on session start
-const context = await get_context_bootstrap({
-  max_tokens: 4000,
-  recent_sessions: 3,
-  current_context: "discussing RAG pipeline"
-});
-```
+That runs strict TypeScript validation for `src-simplified` plus the simplified worker tests.
 
-### Database Schema
+## Deploy
 
-Run the migration to add assistant memory tables:
 ```bash
-wrangler d1 execute MEMORY_DB --file=./migrations/002_assistant_memory.sql
+./scripts/deploy.sh
 ```
 
-Create the vectorize index:
-```bash
-wrangler vectorize create assistant-memory-index --dimensions=1024 --metric=cosine
-```
-
-Add to `wrangler.toml`:
-```toml
-[[vectorize]]
-binding = "VECTORIZE_ASSISTANT"
-index_name = "assistant-memory-index"
-```
-
----
-
-## 📋 Requirements
-
-- **Node.js** 16.0.0 or higher
-- **Internet connection** (connects to Cloudflare Worker)
-- **MCP client** (Augment, Claude Desktop, etc.)
-
-## 🚀 Why CF Memory MCP?
-
-### Traditional Approach ❌
-- Clone repository
-- Set up local database
-- Configure environment variables
-- Manage local server process
-- Handle updates manually
-
-### CF Memory MCP ✅
-- Run `npx cf-memory-mcp`
-- That's it! 🎉
-
-## 🔒 Privacy & Security
-
-- **No local data storage** - All data stored securely in Cloudflare D1
-- **HTTPS encryption** - All communication encrypted in transit
-- **Edge deployment** - Data replicated globally for reliability
-- **No API keys required** - Public read/write access for simplicity
-
-## 🤝 Contributing
-
-Contributions are welcome! Please see the [GitHub repository](https://github.com/johnlam90/cf-memory-mcp) for more information.
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file for details.
+That deploys the active worker and applies the simplified D1 schema and required migrations.
 
-## 🔗 Links
+## Canonical Files
 
-- **GitHub Repository**: https://github.com/johnlam90/cf-memory-mcp
-- **npm Package**: https://www.npmjs.com/package/cf-memory-mcp
-- **Issues**: https://github.com/johnlam90/cf-memory-mcp/issues
-- **MCP Specification**: https://modelcontextprotocol.io/
+- [src-simplified/index.ts](/Users/johnlam/cf-memory-mcp/src-simplified/index.ts)
+- [src-simplified/services/IndexingService.ts](/Users/johnlam/cf-memory-mcp/src-simplified/services/IndexingService.ts)
+- [src-simplified/services/RetrievalService.ts](/Users/johnlam/cf-memory-mcp/src-simplified/services/RetrievalService.ts)
+- [src-simplified/queue-consumer.ts](/Users/johnlam/cf-memory-mcp/src-simplified/queue-consumer.ts)
+- [wrangler.toml](/Users/johnlam/cf-memory-mcp/wrangler.toml)
+- [bin/cf-memory-mcp.js](/Users/johnlam/cf-memory-mcp/bin/cf-memory-mcp.js)
+- [bin/cf-memory-mcp-indexer.js](/Users/johnlam/cf-memory-mcp/bin/cf-memory-mcp-indexer.js)
 
----
+## Notes
 
-Made with ❤️ by [John Lam](https://github.com/johnlam90)
+- The simplified worker is the active product path.
+- Older material from previous architectures still exists in the repo; treat the simplified worker and `wrangler.toml` as canonical.
+- If repo-level long-running orchestration is needed later, add Workflows on top of the current stack rather than replacing Queues.