Knowledge Graph Memory MCP server for AI agents

The Memory MCP Server provides knowledge graph functionality for managing entities, relations, and observations in memory. It enforces strict validation rules to maintain data consistency, making it ideal for applications that need structured knowledge representation.

Installation

To 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

Using the Server

Get Entity

To retrieve information about a specific 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

To retrieve the entire knowledge 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

To create new entities in the knowledge graph:

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

To add a new observation to an existing entity:

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

To establish a relationship between two entities:

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

To search for information within the knowledge graph:

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

To remove entities from the knowledge graph:

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

To remove a relationship between entities:

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

To clear all data from the knowledge graph:

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "knowledge-graph-memory" '{"command":"python","args":["-m","main.py"],"env":{"MEMORY_FILE_PATH":"/path/to/memory.jsonl"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "knowledge-graph-memory": {
            "command": "python",
            "args": [
                "-m",
                "main.py"
            ],
            "env": {
                "MEMORY_FILE_PATH": "/path/to/memory.jsonl"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "knowledge-graph-memory": {
            "command": "python",
            "args": [
                "-m",
                "main.py"
            ],
            "env": {
                "MEMORY_FILE_PATH": "/path/to/memory.jsonl"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect