Skip to main content

​
Episode Formats

The Memory API accepts data in three formats: Messages, JSON, and Text.

​
Message Episode

For conversation messages, dialogues, and multi-turn conversations. 
interface MessageEpisode {
  group_id: string;              // User identifier
  messages: Message[];           // Array of conversation messages
}

interface Message {
  content: string;               // Message content
  role_type: "user" | "assistant" | "system";  // Role type
  role: string;                  // Role name (e.g., username, "assistant")
  timestamp: string;             // ISO 8601 datetime
  uuid?: string;                 // Optional message UUID
  source_description?: string;   // Optional conversation ID for grouping
}

​
Example

{
  "group_id": "user_oauth_sub",
  "messages": [
    {
      "content": "I'm working on a 12-story building in SF",
      "role_type": "user",
      "role": "bhosh",
      "timestamp": "2025-10-11T03:00:00Z",
      "source_description": "conv_12345"
    },
    {
      "content": "For SF, use ASCE 7-22 seismic design standards...",
      "role_type": "assistant",
      "role": "assistant",
      "timestamp": "2025-10-11T03:00:15Z",
      "source_description": "conv_12345"
    }
  ]
}

​
Role Types

user

Messages from the user

assistant

Messages from AI/assistant

system

System messages

​
JSON Episode

For structured JSON data like project specs, analysis results, and metadata. 
interface JsonEpisode {
  group_id: string;              // User identifier
  json_data: JsonData[];         // Array of structured data
}

interface JsonData {
  content: object;               // Any JSON object
  timestamp: string;             // ISO 8601 datetime
  uuid?: string;                 // Optional UUID
  source_description?: string;   // Optional conversation ID
}

​
Example

{
  "group_id": "user_oauth_sub",
  "json_data": [
    {
      "content": {
        "project": "Presidio Tower",
        "location": "San Francisco",
        "specs": {
          "stories": 12,
          "structural_system": "steel_moment_frame",
          "design_codes": ["ASCE 7-22", "AISC 360-22"]
        }
      },
      "timestamp": "2025-10-11T03:02:00Z",
      "source_description": "conv_12345"
    }
  ]
}
Use meaningful keys in your JSON for better entity extraction. Include units and context (e.g., "height_ft": 144 not just "height": 144).

​
Text Episode

For unstructured text like analysis notes, reports, and documentation. 
interface TextEpisode {
  group_id: string;              // User identifier
  text_data: TextData[];         // Array of text documents
}

interface TextData {
  content: string;               // Unstructured text content
  timestamp: string;             // ISO 8601 datetime
  uuid?: string;                 // Optional UUID
  source_description?: string;   // Optional conversation ID
}

​
Example

{
  "group_id": "user_oauth_sub",
  "text_data": [
    {
      "content": "Analysis Results: Max drift 1.8% at Story 8. Base shear 1850 kips. Column DCR = 0.91 at corner columns.",
      "timestamp": "2025-10-11T03:15:00Z",
      "source_description": "conv_12345"
    }
  ]
}
Use clear, descriptive text with technical terms. Include context and units. Structure with headings/sections for better parsing.

​
Fact Response

Facts are auto-extracted knowledge statements from your episodes. 
interface Fact {
  uuid: string;                  // Fact UUID
  name: string;                  // Relationship type (e.g., "HAS_CONCERN", "USES")
  fact: string;                  // Natural language statement
  valid_at: string;              // ISO 8601 datetime when fact became true
  invalid_at: string | null;     // When fact became false (null if still valid)
  created_at: string;            // When fact was extracted
  expired_at: string | null;     // Expiration timestamp
  score: number;                 // Relevance score (0.0-1.0)
}

​
Example

{
  "uuid": "fact_uuid_123",
  "name": "HAS_CONCERN",
  "fact": "The engineer identified Story 8 drift at 1.8% approaching the 2.0% limit",
  "valid_at": "2025-10-11T03:15:00Z",
  "invalid_at": null,
  "created_at": "2025-10-11T03:16:45Z",
  "expired_at": null,
  "score": 0.92
}

​
Common Relationship Types

The name field indicates the relationship type. Examples include:
  • WANTS_TO, HAS_CONCERN, USES, LOCATED_IN, DESIGNED_BY
  • INCLUDES, COVERS, CALCULATED, ANALYZED
  • REQUESTS, ADVISES, RECOMMENDS
  • And many more, auto-extracted from your data

​
Memory Response

The response format for /get-memory and /search endpoints. 
interface MemoryResponse {
  facts: Fact[];                 // Array of relevant facts
}

​
Example

{
  "facts": [
    {
      "uuid": "857358ad-8c85-428e-853f-d348f92b0ac4",
      "name": "USES",
      "fact": "The engineer analyzed steel moment frame structural systems",
      "valid_at": "2025-10-11T03:02:00Z",
      "invalid_at": null,
      "created_at": "2025-10-11T03:05:23Z",
      "expired_at": null,
      "score": 0.88
    }
  ]
}
Facts include relevance scores (0.0-1.0) for filtering. Higher scores indicate stronger relevance to your query.