MemoryMesh

MemoryMesh

MemoryMesh 是一款面向 AI 模型的知识图谱服务，专注于文本类 RPG 和互动式叙事。它能帮助 AI 在多轮对话中保持连贯、有条理的记忆，从而实现更丰富、更动态的互动。

本项目基于 MCP 服务仓库中的 Knowledge Graph Memory Server，并保留了其核心功能。

重要说明

v0.3.0 更新： MCP SDK 已从 v1.0.4 更新至 v1.25.2，以符合当前的 Model Context Protocol 规范（2025-11-25）。这是一次重大更新，可兼容最新的 MCP 客户端，包括 Claude Desktop、ChatGPT、Cursor、Gemini 和 VS Code。更新后，请运行 npm install 获取新的依赖项。

从 v0.2.7 起，架构文件的默认位置已更改为 dist/data/schemas。 预计今后不会再更改此位置，但如果你从旧版本更新，请务必将架构文件移至新位置。

快速链接

• 安装
• 示例
• SchemaManager 指南讨论
• MemoryViewer 指南讨论

概述

MemoryMesh 是一款本地知识图谱服务，可帮助你为 AI 模型构建和管理结构化信息。它尤其适用于文本类 RPG，但其灵活的设计也适用于各种场景，包括社交网络模拟、组织规划，或任何涉及结构化数据的情形。

主要功能

• 动态架构工具： 使用架构定义数据结构，MemoryMesh 会自动生成用于添加、更新和删除数据的工具。
• 直观的架构设计： 创建架构来引导 AI 生成节点并建立节点间的连接；架构支持必填字段、枚举类型和关系定义。
• 为 AI 提供指导的元数据： 使用元数据提供上下文和结构，帮助 AI 理解数据的含义及其相互关系。
• 关系处理： 在架构中定义关系，引导 AI 在相关数据点（节点）之间建立连接（边）。
• 提供有效反馈： 向 AI 提供错误反馈，使其能够从错误中学习，并改进与知识图谱的交互。
• 事件支持： 事件系统会跟踪操作，帮助了解知识图谱的变更情况。

节点

节点表示知识图谱中的实体或概念。每个节点包含：

• name：唯一标识符。
• nodeType：节点的类型（例如 npc、artifact、location），由你的架构定义。
• metadata：由字符串组成的数组，用于提供节点的描述性细节。
• weight：（可选）介于 0 和 1 之间的数值，表示关系强度；默认值为 1。

节点示例：

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

边

边表示节点之间的关系。每条边都包含：

• from：源节点的名称。
• to：目标节点的名称。
• edgeType：关系类型（例如，owns、located_in）。

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

架构

架构是 MemoryMesh 的核心。它们定义数据的结构，并驱动工具的自动生成。

架构文件位置

将架构文件（.schema.json）放在构建后的 MemoryMesh 项目的 dist/data/schemas 目录中。MemoryMesh 会在启动时自动检测并处理这些文件。

架构结构

文件名：[name].schema.json。例如，对于定义“npc”的架构，文件名应为 add_npc.schema.json。

• name - 架构及记忆中节点类型的标识符。重要：架构名称必须以 add_ 开头，才能被识别。
• description - 用作 add_<name> 工具的描述，为 AI 提供上下文。（delete 和 update 工具使用通用描述）
• properties - 每个属性都包含其类型、描述和其他约束。
  • property
    • type - 支持的值为 string 或 array。
    • description - 帮助引导 AI 理解该实体的用途。
    • required - 布尔值。如果为 true，则AI 必须在创建节点时提供此属性。
    • enum - 字符串数组。如果存在，AI 必须从给定选项中选择一个。
    • relationship - 定义与另一个节点的连接。如果某个属性为必填项且具有关系，AI 将始终同时创建该节点和相应的边。
      • edgeType - 要创建的关系类型。
      • description - 帮助引导 AI 理解该关系的用途。
• additionalProperties - 布尔值。如果为 true，则允许 AI 添加超出已定义的必填或可选属性之外的额外属性。

架构示例（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
}

根据此架构，MemoryMesh 会自动创建：

• add_npc：用于添加新的 NPC 节点。
• update_npc：用于修改现有的 NPC 节点。
• delete_npc：用于移除 NPC 节点。

MemoryMesh 内置了 11 个专为文本类 RPG 设计的预构建架构，为游戏开发提供开箱即用的基础。

SchemaManager 工具

MemoryMesh 提供了 SchemaManager 工具，让架构的创建和编辑更加简单。它提供了可视化界面，让你无需直接编写 JSON 即可轻松定义数据结构。

动态工具

MemoryMesh 通过动态工具简化了与知识图谱的交互。这些工具不是手动编写的，而是直接根据架构定义自动生成。这意味着，当你使用架构定义数据结构时，MemoryMesh 会智能地创建一组针对该数据结构量身定制的工具。

**可以这样理解：**你提供一个蓝图（架构），MemoryMesh 就会根据该蓝图自动构建用于创建、修改和移除元素所需的工具。

它在幕后是如何运作的？

MemoryMesh 拥有一个智能系统，可以读取你的架构定义。它会分析你定义的结构，包括实体的属性及其关系。根据分析结果，它会为每种实体类型自动创建一组工具：

• add_<entity>： 用于创建实体新实例的工具。
• update_<entity>： 用于修改现有实体的工具。
• delete_<entity>： 用于移除实体的工具。

随后，这些工具会通过 MemoryMesh 中的中央枢纽提供，确保任何已连接的客户端或 AI 都能轻松访问和使用它们。

本质上，MemoryMesh 的动态工具系统提供了一种强大且高效的知识图谱管理方式，让你可以专注于应用的内容和逻辑，而不必操心底层的数据操作机制。

Memory file

默认情况下，数据存储在 dist/data/memory.json 中的 JSON 文件里。

Memory Viewer

Memory Viewer 是一个独立工具，旨在帮助你直观查看和检查 MemoryMesh 管理的知识图谱内容。它提供了一个易于使用的界面，用于探索节点、边及其属性。

主要功能：

• 图形可视化：以交互式节点链接图的形式查看知识图谱。
• 节点检查：选择节点以查看其 nodeType、元数据和关联的边。
• 边探索：检查节点之间的关系，包括 edgeType 和方向。
• 搜索和筛选：快速查找特定节点，或按类型筛选节点。
• 表格视图：方便你查找和检查特定节点与边，也可以一次查看所有节点和边。
• 原始 JSON 视图：查看 memory file 中的原始 JSON 数据。
• 统计面板：提供知识图谱的关键指标和信息：节点总数、边总数、节点类型和边类型。
• 搜索和筛选：按节点类型或边类型筛选，并选择显示节点、边或两者。

访问 Memory Viewer

Memory Viewer 是一个独立的 Web 应用。Memory Viewer 讨论

使用 Memory Viewer

• 选择 Memory File：在 Memory Viewer 中，点击“Select Memory File”按钮。
• 选择文件：进入你的 MemoryMesh 项目目录，然后选择 memory.json 文件（默认位于 dist/data/memory.json）。
• 探索：Memory Viewer 将加载并显示知识图谱的内容。

Memory Flow

提示词

为了获得最佳效果，请将 Claude 的“Projects”功能与自定义指令搭配使用。以下是一个你可以开始使用的提示词示例：

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.

你也可以直接在聊天中指示 AI 执行特定操作。

尝试不同的提示词，找到最适合你使用场景的方案！

示例

1. 一个简单示例，附带自定义指令。
2. 一个仅作示例的可视化示例（不属于功能的一部分）

添加几座城市、一些 NPC、城市周围几个可供探索的地点，再在某处藏一两件神器

安装

前置条件

• Node.js： 版本 18 或更高。你可以从 nodejs.org 下载。
• npm： 通常随 Node.js 一同提供。
• Claude for Desktop： 确保已从 claude.ai/download 安装最新版本。

安装步骤

1. 克隆仓库：

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

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

   此命令会将 TypeScript 代码编译为 JavaScript，并放入 dist 目录，同时也会将示例架构和数据文件复制到该目录中。

4. 验证文件复制（可选）：

   • 构建过程应会自动将 data 文件夹复制到 dist。
   • 检查 dist/data 是否存在且包含 .json 文件。还要确认 dist/data/schemas 是否存在且包含 .schema.json 文件。

5. 配置 Claude Desktop：

   打开 Claude Desktop 配置文件：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json
   • 在 mcpServers 部分中为 memorymesh 添加一项。可从以下配置选项中选择一个：

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

   • 将 /ABSOLUTE/PATH/TO/YOUR/PROJECT/ 替换为 memorymesh 项目目录的实际绝对路径。
   • 示例（macOS）：

     "command": "node",
     "args": ["/Users/yourusername/Projects/memorymesh/dist/index.js"]
     

   • 示例（Windows）：

     "command": "node",
     "args": ["C:\\Projects\\memorymesh\\dist\\index.js"]
     

6. 重启 Claude Desktop： 完全重启 Claude Desktop，使更改生效。

验证安装

1. 启动 Claude Desktop。
2. 打开一个新聊天。
3. 在右上角查找 MCP 插件图标 。如果该图标存在，说明配置可能正确。
4. 点击 图标。你应该会在已连接服务列表中看到“memorymesh”。
5. 点击 图标。如果看到列出的工具（例如，add_npc、update_npc 等），说明服务正在正常运行并正确提供工具。

更新

更新前，请务必备份 dist/data 目录，以免丢失记忆数据。

故障排查

• Claude 中未显示服务：

  • 再次检查 claude_desktop_config.json 中的路径。确保它们是正确的绝对路径。
  • 确认 dist 目录存在，并包含已编译的 JavaScript 文件，包括 index.js。
  • 检查 Claude Desktop 日志中的错误：
    • macOS： ~/Library/Logs/Claude/mcp-server-memorymesh.log（以及 mcp.log）
    • Windows：（可能位于 %AppData%\Claude 下的 Logs 文件夹中）

• 未显示工具：

  • 确保 npm run build 命令已成功完成且未报错。
  • 确认架构文件已正确放置在 dist/data/schemas 中，并遵循正确的命名约定（add_[entity].schema.json）。
  • 检查服务的控制台输出或日志，查看初始化期间是否有错误。

高级配置

MemoryMesh 提供了多种方式，可在基本设置之外自定义其行为：

变量

你可以使用 /config/config.ts 覆盖默认设置

• MEMORY_FILE：指定用于存储知识图谱数据的 JSON 文件路径。（默认值：dist/data/memory.json）
• SCHEMAS_DIR：架构文件目录的路径。（默认值：dist/data/schemas/memory.json）

局限性

1. 删除节点： AI 可能会犹豫是否从知识图谱中删除节点。如有需要，可通过提示词鼓励它。

2. 知识冲突： MemoryMesh 当前采用“后写入者胜出”的方式处理数据。如果针对同一实体提供了相互冲突的信息，最新更新会覆盖先前的值。以下是管理冲突信息的策略：

   当前方法：

   • 使用元数据追踪来源： 添加 "Source: Character testimony" 或 "Source: Official records" 之类的元数据条目，追踪信息来源。
   • 使用时间元数据： 在元数据中包含时间戳或叙事时间标记（例如 "As of Chapter 3"），追踪信息的有效时间。
   • 为不同观点创建单独的节点： 对于主观或有争议的信息，创建代表不同观点的单独节点（例如，rumor_about_villain 与 truth_about_villain）。
   • 使用边权重： 利用边上可选的 weight 属性（取值范围为 0-1）表示关系的置信度或可靠性。

   示例——追踪不确定信息：

   {
     "name": "VillainOrigin_Rumor",
     "nodeType": "information",
     "metadata": [
       "Source: Tavern gossip",
       "Reliability: Low",
       "Claims: Villain came from the northern mountains"
     ]
   }
   

   未来考虑： 对于需要复杂冲突解决的应用，可以考虑实现一个自定义层，用于：

   • 保留节点变更的版本历史
   • 追踪每条信息的来源
   • 为断言设置置信度分数
   • 支持事实的时间有效期

贡献

欢迎贡献、反馈和创意！ 本项目是一次个人探索，旨在将结构化数据与 AI 推理能力相结合。欢迎贡献、反馈和创意，助力项目进一步发展或启发新项目。