Hippo 记忆管理服务 API 接口文档

概述

Hippo 是 AnyoneAI 的记忆管理微服务，负责角色的个人知识图谱（PKG）、人物关系、日记的查询与管理，以及 Dream（做梦）记忆整理流程。

Base URL: https://hippo.adventists.cn

路由前缀: /api

数据格式: JSON

编码: UTF-8

接口一览

方法	路径	说明
GET	`/api/pkg/{npcid}`	查询角色 PKG
PUT	`/api/pkg/{npcid}`	更新角色 PKG 字段
GET	`/api/relationship/{npcid}`	查询角色人物关系
GET	`/api/diary/{npcid}`	查询角色日记
POST	`/api/dream/{npcid}`	触发角色做梦（记忆整理）
POST	`/api/memory/{npcid}`	写入一条对话记忆
GET	`/api/memory/{npcid}`	分页读取对话记忆

数据管理接口

查询 PKG

获取指定角色的个人知识图谱（Personal Knowledge Graph）。

GET /api/pkg/{npcid}

路径参数

参数名	类型	必填	说明
npcid	string	是	角色唯一标识

成功响应（200）

{
  "npcid": "abc123",
  "pkg": {
    "Name": "小明",
    "Nickname": ["明明", "小M"],
    "Hobbies": ["阅读", "跑步"],
    "Important Friends": ["小红"],
    "voice_registered": true
  }
}

错误响应（500）

{
  "status": "error",
  "message": "错误详情"
}

cURL 示例

更新 PKG 字段

按字段合并更新角色的 PKG，非全量替换。

PUT /api/pkg/{npcid}

路径参数

参数名	类型	必填	说明
npcid	string	是	角色唯一标识

请求体

{
  "updates": [
    {"key": "Hobbies", "value": "游泳,画画"},
    {"key": "Favorite Books", "value": ["三体", "百年孤独"]}
  ]
}

请求参数

参数名	类型	必填	说明
updates	array	是	更新项数组，每项包含 `key` 和 `value`
updates[].key	string	是	PKG 字段名
updates[].value	string / array	是	字段值；多值字段可传逗号分隔字符串或数组

PKG 字段完整参考

以下列出所有标准字段及其用途，可按需选择写入。字段名大小写不敏感，name/Name/NAME 均被识别为同一字段。

单值字段（直接覆盖，字符串长度上限 1024 字符）

字段名	用途说明	示例值
`Name`	角色姓名。已有值时写入会被忽略（不可覆盖）	`"小明"`
`Gender`	角色性别，影响人称代词与自我描述	`"男"`
`Age`	年龄，影响语气风格与世界观参照	`"22岁"`
`Occupation`	职业，影响专业话题的回答风格	`"大学生"`
`City`	所在城市，影响地域话题响应	`"上海"`
`Location`	所在地点（比 City 更具体），与 City 可并用	`"上海浦东"`
`Timezone`	时区偏移整数，影响 AI 对"现在几点"等时间的感知，默认 `8`（北京时间），取值范围 -12 ~ 14	`8`
`Description`	角色简介，提供通用背景信息	`"开朗活泼，喜欢旅行"`
`Relationship`	角色与用户的关系描述，影响亲密度语气	`"闺蜜"`
`Favorite Food`	喜爱的食物，影响饮食话题的共鸣	`"麻辣火锅"`
`Philosophy`	人生观 / 价值观，影响观点类回答的立场	`"活在当下，享受生活"`
`Father`	父亲信息，用于家庭话题回应	`"父亲是一名工程师"`
`Mother`	母亲信息，用于家庭话题回应	`"母亲是老师，很温柔"`
`other`	自由扩展信息，存放不在标准字段内的补充内容	`"喜欢夜跑"`
`profile`	角色档案，适合存放格式化的综合描述	`"性格内敛，理工科背景"`

多值字段（去重追加，超出上限时保留最新的 N 条；可传逗号分隔字符串或数组）

字段名	条数上限	用途说明	示例值
`Nickname`	5	昵称列表，用于称呼变换与亲密互动	`["明明", "小M"]`
`Favorite Sports`	10	喜爱的运动，影响运动话题共鸣	`["篮球", "跑步"]`
`Favorite Books`	10	喜爱的书籍，影响阅读话题推荐	`["三体", "百年孤独"]`
`Favorite Movies`	10	喜爱的电影，影响观影话题推荐	`["星际穿越"]`
`Hobbies`	10	兴趣爱好，用于扩展日常闲聊话题	`["摄影", "做饭"]`
`Entertainment and Leisure`	10	娱乐休闲方式，与 Hobbies 可并用	`["看综艺", "桌游"]`
`Important Friends`	10	重要朋友，影响人际关系话题的具体回应	`["小红", "Tom"]`
`Other Important People`	10	其他重要人物（非朋友分类），如导师、偶像等	`["班主任李老师"]`
`Important Appointments`	10	重要约定或待办事项，影响日程相关对话	`["周五和小红看电影"]`

字段名规则

大小写不敏感：city、City、CITY 均写入同一字段

自定义字段：不在上述标准列表内的字段名会原样保存，可用于存储业务侧自定义数据

受保护字段：voice_registered、face_registered 为系统内部状态字段，通过此接口写入会被自动忽略

Name 特殊保护：Name 字段已有非空值时，写入请求会被忽略，不会覆盖现有姓名

成功响应（200）

{
  "status": "ok",
  "updated_fields": ["Hobbies", "Favorite Books"]
}

错误响应

400 - 参数错误

{
  "status": "error",
  "message": "updates 不能为空"
}

404 - 角色不存在

{
  "status": "error",
  "message": "NPC abc123 不存在或无 PKG"
}

500 - 服务器错误

{
  "status": "error",
  "message": "错误详情"
}

cURL 示例

查询人物关系

获取指定角色的人物关系数据。

GET /api/relationship/{npcid}

路径参数

参数名	类型	必填	说明
npcid	string	是	角色唯一标识

成功响应（200）

{
  "npcid": "abc123",
  "relationship": {
    "entity_001": {
      "name": "小红",
      "alias": ["红红"],
      "title": ["同学"],
      "remark": "经常一起打球"
    },
    "entity_002": {
      "name": "老师张",
      "alias": [],
      "title": ["班主任"],
      "remark": "数学老师"
    }
  },
  "count": 2
}

字段	类型	说明
npcid	string	角色 ID
relationship	object	关系数据，键为实体 ID
relationship.{id}.name	string	人物名称
relationship.{id}.alias	array	别名列表
relationship.{id}.title	array	称谓列表
relationship.{id}.remark	string	备注说明
count	number	关系条目总数

错误响应（500）

{
  "status": "error",
  "message": "错误详情"
}

cURL 示例

查询日记

获取指定角色的日记数据，包含历史摘要（prior）和近期每日日记条目。

GET /api/diary/{npcid}

路径参数

参数名	类型	必填	说明
npcid	string	是	角色唯一标识

成功响应（200）

{
  "npcid": "abc123",
  "prior": "小明是一个热爱运动的人，经常和朋友们一起打篮球...",
  "dailies": [
    {
      "date": "2026-04-08",
      "summary": "今天和小红一起去了图书馆，讨论了新项目的方案..."
    },
    {
      "date": "2026-04-07",
      "summary": "参加了部门的周会，分享了上周的工作进展..."
    }
  ],
  "count": 2
}

字段	类型	说明
npcid	string	角色 ID
prior	string	历史综合摘要（滚动窗口外的记忆合并）
dailies	array	近期每日日记，按日期排序
dailies[].date	string	日期，格式 `YYYY-MM-DD`
dailies[].summary	string	当日日记摘要
count	number	日记条目数量

错误响应（500）

{
  "status": "error",
  "message": "错误详情"
}

cURL 示例

Dream 做梦接口

触发做梦

对指定角色执行一次完整的 Dream（记忆整理）流程。流程包含四个阶段：

扫描（scan）：扫描近期对话摘要，判断是否有新数据

日记（diary）：生成当日日记，管理滚动窗口

实体抽取（extraction）：从对话中抽取实体，更新 PKG 和人物关系

清理（cleanup）：清理过期的向量数据

POST /api/dream/{npcid}

路径参数

参数名	类型	必填	说明
npcid	string	是	角色唯一标识

查询参数

参数名	类型	必填	默认值	说明
dry_run	string	否	false	设为 `true` 时只执行计算，不写入数据库

成功响应（200）

{
  "status": "ok",
  "report": {
    "skipped": false,
    "diary": {
      "date": "2026-04-09",
      "diary_text": "今天和用户讨论了旅行计划...",
      "prior_merged": false,
      "overflow_count": 0
    },
    "extractions": {
      "entity_ops_count": 2,
      "pkg_updates_count": 3,
      "entity_ops": [...],
      "pkg_updates": [...],
      "rel_written": true,
      "pkg_written": true
    },
    "cleanup": {
      "content_hybrid_deleted": 5,
      "emotion_v2_deleted": 3
    },
    "error": null
  }
}

report 字段说明

字段	类型	说明
skipped	boolean	是否跳过。为 `true` 表示没有新数据，后续步骤未执行
diary	object / null	日记生成结果。包含 `date`（日期）、`diary_text`（日记文本）、`prior_merged`（是否合并了历史摘要）、`overflow_count`（溢出条数）
extractions	object / null	实体抽取结果。包含 `entity_ops_count`（实体操作数）、`pkg_updates_count`（PKG 更新数）、`rel_written`（关系是否已写入）、`pkg_written`（PKG 是否已写入）
cleanup	object / null	过期向量清理结果。包含 `content_hybrid_deleted`（内容向量删除数）、`emotion_v2_deleted`（情绪向量删除数）
error	string / null	错误信息。某步骤失败时记录错误，多个错误用分号拼接

当 skipped 为 true 时，diary、extractions、cleanup 均为 null。

当 dry_run=true 时，各步骤会正常计算但不会写入数据库，diary 和 cleanup 中可能包含 dry_run: true 标记。

错误响应（500）

{
  "status": "error",
  "message": "错误详情"
}

cURL 示例

对话记忆接口

v1.0.9 新增。负责存储和读取 NPC 与用户的对话历史记录，与主流程 set_local_memory / load_npc_memory 保持完全一致的写入逻辑。
每个 NPC 最多保留 250 条记忆，超限后自动淘汰最早的一条。
读取默认倒序返回（最新记录在前）。

写入对话记忆

POST /api/memory/{npcid}

路径参数

参数名	类型	必填	说明
npcid	string	是	角色唯一标识

请求体

{
  "user_content": "今天天气真好",
  "assistant_content": "是的，阳光明媚，心情也很好！",
  "timestamp": "1777098479727"
}

参数名	类型	必填	说明
user_content	string	否	用户说的内容（与 assistant_content 至少填一个）
assistant_content	string	否	助手回复内容（与 user_content 至少填一个）
timestamp	string	否	毫秒时间戳；不传时由服务端自动生成

成功响应（200）

{
  "status": "success",
  "timestamp": "1777098479727"
}

错误响应

400 - 内容为空

{
  "status": "error",
  "message": "user_content 和 assistant_content 不能同时为空"
}

500 - 服务器错误

{
  "status": "error",
  "message": "错误详情"
}

cURL 示例

读取对话记忆

分页读取 NPC 的历史对话记忆，默认倒序（最新在前）。

GET /api/memory/{npcid}

路径参数

参数名	类型	必填	说明
npcid	string	是	角色唯一标识

查询参数

参数名	类型	必填	默认值	说明
page_size	integer	否	20	每页条数，范围 1–100
last_key	string	否	—	上一页返回的 `next_key`，URL encode 后传入，用于翻页

成功响应（200）

{
  "status": "success",
  "code": 200,
  "data": [
    {
      "timestamp": "1777098479800",
      "user_content": "今天天气真好",
      "assistant_content": "是的，阳光明媚！"
    },
    {
      "timestamp": "1777098479727",
      "user_content": "你好",
      "assistant_content": "你好！很高兴见到你！"
    }
  ],
  "page_size": 20,
  "has_more": false
}

有更多数据时额外返回 next_key 字段：

{
  "status": "success",
  "code": 200,
  "data": [...],
  "page_size": 20,
  "has_more": true,
  "next_key": {"npcid": {"S": "abc123"}, "timestamp": {"S": "1777098479727"}}
}

字段	类型	说明
data	array	记忆列表，按时间戳倒序排列
data[].timestamp	string	毫秒时间戳
data[].user_content	string	用户内容
data[].assistant_content	string	助手内容
page_size	integer	本次请求的 page_size
has_more	boolean	是否还有更多数据
next_key	object	翻页游标，仅 `has_more=true` 时返回

翻页方式

将 next_key JSON 字符串 URL encode 后作为下一次请求的 last_key 参数：

错误响应（500）

{
  "status": "error",
  "message": "错误详情"
}

错误码说明

HTTP 状态码	说明
200	请求成功
400	请求参数错误（如 updates 为空）
404	资源不存在（如 NPC 不存在或无 PKG）
500	服务器内部错误

所有错误响应均返回 JSON 格式：

{
  "status": "error",
  "message": "具体的错误描述"
}

概述#

接口一览#

数据管理接口#

查询 PKG#

路径参数#

成功响应（200）#

错误响应（500）#

cURL 示例#

更新 PKG 字段#

路径参数#

请求体#

请求参数#

PKG 字段完整参考#

字段名规则#

成功响应（200）#

错误响应#

cURL 示例#

查询人物关系#

路径参数#

成功响应（200）#

错误响应（500）#

cURL 示例#

查询日记#

路径参数#

成功响应（200）#

错误响应（500）#

cURL 示例#

Dream 做梦接口#

触发做梦#

路径参数#

查询参数#

成功响应（200）#

report 字段说明#

错误响应（500）#

cURL 示例#

对话记忆接口#

写入对话记忆#

路径参数#

请求体#

成功响应（200）#

错误响应#

cURL 示例#

读取对话记忆#

路径参数#

查询参数#

成功响应（200）#

翻页方式#

错误响应（500）#

错误码说明#

概述

接口一览

数据管理接口

查询 PKG

路径参数

成功响应（200）

错误响应（500）

cURL 示例

更新 PKG 字段

路径参数

请求体

请求参数

PKG 字段完整参考

字段名规则

成功响应（200）

错误响应

cURL 示例

查询人物关系

路径参数

成功响应（200）

错误响应（500）

cURL 示例

查询日记

路径参数

成功响应（200）

错误响应（500）

cURL 示例

Dream 做梦接口

触发做梦

路径参数

查询参数

成功响应（200）

report 字段说明

错误响应（500）

cURL 示例

对话记忆接口

写入对话记忆

路径参数

请求体

成功响应（200）

错误响应

cURL 示例

读取对话记忆

路径参数

查询参数

成功响应（200）

翻页方式

错误响应（500）

错误码说明