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

• 🏷️ 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

Install directly from PyPI:

pip install elasticsearch-memory-mcp

• Python 3.8+
• Elasticsearch 8.0+

# Using Docker (recommended) 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

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

{ "mcpServers": { "elasticsearch-memory": { "command": "uvx", "args": ["elasticsearch-memory-mcp"], "env": { "ELASTICSEARCH_URL": "http://localhost:9200" } } } }

Note: If you don't have uvx, install with pip install uvx or use python -m elasticsearch_memory_mcp instead.

claude mcp add elasticsearch-memory uvx elasticsearch-memory-mcp \ -e ELASTICSEARCH_URL=http://localhost:9200

If you want to contribute or modify the code:

# Clone repository git clone https://github.com/fredac100/elasticsearch-memory-mcp.git cd elasticsearch-memory-mcp # Create virtual environment python3 -m venv venv source venv/bin/activate # Install in development mode pip install -e .

Then configure MCP pointing to your local installation:

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

Save a new memory with automatic categorization.

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

Loads hierarchical context with:

• Identity memories (who you are)
• Active context (current work)
• Active projects (ongoing)
• Technical knowledge (relevant facts)

Review uncategorized memories in batches.

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

Returns suggestions with auto-detected categories and confidence scores.

Apply categorizations in batch after review.

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

Semantic search with filters.

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

Batch auto-categorize uncategorized memories.

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

┌─────────────────┐ │ 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 │ │ │ └────────────────────────┘ │ └──────────────────────────────┘ 

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

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

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

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

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

# Run quick test python test_quick.py # Expected output: # ✅ Elasticsearch connected # ✅ Context loaded # ✅ Identity memories found # ✅ Projects separated from fallback

• ✅ 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

• ✅ Fallback mechanism for uncategorized memories
• ✅ Backward compatibility with v5

• ✅ Memory categorization system
• ✅ Hierarchical context loading
• ✅ Auto-detection with confidence

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

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with Model Context Protocol (MCP)
• Powered by Elasticsearch
• Embeddings by Sentence Transformers

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ for the Claude ecosystem