Skip to main content

​
Overview

Memory Management enables agents to maintain persistent context and learn from previous interactions across conversations. By integrating with Memory Stores, agents can store, retrieve, and manage information that persists beyond individual sessions.

​
Key Features

  • Persistent Memory: Store information that persists across conversations and sessions
  • Entity-Based Isolation: Use entity IDs to separate memories by user, organization, or session
  • Dynamic Memory Discovery: Discover available memory stores using retrieve_memory_stores
  • Memory Operations: Query, write, and delete memory documents programmatically
  • Contextual Recall: Automatically retrieve relevant memories based on conversation context
Memory stores don’t automatically save all information from conversations.
  • What gets saved depends on the memory store’s description field and how you prompt the agent.
  • For best results, explicitly tell the agent what to save (e.g., “Remember that my preferred language is Python”).
  • Without explicit save instructions, the system may only retain some information while missing other details.
  • Make sure your memory store description clearly states what type of data it should store.

​
Examples

​
Creating Memory Store

Create a new memory store with a unique key and embedding model configuration. 
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "key": "customer_information",
  "description": "Store for customer interaction history and preferences",
  "path": "Default/agents",
  "embedding_config": {
    "model": "openai/text-embedding-3-small"
  }
}'

​
Creating Memory

Create a new memory for a specific entity within a memory store. 
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "entity_id": "customer_456",
  "metadata": {
    "type": "customer",
    "segment": "premium",
    "region": "north_america",
    "status": "active"
  }
}'
The ID of the entity will be returned after created to be used when calling the agent

​
Creating an Agent

curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "agent-memories",
  "role": "Personalized Assistant",
  "description": "Agent using external ID for memory store access",
  "instructions": "You have access to user-specific memories. Remember information about the user and recall it when asked.",
  "system_prompt": "Please answer with a lot of emojis for all questions. Use retrieve_memory_stores to see what memory stores are available, then use query_memory_store to search for relevant information before responding",
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 300,
    "tools": [
      {
        "type": "current_date"
      },
      {
        "type": "retrieve_memory_stores"
      },
      {
        "type": "query_memory_store"
      },
      {
        "type": "write_memory_store"
      },
      {
        "type": "delete_memory_document"
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents",
  "memory_stores": [
    "customer_information"
  ]
}'
Agents must use the retrieve_memory_stores tool first to discover available memory stores before they can query or write to them. Include instructions in your system prompt like: Use retrieve_memory_stores to see what memory stores are available, then use query_memory_store to search for relevant information before responding.

​
Calling the agent

To call the Agent, we’ll use the Responses API with an Embedded message and Linked memory. 
curl -X POST https://api.orq.ai/v2/agents/agent-memories/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "agent-memories",
  "memory": {
    "entity_id": "customer_456"
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Do you remember what is my name?"
      }
    ]
  }
}'
You can use multiple memory stores per call, ensure that the entity_id sent during the calls maps the same way to all previously declared memory stores during agent creation.

​
Viewing Traces

Within Traces, you can visualize the memory store usage and retrieval from the Agent, confirming that it was correctly created and used.
Memory Store Trace

Memory Stores will show retrieval or storage when needed