Memory MCP Server

Implements a schema-based knowledge graph that stores entities, relations, and observations in a local JSON file, enabling structured semantic memory without requiring external databases. Uses MCP's Tool primitive to expose create/read/update/delete operations for graph nodes and edges, with automatic file serialization on each mutation. The architecture treats the JSON file as a single source of truth, avoiding distributed state complexity while maintaining ACID-like guarantees through synchronous writes.

Extends the knowledge graph with an observations layer that tracks when facts were learned, from which source, and with what confidence. Each observation is a timestamped assertion that can reference entities and relations, enabling the LLM to reason about fact provenance and recency. The architecture supports multiple observations per entity (e.g., 'user prefers coffee' observed on 2024-01-15 vs 2024-02-20), allowing the LLM to detect contradictions or track preference changes over time.

Exposes the knowledge graph through MCP's Tool primitive, allowing LLMs to query and mutate the graph using natural language descriptions that are translated into structured tool calls. The server defines tools like 'add_entity', 'add_relation', 'query_entities', 'get_relations' that accept JSON payloads and return structured results. This design treats the LLM as a first-class graph client, enabling it to reason about its own memory state and make deliberate updates without requiring external orchestration.

Implements a typed relation system where edges between entities carry semantic meaning (e.g., 'user_prefers', 'works_at', 'knows'). Relations are stored as first-class graph objects with source entity, target entity, and relation type, enabling the LLM to reason about entity connections and traverse the graph semantically. The architecture supports both directed and undirected relations, and allows querying all relations of a given type or all relations involving a specific entity.

Persists the entire knowledge graph to a single local JSON file using synchronous writes, ensuring that every graph mutation is immediately durable. The architecture reads the entire file into memory on startup, performs mutations in-memory, and writes the complete updated graph back to disk on each operation. This design trades write latency for simplicity and ACID-like guarantees, avoiding the complexity of distributed consensus or transaction logs.

Implements the MCP server lifecycle using the official TypeScript SDK, handling server initialization, tool registration, request routing, and graceful shutdown. The server exposes tools through MCP's standardized Tool primitive, registers them with the MCP host during initialization, and routes incoming tool calls to handler functions. The architecture follows MCP's request-response pattern, where each tool call is a JSON-RPC request that the server processes and returns a result.

Manages entity identity by storing entities with unique IDs and supporting name-based lookups to prevent duplicate entities from being created. When the LLM references an entity by name, the server checks if an entity with that name already exists before creating a new one. The architecture uses a simple name-to-ID mapping, enabling the LLM to refer to entities consistently across multiple conversations without creating duplicates.

Provides access to the raw knowledge graph state through the JSON file, enabling developers and LLMs to inspect what facts have been learned and how they're organized. The entire graph is stored in a human-readable JSON format with clear entity, relation, and observation structures. This design supports debugging by allowing developers to read the file directly, and enables LLMs to reason about their own memory state by querying the graph structure.