Memento Community

Frequently asked questions

What does the Memento MCP server do?

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: 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: Download and install Neo4j Desktop from ://neo4j.com/download/> Create a new project Add a new database Set password to memento password (or your preferred password) Start the database The Neo4j database will be available at: Bolt URI : bolt://127.0.0.1:7687 (for driver connections) HTTP : (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 : (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: Update the Neo4j image version in docker-compose.yml Restart the container with docker-compose down && docker-compose up -d neo4j 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 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: Source Tracking : Record where information originated (user input, analysis, external sources) Confidence Levels : Assign confidence scores (0.0-1.0) to relations based on certainty Relation Strength : Indicate importance or strength of relationships (0.0-1.0) Temporal Metadata : Track when information was added, modified, or verified Custom Tags : Add arbitrary tags for classification and filtering Structured Data : Store complex structured data within metadata fields Query Support : Search and filter based on metadata properties Extensible Schema : Add custom fields as needed without modifying the core data model MCP API Tools The following tools are available to LLM client hosts through the Model Context Protocol: Entity Management create entities Create multiple new entities in the knowledge graph Input: entities (array of objects) Each object contains: name (string): Entity identifier entityType (string): Type classification observations (string[]): Associated observations add observations Add new observations to existing entities Input: observations (array of objects) Each object contains: entityName (string): Target entity contents (string[]): New observations to add delete entities Remove entities and their relations Input: entityNames (string[]) delete observations Remove specific observations from entities Input: deletions (array of objects) Each object contains: entityName (string): Target entity observations (string[]): Observations to remove Relation Management create relations Create multiple new relations between entities with enhanced properties Input: relations (array of objects) Each object contains: from (string): Source entity name to (string): Target entity name relationType (string): Relationship type strength (number, optional): Relation strength (0.0-1.0) confidence (number, optional): Confidence level (0.0-1.0) metadata (object, optional): Custom metadata fields get relation Get a specific relation with its enhanced properties Input: from (string): Source entity name to (string): Target entity name relationType (string): Relationship type update relation Update an existing relation with enhanced properties Input: relation (object): Contains: from (string): Source entity name to (string): Target entity name relationType (string): Relationship type strength (number, optional): Relation strength (0.0-1.0) confidence (number, optional): Confidence level (0.0-1.0) metadata (object, optional): Custom metadata fields delete relations Remove specific relations from the graph Input: relations (array of objects) Each object contains: from (string): Source entity name to (string): Target entity name relationType (string): Relationship type Graph Operations read graph Read the entire knowledge graph No input required search nodes Search for nodes based on query Input: query (string) open nodes Retrieve specific nodes by name Input: names (string[]) Semantic Search semantic search Search for entities semantically using vector embeddings and similarity Input: query (string): The text query to search for semantically limit (number, optional): Maximum results to return (default: 10) min similarity (number, optional): Minimum similarity threshold (0.0-1.0, default: 0.6) entity types (string[], optional): Filter results by entity types hybrid search (boolean, optional): Combine keyword and semantic search (default: true) semantic weight (number, optional): Weight of semantic results in hybrid search (0.0-1.0, default: 0.6) Features: Intelligently selects optimal search method (vector, keyword, or hybrid) based on query context Gracefully handles queries with no semantic matches through fallback mechanisms Maintains high performance with automatic optimization decisions get entity embedding Get the vector embedding for a specific entity Input: entity name (string): The name of the entity to get the embedding for Temporal Features get entity history Get complete version history of an entity Input: entityName (string) get relation history Get complete version history of a relation Input: from (string): Source entity name to (string): Target entity name relationType (string): Relationship type get graph at time Get the state of the graph at a specific timestamp Input: timestamp (number): Unix timestamp (milliseconds since epoch) get decayed graph Get graph with time-decayed confidence values Input: options (object, optional): reference time (number): Reference timestamp for decay calculation (milliseconds since epoch) decay factor (number): Optional decay factor override Configuration Environment Variables Configure Memento MCP with these environment variables: Command Line Options The Neo4j CLI tools support the following options: Embedding Models Available OpenAI embedding models: text-embedding-3-small : Efficient, cost-effective (1536 dimensions) text-embedding-3-large : Higher accuracy, more expensive (3072 dimensions) text-embedding-ada-002 : Legacy model (1536 dimensions) OpenAI API Configuration To use semantic search, you'll need to configure OpenAI API credentials: Obtain an API key from OpenAI Configure your environment with: > Note : For testing environments, the system will mock embedding generation if no API key is provided. However, using real embeddings is recommended for integration testing. Integration with Claude Desktop Configuration Add this to your claude desktop config.json : Alternatively, for local development, you can use: > Important : Always explicitly specify the embedding model in your Claude Desktop configuration to ensure consistent behavior. Recommended System Prompts For optimal integration with Claude, add these statements to your system prompt: Testing Semantic Search Once configured, Claude can access the semantic search capabilities through natural language: To create entities with semantic embeddings: To search semantically: To retrieve specific information: The power of this approach is that users can interact naturally, while the LLM handles the complexity of selecting and using the appropriate memory tools. Real-World Applications Memento's adaptive search capabilities provide practical benefits: Query Versatility : Users don't need to worry about how to phrase questions - the system adapts to different query types automatically Failure Resilience : Even when semantic matches aren't available, the system can fall back to alternative methods without user intervention Performance Efficiency : By intelligently selecting the optimal search method, the system balances performance and relevance for each query Improved Context Retrieval : LLM conversations benefit from better context retrieval as the s

How do I install Memento?

Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.

Is Memento free to use?

The MCP server itself is free to install. The source is public on https://github.com/gannonh/memento-mcp. Any third-party service it calls may require its own API key and account.

Which clients support Memento?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.