MemoryMesh

Un servidor de grafo de conocimiento para modelos de IA, centrado en juegos de rol basados en texto y narración interactiva.

GitHub

353

Prueba este MCPPatrocinado

Documentación

MemoryMesh

MemoryMesh es un servidor de grafo de conocimiento diseñado para modelos de IA, con un enfoque en juegos de rol basados en texto y narración interactiva. Ayuda a la IA a mantener una memoria consistente y estructurada a través de conversaciones, permitiendo interacciones más ricas y dinámicas.

El proyecto se basa en el Servidor de Memoria de Grafo de Conocimiento del repositorio de servidores MCP y conserva su funcionalidad principal.

IMPORTANTE

Actualización v0.3.0: El SDK de MCP se ha actualizado de v1.0.4 a v1.25.2 para cumplir con la Especificación del Protocolo de Contexto de Modelo (2025-11-25) actual. Esta es una actualización importante que trae compatibilidad con los clientes MCP más recientes, incluyendo Claude Desktop, ChatGPT, Cursor, Gemini y VS Code. Después de actualizar, ejecuta npm install para obtener las nuevas dependencias.

Desde v0.2.7 la ubicación predeterminada de los esquemas se cambió a dist/data/schemas. No se espera que esta ubicación cambie en el futuro, pero si estás actualizando desde una versión anterior, asegúrate de mover tus archivos de esquema a la nueva ubicación.

Enlaces Rápidos

Descripción General

MemoryMesh es un servidor local de grafo de conocimiento que te permite construir y gestionar información estructurada para modelos de IA. Aunque es particularmente adecuado para juegos de rol basados en texto, su diseño adaptable lo hace útil para diversas aplicaciones, incluyendo simulaciones de redes sociales, planificación organizacional o cualquier escenario que involucre datos estructurados.

Características Clave

Herramientas Dinámicas Basadas en Esquemas: Define tu estructura de datos con esquemas, y MemoryMesh genera automáticamente herramientas para agregar, actualizar y eliminar datos.
Diseño Intuitivo de Esquemas: Crea esquemas que guíen a la IA en la generación y conexión de nodos, utilizando campos obligatorios, tipos enumerados y definiciones de relaciones.
Metadatos para Guía de IA: Utiliza metadatos para proporcionar contexto y estructura, ayudando a la IA a comprender el significado y las relaciones dentro de tus datos.
Manejo de Relaciones: Define relaciones dentro de tus esquemas para fomentar que la IA cree conexiones (aristas) entre puntos de datos relacionados (nodos).
Retroalimentación Informativa: Proporciona retroalimentación de errores a la IA, permitiéndole aprender de los errores y mejorar sus interacciones con el grafo de conocimiento.
Soporte de Eventos: Un sistema de eventos rastrea las operaciones, proporcionando información sobre cómo se está modificando el grafo de conocimiento.

Nodos

Los nodos representan entidades o conceptos dentro del grafo de conocimiento. Cada nodo tiene:

name: Un identificador único.
nodeType: El tipo de nodo (por ejemplo, npc, artifact, location), definido por tus esquemas.
metadata: Un arreglo de cadenas que proporcionan detalles descriptivos sobre el nodo.
weight: (Opcional) Un valor numérico entre 0 y 1 que representa la fuerza de la relación, con un valor predeterminado de 1.

Ejemplo de Nodo:

    {
      "name": "Aragorn",
      "nodeType": "player_character",
      "metadata": [
        "Race: Human",
        "Class: Ranger",
        "Skills: Tracking, Swordsmanship",
        "Affiliation: Fellowship of the Ring"
      ]
    }

Aristas

Las aristas representan relaciones entre nodos. Cada arista tiene:

from: El nombre del nodo fuente.
to: El nombre del nodo destino.
edgeType: El tipo de relación (por ejemplo, owns, located_in).

{
  "from": "Aragorn",
  "to": "Andúril",
  "edgeType": "owns"
}

Esquemas

Los esquemas son el corazón de MemoryMesh. Definen la estructura de tus datos y impulsan la generación automática de herramientas.

Ubicación de Archivos de Esquema

Coloca tus archivos de esquema (.schema.json) en el directorio dist/data/schemas de tu proyecto MemoryMesh compilado. MemoryMesh detectará y procesará automáticamente estos archivos al iniciar.

Estructura del Esquema

Nombre del archivo: [name].schema.json. Por ejemplo, para un esquema que define un 'npc', el nombre del archivo sería add_npc.schema.json.

name - Identificador para el esquema y tipo de nodo dentro de la memoria. IMPORTANTE: El nombre del esquema debe comenzar con add_ para ser reconocido.
description - Se utiliza como descripción para la herramienta add_<name>, proporcionando contexto para la IA. (Las herramientas delete y update tienen una descripción genérica)
properties - Cada propiedad incluye su tipo, descripción y restricciones adicionales.
- property
  - type - Los valores admitidos son string o array.
  - description - Ayuda a guiar a la IA sobre el propósito de la entidad.
  - required - Booleano. Si es true, la IA está obligada a proporcionar esta propiedad al crear un nodo.
  - enum - Un arreglo de cadenas. Si está presente, la IA debe elegir una de las opciones dadas.
  - relationship - Define una conexión a otro nodo. Si una propiedad es obligatoria y tiene una relación, la IA siempre creará tanto el nodo como la arista correspondiente.
    - edgeType - Tipo de relación a crear.
    - description - Ayuda a guiar a la IA sobre el propósito de la relación.
additionalProperties - Booleano. Si es true, permite a la IA agregar atributos adicionales más allá de los definidos como obligatorios u opcionales.

Ejemplo de Esquema (add_npc.schema.json):

{
  "name": "add_npc",
  "description": "Schema for adding an NPC to the memory" ,
  "properties": {
    "name": {
      "type": "string",
      "description": "A unique identifier for the NPC",
      "required": true
    },
    "race": {
      "type": "string",
      "description": "The species or race of the NPC",
      "required": true,
      "enum": [
        "Human",
        "Elf",
        "Dwarf",
        "Orc",
        "Goblin"
      ]
    },
    "currentLocation": {
      "type": "string",
      "description": "The current location of the NPC",
      "required": true,
      "relationship": {
        "edgeType": "located_in",
        "description": "The current location of the NPC"
      }
    }
  },
  "additionalProperties": true
}

Basado en este esquema, MemoryMesh crea automáticamente:

add_npc: Para agregar nuevos nodos NPC.
update_npc: Para modificar nodos NPC existentes.
delete_npc: Para eliminar nodos NPC.

MemoryMesh incluye 11 esquemas preconstruidos diseñados para juegos de rol basados en texto, proporcionando una base lista para usar en el desarrollo de juegos.

Herramienta SchemaManager

MemoryMesh incluye una herramienta SchemaManager para simplificar la creación y edición de esquemas. Proporciona una interfaz visual, facilitando la definición de tus estructuras de datos sin escribir JSON directamente.

Herramientas Dinámicas

MemoryMesh simplifica la interacción con tu grafo de conocimiento a través de herramientas dinámicas. Estas herramientas no están codificadas manualmente, sino que se generan automáticamente directamente desde tus definiciones de esquemas. Esto significa que cuando defines la estructura de tus datos usando esquemas, MemoryMesh crea inteligentemente un conjunto de herramientas adaptadas para trabajar con esa estructura de datos específica.

Piénsalo de esta manera: Tú proporcionas un plano (el esquema), y MemoryMesh construye automáticamente las herramientas necesarias para crear, modificar y eliminar elementos basados en ese plano.

¿Cómo funciona entre bastidores?

MemoryMesh tiene un sistema inteligente que lee tus definiciones de esquemas. Analiza la estructura que has definido, incluyendo las propiedades de tus entidades y sus relaciones. Basado en este análisis, crea automáticamente un conjunto de herramientas para cada tipo de entidad:

add_<entity>: Una herramienta para crear nuevas instancias de una entidad.
update_<entity>: Una herramienta para modificar entidades existentes.
delete_<entity>: Una herramienta para eliminar entidades.

Estas herramientas se ponen a disposición a través de un centro central dentro de MemoryMesh, asegurando que puedan ser fácilmente accedidas y utilizadas por cualquier cliente o IA conectado.

En esencia, el sistema de herramientas dinámicas de MemoryMesh proporciona una forma poderosa y eficiente de gestionar tu grafo de conocimiento, liberándote para enfocarte en el contenido y la lógica de tu aplicación en lugar de la mecánica subyacente de manipulación de datos.

Archivo de Memoria

Por defecto, los datos se almacenan en un archivo JSON en dist/data/memory.json.

Visor de Memoria

El Visor de Memoria es una herramienta separada diseñada para ayudarte a visualizar e inspeccionar el contenido del grafo de conocimiento gestionado por MemoryMesh. Proporciona una interfaz fácil de usar para explorar nodos, aristas y sus propiedades.

Características Clave:

Visualización de Grafos: Ve el grafo de conocimiento como un diagrama interactivo de nodos y enlaces.
Inspección de Nodos: Selecciona nodos para ver su nodeType, metadatos y aristas conectadas.
Exploración de Aristas: Examina las relaciones entre nodos, incluyendo edgeType y dirección.
Búsqueda y Filtrado: Encuentra rápidamente nodos específicos o fíltralos por tipo.
Vista de Tabla: Te permite encontrar e inspeccionar fácilmente nodos y aristas específicos, o todos a la vez.
Vista JSON Crudo: Te permite ver los datos JSON crudos del archivo de memoria.
Panel de Estadísticas: Proporciona métricas clave e información sobre el grafo de conocimiento: total de nodos, total de aristas, tipos de nodos y tipos de aristas.
Búsqueda y Filtro: Te permite filtrar por tipo de nodo o tipo de arista y filtrar si mostrar nodos, aristas o ambos.

Acceso al Visor de Memoria

El Visor de Memoria es una aplicación web independiente. Discusión del Visor de Memoria

Uso del Visor de Memoria

Seleccionar Archivo de Memoria: En el Visor de Memoria, haz clic en el botón "Seleccionar Archivo de Memoria".
Elegir Archivo: Navega al directorio de tu proyecto MemoryMesh y selecciona el archivo memory.json (ubicado en dist/data/memory.json por defecto).
Explorar: El Visor de Memoria cargará y mostrará el contenido de tu grafo de conocimiento.

Flujo de Memoria

Prompt

Para obtener resultados óptimos, utiliza la función "Proyectos" de Claude con instrucciones personalizadas. Aquí tienes un ejemplo de un prompt con el que puedes comenzar:

You are a helpful AI assistant managing a knowledge graph for a text-based RPG. You have access to the following tools: add_npc, update_npc, delete_npc, add_location, update_location, delete_location, and other tools for managing the game world.

When the user provides input, first process it using your available tools to update the knowledge graph. Then, respond in a way that is appropriate for a text-based RPG.

También puedes instruir a la IA para que realice acciones específicas directamente en el chat.

¡Experimenta con diferentes prompts para encontrar lo que funcione mejor para tu caso de uso!

Ejemplo

Un ejemplo simple con instrucciones personalizadas.
Un ejemplo por el bien del ejemplo, con visualización (NO parte de la funcionalidad)

Agrega un par de ciudades, algunos npcs, un par de ubicaciones alrededor de la ciudad para explorar, esconde un artefacto o dos en algún lugar

Instalación

Requisitos Previos

Node.js: Versión 18 o superior. Puedes descargarlo desde nodejs.org.
npm: Generalmente incluido con Node.js.
Claude para Desktop: Asegúrate de tener la última versión instalada desde claude.ai/download.

Pasos de Instalación

Clonar el Repositorio:

git clone https://github.com/CheMiguel23/memorymesh.git
cd memorymesh

Instalar Dependencias:
```
npm install
```
Compilar el Proyecto:
```
npm run build
```
Este comando compila el código TypeScript a JavaScript en el directorio dist y copia archivos de esquema y datos de muestra en él también.
Verificar la Copia de Archivos (Opcional):
- El proceso de compilación debería copiar automáticamente la carpeta data a dist.
- Verifica que dist/data exista y contenga archivos .json. También verifica que dist/data/schemas exista y contenga archivos .schema.json.
Configurar Claude Desktop:

Abre tu archivo de configuración de Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Agrega una entrada para memorymesh a la sección mcpServers. Puedes elegir una de las siguientes opciones de configuración:
```
"mcpServers": {
  "memorymesh": {
    "command": "node", 
    "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/memorymesh/dist/index.js"]
  }
}
```
- Reemplaza /ABSOLUTE/PATH/TO/YOUR/PROJECT/ con la ruta absoluta real a tu directorio del proyecto memorymesh.
- Ejemplo (macOS):
```
"command": "node",
"args": ["/Users/yourusername/Projects/memorymesh/dist/index.js"]
```
- Ejemplo (Windows):
```
"command": "node",
"args": ["C:\\Projects\\memorymesh\\dist\\index.js"]
```
Reiniciar Claude Desktop: Reinicia completamente Claude Desktop para que los cambios surtan efecto.

Verificar Instalación

Inicia Claude Desktop.
Abre un nuevo chat.
Busca el ícono del plugin MCP en la esquina superior derecha. Si está ahí, tu configuración probablemente sea correcta.
Haz clic en el ícono . Deberías ver "memorymesh" en la lista de servidores conectados.
Haz clic en el ícono . Si ves herramientas listadas (por ejemplo, add_npc, update_npc, etc.), tu servidor está funcionando y exponiendo herramientas correctamente.

Actualización

Antes de las actualizaciones, asegúrate de hacer una copia de seguridad de tu directorio dist/data para evitar perder tus datos de memoria.

Solución de Problemas

El servidor no aparece en Claude:
- Vuelve a verificar las rutas en tu claude_desktop_config.json. Asegúrate de que sean rutas absolutas y correctas.
- Verifica que el directorio dist exista y contenga los archivos JavaScript compilados, incluyendo index.js.
- Revisa los registros de Claude Desktop para ver si hay errores:
  - macOS: ~/Library/Logs/Claude/mcp-server-memorymesh.log (y mcp.log)
  - Windows: (Probablemente en una carpeta Logs dentro de %AppData%\Claude)
Las herramientas no aparecen:
- Asegúrate de que tu comando npm run build se haya completado sin errores.
- Verifica que tus archivos de esquema estén colocados correctamente en dist/data/schemas y sigan la convención de nomenclatura correcta (add_[entity].schema.json).
- Revisa la salida de la consola o los registros de tu servidor para detectar errores durante la inicialización.

Configuración avanzada

MemoryMesh ofrece varias formas de personalizar su comportamiento más allá de la configuración básica:

Variables

Puedes anular la configuración predeterminada usando /config/config.ts

MEMORY_FILE: Especifica la ruta al archivo JSON utilizado para almacenar los datos del grafo de conocimiento. (Predeterminado: dist/data/memory.json)
SCHEMAS_DIR: Ruta al directorio de archivos de esquema. (Predeterminado: dist/data/schemas/memory.json)

Limitaciones

Eliminación de nodos: Es posible que la IA dude en eliminar nodos del grafo de conocimiento. Anímala mediante indicaciones si es necesario.
Conocimiento conflictivo: MemoryMesh utiliza actualmente un enfoque de "última escritura gana" para manejar los datos. Si se proporciona información conflictiva sobre la misma entidad, la actualización más reciente sobrescribirá los valores anteriores. Aquí hay estrategias para gestionar información conflictiva:

Enfoques actuales:
- Usa metadatos para rastrear fuentes: Agrega entradas de metadatos como "Source: Character testimony" o "Source: Official records" para rastrear de dónde proviene la información.
- Usa metadatos temporales: Incluye marcas de tiempo o marcadores de tiempo narrativos (por ejemplo, "As of Chapter 3") en los metadatos para rastrear cuándo la información era válida.
- Crea nodos separados para perspectivas: Para información subjetiva o en disputa, crea nodos separados que representen diferentes puntos de vista (por ejemplo, rumor_about_villain frente a truth_about_villain).
- Usa pesos de aristas: Aprovecha la propiedad opcional weight en las aristas (rango 0-1) para indicar la confianza o confiabilidad de las relaciones.
Ejemplo: seguimiento de información incierta:
```
{
  "name": "VillainOrigin_Rumor",
  "nodeType": "information",
  "metadata": [
    "Source: Tavern gossip",
    "Reliability: Low",
    "Claims: Villain came from the northern mountains"
  ]
}
```
Consideraciones futuras: Para aplicaciones que requieran una resolución de conflictos sofisticada, considera implementar una capa personalizada que:
- Mantenga el historial de versiones de los cambios de nodos
- Rastree la procedencia (fuente) de cada pieza de información
- Implemente puntuaciones de confianza para las afirmaciones
- Soporte períodos de validez temporal para los hechos

Contribución

¡Las contribuciones, comentarios e ideas son bienvenidos! Este proyecto es una exploración personal sobre la integración de datos estructurados con capacidades de razonamiento de IA. Las contribuciones, comentarios e ideas son bienvenidos para impulsarlo más o inspirar nuevos proyectos.