Hippo - Character Memory Management Microservice - Adventists

Hippo is the memory management microservice for AnyoneAI, responsible for querying and managing Personal Knowledge Graphs (PKG), character relationships, diaries, and Dream (memory consolidation) processes.

Base URL:

Route Prefix: /api

Data Format: JSON

Encoding: UTF-8

API Summary

Method	Path	Description
GET	`/api/pkg/{npcid}`	Query character PKG
PUT	`/api/pkg/{npcid}`	Update character PKG fields
GET	`/api/relationship/{npcid}`	Query character relationships
GET	`/api/diary/{npcid}`	Query character diary
POST	`/api/dream/{npcid}`	Trigger character dreaming (memory consolidation)

Data Management APIs

Query PKG

Retrieve the Personal Knowledge Graph for a specified character.

GET /api/pkg/{npcid}

Path Parameters

Parameter	Type	Required	Description
npcid	string	Yes	Unique character identifier

Success Response (200)

{
  "npcid": "abc123",
  "pkg": {
    "Name": "Xiao Ming",
    "Nickname": ["Mingming", "Little M"],
    "Hobbies": ["Reading", "Running"],
    "Important Friends": ["Xiao Hong"],
    "voice_registered": true
  }
}

Error Response (500)

{
  "status": "error",
  "message": "Error details"
}

cURL Example

Update PKG Fields

Merge-update PKG fields for a character. This is not a full replacement.

PUT /api/pkg/{npcid}

Path Parameters

Parameter	Type	Required	Description
npcid	string	Yes	Unique character identifier

Request Body

{
  "updates": [
    {"key": "Hobbies", "value": "Swimming,Painting"},
    {"key": "Favorite Books", "value": ["Three-Body Problem", "One Hundred Years of Solitude"]}
  ]
}

Request Parameters

Parameter	Type	Required	Description
updates	array	Yes	Array of update items, each containing `key` and `value`
updates[].key	string	Yes	PKG field name
updates[].value	string / array	Yes	Field value; multi-value fields can use comma-separated strings or arrays

Update Rules

Multi-value fields: New values are deduplicated and appended to the end of the existing list. When exceeding the item limit, the latest N items are retained.

Field Name	Item Limit
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

Regular fields: Direct overwrite, string length limit is 1024 characters.

Ignore Rules:

Ignored if key is empty

Ignored if key is a protected field (voice_registered, face_registered)

Ignored if key is Name and the current name is non-empty

Success Response (200)

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

Error Responses

400 - Invalid Parameters

{
  "status": "error",
  "message": "updates cannot be empty"
}

404 - Character Not Found

{
  "status": "error",
  "message": "NPC abc123 does not exist or has no PKG"
}

500 - Server Error

{
  "status": "error",
  "message": "Error details"
}

cURL Example

Query Relationships

Retrieve relationship data for a specified character.

GET /api/relationship/{npcid}

Path Parameters

Parameter	Type	Required	Description
npcid	string	Yes	Unique character identifier

Success Response (200)

{
  "npcid": "abc123",
  "relationship": {
    "entity_001": {
      "name": "Xiao Hong",
      "alias": ["Honghong"],
      "title": ["Classmate"],
      "remark": "Often plays basketball together"
    },
    "entity_002": {
      "name": "Teacher Zhang",
      "alias": [],
      "title": ["Class Teacher"],
      "remark": "Math teacher"
    }
  },
  "count": 2
}

Field	Type	Description
npcid	string	Character ID
relationship	object	Relationship data, keys are entity IDs
relationship.{id}.name	string	Person's name
relationship.{id}.alias	array	List of aliases
relationship.{id}.title	array	List of titles
relationship.{id}.remark	string	Remarks
count	number	Total number of relationship entries

Error Response (500)

{
  "status": "error",
  "message": "Error details"
}

cURL Example

Query Diary

Retrieve diary data for a specified character, including historical summary (prior) and recent daily diary entries.

GET /api/diary/{npcid}

Path Parameters

Parameter	Type	Required	Description
npcid	string	Yes	Unique character identifier

Success Response (200)

{
  "npcid": "abc123",
  "prior": "Xiao Ming is a sports enthusiast, often playing basketball with friends...",
  "dailies": [
    {
      "date": "2026-04-08",
      "summary": "Went to the library with Xiao Hong today, discussed the new project plan..."
    },
    {
      "date": "2026-04-07",
      "summary": "Attended the department weekly meeting, shared last week's work progress..."
    }
  ],
  "count": 2
}

Field	Type	Description
npcid	string	Character ID
prior	string	Historical summary (merged memories outside the rolling window)
dailies	array	Recent daily diaries, sorted by date
dailies[].date	string	Date in `YYYY-MM-DD` format
dailies[].summary	string	Daily diary summary
count	number	Total number of diary entries

Error Response (500)

{
  "status": "error",
  "message": "Error details"
}

cURL Example

Dream API

Trigger Dreaming

Execute a complete Dream (memory consolidation) process for a specified character. The process consists of four stages:

Scan: Scan recent conversation summaries to determine if there is new data

Diary: Generate today's diary and manage the rolling window

Extraction: Extract entities from conversations and update PKG and relationships

Cleanup: Clean up expired vector data

POST /api/dream/{npcid}

Path Parameters

Parameter	Type	Required	Description
npcid	string	Yes	Unique character identifier

Query Parameters

Parameter	Type	Required	Default	Description
dry_run	string	No	false	When set to `true`, only computes results without writing to the database

Success Response (200)

{
  "status": "ok",
  "report": {
    "skipped": false,
    "diary": {
      "date": "2026-04-09",
      "diary_text": "Discussed travel plans with the user today...",
      "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 Fields

Field	Type	Description
skipped	boolean	Whether skipped. When `true`, no new data was found and subsequent steps were not executed
diary	object / null	Diary generation result. Contains `date`, `diary_text`, `prior_merged`, `overflow_count`
extractions	object / null	Entity extraction result. Contains `entity_ops_count`, `pkg_updates_count`, `rel_written`, `pkg_written`
cleanup	object / null	Expired vector cleanup result. Contains `content_hybrid_deleted`, `emotion_v2_deleted`
error	string / null	Error message. Multiple errors are separated by semicolons

When skipped is true, diary, extractions, and cleanup are all null.

When dry_run=true, each step computes normally but does not write to the database. diary and cleanup may contain dry_run: true markers.

Error Response (500)

{
  "status": "error",
  "message": "Error details"
}

cURL Examples

Error Codes

HTTP Status Code	Description
200	Request successful
400	Invalid request parameters (e.g., updates is empty)
404	Resource not found (e.g., NPC does not exist or has no PKG)
500	Internal server error

All error responses return JSON format:

{
  "status": "error",
  "message": "Detailed error description"
}

Hippo - Character Memory Management Microservice

API Summary#

Data Management APIs#

Query PKG#

Path Parameters#

Success Response (200)#

Error Response (500)#

cURL Example#

Update PKG Fields#

Path Parameters#

Request Body#

Request Parameters#

Update Rules#

Success Response (200)#

Error Responses#

cURL Example#

Query Relationships#

Path Parameters#

Success Response (200)#

Error Response (500)#

cURL Example#

Query Diary#

Path Parameters#

Success Response (200)#

Error Response (500)#

cURL Example#

Dream API#

Trigger Dreaming#

Path Parameters#

Query Parameters#

Success Response (200)#

Report Fields#

Error Response (500)#

cURL Examples#

Error Codes#

API Summary

Data Management APIs

Query PKG

Path Parameters

Success Response (200)

Error Response (500)

cURL Example

Update PKG Fields

Path Parameters

Request Body

Request Parameters

Update Rules

Success Response (200)

Error Responses

cURL Example

Query Relationships

Path Parameters

Success Response (200)

Error Response (500)

cURL Example

Query Diary

Path Parameters

Success Response (200)

Error Response (500)

cURL Example

Dream API

Trigger Dreaming

Path Parameters

Query Parameters

Success Response (200)

Report Fields

Error Response (500)

cURL Examples

Error Codes