Skip to content
Projects

CheMiguel23/MemoryMesh has 356 GitHub stars and 50 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-17 02:29 UTC. Last push 2026-11-14.

How these counts are measured

Measured star growth

in 24h
+1
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

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

Developer Tools

README.md

Original

MemoryMesh

Release TypeScript License: MIT GitHub Stars

MemoryMesh is an MCP server that gives AI models a structured, long-term memory in the form of a knowledge graph. You describe the kinds of things you want to remember in small schema files (people, projects, characters, locations, books...), and MemoryMesh turns each one into tools the AI uses to add, update and delete that information, linking related items as it goes.

It works for anything you can describe as things and the connections between them: a text-based RPG world, the people and teams at your company, a personal CRM, or your reading notes.

Based on the Knowledge Graph Memory Server from the MCP servers repository.

MemoryMesh MCP server

MseeP.ai Security Assessment

How it works

The memory is a graph of nodes and edges:

  • A node is a thing: {"name": "Mara", "nodeType": "npc", "metadata": ["role: Blacksmith", "status: injured"]}
  • An edge is a connection between two nodes: {"from": "Mara", "to": "Riverton", "edgeType": "located_in"}. Edges can have an optional weight from 0 to 1 (strength or confidence; treated as 1 when not set).

A schema describes one type of node. For a schema named add_npc, MemoryMesh creates three tools:

  • add_npc creates an NPC. Fields marked as relationships also create edges to the nodes they name.
  • update_npc changes the fields you pass and keeps everything else. Passing an empty list ([]) clears a field, and passing metadata replaces the whole list.
  • delete_npc removes the NPC and its edges.

Every call is all-or-nothing: if anything is wrong (a missing required field, a link to a node that doesn't exist), nothing is saved, and the AI gets a clear error it can act on.

Schema format

Each schema is a JSON file ending in .schema.json. This is the npc example that ships with MemoryMesh:

{
  "name": "add_npc",
  "description": "Add a new character (NPC) to the knowledge graph",
  "properties": {
    "name": { "type": "string", "description": "The character's unique name", "required": true },
    "description": { "type": "string", "description": "Who the character is", "required": true },
    "status": { "type": "string", "description": "Current condition", "enum": ["alive", "injured", "dead", "missing"] },
    "traits": { "type": "array", "description": "Personality traits" },
    "currentLocation": {
      "type": "string",
      "description": "Where the character is now",
      "relationship": { "edgeType": "located_in", "description": "Where the character is now (must already exist)" }
    }
  },
  "additionalProperties": true
}
Key Meaning
name Must start with add_. The rest becomes the node type and tool suffix (npc → add_npc, update_npc, delete_npc).
description Description of the add_ tool, shown to the AI.
properties The fields. Each has a type (string or array) and a description, plus optionally:
↳ required true if the AI must provide this field. Keep this to a minimum, or the AI will invent values it doesn't know.
↳ enum A list of allowed values. Anything else is rejected.
↳ relationship Creates an edge (edgeType) to each node named in this field. Those nodes must already exist. Updating the field replaces every edge of that edgeType going out from the node, so give each relationship field its own edgeType.
additionalProperties true (default) saves fields not listed above as extra metadata; false rejects them.

If a schema file is invalid, MemoryMesh skips it, logs the reason, and starts with the others. It also logs a warning for a schema that loads but probably won't behave as you expect, such as two relationship fields sharing an edgeType.

The SchemaManager lets you create and edit schemas visually (guide).

SchemaManager

Example schema sets

MemoryMesh ships with two small examples, npc and location. Ready-made sets for different uses are shared in Discussions:

Feel free to share your own.

Built-in tools

These are always available, whatever schemas you use:

Tool Purpose
read_graph Return the whole graph
search_nodes Find nodes that contain every word of the query in their name, type or metadata, with their direct neighbours
open_nodes Return specific nodes by name, with their direct neighbours
add_nodes, update_nodes, delete_nodes Work with nodes of any type. update_nodes can also rename a node (newName): its edges, and metadata of linked nodes that names it, follow
add_edges, update_edges, delete_edges Work with edges
add_metadata, delete_metadata Add or remove individual metadata entries

Installation

You need Node.js 22 or newer and an MCP client such as Claude Desktop.

  1. Download and build MemoryMesh:

    git clone https://github.com/CheMiguel23/MemoryMesh.git
    
    cd MemoryMesh
    
    npm install
    

    npm install also builds the project into dist/.

  2. Add MemoryMesh to Claude Desktop. Open Settings → Developer → Edit Config and add:

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

    On Windows, double every backslash: "C:\\Projects\\MemoryMesh\\dist\\index.js".

  3. Fully quit and restart Claude Desktop. MemoryMesh and its tools (add_npc, read_graph, ...) appear in the tools menu of the chat box.

Updating

git pull
npm install

Then restart your MCP client. Updating keeps your memory file and any schemas you edited.

If your memory file is still in dist/data/memory.json (the old default), MemoryMesh keeps using it but logs a warning, because deleting dist/ would delete your memory. To fix it, quit your MCP client and move the file to .memorymesh/memory.json in your home folder.

Configuration

Environment variable What it sets Default
MEMORYMESH_MEMORY_FILE Path of the memory file .memorymesh/memory.json in your home folder
MEMORYMESH_SCHEMAS_DIR Folder containing .schema.json files dist/data/schemas

Set them in your Claude Desktop config:

"memorymesh": {
  "command": "node",
  "args": ["/ABSOLUTE/PATH/TO/MemoryMesh/dist/index.js"],
  "env": {
    "MEMORYMESH_MEMORY_FILE": "/ABSOLUTE/PATH/TO/my-project/memory.json",
    "MEMORYMESH_SCHEMAS_DIR": "/ABSOLUTE/PATH/TO/my-project/schemas"
  }
}

Keeping your schemas and memory in a folder of your own keeps them separate from the MemoryMesh code. You can also run several MemoryMesh entries with different folders, for example one per campaign or project. Several MCP clients can also share one memory file: each change locks the file briefly, so they don't overwrite each other.

Docker: docker build -t memorymesh . then docker run -i --rm -v memorymesh-data:/data memorymesh. The memory file is /data/memory.json inside the container.

Viewing your memory

The memory file stores one JSON object per line. The MemoryViewer displays it as a searchable table with stats (guide): open it in Chrome or Edge, click Select Memory File, and pick your memory.json. Its path is in the first lines of the log. The default .memorymesh folder is hidden on macOS and Linux: press Cmd+Shift+. in the macOS file dialog to show it.

Tips

  • Tell the AI what the memory is for, for example in a Claude Project's instructions: "Use the memorymesh tools to record every person, team and project I mention, and check the graph before answering questions about them."
  • The AI can be hesitant to delete things. Ask explicitly when you want something removed.
  • When information conflicts, the latest update wins. To keep both versions, record the source or date in metadata ("source: tavern gossip", "as of: chapter 3"), or store competing claims as separate nodes.

Troubleshooting

  • MemoryMesh doesn't appear in Claude Desktop: check that the path in the config is absolute and points to dist/index.js (with doubled backslashes on Windows), and that npm install finished without errors.
  • Tools are missing: check that your schema files end in .schema.json and that their name starts with add_.
  • Check the log, where MemoryMesh reports which schemas it loaded and why any were skipped:
    • macOS: ~/Library/Logs/Claude/mcp-server-memorymesh.log
    • Windows: the logs folder inside %APPDATA%\Claude

Development

npm install     # also builds
npm test        # runs the test suite
npm run watch   # recompiles on change
File Purpose
src/index.ts Entry point: loads schemas and starts the server on stdio
src/server.ts Lists tools and routes each tool call to its handler
src/tools.ts Definitions of the built-in tools
src/schemas.ts Loads schema files and implements the generated add_/update_/delete_ tools
src/graph.ts The graph operations themselves, with input validation
src/store.ts Reads and writes the memory file, one change at a time
src/config.ts Paths and version
src/types.ts Shared types

Contributing

Contributions, feedback, ideas and schema sets are welcome. Open an issue, start a discussion, or send a pull request.