Memento MCP Server: Neo4j Temporal Semantic Memory

Overview

Memento MCP Server is an implementation of the Model Context Protocol (MCP) that lets you index and query a Neo4j-based temporal semantic memory. It combines vectorized semantic embeddings with Neo4j’s graph model and temporal metadata so you can perform fast semantic search, time-aware retrieval (snapshotting, historical queries), and extract knowledge-graph insights with context about when facts were true.

This server is useful for applications that need retrieval augmented generation, explainable history-aware assistants, or analytics over evolving knowledge graphs. Instead of keeping embeddings in a separate vector store, Memento ties embeddings and timestamps directly to graph nodes and relationships, enabling queries constrained by time (e.g., “what was true at T?”) and richer graph traversals for context-aware results.

Features

• Index Neo4j nodes and relationships with semantic embeddings
• Time-aware retrieval: query as-of a timestamp or over intervals
• Semantic ranking of results using vector similarity
• Native integration with Neo4j graph queries and temporal predicates
• HTTP MCP-compatible API for indexing, search, and graph exploration
• Configurable embedding provider (plug-in style for different models)
• Tools and examples for seeding graphs and running snapshot queries

Installation / Configuration

Clone the repository and run the server locally. Two common options are Docker and running from the source.

Clone repo:

git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp

Run with Docker (recommended for fastest setup):

# build the image (if no published image is used)
docker build -t memento-mcp .

# run with required environment variables
docker run --rm -p 8080:8080 \
  -e NEO4J_URI=bolt://neo4j:7687 \
  -e NEO4J_USER=neo4j \
  -e NEO4J_PASSWORD=secret \
  -e EMBEDDING_PROVIDER=openai \
  -e EMBEDDING_API_KEY=$OPENAI_API_KEY \
  memento-mcp:latest

Run from source (Node/Python runtime depends on implementation in repo):

# example for a Node-based project
npm install
cp .env.example .env
# edit .env to set NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD, EMBEDDING_PROVIDER, etc.
npm start

Recommended environment variables

Neo4j schema hints (example Cypher)

// ensure unique ids for nodes used as memory items
CREATE CONSTRAINT memory_id IF NOT EXISTS
FOR (m:Memory) REQUIRE (m.id) IS UNIQUE;

// example property on nodes: embeddings (array<float>), timestamp (datetime)

If your Neo4j version supports vector indexing, create a vector index on the embedding property for faster nearest-neighbor searches. Otherwise, Memento will use an approximate or hybrid search strategy.

Available Resources

• GitHub repository: https://github.com/gannonh/memento-mcp
• Example dataset and seeding scripts (included in repo under /examples)
• Postman/HTTP example collection (look in /tools or /postman)
• Tests and CLI utilities for snapshotting and batch indexing

API Examples

Index a node or document (POST /mcp/index)

POST /mcp/index HTTP/1.1
Content-Type: application/json

{
  "id": "doc:123",
  "labels": ["Memory", "Document"],
  "properties": {
    "text": "Q2 financial results show a 12% increase.",
    "timestamp": "2024-01-25T12:00:00Z"
  }
}

Semantic search with time filter (POST /mcp/search)

POST /mcp/search HTTP/1.1
Content-Type: application/json

{
  "query": "company quarterly revenue increase",
  "as_of": "2024-02-01T00:00:00Z",
  "limit": 5
}

Example response (simplified)

{
  "results": [
    {
      "id": "doc:123",
      "score": 0.92,
      "snippet": "Q2 financial results show a 12% increase.",
      "timestamp": "2024-01-25T12:00:00Z"
    }
  ]
}

Use Cases

• Time-aware conversational assistants: an assistant can answer questions about company status “as of” a given date by retrieving memories that were valid at that time.
• Audit trails and explainability: retrieve the original evidence and graph provenance for model outputs,