Skip to main content

​
What is Stru Memory API?

The Stru Memory API (Graphiti v2) is a knowledge graph system that stores conversation episodes, JSON data, and text documents, automatically extracts entities, relationships, and facts, and enables semantic search and contextual memory retrieval. Base URL: https://memory.stru.ai

​
Authentication

All requests require an API key in the X-API-Key header. Get your API key from app.stru.ai. 
X-API-Key: YOUR_API_KEY

​
Core Concepts

Groups

User identifier (user_id becomes group_id in API). All user data is scoped to their group_id with no cross-user data leakage.

Episodes

Units of data ingestion (conversation messages, JSON data, or text documents). Each episode can be tagged with a source_description for grouping.

Source Description

Conversation/session identifier for grouping related episodes together. Use this to enable batch cleanup.

Facts

Auto-extracted knowledge statements from episodes. The knowledge graph extracts these in the background (1-5 minutes processing time).

Entities

Auto-extracted people, places, concepts, and objects from your data.

Center Node

A focal entity UUID for contextual memory retrieval. Use when you want facts centered around a specific entity.

​
Key Features

  • Automatic Knowledge Extraction: Converts conversations and data into structured knowledge graphs
  • Semantic Search: Find information based on meaning, not just keywords
  • Contextual Retrieval: Get relevant facts based on conversation context
  • User Isolation: Complete data isolation per user (group_id)
  • Multiple Data Formats: Support for messages, JSON, and text documents
  • Temporal Tracking: Facts have validity periods and creation timestamps

​
Quick Start

1

Check API Health

Verify the API is running and warm up cold-start servers.
curl https://memory.stru.ai/health
2

Add Your First Episode

Add a conversation message to the knowledge graph.
curl -X POST https://memory.stru.ai/episodes \
  -H "X-API-Key: windowseat" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "demo_user",
    "messages": [{
      "content": "I love cherry blossoms",
      "role_type": "user",
      "role": "demo",
      "timestamp": "2025-10-11T03:00:00Z",
      "source_description": "demo_conv"
    }]
  }'
3

Wait for Processing

Knowledge extraction happens in the background (1-5 minutes).
4

Search Your Memories

Query the knowledge graph for relevant facts.
curl -X POST https://memory.stru.ai/search \
  -H "X-API-Key: windowseat" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does the user like?",
    "group_ids": ["demo_user"],
    "max_facts": 5
  }'

​
Timing & Performance

​
Async Processing

  • POST /episodes returns 202 Accepted (queued, not processed yet)
  • Processing takes 1-5 minutes depending on data volume
  • Complex multi-episode batches take longer
  • You can continue adding data while previous episodes process

​
Query Timing

  • /get-memory and /search are real-time (synchronous)
  • Typically respond in 200-800ms
  • Response time increases with max_facts and data volume

​
Best Practices

Always use source_description when adding episodes. This groups related data together and enables batch cleanup when users delete conversations.
"source_description": "conversation_id_12345"
Call /health endpoint when your app starts to warm up the API and avoid cold-start delays.
curl https://memory.stru.ai/health
  • Use /get-memory when you have conversation context (preferred)
  • Use /search for standalone queries without context
  • group_id = user’s OAuth sub (unique user identifier)
  • All user’s data is scoped to their group_id
  • No cross-user data leakage
  • Each user has isolated knowledge graph