gannonh/memento-mcp

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:
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:
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:
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:
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:
Backing Up Data
To back up your Neo4j data, you can simply copy the data directory:
Neo4j CLI Utilities
Memento MCP includes command-line utilities for managing Neo4j operations:
Testing Connection
Test the connection to your Neo4j database:
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:
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