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}`	触发角色做梦（记忆整理）

数据管理接口

查询 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	是	字段值；多值字段可传逗号分隔字符串或数组

更新规则

多值字段：新值会去重追加到已有列表末尾，超出条数上限时保留最新的 N 条。

字段名	条数上限
Nickname	5
Important Friends	10
Other Important People	10
Important Appointments	10
Favorite Books	10
Favorite Movies	10
Favorite Sports	10
Hobbies	10
Entertainment and Leisure	10

普通字段：直接覆盖，字符串长度上限 1024 字符。

忽略规则：

key 为空时忽略

key 为受保护字段（voice_registered、face_registered）时忽略

key 为 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 示例

错误码说明

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

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

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

概述#

接口一览#

数据管理接口#

查询 PKG#

路径参数#

成功响应（200）#

错误响应（500）#

cURL 示例#

更新 PKG 字段#

路径参数#

请求体#

请求参数#

更新规则#

成功响应（200）#

错误响应#

cURL 示例#

查询人物关系#

路径参数#

成功响应（200）#

错误响应（500）#

cURL 示例#

查询日记#

路径参数#

成功响应（200）#

错误响应（500）#

cURL 示例#

Dream 做梦接口#

触发做梦#

路径参数#

查询参数#

成功响应（200）#

report 字段说明#

错误响应（500）#

cURL 示例#

错误码说明#

概述

接口一览

数据管理接口

查询 PKG

路径参数

成功响应（200）

错误响应（500）

cURL 示例

更新 PKG 字段

路径参数

请求体

请求参数

更新规则

成功响应（200）

错误响应

cURL 示例

查询人物关系

路径参数

成功响应（200）

错误响应（500）

cURL 示例

查询日记

路径参数

成功响应（200）

错误响应（500）

cURL 示例

Dream 做梦接口

触发做梦

路径参数

查询参数

成功响应（200）

report 字段说明

错误响应（500）

cURL 示例

错误码说明