Memory Management with Agents

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

Examples

curl -X POST https://api.orq.ai/v2/agents/run \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "agent-memories-test-prefs",
  "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",
  "memory": {
    "entity_id": "user_666"
  },
  "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"
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Do you remember what is my name?"
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents",
  "memory_stores": [
    "orq-personal-details"
  ]
}'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.run(request={
        "key": "agent-memories-test-prefs",
        "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",
        "memory": {
            "entity_id": "user_666"
        },
        "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"
                }
            ]
        },
        "message": {
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "Do you remember what is my name?"
                }
            ]
        },
        "model": "openai/gpt-4o",
        "path": "Default/agents",
        "memory_stores": [
            "orq-personal-details"
        ]
    })

    assert res is not None
    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

async function run() {
  const result = await orq.agents.run({
    key: "agent-memories-test-prefs",
    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.",
    systemPrompt: "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",
    memory: {
      entityId: "user_666"
    },
    settings: {
      maxIterations: 5,
      maxExecutionTime: 300,
      tools: [
        {
          type: "current_date"
        },
        {
          type: "retrieve_memory_stores"
        },
        {
          type: "query_memory_store"
        },
        {
          type: "write_memory_store"
        },
        {
          type: "delete_memory_document"
        }
      ]
    },
    message: {
      role: "user",
      parts: [
        {
          kind: "text",
          text: "Do you remember what is my name?"
        }
      ]
    },
    model: "openai/gpt-4o",
    path: "Default/agents",
    memoryStores: [
      "orq-personal-details"
    ]
  });

  console.log(result);
}

run();

❗️
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.

📘
To learn more about Memory Stores and their usage, see Memory Stores.