MCP Memory Server - Python Implementation

Una implementación en Python del servidor de memoria MCP para almacenamiento y recuperación de grafos de conocimiento, utilizando archivos JSONL para persistencia.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MCP Memory Server - Python Implementation

Una implementación completa en Python del servidor de memoria MCP de TypeScript oficial. Este servidor proporciona capacidades de almacenamiento y recuperación de grafos de conocimiento a través del Protocolo de Contexto de Modelo (MCP).

⚠️ Compatibilidad de Plataforma

Esta implementación fue desarrollada y probada exclusivamente en macOS. Aunque debería funcionar en otros sistemas similares a Unix, no se han realizado pruebas en Windows, Linux u otras plataformas. El uso en otras plataformas es bajo su propio riesgo.

Características

  • Gestión Completa de Grafos de Conocimiento: Almacena y gestiona entidades, relaciones y observaciones
  • Formato de Archivo JSONL: Compatible con el formato de archivo de la versión de TypeScript
  • 9 Herramientas MCP: Paridad completa de funciones con la implementación original de TypeScript
  • Capacidades de Búsqueda: Consulta entidades por nombre, tipo o contenido de observación
  • Recorrido de Grafos: Explora conexiones y relaciones entre entidades
  • Configuración de Entorno: Ubicación de almacenamiento personalizable

Configuración del Entorno de Desarrollo

Requisitos Previos

  • Python 3.8 o superior
  • macOS (plataforma probada)

Configuración del Entorno Virtual

  1. Crear un entorno virtual:

    python3 -m venv .venv

  2. Activar el entorno virtual:

    source .venv/bin/activate

  3. Instalar dependencias:

    pip install -r requirements.txt

  4. Desactivar al terminar:

    deactivate

Instalación

  1. Clonar o descargar este repositorio

  2. Configurar el entorno virtual (ver arriba)

  3. Probar la instalación:

    source .venv/bin/activate
python mcp_memory_server.py

    El servidor debería iniciarse y esperar mensajes del protocolo MCP a través de stdin/stdout.

Configuración

Variables de Entorno

  • MEMORY_FILE_PATH: Ruta al archivo de almacenamiento de memoria (predeterminado: ./memory.json)

Ejemplo:

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

Configuración del Cliente MCP

Claude Desktop

Añade esta configuración a los ajustes de Claude Desktop:

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

Nota: Asegúrate de activar tu entorno virtual antes de ejecutar, o usa la ruta completa al intérprete de Python en tu entorno virtual.

Cursor IDE

  1. Abre la configuración de Cursor IDE
  2. Navega a la configuración de Servidores MCP
  3. Añade un nuevo servidor con:
    • Nombre: memory
    • Comando: python
    • Argumentos: ["/path/to/mcp_memory_server.py"]
    • Entorno: {"MEMORY_FILE_PATH": "/path/to/memory.json"}

AWS Q CLI

Configura el servidor de memoria en los ajustes MCP de tu AWS Q CLI:

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

Configuración Genérica de Cliente MCP

Para cualquier cliente MCP que admita servidores basados en stdio:

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

Uso con Claude

Para aprovechar al máximo el servidor de memoria, añade este prompt de sistema a 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

Herramientas Disponibles

El servidor proporciona 9 herramientas MCP con compatibilidad exacta con la versión de TypeScript:

1. create_entities

Crea nuevas entidades en el grafo de conocimiento.

Entrada:

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

2. create_relations

Crea relaciones entre entidades.

Entrada:

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

3. add_observations

Añade nuevas observaciones a entidades existentes.

Entrada:

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

4. delete_entities

Elimina entidades y sus relaciones asociadas.

Entrada:

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

5. delete_relations

Elimina relaciones específicas.

Entrada:

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

6. delete_observations

Elimina observaciones específicas de entidades.

Entrada:

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

7. read_graph

Recupera el grafo de conocimiento completo.

Entrada: Ninguna

Salida: Grafo completo con todas las entidades y relaciones.

8. search_nodes

Busca entidades por cadena de consulta.

Entrada:

{
  "query": "software engineer"
}

Salida: Entidades que coinciden con la consulta y sus interconexiones.

9. open_nodes

Obtiene entidades específicas y sus conexiones.

Entrada:

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

Salida: Entidades solicitadas más cualquier entidad conectada y todas las relaciones relevantes.

Formato de Archivo

El servidor utiliza el formato JSONL (JSON Lines) para el almacenamiento, con cada línea conteniendo una entidad o relación:

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

Este formato es totalmente compatible con la versión de TypeScript, lo que permite migrar archivos de memoria existentes.

Pruebas Directas del Servidor

Puedes probar el servidor directamente sin un cliente MCP:

  1. Iniciar el servidor:

    source .venv/bin/activate
python mcp_memory_server.py

  2. Enviar mensajes del protocolo MCP a través de stdin. El servidor espera mensajes JSON-RPC 2.0 que sigan la especificación MCP.

Manejo de Errores

El servidor incluye un manejo integral de errores para:

  • JSON malformado en archivos de memoria
  • Campos obligatorios faltantes
  • Errores de E/S de archivos
  • Parámetros de herramienta no válidos
  • Protección de acceso concurrente

Rendimiento

El servidor está optimizado para:

  • Grafos con cientos de entidades
  • Búsqueda eficiente en nombres de entidades, tipos y observaciones
  • E/S de archivos rápida con uso mínimo de memoria
  • Seguridad de acceso concurrente

Registro (Logging)

El servidor registra eventos importantes para ayudar con la depuración:

  • Inicio y configuración del servidor
  • Operaciones de carga y guardado de grafos
  • Condiciones de error y advertencias
  • Resultados de ejecución de herramientas

Compatibilidad

Esta implementación en Python proporciona:

  • Compatibilidad funcional: Funciona con archivos memory.json existentes de la versión de TypeScript
  • Compatibilidad de herramientas: Las 9 herramientas funcionan de manera idéntica a la versión de TypeScript
  • Compatibilidad de formato de archivo: Puede leer/escribir el mismo formato JSONL
  • Compatibilidad de clientes: Funciona con Claude Desktop, Cursor IDE, AWS Q CLI y otros clientes MCP

Desarrollo

Estructura del Proyecto

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

Contribuciones

Al contribuir a este proyecto:

  1. Mantener la compatibilidad con la versión de TypeScript
  2. Seguir las mejores prácticas de Python y PEP 8
  3. Añadir un manejo integral de errores
  4. Actualizar la documentación para cualquier cambio
  5. Probar en macOS (plataforma principal compatible)

Licencia

Esta implementación sigue la misma licencia que el servidor de memoria MCP original de TypeScript.

Soporte

Para problemas, errores o solicitudes de funciones, consulta la documentación del servidor de memoria MCP original y adapta las soluciones para esta implementación en Python.

Recuerda: Esta implementación fue desarrollada y probada solo en macOS. El uso en otras plataformas puede requerir pruebas y modificaciones adicionales.