Skip to main content
Glama

Memory MCP Server

by evangstav

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
-
security - not tested
A
license - permissive license
-
quality - not tested

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.

  1. Installation
    1. Data Validation Rules
      1. Entity Names
      2. Entity Types
      3. Observations
      4. Relations
    2. Usage
      1. Get Entity
      2. Get Graph
      3. Create Entities
      4. Add Observation
      5. Create Relation
      6. Search Memory
      7. Delete Entities
      8. Delete Relation
      9. Flush Memory
    3. Error Types
      1. Response Models
        1. EntityResponse
        2. GraphResponse
        3. OperationResponse
      2. Development
        1. Running Tests
        2. Adding New Features

      Related MCP Servers

      • A
        security
        F
        license
        A
        quality
        Provides tools for managing project knowledge graphs, enabling structured representation of projects, tasks, milestones, resources, and team members.
        Last updated 4 months ago
        6
        7
        TypeScript
        • Apple
        • Linux
      • A
        security
        F
        license
        A
        quality
        Provides tools for managing quantitative research knowledge graphs, enabling structured representation of research projects, datasets, variables, hypotheses, statistical tests, models, and results.
        Last updated 4 months ago
        6
        6
        TypeScript
        • Apple
        • Linux
      • -
        security
        F
        license
        -
        quality
        Provides tools for managing qualitative research knowledge graphs, enabling structured representation of research projects, participants, interviews, observations, codes, themes, and findings.
        Last updated 4 months ago
        4
        TypeScript
        • Apple
        • Linux
      • A
        security
        F
        license
        A
        quality
        Provides tools for managing student knowledge graphs, enabling structured representation of courses, assignments, exams, concepts, and study resources.
        Last updated 4 months ago
        6
        TypeScript
        • Apple
        • Linux

      View all related MCP servers

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/evangstav/python-memory-mcp-server'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server