MemoryMesh

MemoryMesh es un servidor de grafos de conocimiento diseñado para modelos de IA, centrado en juegos de rol basados en texto y narraciones interactivas. Ayuda a la IA a mantener una memoria consistente y estructurada en las conversaciones, lo que permite interacciones más ricas y dinámicas.

El proyecto se basa en el servidor de memoria Knowledge Graph del repositorio de servidores MCP y conserva su funcionalidad principal.

IMPORTANTE

Desde v0.2.7 la ubicación predeterminada de los esquemas se cambió a dist/data/schemas . No se prevé que esta ubicación cambie en el futuro, pero si actualiza desde una versión anterior, asegúrese de mover los archivos de esquema a la nueva ubicación.

Enlaces rápidos

• Instalación
• Ejemplo
• Discusión sobre la guía de SchemaManager
• Discusión sobre la guía de MemoryViewer

Descripción general

MemoryMesh es un servidor local de grafos de conocimiento que permite crear y gestionar información estructurada para modelos de IA. Si bien es especialmente adecuado para juegos de rol basados en texto, su diseño adaptable lo hace útil para diversas aplicaciones, como simulaciones de redes sociales, planificación organizacional o cualquier escenario que involucre datos estructurados.

Características principales

• Herramientas basadas en esquemas dinámicos: defina su estructura de datos con esquemas y MemoryMesh genera automáticamente herramientas para agregar, actualizar y eliminar datos.
• Diseño de esquemas intuitivos: cree 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 la orientación de la IA: utilice metadatos para proporcionar contexto y estructura, ayudando a la IA a comprender el significado y las relaciones dentro de sus datos.
• Manejo de relaciones: defina relaciones dentro de sus esquemas para alentar a la IA a crear conexiones (bordes) entre puntos de datos relacionados (nodos).
• Retroalimentación informativa: proporciona retroalimentación de errores a la IA, lo que le permite aprender de los errores y mejorar sus interacciones con el gráfico de conocimiento.
• Soporte de eventos: un sistema de eventos rastrea las operaciones y proporciona información sobre cómo se modifica el gráfico 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 sus esquemas.
• metadata : una matriz 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.

Nodo de ejemplo:

Bordes

Las aristas representan relaciones entre nodos. Cada arista tiene:

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

Esquemas

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

Ubicación del archivo de esquema

Coloque sus archivos de esquema ( .schema.json ) en el directorio dist/data/schemas de su proyecto MemoryMesh. MemoryMesh detectará y procesará automáticamente estos archivos al iniciarse.

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 del esquema y tipo de nodo en la memoria. IMPORTANTE : El nombre del esquema debe empezar por add_ para ser reconocido.
• description : Se utiliza como descripción de 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 : Una matriz de cadenas. Si está presente, la IA debe elegir una de las opciones dadas.
    • relationship : Define una conexión con otro nodo. Si se requiere una propiedad y existe una relación, la IA siempre creará tanto el nodo como la arista correspondiente.
      • edgeType - Tipo de relación que se creará.
      • description : Ayuda a guiar a la IA sobre el propósito de la relación.
• additionalProperties - Booleano. Si es true , permite que la IA agregue atributos adicionales a los definidos como obligatorios u opcionales.

Esquema de ejemplo (add_npc.schema.json):

Basándose en este esquema, MemoryMesh crea automáticamente:

• add_npc: para agregar nuevos nodos NPC.
• update_npc: para modificar los nodos NPC existentes.
• delete_npc: para eliminar nodos NPC.

MemoryMesh incluye 11 esquemas prediseñados diseñados para juegos de rol basados en texto, lo que proporciona una base lista para usar para el desarrollo de juegos.

Herramienta SchemaManager

MemoryMesh incluye una herramienta SchemaManager para simplificar la creación y edición de esquemas. Ofrece una interfaz visual que facilita la definición de estructuras de datos sin necesidad de escribir JSON directamente.

Herramientas dinámicas

MemoryMesh simplifica la interacción con su gráfico de conocimiento mediante herramientas dinámicas . Estas herramientas no se codifican manualmente, sino que se generan automáticamente a partir de las definiciones de esquema . Esto significa que, al definir la estructura de sus datos mediante esquemas, MemoryMesh crea de forma inteligente un conjunto de herramientas adaptadas a esa estructura de datos específica.

Piénselo de esta manera: usted proporciona un plano (el esquema) y MemoryMesh construye automáticamente las herramientas necesarias para crear, modificar y eliminar elementos basándose en ese plano.

¿Cómo funciona detrás de escena?

MemoryMesh cuenta con un sistema inteligente que lee las definiciones de esquema. Analiza la estructura definida, incluyendo las propiedades de las entidades y sus relaciones. Con base 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.

Luego, estas herramientas se ponen a disposición a través de un centro central dentro de MemoryMesh, lo que garantiza que cualquier cliente o IA conectado pueda acceder a ellas y utilizarlas fácilmente.

En esencia, el sistema de herramientas dinámicas de MemoryMesh proporciona una forma poderosa y eficiente de administrar su gráfico de conocimiento, permitiéndole concentrarse en el contenido y la lógica de su aplicación en lugar de en la mecánica subyacente de la manipulación de datos.

Archivo de memoria

De forma predeterminada, los datos se almacenan en un archivo JSON en dist/data/memory.json .

Visor de memoria

El Visor de Memoria es una herramienta independiente diseñada para visualizar e inspeccionar el contenido del grafo de conocimiento administrado por MemoryMesh. Ofrece una interfaz intuitiva para explorar nodos, aristas y sus propiedades.

Características principales:

• Visualización de gráficos: vea el gráfico de conocimiento como un diagrama interactivo de nodos y enlaces.
• Inspección de nodos: seleccione nodos para ver su tipo de nodo, metadatos y bordes conectados.
• Exploración de bordes: examine las relaciones entre los nodos, incluido el tipo de borde y la dirección.
• Búsqueda y filtrado: encuentre rápidamente nodos específicos o fíltrelos por tipo.
• Vista de tabla: le permite encontrar e inspeccionar fácilmente nodos y bordes específicos, o todos ellos a la vez.
• Vista JSON sin procesar: le permite ver los datos JSON sin procesar del archivo de memoria.
• Panel de estadísticas: proporciona métricas clave e información sobre el gráfico de conocimiento: total de nodos, total de bordes, tipos de nodos y tipos de bordes.
• Buscar y filtrar: le permite filtrar por tipo de nodo o tipo de borde y filtrar si desea mostrar nodos, bordes o ambos.

Acceder al Visor de memoria

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

Uso del Visor de memoria

• Seleccionar archivo de memoria: en el Visor de memoria, haga clic en el botón "Seleccionar archivo de memoria".
• Elegir archivo: navegue al directorio de su proyecto MemoryMesh y seleccione el archivo memory.json (ubicado en dist/data/memory.json de manera predeterminada).
• Explorar: El Visor de memoria cargará y mostrará el contenido de su gráfico de conocimiento.

Flujo de memoria

Inmediato

Para obtener resultados óptimos, use la función "Proyectos" de Claude con instrucciones personalizadas. Aquí tiene un ejemplo de una instrucción con la que puede empezar:

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

¡Experimente con diferentes indicaciones para encontrar lo que funciona mejor para su caso de uso!

Ejemplo

1. Un ejemplo sencillo con instrucciones personalizadas.
2. Un ejemplo a modo de ejemplo, con visualización (NO parte de la funcionalidad)

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

Instalación

Instalación mediante herrería

Para instalar MemoryMesh para Claude Desktop automáticamente a través de Smithery :

Prerrequisitos

• Node.js: Versión 18 o superior. Puedes descargarlo desde nodejs.org .
• npm: generalmente incluido con Node.js.
• Claude para escritorio: asegúrese de tener instalada la última versión desde claude.ai/download .

Pasos de instalación

1. Clonar el repositorio:
   git clone https://github.com/CheMiguel23/memorymesh.git cd memorymesh
2. Dependencias de instalación:
   npm install
3. Construir el proyecto:
   npm run build
   Este comando compila el código TypeScript en JavaScript en el directorio dist y también copia allí el esquema de muestra y los archivos de datos.
4. Verificar copia de archivo (opcional):
   • El proceso de compilación debería copiar automáticamente la carpeta data a dist .
   • Comprueba que dist/data exista y contenga archivos .json . También verifica que dist/data/schemas exista y contenga archivos .schema.json .
5. Configurar Claude Desktop:Abra el archivo de configuración de Claude Desktop:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Ventanas: %APPDATA%\Claude\claude_desktop_config.json
   • Agregue una entrada para memorymesh a la sección mcpServers . Puede elegir una de las siguientes opciones de configuración:
   "mcpServers": { "memorymesh": { "command": "node", "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/memorymesh/dist/index.js"] } }
   • Reemplace /ABSOLUTE/PATH/TO/YOUR/PROJECT/ con la ruta absoluta real a su directorio de 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"]
6. Reiniciar Claude Desktop: reinicie completamente Claude Desktop para que los cambios surtan efecto.

Verificar la instalación

1. Inicie Claude Desktop.
2. Abrir un nuevo chat.
3. Busca el icono del complemento MCP en la esquina superior derecha. Si está ahí, es probable que tu configuración sea correcta.
4. Haz clic en el icono. Deberías ver "memorymesh" en la lista de servidores conectados.
5. Haz clic en el icono. Si ves herramientas en la lista (p. ej., add_npc , update_npc , etc.), tu servidor funciona y las expone correctamente.

Actualizando

Antes de realizar actualizaciones, asegúrese de hacer una copia de seguridad de su directorio dist/data para evitar perder los datos de su memoria.

Solución de problemas

• El servidor no aparece en Claude:
  • Revisa las rutas en tu claude_desktop_config.json . Asegúrate de que sean rutas absolutas y correctas.
  • Verifique que el directorio dist exista y contenga los archivos JavaScript compilados, incluido index.js .
  • Consulte 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 en %AppData%\Claude )
• Herramientas que no aparecen:
  • Asegúrese de que su comando npm run build se haya completado sin errores.
  • Verifique que sus archivos de esquema estén ubicados correctamente en dist/data/schemas y sigan la convención de nomenclatura correcta ( add_[entity].schema.json ).
  • Verifique la salida de la consola o los registros de su servidor para detectar cualquier error 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

Puede anular la configuración predeterminada utilizando /config/config.ts

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

Limitaciones

1. Eliminación de nodos: La IA puede dudar en eliminar nodos del grafo de conocimiento. Anímela con indicaciones si es necesario.

Contribución

¡Agradecemos sus contribuciones, comentarios e ideas! Este proyecto es una exploración personal sobre la integración de datos estructurados con las capacidades de razonamiento de la IA. Agradecemos sus contribuciones, comentarios e ideas para impulsarlo o inspirar nuevos proyectos.