Servidor MCP de memoria

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona una funcionalidad de gráfico de conocimiento para administrar entidades, relaciones y observaciones en la memoria, con reglas de validación estrictas para mantener la consistencia de los datos.

Instalación

Instalar el servidor en Claude Desktop:

mcp install main.py -v MEMORY_FILE_PATH=/path/to/memory.jsonl

Reglas de validación de datos

Nombres de entidades

Debe comenzar con una letra minúscula
Puede contener letras minúsculas, números y guiones.
Longitud máxima de 100 caracteres
Debe ser único dentro del gráfico
Ejemplos de nombres válidos: python-project , meeting-notes-2024 , user-john

Tipos de entidad

Se admiten los siguientes tipos de entidades:

person : Entidades humanas
concept : Ideas o principios abstractos
project : Iniciativas o tareas de trabajo
document : Cualquier forma de documentación
tool : Herramientas o utilidades de software
organization : Empresas o grupos
location : Lugares físicos o virtuales
event : Sucesos limitados en el tiempo

Observaciones

Cadenas no vacías
Longitud máxima de 500 caracteres
Debe ser único por entidad
Deben ser declaraciones fácticas y objetivas.
Incluir marca de tiempo cuando sea relevante

Relaciones

Se admiten los siguientes tipos de relación:

knows : Conexión de persona a persona
contains : Relación padre/hijo
uses : Entidad que utiliza otra entidad
created : Relación de autoría/creación
belongs-to : Membresía/propiedad
depends-on : Relación de dependencia
related-to : Relación genérica

Reglas de relación adicionales:

Deben existir tanto las entidades de origen como las de destino
No se permiten relaciones autorreferenciales
No se permiten dependencias circulares
Debe utilizar tipos de relación predefinidos

Uso

El servidor proporciona herramientas para gestionar un gráfico de conocimiento:

Obtener entidad

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}")

Obtener gráfico

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}")

Crear entidades

# 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}")

Añadir observación

# 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}")

Crear relación

# 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}")

Buscar memoria

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}")

La función de búsqueda admite:

Consultas temporales (por ejemplo, "más reciente", "último", "más reciente")
Consultas de actividad (p. ej., "entrenamiento", "ejercicio")
Búsquedas generales de entidades
Coincidencia difusa con un umbral de similitud del 80 %
Búsqueda ponderada en:
- Nombres de entidades (peso: 1.0)
- Tipos de entidad (peso: 0,8)
- Observaciones (peso: 0,6)

Eliminar entidades

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}")

Eliminar relación

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}")

Vaciar memoria

result = await session.call_tool("flush_memory", {})
if not result.success:
    print(f"Error flushing memory: {result.error}")

Tipos de error

El servidor utiliza los siguientes tipos de errores:

NOT_FOUND : Entidad o recurso no encontrado
VALIDATION_ERROR : Datos de entrada no válidos
INTERNAL_ERROR : Error del lado del servidor
ALREADY_EXISTS : El recurso ya existe
INVALID_RELATION : Relación no válida entre entidades

Modelos de respuesta

Todas las herramientas devuelven respuestas tipificadas utilizando estos modelos:

Respuesta de entidad

class EntityResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

Respuesta gráfica

class GraphResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

OperaciónRespuesta

class OperationResponse(BaseModel):
    success: bool
    error: Optional[str] = None
    error_type: Optional[str] = None

Desarrollo

Ejecución de pruebas

pytest tests/

Añadiendo nuevas funciones

Actualizar las reglas de validación en validation.py
Agregar pruebas en tests/test_validation.py
Implementar cambios en knowledge_graph_manager.py

Memory MCP Server

Integrations