cf-memory-mcp/README.md

Best-in-class MCP server with CONTEXTUAL CHUNKING (Anthropic-style, 35-67% better retrieval), Optimized LLM stack (Llama-3.1-8B), BGE-M3 embeddings, Query Expansion Caching, Hybrid Embedding Strategy, and Unified Project Intelligence

# 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)

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.

## 🎯 Current Version: v3.2.1 (Tool Consolidation Release)

**🔧 Major Update: Tool Consolidation** - Reduced from 95+ tools to 20 essential tools (79% reduction) for improved usability and performance.

## 📊 Real-time Analytics Dashboard

**NEW: Beautiful, high-performance analytics dashboard with interactive visualizations and business intelligence**

🌐 **Live Dashboard**: [https://55a2aea1.cf-memory-dashboard-vue.pages.dev](https://55a2aea1.cf-memory-dashboard-vue.pages.dev)

### 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

### 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

### 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

**Previous Features (Phase 2 Enhancements):**

- 🚀 **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

**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
```

### 💡 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

```bash
# Run directly with npx (no installation required)
npx cf-memory-mcp

# Or install globally
npm install -g cf-memory-mcp
cf-memory-mcp
```

## ✨ 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

### Advanced Features

- **🧠 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

## 🛠️ Usage

### With MCP Clients

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "cf-memory": {
      "command": "npx",
      "args": ["cf-memory-mcp"]
    }
  }
}
```

### With Augment

Add to your `augment-config.json`:

```json
{
  "mcpServers": {
    "cf-memory": {
      "command": "npx",
      "args": ["cf-memory-mcp"]
    }
  }
}
```

### With Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "cf-memory": {
      "command": "npx",
      "args": ["cf-memory-mcp"]
    }
  }
}
```

## 🔧 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

#### `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       │
                                               └─────────────────────┘
```

### 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

📖 **[Detailed Architecture Documentation](docs/vectorize-architecture.md)** - Complete technical overview with diagrams, data flows, and performance characteristics.

## 🔧 Command Line Options

```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
```

## 🌍 Environment Variables

- `DEBUG=1` - Enable debug logging
- `MCP_DEBUG=1` - Enable MCP-specific debug logging

## 📋 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.

## 🔗 Links

- **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/

---

Made with ❤️ by [John Lam](https://github.com/johnlam90)