Elasticsearch Knowledge Graph for MCP

A scalable knowledge graph implementation for Model Context Protocol (MCP) using Elasticsearch as the backend. This implementation is designed to replace the previous JSON file-based approach with a more scalable, performant solution.

Key Features

Scalable Storage: Elasticsearch provides distributed, scalable storage for knowledge graph entities and relations
Advanced Search: Full-text search with fuzzy matching and relevancy ranking
Memory-like Behavior: Tracks access patterns to prioritize recently viewed and important entities
Import/Export Tools: Easy migration from existing JSON-based knowledge graphs
Rich Query API: Advanced querying capabilities not possible with the previous implementation
Admin Tools: Management CLI for inspecting and maintaining the knowledge graph
Complete CRUD Operations: Full create, read, update, and delete capabilities for entities and relations
Elasticsearch Query Support: Native support for Elasticsearch query DSL for advanced search capabilities
Multi-Zone Architecture: Separate memory zones for organizing domain-specific knowledge
Cross-Zone Relations: Relations between entities in different memory zones

Architecture

The knowledge graph system consists of:

Elasticsearch Cluster: Core data store for entities and relations
Knowledge Graph Library: TypeScript interface to Elasticsearch with all core operations
MCP Server: Protocol-compliant server for AI models to interact with the knowledge graph
Admin CLI: Command-line tools for maintenance and management
Import/Export Tools: Utilities for data migration and backup
Multiple Memory Zones: Ability to partition knowledge into separate zones/indices

Getting Started

Prerequisites

Node.js 18+
Docker and Docker Compose

Installation

Clone the repository:
git clone https://github.com/mcp-servers/mcp-servers.git cd mcp-servers/memory
Install dependencies:
npm install
Start the Elasticsearch cluster:
npm run es:start
Build the project:
npm run build

Migration from JSON

If you have an existing JSON-based knowledge graph, you can import it:

node dist/admin-cli.js init
node dist/admin-cli.js import memory.json

Running the MCP Server

Start the MCP server that connects to Elasticsearch:

npm start

Configuration

The system can be configured via environment variables:

ES_NODE: Elasticsearch node URL (default: http://localhost:9200)
ES_USERNAME: Elasticsearch username (if authentication is enabled)
ES_PASSWORD: Elasticsearch password (if authentication is enabled)
MEMORY_FILE_PATH: Path to memory JSON file (for import/export)
KG_DEFAULT_ZONE: Default memory zone to use (default: default)
KG_INDEX_PREFIX: Prefix for Elasticsearch indices (default: knowledge-graph)

Admin CLI Commands

The admin CLI provides tools for managing the knowledge graph:

# Initialize Elasticsearch index
node dist/admin-cli.js init

# Import data from JSON file to a specific zone
node dist/admin-cli.js import memory.json [zone]

# Export data from a specific zone to JSON file
node dist/admin-cli.js export backup.json [zone]

# Backup all zones and relations
node dist/admin-cli.js backup full-backup.json

# Restore from a full backup
node dist/admin-cli.js restore full-backup.json [--yes]

# Show statistics about all zones or a specific zone
node dist/admin-cli.js stats [zone]

# Search the knowledge graph with optional zone parameter
node dist/admin-cli.js search "search query" [zone]

# Show details about a specific entity
node dist/admin-cli.js entity "John Smith" [zone]

# Show relations for a specific entity
node dist/admin-cli.js relations "John Smith" [zone]

# List all memory zones
node dist/admin-cli.js zones list

# Add a new memory zone
node dist/admin-cli.js zones add projectX "Project X knowledge zone"

# Delete a memory zone
node dist/admin-cli.js zones delete projectX [--yes]

# Show statistics for a specific zone
node dist/admin-cli.js zones stats projectX

# Reset all zones or a specific zone
node dist/admin-cli.js reset [zone] [--yes]

# Show help
node dist/admin-cli.js help

Memory Zones

The knowledge graph supports multiple memory zones to organize domain-specific knowledge. This allows you to:

Partition Knowledge: Separate data into different domains (projects, departments, etc.)
Improve Query Performance: Search within specific zones for faster and more relevant results
Maintain Context: Keep context-specific information isolated but connected

Working with Zones

# Create a new zone
node dist/admin-cli.js zones add projectX "Project X knowledge zone"

# List all zones
node dist/admin-cli.js zones list

# Import data into a specific zone
node dist/admin-cli.js import project-data.json projectX

# Search within a specific zone
node dist/admin-cli.js search "feature" projectX

Cross-Zone Relations

Entities in different zones can be related to each other. When creating a relation, you can specify the zones for both entities:

{
  "type": "relation",
  "from": "Project Feature",
  "fromZone": "projectX",
  "to": "General Concept",
  "toZone": "default",
  "relationType": "implements"
}

Automation Support

For scripting and automation, you can use the --yes or -y flag to skip confirmation prompts:

# Reset without confirmation
node dist/admin-cli.js reset --yes

# Delete a zone without confirmation
node dist/admin-cli.js zones delete projectX --yes

# Restore from backup without confirmation
node dist/admin-cli.js restore backup.json --yes

Search Examples

The Elasticsearch-backed knowledge graph provides powerful search capabilities:

# Basic search
node dist/admin-cli.js search "cordova plugin"

# Search in a specific zone
node dist/admin-cli.js search "feature" projectX

# Fuzzy search (will find "subscription" even with typo)
node dist/admin-cli.js search "subscrption"

# Person search
node dist/admin-cli.js search "Jean"

Search results include:

Relevancy scoring
Highlighted matches showing where the terms were found
Entity types and observation counts
Sorted by most relevant first

MCP Server Tools

The MCP server exposes the following tools for interacting with the knowledge graph:

Entity Operations

Tool	Description
`create_entities`	Create one or more entities in the knowledge graph
`update_entities`	Update properties of existing entities
`delete_entities`	Delete one or more entities from the knowledge graph
`add_observations`	Add observations to an existing entity
`mark_important`	Mark an entity as important or not

Relation Operations

Tool	Description
`create_relations`	Create relations between entities
`delete_relations`	Delete relations between entities

Query Operations

Tool	Description
`search_nodes`	Search for entities using Elasticsearch query capabilities
`open_nodes`	Get details about specific entities by name
`get_recent`	Get recently accessed entities

Each tool can include an optional memory_zone parameter to specify which zone to operate on.

Relevancy Ranking

The knowledge graph implements a sophisticated relevancy ranking system that considers:

Text Relevance: How well entities match the search query
Recency: Prioritizes recently accessed entities
Importance: Entities marked as important receive higher ranking
Usage Frequency: Entities accessed more frequently rank higher

This approach simulates memory-like behavior where important, recent, and frequently accessed information is prioritized.

Benefits Over JSON Implementation

Scalability: Handles millions of entities efficiently
Performance: Optimized for fast queries even with large datasets
Rich Queries: Advanced search capabilities like fuzzy matching and relevancy ranking
Resiliency: Better handling of concurrent operations
Observability: Built-in monitoring and diagnostics
Complete CRUD: Full lifecycle management for entities and relations

License

MIT