Skip to main content
POST
/
get-memory
Get Memory
curl --request POST \
  --url https://memory.stru.ai/get-memory \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '{
  "group_id": "<string>",
  "center_node_uuid": {},
  "messages": [
    {
      "content": "<string>",
      "role_type": "<string>",
      "role": {},
      "timestamp": "<string>",
      "uuid": "<string>",
      "name": "<string>",
      "source_description": "<string>"
    }
  ],
  "max_facts": 123,
  "reranker": "<string>",
  "min_score": 123,
  "episode_source_filter": "<string>",
  "mmr_lambda": 123
}'
{
  "422": {},
  "facts": [
    {
      "uuid": "<string>",
      "name": "<string>",
      "fact": "<string>",
      "valid_at": "<string>",
      "invalid_at": {},
      "created_at": "<string>",
      "expired_at": {},
      "score": 123
    }
  ]
}

​
Overview

Retrieve relevant facts from the knowledge graph based on current conversation context and an optional focal entity. This is the preferred method for context-aware memory retrieval during conversations.
Use this endpoint when you have conversation messages for context. For standalone queries, use /search.

​
Authentication

​
X-API-Key
string
required
Your API key for authentication
X-API-Key: windowseat

​
Request Body

​
group_id
string
required
User identifier (group ID) to retrieve memories for
"group_id": "user_oauth_sub"
​
center_node_uuid
string | null
required
UUID of entity to focus retrieval around. Set to null for general retrieval across all user’s memory.
"center_node_uuid": "e090f257-c182-4930-819d-161c66bee335"
Use null when you don’t have a specific focal entity. Use a UUID when retrieving facts about a specific project, person, or concept.
​
messages
array
required
Current conversation messages to build the retrieval query from
"messages": [
  {
    "content": "What were my concerns about drift?",
    "role_type": "user",
    "role": "bhosh",
    "timestamp": "2025-10-11T03:30:00Z"
  }
]
​
max_facts
integer
default:"10"
Maximum number of facts to return. Typical range: 10-20.
"max_facts": 15
​
reranker
string
default:"null"
Reranking method for result ordering:
  • rrf - Reciprocal Rank Fusion (good general purpose)
  • mmr - Maximal Marginal Relevance (balances relevance + diversity)
  • cross_encoder - Deep learning reranker (most accurate, slower)
"reranker": "mmr"
​
min_score
number
default:"null"
Minimum relevance score threshold:
  • For rrf and cross_encoder: 0.0 to 1.0 (defaults to 0.0)
  • For mmr: -1.0 to 1.0 (defaults to -1.0)
"min_score": 0.5
​
episode_source_filter
string
default:"null"
Limit facts to specific conversation/source
"episode_source_filter": "conv_12345"
​
mmr_lambda
number
default:"null"
MMR diversity parameter (0.0-1.0, only used when reranker="mmr"):
  • 0.0 = Maximum diversity
  • 1.0 = Maximum relevance
  • 0.7 = Balanced (recommended)
"mmr_lambda": 0.7

​
Response

Returns an array of relevant facts with relevance scores.
​
facts
array
Array of fact objects relevant to the conversation context

​
Example Request

curl -X POST https://memory.stru.ai/get-memory \
  -H "X-API-Key: windowseat" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "user_oauth_sub",
    "center_node_uuid": null,
    "messages": [
      {
        "content": "What were my concerns about drift?",
        "role_type": "user",
        "role": "bhosh",
        "timestamp": "2025-10-11T03:30:00Z"
      }
    ],
    "max_facts": 10,
    "reranker": "mmr",
    "mmr_lambda": 0.7,
    "min_score": 0.5
  }'

​
Example Response

{
  "facts": [
    {
      "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
    },
    {
      "uuid": "fact_uuid_456",
      "name": "CALCULATED",
      "fact": "Maximum drift ratio occurs at the 8th story of the building",
      "valid_at": "2025-10-11T03:15:00Z",
      "invalid_at": null,
      "created_at": "2025-10-11T03:16:50Z",
      "expired_at": null,
      "score": 0.87
    }
  ]
}

​
Error Responses

​
422
Validation Error
Request validation failed - check your parameters
{
  "detail": [
    {
      "loc": ["body", "group_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Best Practices

Use center_node_uuid strategically - Set to null for general retrieval, or provide a specific entity UUID when you want facts centered around a project/person/concept
Include recent conversation context - Provide the last few messages for best semantic matching
Adjust max_facts based on use case - Use 10-20 for chat applications, more for comprehensive analysis
Use MMR reranker - reranker="mmr" with mmr_lambda=0.7 provides good balance between relevance and diversity
Response time: Typically 200-800ms. This is a synchronous endpoint - you’ll get results immediately.