# myKGM

**Repository Path**: openminds/mykgm

## Basic Information

- **Project Name**: myKGM
- **Description**: 基于知识图谱的持久化记忆 MCP 服务器。让 AI 助手能够在对话中记住用户信息，跨会话保持记忆。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-03
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: KGM, MCP

## README

# Knowledge Graph Memory Server

基于知识图谱的持久化记忆 MCP 服务器。让 AI 助手能够在对话中记住用户信息，跨会话保持记忆。

## 核心概念

### 实体 (Entities)
实体是知识图谱中的主要节点，每个实体包含：
- 唯一名称（标识符）
- 实体类型（如 "person"、"organization"、"event"）
- 观察列表

```json
{
  "name": "张三",
  "entityType": "person",
  "observations": ["会说流利的中文", "偏好早起工作"]
}
```

### 关系 (Relations)
关系定义实体之间的有向连接，始终使用主动语态描述实体间的交互关系。

```json
{
  "from": "张三",
  "to": "北京科技公司",
  "relationType": "works_at"
}
```

### 观察 (Observations)
观察是关于实体的离散信息片段：
- 以字符串形式存储
- 附加到特定实体
- 可独立添加或删除
- 建议保持原子性（每条观察对应一个事实）

---

## 环境要求

- **Node.js**: >= 18.x
- **操作系统**: Windows / macOS / Linux

---

## 本地部署

### 1. 安装依赖

```bash
npm install
```

### 2. 构建项目

```bash
npm run build
```

构建完成后，产物位于 `dist/index.js`。

### 3. 创建数据目录

服务器通过 `fs.writeFile` 写入记忆文件，不会自动创建父目录。请先创建数据存储目录：

```bash
# Windows PowerShell
New-Item -ItemType Directory -Force -Path "E:\mykgm_data"

# macOS / Linux
mkdir -p /path/to/memory_data
```

### 4. 配置 Claude Desktop

在 Claude Desktop 的 `claude_desktop_config.json` 中添加以下配置：

```json
{
  "mcpServers": {
    "kgm-server": {
      "command": "node",
      "args": ["E:/myworkspace/mykgm/dist/index.js"],
      "env": {
        "MEMORY_FILE_PATH": "E:/mykgm_data/memory.jsonl"
      }
    }
  }
}
```

#### 环境变量说明

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `MEMORY_FILE_PATH` | 记忆存储文件路径 | `dist/memory.jsonl` |

**路径解析规则：**
- **绝对路径**：直接使用（如 `E:/mykgm_data/memory.jsonl`）
- **相对路径**：相对于 `dist/index.js` 所在目录解析
- **未设置**：默认使用 `dist/memory.jsonl`

#### 兼容旧数据格式

如果之前使用的是 `memory.json`（JSON 格式），首次启动时会自动迁移为 `memory.jsonl`（JSONL 格式），无需手动操作。

---

## API 工具

### 变更类工具

#### `create_entities`
在知识图谱中创建多个新实体。

- **输入**: `entities`（对象数组）
  - `name` (string): 实体标识符
  - `entityType` (string): 类型分类
  - `observations` (string[]): 关联观察
- **行为**: 忽略已存在的同名实体

#### `create_relations`
在实体之间创建多个新关系。

- **输入**: `relations`（对象数组）
  - `from` (string): 源实体名称
  - `to` (string): 目标实体名称
  - `relationType` (string): 主动语态的关系类型
- **行为**: 跳过重复关系

#### `add_observations`
向已有实体添加新观察。

- **输入**: `observations`（对象数组）
  - `entityName` (string): 目标实体
  - `contents` (string[]): 要添加的新观察
- **行为**: 返回每个实体新增的观察；若实体不存在则报错

#### `delete_entities`
删除实体及其关联关系。

- **输入**: `entityNames` (string[])
- **行为**: 级联删除关联关系；若实体不存在则静默跳过

#### `delete_observations`
从实体中删除特定观察。

- **输入**: `deletions`（对象数组）
  - `entityName` (string): 目标实体
  - `observations` (string[]): 要删除的观察
- **行为**: 若观察不存在则静默跳过

#### `delete_relations`
从图谱中删除特定关系。

- **输入**: `relations`（对象数组）
  - `from` (string): 源实体名称
  - `to` (string): 目标实体名称
  - `relationType` (string): 关系类型
- **行为**: 若关系不存在则静默跳过

### 查询类工具

#### `read_graph`
读取完整的知识图谱。

- **输入**: 无
- **输出**: 完整的图谱结构，包含所有实体和关系

#### `search_nodes`
根据查询搜索图谱中的节点。

- **输入**: `query` (string)
- **搜索范围**:
  - 实体名称
  - 实体类型
  - 观察内容
- **输出**: 匹配的实体及其关联关系

#### `open_nodes`
按名称检索特定节点。

- **输入**: `names` (string[])
- **输出**:
  - 请求的实体
  - 涉及这些实体的关系
- **行为**: 若节点不存在则静默跳过

### 资源

#### `knowledge-graph` (`memory://knowledge-graph`)
以 MCP 资源形式提供完整的知识图谱。

- **MIME 类型**: `application/json`
- **数据格式**: 与 `read_graph` 工具返回值相同
- **实时更新**: 任何变更类工具操作后，已订阅的客户端会收到 `notifications/resources/updated` 通知

---

## 使用建议

### 系统提示词示例

以下是聊天个性化场景的提示词示例，可用于 Claude 的自定义指令：

```
每次交互遵循以下步骤：

1. 用户识别：
   - 假设与 default_user 交互
   - 主动尝试识别用户身份

2. 记忆检索：
   - 每次开始对话时说"正在读取记忆..."，并从知识图谱中检索所有相关信息
   - 将知识图谱称为"我的记忆"

3. 记忆记录：
   - 对话中注意收集以下类别信息：
     a) 基本信息（年龄、性别、所在地、职位、教育背景等）
     b) 行为偏好（兴趣、习惯等）
     c) 沟通偏好（沟通风格、首选语言等）
     d) 目标规划（目标、抱负等）
     e) 人际关系（个人和职业关系，最多3度分离）

4. 记忆更新：
   - 收集到新信息时，执行以下操作：
     a) 为重复出现的组织、人物和重要事件创建实体
     b) 使用关系将它们连接到现有实体
     c) 将事实存储为观察
```

---

## 数据格式

记忆数据以 JSONL 格式存储（每行一个 JSON 对象）：

```
{"type":"entity","name":"张三","entityType":"person","observations":["会说流利的中文","偏好早起工作"]}
{"type":"entity","name":"北京科技公司","entityType":"organization","observations":["成立于2015年"]}
{"type":"relation","from":"张三","to":"北京科技公司","relationType":"works_at"}
```

---

## 故障排查

| 问题 | 解决方案 |
|------|----------|
| `ENOENT: no such file or directory` | 确保 `MEMORY_FILE_PATH` 的父目录已创建 |
| 端口被占用 | 本服务器使用 stdio 协议，无需端口 |
| 权限不足 | 检查数据目录的读写权限 |
| 旧版 `memory.json` 无法读取 | 首次启动会自动迁移为 `memory.jsonl` |

---

## 技术栈

- **运行时**: Node.js 18+
- **语言**: TypeScript 5.6+
- **MCP SDK**: `@modelcontextprotocol/sdk` ^1.30.0
- **数据校验**: Zod ^3.24.1
- **存储**: JSONL 文件

## 许可证

本 MCP 服务器基于 MIT 许可证开源。