Home

Awesome

MemoryMesh

License: MIT smithery badge

MemoryMesh is a knowledge graph server designed for AI models, with a focus 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.

Why MemoryMesh?

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 for various applications, including social network simulations, organizational planning, or any scenario involving structured data.

Key Features

Nodes

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

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": "Aragorn",
  "to": "Andúril",
  "edgeType": "owns"
}

Schemas

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

Schema File Location

Place your schema files (.schema.json) in the dist/config/schemas directory of your built MemoryMesh project. MemoryMesh will automatically detect and process these files on startup.

Schema Structure

File name: [name].schema.json. For example, for a schema defining an 'npc', the filename would be add_npc.schema.json.

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:

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

SchemaManager Tool

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

<img width="370" alt="image" src="https://github.com/user-attachments/assets/e8f0c808-2ff6-48da-ac7c-cf51aebde7b8">

Dynamic Tools

MemoryMesh simplifies interaction with your knowledge graph through dynamic tools. These tools are not manually coded but are automatically generated directly from your schema definitions. This means that when you define the structure of your data using schemas, MemoryMesh intelligently creates a set of tools tailored to work with that specific data structure.

Think of it like this: You provide a blueprint (the schema), and MemoryMesh automatically constructs the necessary tools to build, modify, and remove elements based on that blueprint.

How does it work behind the scenes?

MemoryMesh has an intelligent system that reads your schema definitions. It analyzes the structure you've defined, including the properties of your entities and their relationships. Based on this analysis, it automatically creates a set of tools for each entity type:

These tools are then made available through a central hub within MemoryMesh, ensuring they can be easily accessed and used by any connected client or AI.

In essence, MemoryMesh's dynamic tool system provides a powerful and efficient way to manage your knowledge graph, freeing you to focus on the content and logic of your application rather than the underlying mechanics of data manipulation.

Memory file

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

Memory Viewer

The Memory Viewer is a separate tool designed to help you visualize and inspect the contents of the knowledge graph managed by MemoryMesh. It provides a user-friendly interface for exploring nodes, edges, and their properties.

Key Features:
Accessing the Memory Viewer

The Memory Viewer is a standalone web application. Memory Viewer discussion

Using the Memory Viewer

Memory Flow

image

Prompt

For optimal results, use Claude's "Projects" feature with custom instructions. Here's an example of a prompt you can start with:

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.

Trivial Example Interactions:

User: "Start a new game. I want to play a human ranger named Aragorn."

(AI - behind the scenes): Use add_player_character to create a node for Aragorn with the appropriate metadata.

(AI - response): "You begin your adventure as Aragorn, a skilled human ranger. What is your first move?"

User: "Create a new city called 'Minas Tirith'."

(AI - behind the scenes): Use add_city to create a node for Minas Tirith.

(AI - response): "The great city of Minas Tirith has been added to the world. It is known for..."

User: "Aragorn is now in Minas Tirith."

(AI - behind the scenes): Use update_player_character to update Aragorn's currentLocation to Minas Tirith.

(AI - response): "Aragorn has arrived in Minas Tirith. What would you like to do here?"

You can also instruct the AI to perform specific actions directly in the chat, such as:

"Give the player an artifact called the 'One Ring'."

"Make the NPC 'Gandalf' a wizard."

"Update the memory with the latest events." (Useful before switching to a new chat)

Experiment with different prompts to find what works best for your use case!

Example

  1. A simple example with custom instructions.
  2. An example for the sake of example, with visualization (NOT part of the functionality)

Add a couple of cities, some npcs, couple locations around the city to explore, hide an artifact or two somewhere

image

Installation

Prerequisites

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 command compiles the TypeScript code into JavaScript in the dist directory and copies sample schema and data files into it as well.

  4. Verify File Copy (Optional):

    • The build process should automatically copy the config and data folders to dist.
    • Check that dist/config and dist/data exist and contain .json files.

  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 for memorymesh to the mcpServers section. You can choose one of the following configuration options:
    "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 to your memorymesh project directory.
    • Example (macOS): 
      "command": "node",
"args": ["/Users/yourusername/Projects/memorymesh/dist/index.js"]
    • Example (Windows): 
      "command": "node",
"args": ["C:\\Projects\\memorymesh\\dist\\index.js"]

  6. Restart Claude Desktop: Completely restart Claude Desktop for the changes to take effect.

Verify Installation

  1. Start Claude Desktop.
  2. Open a new chat.
  3. Look for the MCP plugin icon <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg"/> in the top-right corner. If it's there, your configuration is likely correct.
  4. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg"/> icon. You should see "memorymesh" in the list of connected servers.
  5. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg"/> icon. If you see tools listed (e.g., add_npc, update_npc, etc.), your server is working and exposing tools correctly.

Troubleshooting

Installing via Smithery

To install MemoryMesh for Claude Desktop automatically via Smithery:

npx @smithery/cli install memorymesh --client claude

MemoryMesh on glama.ai

<a href="https://glama.ai/mcp/servers/kf6n6221pd"> <img width="380" height="200" src="https://glama.ai/mcp/servers/kf6n6221pd/badge" /> </a>

Advanced Configuration

MemoryMesh offers several ways to customize its behavior beyond the basic setup:

Variables

You can override default settings using in /config/config.ts

Limitations

  1. Node Deletion: The AI may be hesitant to delete nodes from the knowledge graph. Encourage it through prompts if needed.

Contribution

Contributions, feedback, and ideas are welcome! This project is a personal exploration into integrating structured data with AI reasoning capabilities. Contributions, feedback, and ideas are welcome to push it further or inspire new projects.