MemoryMesh

TypeScript GitHub Stars

MemoryMesh 是一个专为 AI 模型设计的知识图谱服务器，特别关注基于文本的 RPG 和交互式叙事。它帮助 AI 在对话中保持一致、结构化的记忆，从而实现更丰富、更动态的交互。

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

重要提示

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

快速链接

概述

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": [
        "种族: 人类",
        "职业: 游侠",
        "技能: 追踪、剑术",
        "所属组织: 环球使者团"
      ]
    }

边

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

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": "添加 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": "located_in",
        "description": "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 的动态工具系统提供了一种强大且高效的方式来管理您的知识图谱，让您可以专注于应用的内容和逻辑，而不是数据操作的底层机制。

内存文件

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

内存查看器

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

主要功能:

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

访问内存查看器

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

使用内存查看器

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

内存流

提示

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

您是一个帮助管理基于文本的 RPG 知识图谱的 AI 助手。您可以使用以下工具：add_npc、update_npc、delete_npc、add_location、update_location、delete_location，以及管理游戏世界的其他工具。

当用户提供输入时，首先使用您的可用工具更新知识图谱。然后，以适合基于文本的 RPG 的方式回应。

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

尝试不同的提示，找到最适合您用例的方案！

示例

简单示例带有自定义指令。
一个为了示例而示例的示例，带可视化 (不属于功能功能)。

添加几个城市，一些 NPC，城市周围一些可探索的位置，隐藏几个宝藏

安装

通过 Smithery 安装

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

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

前置条件

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

安装步骤

克隆仓库:

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

安装依赖:
```
npm install
```
构建项目:
```
npm run build
```

此命令将 TypeScript 代码编译为 JavaScript，并复制到 dist 目录中的示例模式和数据文件。

验证文件复制（可选）:
- 构建过程应自动将 data 文件夹复制到 dist。
- 检查 dist/data 是否存在，并包含 .json 文件。同时验证 dist/data/schemas 是否存在并包含 .schema.json 文件。
配置 Claude Desktop:

打开您的 Claude Desktop 配置文件：

*   **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
*   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
*   在 `mcpServers` 部分添加 `memorymesh` 的条目。您可以选择 **一个** 以下配置选项：

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

*   将 `/ABSOLUTE/PATH/TO/YOUR/PROJECT/` 替换为您 `memorymesh` 项目目录的**实际绝对路径**。
*   **示例 (macOS):**
    ```json
    "command": "node",
    "args": ["/Users/yourusername/Projects/memorymesh/dist/index.js"]
    ```
*   **示例 (Windows):**
    ```json
    "command": "node",
    "args": ["C:\\Projects\\memorymesh\\dist\\index.js"]
    ```

6. 重启 Claude Desktop: 完全重启 Claude Desktop 以使更改生效。

验证安装

启动 Claude Desktop。
打开新聊天。
查找右上角的 MCP 插件图标。如果它在那里，您的配置很可能正确。
点击图标。您应该看到列表中的 "memorymesh"。
点击图标。如果您看到列出了工具（例如，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)

限制

节点删除: AI 可能不太愿意从知识图谱中删除节点。如果需要，通过提示鼓励它。

CheMiguel23/MemoryMesh

星标增长

证据时间轴