记忆系统

记忆系统允许 AI 助手跨会话记住玩家的偏好、事件和待办事项。每次新对话时，助手能回忆起之前的交互内容。

核心概念

记忆 vs 会话

	会话（Session）	记忆（Memory）
作用范围	单次对话内	跨会话持久化
触发方式	自动（对话开始/结束）	AI 主动调用 memory_write
内容类型	完整对话记录	结构化信息片段
生命周期	随会话存在，可压缩	独立于会话，持久保存

数据隔离

记忆按 assistantId × playerUUID 完全隔离：

• 玩家 A 与小墨的记忆 ≠ 玩家 A 与小匠的记忆
• 玩家 A 的记忆 ≠ 玩家 B 的记忆

默认分类

分类	用途	示例
identity	玩家身份信息	称呼：小明
preferences	玩家偏好	喜欢中世纪风格建筑
events	重要事件	2025-01-15 完成了钻石套装
todos	待办事项	帮玩家记住明天的活动

identity 由助手自动创建。其余分类在 config.yml 的 memory.defaultCategories 中配置。

记忆工具

memory_read — 读取记忆

两种使用方式：

1. 按分类读取：读取某个分类的全部记忆

   memory_read(category: "preferences")

2. 关键词搜索：跨所有分类搜索

   memory_read(keyword: "建筑")

搜索结果格式为 [category#index]，方便后续删除操作。

memory_write — 写入/删除记忆

• 添加记忆：

  memory_write(category: "preferences", action: "add", content: "喜欢用石砖做墙壁")

• 删除记忆：

  memory_write(category: "preferences", action: "remove", index: 2)

记忆注入方式

系统提示中只注入摘要（分类名 + 条目数），不全量注入内容：

你有与该玩家的长期记忆：
- identity（2 条）— 玩家身份信息
- preferences（3 条）— 玩家偏好
- events（5 条）— 重要事件
需要查看具体内容时调用 memory_read，需要记录时调用 memory_write。

优势

• token 消耗恒定，不随记忆增长
• AI 按需读取，精确查找

记忆存储

文件存储

data/memory/{assistantId}/{playerUUID}/
├── identity.md
├── preferences.md
├── events.md
└── todos.md

每个文件是 Markdown 列表，每条 - 开头：

- 称呼：小明
- 喜欢中世纪风格
- 常用石砖和橡木

数据库存储

MySQL / PostgreSQL 存储在 ark_memories 表中，按 (assistant_id, player_uuid, category) 索引。

配置

全局配置（config.yml）

memory:
  enabled: true           # 启用记忆系统
  autoUpdate: true         # 允许 AI 主动记录
  defaultCategories:       # 默认分类
    - preferences
    - events
    - todos

助手级覆盖

# assistants/{id}/config.yml
memory:
  enabled: true            # 此助手是否启用记忆
  autoUpdate: true         # 此助手是否可自动更新

内部助手（如蓝图生成器）通常设为 enabled: false。

AI 记忆行为

在 SOUL.md 中可以指导 AI 如何使用记忆：

• 首次回复时：先调用 memory_read 读取所有非空分类
• 发现值得记住的信息时：立即调用 memory_write
• 自然融入：引用记忆时不要说"我查了记忆"，而是自然地使用

跨服记忆

使用 MySQL / PostgreSQL 时，记忆自动跨服共享。玩家在 A 服告诉助手的偏好，在 B 服也能被记住。