jason-c-dev/memory-mcp-server-py

MCP Memory Server - Python Implementation

A complete Python port of the official TypeScript MCP memory server. This server provides knowledge graph storage and retrieval capabilities via the Model Context Protocol (MCP).

⚠️ Platform Compatibility

This implementation was developed and tested exclusively on macOS. While it should work on other Unix-like systems, no testing has been performed on Windows, Linux, or other platforms. Use on other platforms is at your own risk.

Features

• Complete Knowledge Graph Management: Store and manage entities, relations, and observations
• JSONL File Format: Compatible with the TypeScript version's file format
• 9 MCP Tools: Full feature parity with the original TypeScript implementation
• Search Capabilities: Query entities by name, type, or observation content
• Graph Traversal: Explore entity connections and relationships
• Environment Configuration: Customizable storage location

Development Environment Setup

Prerequisites

• Python 3.8 or higher
• macOS (tested platform)

Virtual Environment Setup

1. Create a virtual environment:

   python3 -m venv .venv
   

2. Activate the virtual environment:

   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Deactivate when done:

   deactivate
   

Installation

1. Clone or download this repository

2. Set up the virtual environment (see above)

3. Test the installation:

   source .venv/bin/activate
   python mcp_memory_server.py
   

   The server should start and wait for MCP protocol messages via stdin/stdout.

Configuration

Environment Variables

• MEMORY_FILE_PATH: Path to the memory storage file (default: ./memory.json)

Example:

export MEMORY_FILE_PATH="/path/to/my/memory.json"
source .venv/bin/activate
python mcp_memory_server.py

MCP Client Configuration

Claude Desktop

Add this configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["/path/to/mcp_memory_server.py"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

Note: Make sure to activate your virtual environment before running, or use the full path to the Python interpreter in your virtual environment.

Cursor IDE

1. Open Cursor IDE settings
2. Navigate to MCP Servers configuration
3. Add a new server with:
   • Name: memory
   • Command: python
   • Args: ["/path/to/mcp_memory_server.py"]
   • Environment: {"MEMORY_FILE_PATH": "/path/to/memory.json"}

AWS Q CLI

Configure the memory server in your AWS Q CLI MCP settings:

{
  "mcp_servers": {
    "memory": {
      "command": ["python", "/path/to/mcp_memory_server.py"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

Generic MCP Client Configuration

For any MCP client that supports stdio-based servers:

{
  "servers": {
    "memory": {
      "command": "python",
      "args": ["/path/to/mcp_memory_server.py"],
      "cwd": "/path/to/server/directory",
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

Usage with Claude

To get the most out of the memory server, add this system prompt to Claude:

Follow these steps for each interaction:

1. User Identification:
   - You should assume that you are interacting with default_user
   - If you have not identified default_user, proactively try to do so.

2. Memory Retrieval:
   - Always begin your chat by saying only "Remembering..." and retrieve all relevant information from your knowledge graph
   - Always refer to your knowledge graph as your "memory"

3. Memory
   - While conversing with the user, be attentive to any new information that falls into these categories:
     a) Basic Identity (age, gender, location, job title, education level, etc.)
     b) Behaviors (interests, habits, etc.)
     c) Preferences (communication style, preferred language, etc.)
     d) Goals (goals, targets, aspirations, etc.)
     e) Relationships (personal and professional relationships up to 3 degrees of separation)

4. Memory Update:
   - If any new information was gathered during the interaction, update your memory as follows:
     a) Create entities for recurring organizations, people, and significant events
     b) Connect them to the current entities using relations
     c) Store facts about them as observations

Available Tools

The server provides 9 MCP tools with exact compatibility to the TypeScript version:

1. create_entities

Create new entities in the knowledge graph.

Input:

{
  "entities": [
    {
      "name": "John Doe",
      "entityType": "person",
      "observations": ["Software engineer", "Lives in San Francisco"]
    }
  ]
}

2. create_relations

Create relationships between entities.

Input:

{
  "relations": [
    {
      "from": "John Doe",
      "to": "Acme Corp",
      "relationType": "works_at"
    }
  ]
}

3. add_observations

Add new observations to existing entities.

Input:

{
  "additions": [
    {
      "entityName": "John Doe",
      "observations": ["Enjoys hiking", "Plays guitar"]
    }
  ]
}

4. delete_entities

Delete entities and their associated relations.

Input:

{
  "names": ["John Doe", "Jane Smith"]
}

5. delete_relations

Delete specific relations.

Input:

{
  "relations": [
    {
      "from": "John Doe",
      "to": "Acme Corp",
      "relationType": "works_at"
    }
  ]
}

6. delete_observations

Remove specific observations from entities.

Input:

{
  "deletions": [
    {
      "entityName": "John Doe",
      "observations": ["Old observation to remove"]
    }
  ]
}

7. read_graph

Retrieve the entire knowledge graph.

Input: None

Output: Complete graph with all entities and relations.

8. search_nodes

Search for entities by query string.

Input:

{
  "query": "software engineer"
}

Output: Entities matching the query and their interconnections.

9. open_nodes

Get specific entities and their connections.

Input:

{
  "names": ["John Doe", "Acme Corp"]
}

Output: Requested entities plus any connected entities and all relevant relations.

File Format

The server uses JSONL (JSON Lines) format for storage, with each line containing either an entity or relation:

{"type": "entity", "name": "John Doe", "entityType": "person", "observations": ["Software engineer"]}
{"type": "relation", "from": "John Doe", "to": "Acme Corp", "relationType": "works_at"}

This format is fully compatible with the TypeScript version, allowing you to migrate existing memory files.

Direct Server Testing

You can test the server directly without an MCP client:

1. Start the server:

   source .venv/bin/activate
   python mcp_memory_server.py
   

2. Send MCP protocol messages via stdin. The server expects JSON-RPC 2.0 messages following the MCP specification.

Error Handling

The server includes comprehensive error handling for:

• Malformed JSON in memory files
• Missing required fields
• File I/O errors
• Invalid tool parameters
• Concurrent access protection

Performance

The server is optimized for:

• Graphs with hundreds of entities
• Efficient search across entity names, types, and observations
• Fast file I/O with minimal memory usage
• Concurrent access safety

Logging

The server logs important events to help with debugging:

• Server startup and configuration
• Graph loading and saving operations
• Error conditions and warnings
• Tool execution results

Compatibility

This Python implementation provides:

• Functional compatibility: Works with existing memory.json files from the TypeScript version
• Tool compatibility: All 9 tools work identically to the TypeScript version
• File format compatibility: Can read/write the same JSONL format
• Client compatibility: Works with Claude Desktop, Cursor IDE, AWS Q CLI, and other MCP clients

Development

Project Structure

mcp-memory-server-py/
├── mcp_memory_server.py          # Main server implementation
├── requirements.txt              # Python dependencies
├── README.md                     # This documentation

Contributing

When contributing to this project:

1. Maintain compatibility with the TypeScript version
2. Follow Python best practices and PEP 8
3. Add comprehensive error handling
4. Update documentation for any changes
5. Test on macOS (primary supported platform)

License

This implementation follows the same licensing as the original TypeScript MCP memory server.

Support

For issues, bugs, or feature requests, please refer to the original MCP memory server documentation and adapt solutions for this Python implementation.

Remember: This implementation was developed and tested only on macOS. Use on other platforms may require additional testing and modifications.