Memory

Sistema de memoria persistente basado en grafos de conocimiento

GitHub
90.5k

Documentación

Servidor de Memoria de Knowledge Graph

Una implementación básica de memoria persistente usando un knowledge graph local. Esto permite que Claude recuerde información sobre el usuario entre chats.

Publicado en npm como @modelcontextprotocol/server-memory.

Conceptos Centrales

Entidades

Las entidades son los nodos primarios en el knowledge graph. Cada entidad tiene:

  • Un nombre único (identificador)
  • Un tipo de entidad (ej., "persona", "organización", "evento")
  • Una lista de observaciones

Ejemplo:

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["Speaks fluent Spanish"]
}

Relaciones

Las relaciones definen conexiones dirigidas entre entidades. Siempre se almacenan en voz activa y describen cómo interactúan o se relacionan las entidades entre sí.

Ejemplo:

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at"
}

Observaciones

Las observaciones son piezas discretas de información sobre una entidad. Son:

  • Almacenadas como cadenas de texto
  • Adjuntas a entidades específicas
  • Pueden agregarse o eliminarse de forma independiente
  • Deben ser atómicas (un hecho por observación)

Ejemplo:

{
  "entityName": "John_Smith",
  "observations": [
    "Speaks fluent Spanish",
    "Graduated in 2019",
    "Prefers morning meetings"
  ]
}

API

Herramientas

  • create_entities

    • Crea múltiples entidades nuevas en el knowledge graph
    • Entrada: entities (arreglo de objetos)
      • Cada objeto contiene:
        • name (cadena): Identificador de la entidad
        • entityType (cadena): Clasificación de tipo
        • observations (cadena[]): Observaciones asociadas
    • Ignora entidades con nombres existentes

  • create_relations

    • Crea múltiples relaciones nuevas entre entidades
    • Entrada: relations (arreglo de objetos)
      • Cada objeto contiene:
        • from (cadena): Nombre de la entidad fuente
        • to (cadena): Nombre de la entidad destino
        • relationType (cadena): Tipo de relación en voz activa
    • Omite relaciones duplicadas
    • Falla si la entidad fuente o destino no existe

  • add_observations

    • Agrega nuevas observaciones a entidades existentes
    • Entrada: observations (arreglo de objetos)
      • Cada objeto contiene:
        • entityName (cadena): Entidad destino
        • contents (cadena[]): Nuevas observaciones a agregar
    • Devuelve las observaciones agregadas por entidad
    • Falla si la entidad no existe

  • delete_entities

    • Elimina entidades y sus relaciones
    • Entrada: entityNames (cadena[])
    • Eliminación en cascada de relaciones asociadas
    • No genera error si una entidad no existe; la respuesta informa qué nombres no fueron encontrados

  • delete_observations

    • Elimina observaciones específicas de entidades
    • Entrada: deletions (arreglo de objetos)
      • Cada objeto contiene:
        • entityName (cadena): Entidad destino
        • observations (cadena[]): Observaciones a eliminar
    • No genera error si una observación no existe; la respuesta informa cuántas fueron eliminadas

  • delete_relations

    • Elimina relaciones específicas del grafo
    • Entrada: relations (arreglo de objetos)
      • Cada objeto contiene:
        • from (cadena): Nombre de la entidad fuente
        • to (cadena): Nombre de la entidad destino
        • relationType (cadena): Tipo de relación
    • No genera error si una relación no existe; la respuesta informa cuántas fueron eliminadas

  • read_graph

    • Lee todo el knowledge graph
    • No requiere entrada
    • Devuelve la estructura completa del grafo con todas las entidades y relaciones

  • search_nodes

    • Busca nodos basándose en una consulta
    • Entrada: query (cadena)
    • Busca en:
      • Nombres de entidades
      • Tipos de entidades
      • Contenido de observaciones
    • Devuelve entidades coincidentes y sus relaciones

  • open_nodes

    • Recupera nodos específicos por nombre
    • Entrada: names (cadena[])
    • Devuelve:
      • Entidades solicitadas
      • Relaciones entre las entidades solicitadas
    • Omite silenciosamente nodos inexistentes

Recursos

  • knowledge-graph (memory://knowledge-graph)
    • El knowledge graph completo como un Recurso MCP legible
    • Tipo MIME: application/json
    • Devuelve la misma forma que read_graph (entidades y relaciones)
    • Las herramientas de mutación (create_entities, create_relations, add_observations, delete_entities, delete_observations, delete_relations) emiten notifications/resources/updated para este URI, de modo que los clientes suscritos vean cambios en vivo

Uso con Claude Desktop

Configuración

Agrega esto a tu claude_desktop_config.json:

Docker

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
    }
  }
}

NPX

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

En Windows, usa cmd /c para lanzar npx:

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

NPX con configuración personalizada

El servidor se puede configurar usando las siguientes variables de entorno:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
      }
    }
  }
}

En Windows, usa:

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.jsonl"
      }
    }
  }
}
  • MEMORY_FILE_PATH: Ruta al archivo JSONL de almacenamiento de memoria (predeterminado: memory.jsonl en el directorio del servidor)

Instrucciones de Instalación para VS Code

Para una instalación rápida, usa uno de los botones de instalación con un solo clic a continuación:

Install with NPX in VS Code Install with NPX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

Para instalación manual, puedes configurar el servidor MCP usando uno de estos métodos:

Método 1: Configuración de Usuario (Recomendado) Agrega la configuración a tu archivo de configuración MCP a nivel de usuario. Abre la Paleta de Comandos (Ctrl + Shift + P) y ejecuta MCP: Open User Configuration. Esto abrirá tu archivo mcp.json de usuario donde puedes agregar la configuración del servidor.

Método 2: Configuración del Espacio de Trabajo Alternativamente, puedes agregar la configuración a un archivo llamado .vscode/mcp.json en tu espacio de trabajo. Esto te permitirá compartir la configuración con otros.

Para más detalles sobre la configuración de MCP en VS Code, consulta la documentación oficial de MCP de VS Code.

NPX

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

En Windows, usa:

{
  "servers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

Docker

{
  "servers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-v",
        "claude-memory:/app/dist",
        "--rm",
        "mcp/memory"
      ]
    }
  }
}

Prompt del Sistema

El prompt para utilizar la memoria depende del caso de uso. Cambiar el prompt ayudará al modelo a determinar la frecuencia y los tipos de memorias creadas.

Aquí hay un ejemplo de prompt para personalización de chat. Podrías usar este prompt en el campo "Instrucciones Personalizadas" de un Proyecto de Claude.ai.

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

Compilación

Docker:

docker build -t mcp/memory -f src/memory/Dockerfile .

Para tu conocimiento: un volumen mcp/memory anterior contiene un archivo index.js que podría ser sobrescrito por el nuevo contenedor. Si estás usando un volumen de docker para almacenamiento, elimina el archivo index.js del volumen de docker anterior antes de iniciar el nuevo contenedor.

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.