GitHub Stats

    Stars

    14

    Forks

    5

    Release Date

    4/10/2025

    about 2 months ago

    Detailed Description

    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

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

    Star History

    Star History

    Jan 22Feb 21Mar 17Mar 24Apr 11Apr 29May 270481216
    Powered by MSeeP Analytics

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.