Memento

Memento MCP provides persistent, graph-backed memory for LLMs. It stores entities and their relations in a knowledge graph, enables semantic retrieval and temporal awareness, and exposes an MCP interface for client applications to perform memory operations with high performance and reliability.

How to use

You connect to Memento MCP from an MCP client (for example Claude Desktop or similar) to perform memory operations that enrich your conversations with persistent context. Use semantic_search to retrieve concepts by meaning, get_entity_embedding to inspect embeddings, and manage entities and relations with the available tools. The system intelligently chooses the best search strategy (vector, keyword, or hybrid) and maintains a complete history for entities and relationships to support point-in-time queries and decay-based reasoning over time.

How to install

Prerequisites: you need a supported runtime for the MCP server (Node.js and npm are typical). You should also have access to a Neo4j 5.13+ database with vector search enabled.

# Clone the MCP repository (or obtain the package from your preferred source)
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests (optional)
npm test

Claude Desktop integration and startup flow

To run the MCP server locally and connect via Claude Desktop, you can use the standard MCP runtime configuration shown below. This starts the server as a local process and exposes the necessary environment variables for memory storage, vector indexing, and embedding service access.

{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": ["-y", "@gannonh/memento-mcp"],
      "env": {
        "MEMORY_STORAGE_TYPE": "neo4j",
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "memento_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

Local development start (alternative)

As an alternative, you can run the MCP server locally by invoking the Node runtime with the built entry point. This form is useful for development and testing.

{
  "mcpServers": {
    "memento_local": {
      "command": "/path/to/node",
      "args": ["/path/to/memento-mcp/dist/index.js"],
      "env": {
        "MEMORY_STORAGE_TYPE": "neo4j",
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "memento_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

Available tools

create_entities

Create multiple new entities with identifiers, types, and initial observations.

add_observations

Attach new observations to existing entities to enrich their context.

delete_entities

Remove entities and all their related relations from the graph.

delete_observations

Remove specific observations from entities.

create_relations

Establish new relations between entities with strength, confidence, and metadata.

get_relation

Retrieve a specific relation with its enhanced properties.

update_relation

Modify an existing relation's strength, confidence, and metadata.

delete_relations

Delete specific relations between entities.

read_graph

Read the entire knowledge graph.

search_nodes

Search for nodes based on textual queries.

open_nodes

Retrieve specific nodes by name.

semantic_search

Find semantically related entities using embeddings and vector similarity.

get_entity_embedding

Get the vector embedding for a specific entity.

get_entity_history

Obtain complete version history for an entity.

get_relation_history

Obtain complete version history for a relation.

get_graph_at_time

Get the graph state at a specific timestamp.

get_decayed_graph

Get a graph with time-decayed confidence values.