memento-mcp

Constructs and maintains a Neo4j-backed knowledge graph where entities (persons, organizations, concepts) serve as primary nodes with complete version history and temporal audit trails. Each entity stores name, type classification, observational statements, and vector embeddings. The system automatically tracks all mutations through Neo4jStorageProvider, enabling point-in-time reconstruction of entity state at any historical timestamp and supporting confidence decay calculations over time.

Manages directed relationships between entities with multi-dimensional scoring: strength (0.0-1.0 importance indicator) and confidence (0.0-1.0 certainty level). Relationships are stored as Neo4j edges with relationType classification, metadata fields, and automatic timestamp tracking. The system supports relationship creation, updates, and queries that filter by strength/confidence thresholds, enabling LLMs to reason about relationship reliability and importance.

Abstracts Neo4j database operations through a Neo4jStorageProvider interface, enabling potential future storage backend swaps without changing business logic. The provider handles all graph mutations, queries, vector indexing, and temporal operations. This layered architecture separates storage concerns from knowledge graph management, improving testability and maintainability. The provider implements connection pooling, transaction management, and error handling for Neo4j operations.

Stores arbitrary metadata as key-value pairs on relationships, enabling custom fields beyond standard properties (strength, confidence, relationType). Metadata is unstructured and flexible, allowing LLMs to attach domain-specific information to relationships without schema changes. Metadata is queryable and included in relationship results, supporting rich relationship semantics.

Provides a command-line interface for managing knowledge graphs locally without requiring MCP client integration. The CLI enables entity creation, relationship management, search, and temporal queries through terminal commands, supporting scripted workflows and local testing. The CLI uses the same underlying KnowledgeGraphManager as the MCP server, ensuring consistent behavior across interfaces.

Manages system configuration through environment variables and optional config files, enabling deployment flexibility without code changes. Configuration includes Neo4j connection details, OpenAI API keys, embedding batch sizes, decay half-life parameters, and MCP server settings. The system loads configuration at startup with environment variable precedence over file-based config, supporting both development and production deployments.

Generates and caches vector embeddings for entities using OpenAI's text-embedding-3-small model through an EmbeddingJobManager that batches requests and implements exponential backoff retry logic. Embeddings are cached in Neo4j's vector index to enable semantic similarity search. The system queues embedding jobs asynchronously, allowing entity creation to proceed without blocking on embedding generation, while maintaining eventual consistency through background job processing.

Implements hybrid search combining vector similarity (via Neo4j vector index) and keyword matching, with an adaptive strategy selector that automatically chooses the optimal search method based on query characteristics. Semantic search uses entity embeddings to find conceptually similar entities; keyword search uses Neo4j full-text indexes for exact term matching. The system evaluates query properties (length, specificity, entity type) to route to the most effective search path.

Enables querying the knowledge graph state at any historical timestamp through getGraphAtTime() and related temporal query methods. The system uses Neo4j's timestamp metadata on all mutations to reconstruct the graph as it existed at a specific moment, filtering out entities and relationships created after the target timestamp and excluding relationships whose confidence has decayed below a threshold. This enables LLMs to reason about what was known at a particular point in time.

Automatically reduces relationship confidence scores over time using an exponential decay model with configurable half-life parameters. The system applies decay calculations at query time based on the relationship's creation timestamp and current time, allowing older relationships to gradually lose confidence. This models the real-world phenomenon that information becomes less certain as time passes without reinforcement, enabling LLMs to deprioritize stale information.

Exposes all knowledge graph operations through the Model Context Protocol as MCP tools with JSON schema definitions. The system implements a tool registry that maps natural language requests to underlying KnowledgeGraphManager methods, with automatic schema generation for input validation and type safety. LLM clients invoke tools via standard MCP function-calling protocol, receiving structured responses with embedded metadata for error handling and result interpretation.

Supports batch creation and updates of multiple entities and relationships in a single transaction, ensuring all-or-nothing semantics. The system queues batch operations through the KnowledgeGraphManager, which coordinates Neo4j transactions to maintain consistency. Batch operations are more efficient than individual mutations, reducing network round-trips and enabling atomic multi-entity updates (e.g., creating an entity and all its relationships simultaneously).

Manages entity observations (descriptive statements about entities) with support for adding, updating, and removing individual observations without replacing the entire observation set. Each observation is tracked independently with timestamps, enabling LLMs to add new facts about entities incrementally. The system maintains observation history and supports querying observations by creation date or content, allowing temporal reasoning about when facts were learned.

Classifies entities into predefined types (person, organization, concept, event, location) and enables filtering queries by entity type. The system uses entityType as a first-class property on entities, allowing queries to constrain results to specific categories. Type classification enables domain-specific reasoning (e.g., 'find all people related to this organization') and improves search precision by filtering irrelevant entity types.