MCP HubMCP Hub
CheMiguel23

MemoryMesh

by: CheMiguel23

A knowledge graph server that uses the Model Context Protocol (MCP) to provide structured memory persistence for AI models. v0.2.8

155created 06/12/2024
Visit
knowledge-graph
MCP

đź“ŚOverview

Purpose: MemoryMesh aims to create and manage structured knowledge graphs for AI models, particularly enhancing interactions in text-based RPGs.

Overview: MemoryMesh serves as a local knowledge graph server that enables users to effectively organize and manage information tailored for AI applications. Its flexible design facilitates a wide range of uses, from gaming to social simulations.

Key Features:

  • Dynamic Schema-Based Tools: Automatically generates tools for data management based on user-defined schemas, streamlining the data manipulation process.

  • Intuitive Schema Design: Allows users to create schemas that inform the AI on structuring and connecting data, facilitating accurate data creation and relationship definition.

  • Metadata for AI Guidance: Uses metadata to enhance the AI's understanding of data relationships, improving context and insights into interactions.

  • Relationship Handling: Supports the definition of relationships between nodes, promoting dynamic connections and interactions within the knowledge graph.

  • Informative Feedback: Provides error messages to the AI, aiding in recognizing and correcting mistakes, which enhances the learning process.

  • Event Support: Tracks operations within the graph, offering insights into how modifications occur and affecting data flow management.

MemoryMesh

MemoryMesh is a knowledge graph server designed for AI models, focusing on text-based RPGs and interactive storytelling. It helps AI maintain consistent, structured memory across conversations, enabling richer and more dynamic interactions.

The project is based on the Knowledge Graph Memory Server from the MCP servers repository and retains its core functionality.

IMPORTANT

Since v0.2.7 the default location of schemas was changed to dist/data/schemas.
If you are updating from a previous version, make sure to move your schema files to the new location.

Quick Links

Overview

MemoryMesh is a local knowledge graph server that empowers you to build and manage structured information for AI models. While particularly well-suited for text-based RPGs, its adaptable design makes it useful in various applications, including social network simulations, organizational planning, or any scenario involving structured data.

Key Features

  • Dynamic Schema-Based Tools: Define your data structure with schemas; MemoryMesh automatically generates tools for adding, updating, and deleting data.
  • Intuitive Schema Design: Create schemas guiding the AI in generating and connecting nodes, using required fields, enumerated types, and relationship definitions.
  • Metadata for AI Guidance: Use metadata to provide context and structure to help AI understand the meaning and relationships within your data.
  • Relationship Handling: Define relationships within schemas to encourage the AI to create connections (edges) between related nodes.
  • Informative Feedback: Provides error feedback to the AI, enabling it to learn from mistakes and improve interactions.
  • Event Support: Tracks operations, providing insights into how the knowledge graph is being modified.

Nodes

Nodes represent entities or concepts within the knowledge graph. Each node has:

  • name: A unique identifier.
  • nodeType: The type of the node (e.g., npc, artifact, location), defined by your schemas.
  • metadata: An array of strings describing the node.
  • weight (Optional): A numeric value between 0 and 1 indicating the strength of the relationship, defaulting to 1.

Example Node:

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

Edges

Edges represent relationships between nodes. Each edge has:

  • from: The name of the source node.
  • to: The name of the target node.
  • edgeType: The type of relationship (e.g., owns, located_in).

Example Edge:

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

Schemas

Schemas are the heart of MemoryMesh. They define your data structure and drive automatic generation of tools.

Schema File Location

Place your schema files (.schema.json) in the dist/data/schemas directory of the built MemoryMesh project. MemoryMesh automatically detects and processes these files on startup.

Schema Structure

File name: [name].schema.json (e.g., add_npc.schema.json for an NPC schema).

  • name - Identifier for the schema and node type. Must start with add_ to be recognized.
  • description - Description for the add_<name> tool.
  • properties - Each property includes details:
    • type: string or array.
    • description: Guides the AI on the entity’s purpose.
    • required: Boolean, if true AI must provide this property.
    • enum: Array of strings, if present AI must choose one option.
    • relationship: Defines a connection to another node. If required and has a relationship, AI creates both node and edge.
      • edgeType: Type of relationship.
      • description: Guides the AI on the relationship’s purpose.
  • additionalProperties: If true, AI can add extra attributes beyond defined ones.

Example Schema (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
}

Based on this schema, MemoryMesh automatically creates:

  • add_npc: To add new NPC nodes.
  • update_npc: To modify existing NPC nodes.
  • delete_npc: To remove NPC nodes.

MemoryMesh includes 11 pre-built schemas designed for text-based RPGs, providing a ready foundation for game development.

SchemaManager Tool

MemoryMesh includes a SchemaManager tool to simplify schema creation and editing. It provides a visual interface to define data structures without writing JSON directly.

Dynamic Tools

MemoryMesh simplifies interaction with your knowledge graph through dynamic tools automatically generated from your schema definitions. This means when you define schemas, MemoryMesh creates tools tailored for that data structure.

The generated tools for each entity type are:

  • add_<entity>: Create new entities.
  • update_<entity>: Modify existing entities.
  • delete_<entity>: Remove entities.

These tools are accessible through a central hub within MemoryMesh for easy use by connected clients or AI.

Memory File

By default, data is stored in dist/data/memory.json.

Memory Viewer

The Memory Viewer is a separate web application tool to visualize and inspect the knowledge graph. It provides features including:

  • Interactive graph visualization
  • Node inspection with metadata and edges
  • Edge relationship exploration
  • Search and filtering by node or edge type
  • Table view for detailed inspection
  • Raw JSON view of the memory file
  • Stats panel showing key metrics

Memory Viewer discussion

Using the Memory Viewer

  1. Click "Select Memory File" in the Memory Viewer.
  2. Navigate and select dist/data/memory.json from your MemoryMesh project.
  3. Explore the loaded knowledge graph.

Prompt

For optimal results, use Claude's "Projects" feature with custom instructions. Example prompt:

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 others 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 appropriate for a text-based RPG.

You can instruct the AI to perform specific actions directly in chat. Experiment to find the best prompts for your use case.

Installation

Installing via Smithery

To install MemoryMesh for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install memorymesh --client claude

Prerequisites

  • Node.js: Version 18 or higher. Download from nodejs.org.
  • npm: Usually included with Node.js.
  • Claude for Desktop: Latest version from claude.ai/download.

Installation Steps

  1. Clone the Repository:

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

  2. Install Dependencies:

    npm install

  3. Build the Project:

    npm run build

    This compiles TypeScript into JavaScript in dist and copies sample data and schemas.

  4. Verify that dist/data exists with .json and .schema.json files in schemas.

  5. Configure Claude Desktop:

    Open your Claude Desktop configuration file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    Add an entry in the mcpServers section:

    "mcpServers": {
  "memorymesh": {
    "command": "node", 
    "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/memorymesh/dist/index.js"]
  }
}

    Replace /ABSOLUTE/PATH/TO/YOUR/PROJECT/ with the actual absolute path on your system.

  6. Restart Claude Desktop completely.

Verify Installation

  1. Start Claude Desktop.
  2. Open a new chat.
  3. Look for the MCP plugin icon in the top-right corner.
  4. Click the icon and confirm "memorymesh" is listed among connected servers.
  5. Check tools such as add_npc, update_npc appear, indicating server is exposing tools.

Updating

Before updating, back up the dist/data directory to avoid losing memory data.

Troubleshooting

  • Server not appearing:

    • Confirm absolute paths in claude_desktop_config.json.
    • Ensure dist directory exists with compiled JavaScript and index.js.
    • Check Claude Desktop logs:
      • macOS: ~/Library/Logs/Claude/mcp-server-memorymesh.log
      • Windows: Log folder under %AppData%\Claude.

  • Tools not showing:

    • Ensure npm run build completed without errors.
    • Confirm schema files are properly placed and named (add_[entity].schema.json).
    • Check server console or logs for initialization errors.

Advanced Configuration

Override default settings in /config/config.ts:

  • MEMORY_FILE: Path for JSON data file (default: dist/data/memory.json).
  • SCHEMAS_DIR: Path for schema files directory (default: dist/data/schemas/).

Limitations

  • Node Deletion: The AI may be hesitant to delete nodes. Encourage deletion explicitly through prompts if necessary.

Contribution

Contributions, feedback, and ideas are welcome! This project explores integrating structured data with AI reasoning capabilities and encourages community participation to extend or inspire new projects.