Memento MCP

Semantic Search

Memento MCP uses OpenAI embedding models (e.g., text-embedding-3-small/large) to enable meaning-based retrieval.

• Hybrid Search: Combines semantic (vector) and keyword search.
• Adaptive Search: Automatically chooses between vector-only, keyword-only, or hybrid search based on query complexity.
• Thresholds: Uses a default 0.6 similarity threshold to balance precision and recall.

Temporal Awareness

The system tracks the evolution of knowledge over time.

• Version History: Every change to an entity or relation is preserved with timestamps.
• Point-in-Time Queries: Retrieve the state of the graph at any specific moment.
• Non-Destructive Updates: Updates create new versions rather than overwriting existing data.

Confidence Decay

Relations include a configurable half-life (default: 30 days). If a relation is not reinforced by new observations, its confidence naturally decreases over time.

When DEBUG=true is set in your environment variables or Claude Desktop configuration, Memento MCP exposes additional diagnostic tools via the MCP API and includes detailed metadata in semantic search responses.

Available Debug Tools (DEBUG=true only):

• diagnose_vector_search: Directly queries Neo4j for entity embeddings and index status.
• force_generate_embedding: Forces generation of an embedding for a specific entity (e.g., {"entity_name": "EntityName"}).
• debug_embedding_config: Shows current embedding model, dimensions, and service status.

Diagnostic Response Format: Responses will include a diagnostics object containing the original query, timestamps, and a stepsTaken array detailing the execution flow (e.g., embeddingServiceCheck, vectorSearch).

{
  "entities": [...],
  "relations": [...],
  "diagnostics": {
    "query": "original search query",
    "startTime": 1743279841982,
    "stepsTaken": [
      { "step": "embeddingServiceCheck", "status": "available", ... },
      { "step": "vectorSearch", "status": "started", ... },
      { "step": "vectorSearch", "status": "completed", "resultsCount": 3 }
    ],
    "endTime": 1743279842014,
    "totalTimeTaken": 32
  }
}

Memento MCP uses a knowledge graph model composed of two primary abstractions:

Entities

Entities are the nodes in the graph. Each entity contains:

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

Relations

Relations are directed connections between entities. They include:

• strength (0.0-1.0) and confidence (0.0-1.0) indicators.
• Rich metadata (source, timestamps, tags).
• Temporal awareness with version history and time-based confidence decay.

Example Entity:

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

Example Relation:

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

Memento MCP requires Neo4j 5.13+ for vector search capabilities. You can set it up using Neo4j Desktop or Docker.

Option 1: Neo4j Desktop (Recommended)

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

Connection Details:

• Bolt URI: bolt://127.0.0.1:7687
• HTTP: http://127.0.0.1:7474
• Default Credentials: neo4j / memento_password

Option 2: Docker Compose

Use Docker Compose to run Neo4j. Ensure your docker-compose.yml includes volume mappings to persist data:

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

Commands:

# Start Neo4j container
docker-compose up -d neo4j

# Stop Neo4j container
docker-compose stop neo4j

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

To use Memento MCP with Claude Desktop, add the server configuration to your claude_desktop_config.json.

Using npx (Recommended for most users):

{
  "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 (Direct Node path): If developing locally, point the command to your node executable and args to the dist/index.js file of the package.