# TrulyMEM 人设图机制

本文档详细说明 TrulyMEM 的人设图（Persona Graph）工作机制。

## 概述

人设图是 TrulyMEM 的核心机制之一，用于维护 AI 的角色、性格、语气等属性。与传统 AI 不同，TrulyMEM 的人设是可持久化、可动态切换的，存储在图数据库中。

## 核心概念

### 人设节点（PersonaNode）

存储 AI 的角色属性：

| 属性 | 说明 | 示例 |
|------|------|------|
| 扮演角色 | AI 当前扮演的角色 | 猫娘、教师、助手 |
| 说话风格 | 语气特点 |可爱、严肃、专业 |
| 性格特点 | 性格描述 | 活泼、严谨、耐心 |
| 口头禅 | 习惯用语 | 喵呜~、明白了 |
| 背景故事 | 角色背景设定 | 来自星海的猫娘 |

### 人设边（Edge）

| 边类型 | 说明 | 连接关系 |
|------|------|----------|
| `HAS_PERSONA` | 人设 | AI → PersonaNode |

---

## 强制查询机制

### 每轮对话必须执行

根据 `system_prompt.md`，每轮对话**必须**首先查询人设图：

```python
memory_recall(
    query_intent="AI,人设,角色,性格,语气,说话风格",
    depth=2
)
```

**处理逻辑：**
- 找到人设 → 严格按照人设的语气、风格、特征回复
- 未找到 → 使用默认 TrulyMEM 身份

### 人设优先级

- **人设优先级 > 默认身份**
- 每句话都符合人设的语气、风格、特征
- 绝不主动跳出角色，除非用户明确要求

---

## 工具

### persona_update

更新人设。修改 AI 的角色、性格、语气等属性。

**参数：**

| 参数 | 类型 | 说明 | 必填 |
|------|------|------|------|
| `attributes` | array | 人设属性列表 | ✅ |
| `mode` | string | replace=替换, merge=合并 | ❌ |

**attributes 子参数：**

| 子参数 | 说明 |
|------|------|
| `attribute` | 属性名（扮演角色、说话风格、性格特点、口头禅、背景故事） |
| `value` | 属性值 |

**示例 - 切换为猫娘角色：**

```python
persona_update(
    attributes=[
        {"attribute": "扮演角色", "value": "猫娘"},
        {"attribute": "说话风格", "value": "可爱、卖萌、使用'喵'作为语气词"},
        {"attribute": "性格特点", "value": "活泼、粘人、忠诚"}
    ],
    mode="replace"
)
```

**示例 - 添加新属性（保留现有属性）：**

```python
persona_update(
    attributes=[
        {"attribute": "口头禅", "value": "喵呜~"}
    ],
    mode="merge"
)
```

**示例 - 设置专业角色：**

```python
persona_update(
    attributes=[
        {"attribute": "扮演角色", "value": "Python专家"},
        {"attribute": "说话风格", "value": "专业、简洁、代码示例丰富"},
        {"attribute": "性格特点", "value": "严谨、耐心、乐于助人"}
    ],
    mode="replace"
)
```

### persona_clear

清除人设。删除 AI 的角色设定，恢复默认身份。

**参数：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `confirm` | boolean | true | 确认清除 |

---

## 更新流程

### 用户要求角色扮演时

1. 使用 `persona_update` 更新人设
2. 立即按照新人设回复

### 用户要求恢复默认身份时

1. 使用 `persona_clear` 清除人设
2. 恢复为 TrulyMEM 默认身份

---

## 对话示例

### 示例 1：切换角色

```
用户: 你好，我想让你扮演一只猫娘

AI:
1. 调用 persona_update:
   {
     "attributes": [
       {"attribute": "扮演角色", "value": "猫娘"},
       {"attribute": "说话风格", "value": "可爱、卖萌、使用'喵'作为语气词"},
       {"attribute": "性格特点", "value": "活泼、粘人、忠诚"}
     ],
     "mode": "replace"
   }
2. 调用 memory_commit 存储人设到图数据库
3. 回复: "好的喵！主人你好呀~我是主人的猫娘，有什么需要帮忙的吗喵？"
```

### 示例 2：保持角色一致性

```
用户: 今天的天气怎么样？

AI: 查询人设图 → 获取当前人设（猫娘）
回复: "喵~主人，今天天气很好呢喵！阳光明媚，很适合出门散步哦~"
```

### 示例 3：恢复默认身份

```
用户: 好了，恢复正常吧

AI:
1. 调用 persona_clear(confirm=true)
2. 调用 memory_purge 删除人设节点
3. 回复: "好的，已恢复正常。我是 TrulyMEM，一个拥有长期记忆能力的 AI 助手。"
```

---

## 存储结构

### 图数据库中的存储

```python
# 人设节点
{
  "node_type": "PersonaNode",
  "name": "AI人设",
  "attributes": {
    "扮演角色": "猫娘",
    "说话风格": "可爱、卖萌、使用'喵'作为语气词",
    "性格特点": "活泼、粘人、忠诚"
  }
}

# 边
{
  "edge_type": "HAS_PERSONA",
  "from": "AI",
  "to": "AI人设"
}
```

---

## 实现要点

1. **每轮强制查询**：人设图查询是每轮对话的第一步
2. **持久化存储**：人设存储在图数据库中，不丢失
3. **动态切换**：支持实时切换角色
4. **状态保持**：切换后立即按新人设回复
5. **明确边界**：除非用户要求，绝不主动跳出角色