Elasticsearch Memory MCP Server with Hierarchical Semantic Search

Overview

This MCP (Model Context Protocol) server uses Elasticsearch to provide persistent, intelligent memory for LLM-based assistants. It stores memories as documents with vector embeddings, applies hierarchical categorization, and supports semantic search so model prompts can be enriched with the most relevant context. The server is designed to reduce token usage and improve relevance by prioritizing memories by category and semantic similarity.

Built as an MCP-compatible service, it integrates with clients like Claude (desktop and CLI) and can run locally or in containerized environments. It is helpful for assistant applications that need long-lived, searchable memory (user profiles, projects, technical notes, conversation snapshots) with tooling for automatic classification and human-in-the-loop batch review.

Features

• Hierarchical memory categories with priority loading:
  • identity, active_context, active_project, technical_knowledge, archived
• Automatic category detection using keyword heuristics and confidence scoring
• Vector embeddings stored in Elasticsearch for semantic / vector search
• Batch review workflow: review, approve/reject/reclassify uncategorized memories
• Backward-compatible handling for older memory formats
• Optimized context loading to reduce token count and focus on high-relevance memories
• Session management and conversation snapshotting for checkpointed context
• CLI and MCP-compatible execution for easy integration

Categories at a glance:

Installation / Configuration

Prerequisites:

• Python 3.8+
• Elasticsearch 8.x (single-node or cluster)
• (Optional) uvx to run MCP wrappers

Quick install from PyPI:

pip install elasticsearch-memory-mcp

Start Elasticsearch (Docker recommended):

docker run -d -p 9200:9200 -e "discovery.type=single-node" elasticsearch:8.0.0

Run the MCP server (installed CLI) or as a module:

# CLI (after pip install)
elasticsearch-memory-mcp

# or as module
python -m elasticsearch_memory_mcp

Environment variables:

• ELASTICSEARCH_URL (e.g. http://localhost:9200)
• Optional embedding provider variables depending on your setup

Example MCP configuration for Claude Desktop (~/.config/Claude/claude_desktop_config.json):

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

For Claude Code CLI:

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

Install from source (contribute or modify):

git clone https://github.com/fredac100/elasticsearch-memory-mcp.git
cd elasticsearch-memory-mcp
python3 -m venv venv
source venv/bin/activate
pip install -e .

Then point your MCP configuration to the virtualenv python running the module.

Available Tools / API Resources

Common MCP tool endpoints (JSON payload examples):

• save_memory — store a memory (automatic categorization)

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

• load_initial_context — fetch prioritized context (identity → active_context → active_project → technical_knowledge)

Request body examples vary by MCP client; response includes ordered memories and embeddings used for ranking.

• search_memory — semantic search with optional filters

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

• review_uncategorized_batch — pull a batch for human review

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

• apply_batch_categorization — commit batch decisions

{
  "approve": ["id1", "id2"],
  "reject": ["id3"],
  "reclassify": {"id4": "archived"}
}

• auto_categorize_memories — run automated categorization over uncategorized items

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

Use Cases

• Personal assistant memory: persist user preferences, identity facts, and recent tasks so responses remain consistent across sessions.
• Developer knowledge base: store code snippets, design decisions, and technical notes; use semantic search to pull relevant fragments into prompts.
• Customer support augmentation: attach prior tickets, product usage notes, and customer profiles to incoming queries to provide informed responses.
• Project tracking for R&D: prioritize active project memories and surface the most relevant milestones and notes to the LLM during planning.

Concrete example — reduce prompt tokens:

• Without hierarchical filtering, an assistant might load ~117 memories into a context window.
• With category-prioritized loading, the server selects ~30–40 high-priority memories, reducing token usage by ~60–70% while keeping relevance high.

Architecture (high level)

Simple ASCII overview:

Claude (MCP client)
        │
        ▼
MCP Server (elasticsearch-memory-mcp)
 - auto-detection / categorization
 - batch review workflows
 - vector embedding storage
        │
        ▼
Elasticsearch (document + vector indices)

For full source, examples, and issue tracking see the GitHub repo: https://github.com/fredac100/elasticsearch-memory-mcp

If you’re new to MCP servers, this implementation provides a practical combination of semantic vector search and hierarchical memory management to make LLM contexts smaller and more informative.