Metadata-Version: 2.4
Name: elasticsearch-memory-mcp
Version: 6.2.0
Summary: 🧠 Elasticsearch-powered MCP server with hierarchical memory categorization, intelligent auto-detection, and batch review capabilities
Author-email: Frederico Castro <fredac100@users.noreply.github.com>
Maintainer-email: Frederico Castro <fredac100@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/fredac100/elasticsearch-memory-mcp
Project-URL: Documentation, https://github.com/fredac100/elasticsearch-memory-mcp#readme
Project-URL: Repository, https://github.com/fredac100/elasticsearch-memory-mcp
Project-URL: Bug Tracker, https://github.com/fredac100/elasticsearch-memory-mcp/issues
Project-URL: Changelog, https://github.com/fredac100/elasticsearch-memory-mcp/blob/main/README.md#changelog
Keywords: mcp,model-context-protocol,elasticsearch,claude,memory,semantic-search,ai,llm,vector-search,embeddings
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: elasticsearch>=8.0.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: torch>=2.0.0
Requires-Dist: mcp>=0.9.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# 🧠 Elasticsearch Memory MCP

[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful **Model Context Protocol (MCP)** server that provides persistent, intelligent memory using Elasticsearch with hierarchical categorization and semantic search capabilities.

## ✨ Features

### 🎯 V6.2 - Latest Release

- **🏷️ Hierarchical Memory Categorization**
  - 5 category types: `identity`, `active_context`, `active_project`, `technical_knowledge`, `archived`
  - Automatic category detection with confidence scoring
  - Manual reclassification support

- **🤖 Intelligent Auto-Detection**
  - Accumulative scoring system (0.7-0.95 confidence range)
  - 23+ specialized keyword patterns
  - Context-aware categorization

- **📦 Batch Review System**
  - Review uncategorized memories in batches
  - Approve/reject/reclassify workflows
  - 10x faster than individual categorization

- **🔄 Backward Compatible Fallback**
  - Seamlessly loads v5 uncategorized memories
  - No data loss during upgrades
  - Graceful degradation

- **🚀 Optimized Context Loading**
  - Hierarchical priority loading (~30-40 memories vs 117)
  - 60-70% token reduction
  - Smart relevance ranking

- **💾 Persistent Memory**
  - Vector embeddings for semantic search
  - Session management with checkpoints
  - Conversation snapshots

## 🛠️ Installation

### Prerequisites

- Python 3.8+
- Elasticsearch 8.0+
- Git

### Step 1: Clone the Repository

```bash
git clone https://github.com/fredac100/elasticsearch-memory-mcp.git
cd elasticsearch-memory-mcp
```

### Step 2: Install Dependencies

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install requirements
pip install -r requirements.txt
```

### Step 3: Start Elasticsearch

```bash
# Using Docker
docker run -d -p 9200:9200 -e "discovery.type=single-node" elasticsearch:8.0.0

# Or install locally
# https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html
```

### Step 4: Configure MCP

#### For Claude Desktop

Add to `~/.config/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "elasticsearch-memory": {
      "command": "/path/to/elasticsearch-memory-mcp/venv/bin/python",
      "args": [
        "/path/to/elasticsearch-memory-mcp/mcp_server.py"
      ],
      "env": {
        "ELASTICSEARCH_URL": "http://localhost:9200"
      }
    }
  }
}
```

#### For Claude Code CLI

```bash
claude mcp add elasticsearch-memory "/path/to/venv/bin/python /path/to/mcp_server.py" \
  -e ELASTICSEARCH_URL=http://localhost:9200
```

## 📚 Usage

### Available Tools

#### 1. **save_memory**
Save a new memory with automatic categorization.

```json
{
  "content": "Fred prefers direct, brutal communication style",
  "type": "user_profile",
  "importance": 9,
  "tags": ["communication", "preference"]
}
```

#### 2. **load_initial_context** (Resource)
Loads hierarchical context with:
- Identity memories (who you are)
- Active context (current work)
- Active projects (ongoing)
- Technical knowledge (relevant facts)

#### 3. **review_uncategorized_batch** 🆕 V6.2
Review uncategorized memories in batches.

```json
{
  "batch_size": 10,
  "min_confidence": 0.6
}
```

Returns suggestions with auto-detected categories and confidence scores.

#### 4. **apply_batch_categorization** 🆕 V6.2
Apply categorizations in batch after review.

```json
{
  "approve": ["id1", "id2"],           // Auto-categorize
  "reject": ["id3"],                    // Skip
  "reclassify": {"id4": "archived"}    // Force category
}
```

#### 5. **search_memory**
Semantic search with filters.

```json
{
  "query": "SAE project details",
  "limit": 5,
  "category": "active_project"
}
```

#### 6. **auto_categorize_memories**
Batch auto-categorize uncategorized memories.

```json
{
  "max_to_process": 50,
  "min_confidence": 0.75
}
```

## 🏗️ Architecture

```
┌─────────────────┐
│  Claude (MCP)   │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────┐
│  MCP Server (v6.2)          │
│  ┌─────────────────────┐    │
│  │ Auto-Detection      │    │
│  │ - Keyword matching  │    │
│  │ - Confidence score  │    │
│  └─────────────────────┘    │
│                              │
│  ┌─────────────────────┐    │
│  │ Batch Review        │    │
│  │ - Review workflow   │    │
│  │ - Bulk operations   │    │
│  └─────────────────────┘    │
└──────────┬──────────────────┘
           │
           ▼
┌──────────────────────────────┐
│  Elasticsearch               │
│  ┌────────────────────────┐  │
│  │ memories (index)       │  │
│  │ - embeddings (vector)  │  │
│  │ - memory_category      │  │
│  │ - category_confidence  │  │
│  └────────────────────────┘  │
└──────────────────────────────┘
```

## 📊 Category System

| Category | Description | Examples |
|----------|-------------|----------|
| **identity** | Core identity, values, preferences | "Fred prefers brutal honesty" |
| **active_context** | Current work, recent conversations | "Working on SAE implementation" |
| **active_project** | Ongoing projects | "Mirror architecture design" |
| **technical_knowledge** | Facts, configs, tools | "Elasticsearch index settings" |
| **archived** | Completed, deprecated, old migrations | "Refactored old auth system" |

## 🎯 Auto-Detection Examples

### High Confidence (0.8-0.95)

```
"Fred prefere comunicação brutal" → identity (0.9)
"Refatoração do sistema SAE concluída" → archived (0.85)
"Próximos passos: implementar dashboard" → active_context (0.8)
```

### Multiple Keywords (Accumulative Scoring)

```
"Fred prefere comunicação brutal. Primeira vez usando este estilo."
  → Match 1: "Fred prefere" (+0.9)
  → Match 2: "primeira vez" (+0.8)
  → Total: 0.95 (normalized)
```

## 🔄 Migration from V5

The v6.2 system includes automatic fallback for v5 memories:

1. **Uncategorized memories** → Loaded via type/tags fallback
2. **Visual separation** → Categorized vs. fallback sections
3. **Batch review** → Categorize old memories efficiently

```bash
# Review and categorize v5 memories
review_uncategorized_batch(batch_size=20)
apply_batch_categorization(approve=[...])
```

## 🚀 Performance

- **Load initial context**: ~10-15s (includes embedding model load)
- **Save memory**: <1s
- **Search**: <500ms
- **Batch review (10 items)**: ~2s
- **Auto-categorize (50 items)**: ~5s

## 🧪 Testing

```bash
# Run quick test
python test_quick.py

# Expected output:
# ✅ Elasticsearch connected
# ✅ Context loaded
# ✅ Identity memories found
# ✅ Projects separated from fallback
```

## 📝 Changelog

### V6.2 (Latest)
- ✅ Improved auto-detection (0.4 → 0.9 confidence)
- ✅ 23 new specialized keywords
- ✅ Batch review tools (review_uncategorized_batch, apply_batch_categorization)
- ✅ Visual separation (categorized vs fallback)
- ✅ Accumulative confidence scoring

### V6.1
- ✅ Fallback mechanism for uncategorized memories
- ✅ Backward compatibility with v5

### V6.0
- ✅ Memory categorization system
- ✅ Hierarchical context loading
- ✅ Auto-detection with confidence

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
- Powered by [Elasticsearch](https://www.elastic.co)
- Embeddings by [Sentence Transformers](https://www.sbert.net)

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/fredac100/elasticsearch-memory-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/fredac100/elasticsearch-memory-mcp/discussions)

---

Made with ❤️ for the Claude ecosystem
