技术文档摘要

MemoryMesh

MemoryMesh 是一个专为 AI 模型设计的知识图谱服务器，特别适用于基于文本的角色扮演游戏（RPG）和互动叙事。它帮助 AI 在对话中保持一致且结构化的记忆，从而实现更丰富和动态的交互。

该项目基于 MCP 服务器仓库中的 知识图谱内存服务器，并保留了其核心功能。

<a href="https://glama.ai/mcp/servers/kf6n6221pd"><img width="380" height="200" src="https://glama.ai/mcp/servers/kf6n6221pd/badge" alt="MemoryMesh MCP 服务器" /></a>

重要事项

自 v0.2.7 版本起，默认的模式文件位置已更改为 dist/data/schemas。 预计未来不会更改此位置，但如果您是从旧版本升级，请确保将您的模式文件移动到新位置。

快速链接

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

概览

MemoryMesh 是一个本地知识图谱服务器，可帮助您构建和管理用于 AI 模型的结构化信息。虽然特别适合基于文本的角色扮演游戏，但其灵活的设计使其在各种应用中都非常有用，包括社交网络模拟、组织规划或任何涉及结构化数据的场景。

主要特性

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

节点

节点代表知识图谱中的实体或概念。每个节点都有：

• name: 唯一标识符。
• nodeType: 节点类型（例如，npc，artifact，location），由您的模式定义。
• metadata: 包含描述性细节的字符串数组。
• weight: （可选）表示关系强度的介于 0 和 1 之间的数值，默认值为 1。

示例节点：

    {
      "name": "Aragorn",
      "nodeType": "player_character",
      "metadata": [
        "种族: 人类",
        "职业: 游侠",
        "技能: 追踪, 剑术",
        "隶属: 魔戒远征队"
      ]
    }

边

边代表节点之间的关系。每个边都有：

• from: 源节点的名称。
• to: 目标节点的名称。
• edgeType: 关系类型（例如，拥有，位于）。

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

模式

模式是 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": "向内存添加 NPC 的模式" ,
  "properties": {
    "name": {
      "type": "string",
      "description": "NPC 的唯一标识符",
      "required": true
    },
    "race": {
      "type": "string",
      "description": "NPC 的物种或种族",
      "required": true,
      "enum": [
        "人类",
        "精灵",
        "矮人",
        "兽人",
        "哥布林"
      ]
    },
    "currentLocation": {
      "type": "string",
      "description": "NPC 当前的位置",
      "required": true,
      "relationship": {
        "edgeType": "位于",
        "description": "NPC 当前的位置"
      }
    }
  },
  "additionalProperties": true
}

基于此模式，MemoryMesh 自动创建：

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

MemoryMesh 包含 11 个预建模式，专为基于文本的角色扮演游戏设计，提供了游戏开发的现成基础。

SchemaManager 工具

MemoryMesh 包含一个 SchemaManager 工具，简化模式的创建和编辑。它提供了一个可视化界面，使您可以轻松地定义数据结构而无需直接编写 JSON。

<img width="370" alt="image" src="https://gips0.baidu.com/it/u=2819226639,2497952680&fm=3081&app=3081&f=PNG?w=1280&h=1897">

动态工具

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

可以这样理解： 您提供蓝图（模式），MemoryMesh 自动构造必要的工具来根据该蓝图创建、修改和移除元素。

背后的工作原理？

MemoryMesh 有一个智能系统读取您的模式定义。它分析您定义的结构，包括实体的属性及其关系。基于此分析，它自动为每种实体类型创建一组工具：

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

然后，这些工具通过 MemoryMesh 中的一个中心枢纽提供，确保它们可以被任何连接的客户端或 AI 轻松访问和使用。

本质上，MemoryMesh 的动态工具系统提供了一种强大且高效的方式来管理您的知识图谱，让您能够专注于应用程序的内容和逻辑，而不是数据操作的基础机制。

记忆文件

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

记忆查看器

记忆查看器是一个独立的工具，旨在帮助您可视化和检查由 MemoryMesh 管理的知识图谱的内容。它提供了一个用户友好的界面，用于探索节点、边及其属性。

主要特性：

• 图形可视化：作为交互式的节点链接图查看知识图谱。
• 节点检查：选择节点以查看其 nodeType、metadata 和连接的边。
• 边探索：检查节点之间的关系，包括 edgeType 和方向。
• 搜索和过滤：快速找到特定节点或按类型过滤它们。
• 表格视图：允许您轻松找到和检查特定节点和边，或者一次性查看所有内容。
• 原始 JSON 视图：允许您查看来自记忆文件的原始 JSON 数据。
• 统计面板：提供关于知识图谱的关键指标和信息：总节点数、总边数、节点类型和边类型。
• 搜索和过滤：允许您按节点类型或边类型进行过滤，并选择是否显示节点、边或两者。

访问记忆查看器

记忆查看器是一个独立的 Web 应用程序。记忆查看器讨论

使用记忆查看器

• 选择记忆文件：在记忆查看器中，点击“选择记忆文件”按钮。
• 选择文件：导航到您的 MemoryMesh 项目目录并选择 memory.json 文件（默认位于 dist/data/memory.json）。
• 探索：记忆查看器将加载并显示您的知识图谱的内容。

记忆流

提示

为了获得最佳效果，使用 Claude 的“项目”功能并附带自定义指令。以下是一个您可以开始使用的提示示例：

您是一位帮助管理基于文本的角色扮演游戏的知识图谱的 AI 助手。您有权访问以下工具：add_npc, update_npc, delete_npc, add_location, update_location, delete_location，以及其他用于管理游戏世界的工具。

当用户提供输入时，首先使用可用工具更新知识图谱。然后，以适合基于文本的角色扮演游戏的方式作出回应。

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

尝试不同的提示，找到最适合您使用情况的方法！

示例

1. 一个 简单示例 带有自定义指令。
2. 一个示例，仅用于示例目的，带有可视化（不包含在功能中）

添加几个城市，一些 NPC，几个城市周围的地点可供探索，在某个地方隐藏一两个神器

安装

通过 Smithery 安装

要通过 Smithery 自动安装 MemoryMesh 到 Claude Desktop：

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

先决条件

• 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 代码编译到 dist 目录中的 JavaScript，并复制样本模式和数据文件到其中。

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 插件图标 <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg"/>。如果它在那里，您的配置很可能正确。
4. 点击 <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg"/> 图标。您应该看到“memorymesh”在已连接服务器列表中。
5. 点击 <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg"/> 图标。如果您看到列出的工具（如 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 可能对从知识图谱中删除节点犹豫不决。如有需要，可通过提示鼓励它。

贡献

欢迎贡献、反馈和想法！ 这个项目是对将结构化数据与 AI 推理能力相结合的个人探索。欢迎贡献、反馈和想法，以推动其进一步发展或启发新的项目。