Engine API

Conversation-based memory extraction and retrieval endpoints. The Engine processes dialogue turns and automatically extracts structured memories using LLM.

Engine memories are extracted asynchronously. After calling consolidate, memories become available once the worker finishes processing (typically 2-5 seconds per batch).

Consolidate (Add Dialogue)

POST/v1/engine/consolidate/

Add a dialogue turn to the session buffer. When 20+ turns accumulate, memories are auto-extracted in batches of 8.

Auth

Token

Request Body

{
  "session_uuid": "string (required)",
  "parent_session_uuid": "string (required)",
  "new_dialog": {
    "uuid": "string (unique dialog ID)",
    "query": "string (user message)",
    "answer": "string (assistant response)"
  },
  "user_name": "string (default: '당신')",
  "language": "string (default: 'ko')",
  "options": {
    "length_limit": 1000,
    "force_summary": false
  }
}

Response

{"status": "success", "message": null}

Setting force_summary: true triggers immediate processing regardless of buffer size. Use sparingly — it bypasses the batch optimization.

Retrieve (Search Memories)

POST/v1/engine/retrieve/

Search extracted memories using dense vector similarity + lexical re-ranking.

Auth

Token

Request Body

{
  "parent_session_uuids": ["string (session IDs to search)"],
  "last_dialog_uuid": "string",
  "recent_dialogs": [],
  "user_input": {"query": "string (search query)"},
  "options": {"limit": 5}
}

Response

{
  "status": "success",
  "data": [
    {
      "memory_id": "20260318_040037_d60e66",
      "content": "Summary of the extracted memory...",
      "score": 0.2198
    }
  ]
}

Delete

DELETE/v1/engine/delete/

Delete a memory or dialogue turn with cascade. Supports memory ID pattern, buffer turn UUID, and dialog-to-memory cascade.

Auth

Token

Request Body

{
  "session_uuid": "string",
  "dialog_uuid": "string (memory ID or dialog UUID)"
}

Fork Delete

POST/v1/engine/fork-delete/

Clone a session and prune memories from a cutoff point. Used for conversation branching.

Auth

Token

Request Body

{
  "source_session_uuid": "string",
  "target_session_uuid": "string",
  "cutoff_dialog_uuid": "string"
}

Embed

POST/v1/engine/embed/

Generate an embedding vector. Uses all-MiniLM-L6-v2 (384-dim) in development, GPU models (4096-dim) in production.

Auth

Token

Request Body

{"text": "hello world", "mode": "query"}

Response

{"embedding": [0.034, -0.012, ...], "dimension": 384}

Health

GET/v1/engine/health/

Check memory engine service health.

Auth

none

Response

{"status": "ok", "service": "memory-engine"}

Extracted Memory Structure

Each extracted memory contains the following fields:

Field	Type	Description
summary	string	10-sentence episode summary (510-630 tokens)
keywords	string[]	Up to 65 search keywords
key_facts	string[]	Up to 18 chronological event bullet points
key_dialogue	string[]	4 important quotes per character
intent	string	2-4 sentence character intent analysis
location	string	Location, time, weather information
characters	string[]	Identified character names with alias normalization