Memento MCP: A Knowledge Graph Memory System for LLMs

Scalable, high performance knowledge graph memory system with semantic retrieval, contextual recall, and temporal awareness. Provides any LLM client that supports the model context protocol (e.g., Claude Desktop, Cursor, Github Copilot) with resilient, adaptive, and persistent long-term ontological memory.

Core Concepts

Entities

Entities are the primary nodes in the knowledge graph. Each entity has:

• A unique name (identifier)
• An entity type (e.g., "person", "organization", "event")
• A list of observations
• Vector embeddings (for semantic search)
• Complete version history

Example:

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["Speaks fluent Spanish"]
}

Relations

Relations define directed connections between entities with enhanced properties:

• Strength indicators (0.0-1.0)
• Confidence levels (0.0-1.0)
• Rich metadata (source, timestamps, tags)
• Temporal awareness with version history
• Time-based confidence decay

Example:

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at",
  "strength": 0.9,
  "confidence": 0.95,
  "metadata": {
    "source": "linkedin_profile",
    "last_verified": "2025-03-21"
  }
}

Storage Backend

Memento MCP uses Neo4j as its storage backend, providing a unified solution for both graph storage and vector search capabilities.

Why Neo4j?

• Unified Storage: Consolidates both graph and vector storage into a single database
• Native Graph Operations: Built specifically for graph traversal and queries
• Integrated Vector Search: Vector similarity search for embeddings built directly into Neo4j
• Scalability: Better performance with large knowledge graphs
• Simplified Architecture: Clean design with a single database for all operations

Prerequisites

• Neo4j 5.13+ (required for vector search capabilities)

Neo4j Desktop Setup (Recommended)

The easiest way to get started with Neo4j is to use Neo4j Desktop:

1. Download and install Neo4j Desktop from
2. Create a new project
3. Add a new database
4. Set password to memento_password (or your preferred password)
5. Start the database

The Neo4j database will be available at:

• Bolt URI: bolt://127.0.0.1:7687 (for driver connections)
• HTTP: http://127.0.0.1:7474 (for Neo4j Browser UI)
• Default credentials: username: neo4j, password: memento_password (or whatever you configured)

Neo4j Setup with Docker (Alternative)

Alternatively, you can use Docker Compose to run Neo4j:

# Start Neo4j container
docker-compose up -d neo4j

# Stop Neo4j container
docker-compose stop neo4j

# Remove Neo4j container (preserves data)
docker-compose rm neo4j

When using Docker, the Neo4j database will be available at:

• Bolt URI: bolt://127.0.0.1:7687 (for driver connections)
• HTTP: http://127.0.0.1:7474 (for Neo4j Browser UI)
• Default credentials: username: neo4j, password: memento_password

#### Data Persistence and Management

Neo4j data persists across container restarts and even version upgrades due to the Docker volume configuration in the docker-compose.yml file:

volumes:
  - ./neo4j-data:/data
  - ./neo4j-logs:/logs
  - ./neo4j-import:/import

These mappings ensure that:

• /data directory (contains all database files) persists on your host at ./neo4j-data
• /logs directory persists on your host at ./neo4j-logs
• /import directory (for importing data files) persists at ./neo4j-import

You can modify these paths in your docker-compose.yml file to store data in different locations if needed.

##### Upgrading Neo4j Version

You can change Neo4j editions and versions without losing data:

1. Update the Neo4j image version in docker-compose.yml
2. Restart the container with docker-compose down && docker-compose up -d neo4j
3. Reinitialize the schema with npm run neo4j:init

The data will persist through this process as long as the volume mappings remain the same.

##### Complete Database Reset

If you need to completely reset your Neo4j database:

# Stop the container
docker-compose stop neo4j

# Remove the container
docker-compose rm -f neo4j

# Delete the data directory contents
rm -rf ./neo4j-data/*

# Restart the container
docker-compose up -d neo4j

# Reinitialize the schema
npm run neo4j:init

##### Backing Up Data

To back up your Neo4j data, you can simply copy the data directory:

# Make a backup of the Neo4j data
cp -r ./neo4j-data ./neo4j-data-backup-$(date +%Y%m%d)

Neo4j CLI Utilities

Memento MCP includes command-line utilities for managing Neo4j operations:

#### Testing Connection

Test the connection to your Neo4j database:

# Test with default settings
npm run neo4j:test

# Test with custom settings
npm run neo4j:test -- --uri bolt://127.0.0.1:7687 --username myuser --password mypass --database neo4j

#### Initializing Schema

For normal operation, Neo4j schema initialization happens automatically when Memento MCP connects to the database. You don't need to run any manual commands for regular usage.

The following commands are only necessary for development, testing, or advanced customization scenarios:

# Initialize with default settings (only needed for development or troubleshooting)
npm run neo4j:init

# Initialize with custom vector dimensions
npm run neo4j:init -- --dimensions 768 --similarity euclidean

# Force recreation of all constraints and indexes
npm run neo4j:init -- --recreate

# Combine multiple options
npm run neo4j:init -- --vector-index custom_index --dimensions 384 --recreate

Advanced Features

Semantic Search

Find semantically related entities based on meaning rather than just keywords:

• Vector Embeddings: Entities are automatically encoded into high-dimensional vector space using OpenAI's embedding models
• Cosine Similarity: Find related concepts even when they use different terminology
• Configurable Thresholds: Set minimum similarity scores to control result relevance
• Cross-Modal Search: Query with text to find relevant entities regardless of how they were described
• Multi-Model Support: Compatible with multiple embedding models (OpenAI text-embedding-3-small/large)
• Contextual Retrieval: Retrieve information based on semantic meaning rather than exact keyword matches
• Optimized Defaults: Tuned parameters for balance between precision and recall (0.6 similarity threshold, hybrid search enabled)
• Hybrid Search: Combines semantic and keyword search for more comprehensive results
• Adaptive Search: System intelligently chooses between vector-only, keyword-only, or hybrid search based on query characteristics and available data
• Performance Optimization: Prioritizes vector search for semantic understanding while maintaining fallback mechanisms for resilience
• Query-Aware Processing: Adjusts search strategy based on query complexity and available entity embeddings

Temporal Awareness

Track complete history of entities and relations with point-in-time graph retrieval:

• Full Version History: Every change to an entity or relation is preserved with timestamps
• Point-in-Time Queries: Retrieve the exact state of the knowledge graph at any moment in the past
• Change Tracking: Automatically records createdAt, updatedAt, validFrom, and validTo timestamps
• Temporal Consistency: Maintain a historically accurate view of how knowledge evolved
• Non-Destructive Updates: Updates create new versions rather than overwriting existing data
• Time-Based Filtering: Filter graph elements based on temporal criteria
• History Exploration: Investigate how specific information changed over time

Confidence Decay

Relations automatically decay in confidence over time based on configurable half-life:

• Time-Based Decay: Confidence in relations naturally decreases over time if not reinforced
• Configurable Half-Life: Define how quickly information becomes less certain (default: 30 days)
• Minimum Confidence Floors: Set thresholds to prevent over-decay of important information
• Decay Metadata: Each relation includes detailed decay calculation information
• Non-Destructive: Original confidence values are preserved alongside decayed values
• Reinforcement Learning: Relations regain confidence when reinforced by new observations
• Reference Time Flexibility: Calculate decay based on arbitrary reference times for historical analysis

Advanced Metadata

Rich metadata support for both entities and relations with custom fields: