Memory MCP Server

A Model Context Protocol (MCP) server that provides knowledge graph functionality for managing entities, relations, and observations in memory, with strict validation rules to maintain data consistency.

Installation

Install the server in Claude Desktop:

mcp install main.py -v MEMORY_FILE_PATH=/path/to/memory.jsonl

Data Validation Rules

Entity Names

Must start with a lowercase letter
Can contain lowercase letters, numbers, and hyphens
Maximum length of 100 characters
Must be unique within the graph
Example valid names: python-project, meeting-notes-2024, user-john

Entity Types

The following entity types are supported:

person: Human entities
concept: Abstract ideas or principles
project: Work initiatives or tasks
document: Any form of documentation
tool: Software tools or utilities
organization: Companies or groups
location: Physical or virtual places
event: Time-bound occurrences

Observations

Non-empty strings
Maximum length of 500 characters
Must be unique per entity
Should be factual and objective statements
Include timestamp when relevant

Relations

The following relation types are supported:

knows: Person to person connection
contains: Parent/child relationship
uses: Entity utilizing another entity
created: Authorship/creation relationship
belongs-to: Membership/ownership
depends-on: Dependency relationship
related-to: Generic relationship

Additional relation rules:

Both source and target entities must exist
Self-referential relations not allowed
No circular dependencies allowed
Must use predefined relation types

Usage

The server provides tools for managing a knowledge graph:

Get Entity

result = await session.call_tool("get_entity", {
    "entity_name": "example"
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid input: {result.error}")
    else:
        print(f"Error: {result.error}")
else:
    entity = result.data
    print(f"Found entity: {entity}")

Get Graph

result = await session.call_tool("get_graph", {})
if result.success:
    graph = result.data
    print(f"Graph data: {graph}")
else:
    print(f"Error retrieving graph: {result.error}")

Create Entities

# Valid entity creation
entities = [
    Entity(
        name="python-project",  # Lowercase with hyphens
        entityType="project",   # Must be a valid type
        observations=["Started development on 2024-01-29"]
    ),
    Entity(
        name="john-doe",
        entityType="person",
        observations=["Software engineer", "Joined team in 2024"]
    )
]
result = await session.call_tool("create_entities", {
    "entities": entities
})
if not result.success:
    if result.error_type == "VALIDATION_ERROR":
        print(f"Invalid entity data: {result.error}")
    else:
        print(f"Error creating entities: {result.error}")

Add Observation

# Valid observation
result = await session.call_tool("add_observation", {
    "entity": "python-project",
    "observation": "Completed initial prototype"  # Must be unique for entity
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid observation: {result.error}")
    else:
        print(f"Error adding observation: {result.error}")

Create Relation

# Valid relation
result = await session.call_tool("create_relation", {
    "from_entity": "john-doe",
    "to_entity": "python-project",
    "relation_type": "created"  # Must be a valid type
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid relation data: {result.error}")
    else:
        print(f"Error creating relation: {result.error}")

Search Memory

result = await session.call_tool("search_memory", {
    "query": "most recent workout"  # Supports natural language queries
})
if result.success:
    if result.error_type == "NO_RESULTS":
        print(f"No results found: {result.error}")
    else:
        results = result.data
        print(f"Search results: {results}")
else:
    print(f"Error searching memory: {result.error}")

The search functionality supports:

Temporal queries (e.g., "most recent", "last", "latest")
Activity queries (e.g., "workout", "exercise")
General entity searches
Fuzzy matching with 80% similarity threshold
Weighted search across:
- Entity names (weight: 1.0)
- Entity types (weight: 0.8)
- Observations (weight: 0.6)

Delete Entities

result = await session.call_tool("delete_entities", {
    "names": ["python-project", "john-doe"]
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    else:
        print(f"Error deleting entities: {result.error}")

Delete Relation

result = await session.call_tool("delete_relation", {
    "from_entity": "john-doe",
    "to_entity": "python-project"
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    else:
        print(f"Error deleting relation: {result.error}")

Flush Memory

result = await session.call_tool("flush_memory", {})
if not result.success:
    print(f"Error flushing memory: {result.error}")

Error Types

The server uses the following error types:

NOT_FOUND: Entity or resource not found
VALIDATION_ERROR: Invalid input data
INTERNAL_ERROR: Server-side error
ALREADY_EXISTS: Resource already exists
INVALID_RELATION: Invalid relation between entities

Response Models

All tools return typed responses using these models:

EntityResponse

class EntityResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

GraphResponse

class GraphResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

OperationResponse

class OperationResponse(BaseModel):
    success: bool
    error: Optional[str] = None
    error_type: Optional[str] = None

Development

Running Tests

pytest tests/

Adding New Features

Update validation rules in validation.py
Add tests in tests/test_validation.py
Implement changes in knowledge_graph_manager.py

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides knowledge graph functionality for managing entities, relations, and observations in memory with strict validation rules to maintain data consistency.

Related Resources

Reddit Discussion about this server

Related MCP Servers

MemoryMesh
CheMiguel23
-
security
A
license
-
quality
This project is based on the Knowledge Graph Memory Server from the MCP servers repository and retains its core functionality.
Last updated -
44
107
TypeScript
MIT License
Supabase Memory MCP Server
gtrusler
-
security
F
license
-
quality
Provides memory/knowledge graph storage capabilities using Supabase, enabling multiple Claude instances to safely share and maintain a knowledge graph with features like entity storage, concurrent access safety, and full text search.
Last updated -
6
JavaScript
Memory Custom
BRO3886
A
security
A
license
A
quality
A customized MCP memory server that enables creation and management of a knowledge graph with features like custom memory paths and timestamping for capturing interactions via language models.
Last updated -
11
2
JavaScript
MIT License
Project MCP Server
tejpalvirk
-
security
F
license
-
quality
Provides tools for managing project knowledge graphs, enabling structured representation of projects, tasks, milestones, resources, and team members.
Last updated -
TypeScript

View all related MCP servers

Memory MCP Server