entity-relationship graph persistence with json file backend
Stores and retrieves entities, relations, and observations in a local JSON file using a graph-based data model. The server implements MCP Tools that allow clients to create entities (with properties), define typed relationships between entities, and record observations tied to entities. Data persists across conversation sessions in a single JSON file, enabling stateful knowledge accumulation without requiring external databases or network calls.
Unique: Official MCP reference implementation using TypeScript SDK with a deliberately simple JSON file backend (not a database) to demonstrate how MCP Tools can expose memory operations. The graph model separates entities (with properties), relations (typed edges), and observations (timestamped facts), allowing LLMs to reason about both structure and temporal context.
vs alternatives: Simpler to deploy and understand than vector-database RAG systems because it uses explicit entity/relation storage instead of embeddings, making the knowledge graph directly inspectable and editable by humans or LLMs.
mcp tool interface for memory operations
Exposes memory graph operations as MCP Tools (function-calling interface) that LLM clients can invoke. The server implements Tools following the MCP protocol specification, including tool definitions with JSON schemas, input validation, and structured responses. Each Tool maps to a specific memory operation (create entity, add relation, record observation, query entities) and returns results in a format the LLM can parse and reason about.
Unique: Implements the MCP Tool primitive as defined in the protocol specification, using TypeScript SDK's tool registration API. Each Tool includes a JSON schema describing parameters, enabling LLM clients to understand available operations without hardcoding. The server validates inputs against schemas before execution.
vs alternatives: More transparent than REST API endpoints because Tool schemas are introspectable by the LLM, allowing it to discover and reason about available operations; more structured than free-form function calling because schemas enforce parameter contracts.
entity creation and property management
Provides a Tool that allows clients to create new entities in the knowledge graph with arbitrary key-value properties. The implementation stores entities with unique IDs, names, and a properties object. Properties can be strings, numbers, or booleans. The Tool validates that entity names are non-empty and returns the created entity with its assigned ID, enabling the LLM to reference the entity in subsequent operations.
Unique: Implements entity creation as a simple MCP Tool with automatic ID generation (likely UUID or sequential), allowing the LLM to create entities without managing ID assignment. Properties are stored as a flat key-value object, keeping the model simple for reference implementation purposes.
vs alternatives: Simpler than schema-based entity systems (like RDF or property graphs with strict typing) because it accepts any properties, making it more flexible for exploratory LLM use cases where entity structure isn't known in advance.
typed relationship creation and querying
Provides Tools to create directed relationships between entities with a specified relation type (e.g., 'works_on', 'knows', 'parent_of'). Relationships are stored as source entity ID, target entity ID, and relation type string. The implementation allows querying relationships by source entity, target entity, or relation type, returning matching relationships. This enables the LLM to express and retrieve semantic connections between entities.
Unique: Implements relationships as simple typed edges in the knowledge graph, using string relation types rather than a fixed ontology. This allows the LLM to define relationship semantics on-the-fly while keeping the implementation lightweight. The reference design stores relationships in a flat list, making it easy to understand but not optimized for large graphs.
vs alternatives: More flexible than RDF triples because relation types are arbitrary strings rather than URIs, and more explicit than embedding-based similarity because relationships are discrete, queryable facts rather than continuous vectors.
observation recording with temporal context
Provides a Tool to record observations (facts or events) associated with one or more entities, with automatic timestamp recording. Observations are stored as text content, associated entity IDs, and a creation timestamp. The implementation allows querying observations by entity, enabling the LLM to retrieve historical facts about entities. This enables the system to track events, notes, or discoveries over time.
Unique: Observations are first-class citizens in the memory model alongside entities and relationships, allowing the LLM to record facts that don't fit neatly into entity properties or relationships. Automatic server-side timestamps provide temporal ordering without requiring the LLM to manage time explicitly.
vs alternatives: More suitable for conversational memory than pure entity-relationship models because observations capture natural language facts and events, while timestamps enable temporal reasoning without requiring explicit time entities.
graph querying and entity retrieval
Provides Tools to query the knowledge graph and retrieve entities, relationships, and observations. The implementation supports querying by entity ID, entity name (substring or exact match), relationship type, or observation content. Results are returned as structured JSON arrays, allowing the LLM to inspect the graph state and make decisions based on current knowledge. Queries are executed by filtering the in-memory graph representation.
Unique: Queries are implemented as simple in-memory filters over the JSON graph structure, making the implementation transparent and easy to understand. The reference design prioritizes clarity over performance, suitable for small-to-medium graphs but not optimized for large-scale deployments.
vs alternatives: More transparent than vector database queries because results are exact matches rather than similarity-based, making it easier for the LLM to reason about what was found and why; simpler to debug than SQL queries because the data model is flat JSON.
mcp server lifecycle and transport management
Implements the MCP server lifecycle using the TypeScript SDK, including initialization, Tool registration, request handling, and graceful shutdown. The server supports standard MCP transports (stdio, HTTP, SSE) through SDK abstractions. On startup, the server loads the JSON memory file (or creates it if missing), registers all memory Tools with the MCP protocol, and begins accepting requests from MCP clients. The implementation handles connection lifecycle events and ensures the JSON file is persisted after each operation.
Unique: Uses the official MCP TypeScript SDK to implement server lifecycle, abstracting away transport details and protocol handling. The reference implementation demonstrates the minimal boilerplate needed to create an MCP server, making it an educational example for developers learning the SDK.
vs alternatives: Simpler than building an MCP server from scratch using raw JSON-RPC because the SDK handles protocol compliance, transport abstraction, and Tool registration; more maintainable than custom server implementations because it follows official patterns.
json file-based persistence with atomic writes
Persists the entire knowledge graph to a single JSON file on disk after each operation. The implementation reads the JSON file on server startup, maintains the graph in memory, and writes the entire graph back to the file after create/update operations. The file format is a JSON object containing arrays of entities, relationships, and observations. This approach ensures data survives server restarts but requires the entire graph to be serialized on each write.
Unique: Uses a simple JSON file as the storage backend rather than a database, making the implementation portable and debuggable. The entire graph is serialized on each write, prioritizing simplicity and correctness over performance — suitable for reference implementation but not production use.
vs alternatives: More portable than database-backed persistence because it requires no external services or setup; more inspectable than binary formats because the JSON is human-readable; simpler than transaction-based systems because it avoids complex consistency logic.
+1 more capabilities