Memory stores provide persistent storage for agent memories, allowing your agents to maintain context and recall information across conversations. Each memory store contains memories (representing entities) which in turn contain documents (the actual information).

Memory Stores

List Memory Stores

Retrieve all memory stores in your workspace to see available storage containers.

curl --request GET \
     --url 'https://api.orq.ai/v2/memory-stores?limit=10' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

from orq_ai_sdk import Orq
import os

client = Orq(api_key=os.environ["ORQ_API_KEY"])

response = client.memory_stores.list(
    limit=10,
    starting_after="cursor_id"  # optional pagination
)

# Response includes paginated array of memory stores
for store in response.data:
    print(f"Store: {store.key}, Description: {store.description}")

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

const client = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const response = await client.memoryStores.list({
  limit: 10,
  starting_after: 'cursor_id', // optional pagination
});

// Response includes paginated array of memory stores
response.data.forEach((store) => {
  console.log(`Store: ${store.key}, Description: ${store.description}`);
});

Create 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 <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '
{
  "key": "customer_information",
  "description": "Store for customer interaction history and preferences",
  "path": "default",
  "embedding_config": {
    "model": "openai/text-embedding-3-small"
  }
}'

store = client.memory_stores.create(
    key="customer_information",  # Unique, immutable identifier
    description="Store for customer interaction history and preferences",
    path="default",  # Project path (required)
    embedding_config={
        "model": "openai/text-embedding-3-small"  # Embedding model for semantic search
    }
)

await client.memoryStores.create({
  key: 'customer_information', // Unique, immutable identifier
  description: 'Store for customer interaction history and preferences',
  path: 'default', // Project path (required)
  embedding_config: {
    model: 'openai/text-embedding-3-small', // Embedding model for semantic search
  },
});

Important: The key is immutable and must be unique within your workspace. Choose it carefully as it cannot be changed later.

🚧
The key is immutable and must be unique within your workspace. Choose it carefully as it cannot be changed later.

Retrieve Memory Store

Get detailed information about a specific memory store using its key.

curl --request GET \
     --url https://api.orq.ai/v2/memory-stores/customer_information \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

store = client.memory_stores.retrieve(
    memory_store_key="customer_information"
)

print(f"Store: {store.key}")
print(f"Description: {store.description}")
print(f"Embedding model: {store.embedding_config.model}")
print(f"Created: {store.created}")

const store = await client.memoryStores.retrieve({
  memory_store_key: 'customer_information',
});

console.log(`Store: ${store.key}`);
console.log(`Description: ${store.description}`);
console.log(`Embedding model: ${store.embedding_config.model}`);
console.log(`Created: ${store.created}`);

Update Memory Store

Modify memory store configuration and metadata.

curl --request PUT \
     --url https://api.orq.ai/v2/memory-stores/customer_information \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '
{
  "description": "Enhanced customer information with interaction history",
  "embedding_config": {
    "model": "openai/text-embedding-3-large"
  }
}'

updated_store = client.memory_stores.update(
    memory_store_key="customer_information",
    description="Enhanced customer information with interaction history",
    embedding_config={
        "model": "openai/text-embedding-3-large"  # Upgrade embedding model
    }
)

const updatedStore = await client.memoryStores.update({
  memory_store_key: 'customer_information',
  description: 'Enhanced customer information with interaction history',
  embedding_config: {
    model: 'openai/text-embedding-3-large', // Upgrade embedding model
  },
});

Delete Memory Store

Remove a memory store and all its associated memories and documents.

curl --request DELETE \
     --url https://api.orq.ai/v2/memory-stores/customer_information \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

client.memory_stores.delete(
    memory_store_key="customer_information"
)

await client.memoryStores.delete({
  memory_store_key: 'customer_information',
});

Warning: Deleting a memory store is permanent and will remove all memories and documents within it. This action cannot be undone.

Memory

What is a Memory?

A memory represents a specific entity (user, customer, session, etc.) within a memory store. Each memory is identified by an entity_id and can be tagged with metadata for organization and filtering.

List Memories

Retrieve all memories within a specific memory store.

curl --request GET \
     --url 'https://api.orq.ai/v2/memory-stores/customer_information/memories?limit=50' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

response = client.memory_stores.list_memories(
    memory_store_key="customer_information",
    limit=50,
    starting_after="memory_id"  # optional cursor for pagination
)

for memory in response.data:
    print(f"Entity: {memory.entity_id}")
    print(f"Tags: {memory.tags}")

const response = await client.memoryStores.listMemories({
  memory_store_key: 'customer_information',
  limit: 50,
  starting_after: 'memory_id', // optional cursor for pagination
});

response.data.forEach((memory) => {
  console.log(`Entity: ${memory.entity_id}`);
  console.log(`Tags: ${JSON.stringify(memory.tags)}`);
});

Create 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 <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '
{
  "entity_id": "customer_456",
  "tags": {
    "type": "customer",
    "segment": "premium",
    "region": "north_america",
    "status": "active"
  }
}'

memory = client.memory_stores.create_memory(
    memory_store_key="customer_information",
    entity_id="customer_456",  # Your external ID
    tags={
        "type": "customer",
        "segment": "premium",
        "region": "north_america",
        "status": "active"
    }
)

print(f"Created memory with ID: {memory._id}")

const memory = await client.memoryStores.createMemory({
  memory_store_key: 'customer_information',
  entity_id: 'customer_456', // Your external ID
  tags: {
    type: 'customer',
    segment: 'premium',
    region: 'north_america',
    status: 'active',
  },
});

console.log(`Created memory with ID: ${memory._id}`);

Retrieve Memory

Get a specific memory by its ID.

curl --request GET \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

memory = client.memory_stores.retrieve_memory(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123"  # Memory ULID
)

print(f"Memory for entity: {memory.entity_id}")
print(f"Tags: {memory.tags}")

const memory = await client.memoryStores.retrieveMemory({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123', // Memory ULID
});

console.log(`Memory for entity: ${memory.entity_id}`);
console.log(`Tags: ${JSON.stringify(memory.tags)}`);

Update Memory

Update tags and metadata for an existing memory.

curl --request PUT \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '
{
  "tags": {
    "type": "customer",
    "segment": "enterprise",
    "region": "north_america",
    "status": "vip",
    "last_contact": "2024-01-20"
  }
}'

updated_memory = client.memory_stores.update_memory(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123",
    tags={
        "type": "customer",
        "segment": "enterprise",  # Updated segment
        "region": "north_america",
        "status": "vip",  # Changed status
        "last_contact": "2024-01-20"  # New tag
    }
)

const updatedMemory = await client.memoryStores.updateMemory({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123',
  tags: {
    type: 'customer',
    segment: 'enterprise', // Updated segment
    region: 'north_america',
    status: 'vip', // Changed status
    last_contact: '2024-01-20', // New tag
  },
});

Delete Memory

Remove a memory and all its associated documents.

curl --request DELETE \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

client.memory_stores.delete_memory(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123"
)

await client.memoryStores.deleteMemory({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123',
});

Memory Documents

Documents contain the actual information stored within memories. They are the text content that gets embedded and can be retrieved through semantic search.

List Memory Documents

Retrieve all documents within a specific memory.

curl --request GET \
     --url 'https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123/documents?limit=100' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

response = client.memory_stores.list_documents(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123",
    limit=100,
    starting_after="document_id"  # optional pagination
)

for doc in response.data:
    print(f"Document: {doc._id}")
    print(f"Content: {doc.text[:100]}...")
    print(f"Tags: {doc.tags}")

const response = await client.memoryStores.listDocuments({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123',
  limit: 100,
  starting_after: 'document_id', // optional pagination
});

response.data.forEach((doc) => {
  console.log(`Document: ${doc._id}`);
  console.log(`Content: ${doc.text.substring(0, 100)}...`);
  console.log(`Tags: ${JSON.stringify(doc.tags)}`);
});

Create Memory Document

Add a new document to a memory with content and tags.

curl --request POST \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123/documents \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Customer prefers email communication over phone calls. Best time to contact is between 2-4 PM EST. Has expressed interest in our premium support package.",
  "tags": {
    "source": "support_ticket",
    "date": "2024-01-15",
    "category": "preferences",
    "importance": "high"
  }
}'

document = client.memory_stores.create_document(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123",
    text="Customer prefers email communication over phone calls. Best time to contact is between 2-4 PM EST. Has expressed interest in our premium support package.",
    tags={
        "source": "support_ticket",
        "date": "2024-01-15",
        "category": "preferences",
        "importance": "high"
    }
)

print(f"Created document with ID: {document._id}")

const document = await client.memoryStores.createDocument({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123',
  text: 'Customer prefers email communication over phone calls. Best time to contact is between 2-4 PM EST. Has expressed interest in our premium support package.',
  tags: {
    source: 'support_ticket',
    date: '2024-01-15',
    category: 'preferences',
    importance: 'high',
  },
});

console.log(`Created document with ID: ${document._id}`);

Retrieve Memory Document

Get a specific document by its ID.

curl --request GET \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123/documents/01J5DOCXYZ789 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

document = client.memory_stores.retrieve_document(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123",
    document_id="01J5DOCXYZ789"
)

print(f"Document content: {document.text}")
print(f"Tags: {document.tags}")

const document = await client.memoryStores.retrieveDocument({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123',
  document_id: '01J5DOCXYZ789',
});

console.log(`Document content: ${document.text}`);
console.log(`Tags: ${JSON.stringify(document.tags)}`);

Update Memory Document

Modify the content or tags of an existing document.

curl --request PUT \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123/documents/01J5DOCXYZ789 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Customer strongly prefers email communication. Best contact window: 2-4 PM EST on weekdays. Premium support subscriber since Jan 2024. Also accepts scheduled video calls with 24h notice.",
  "tags": {
    "source": "support_ticket",
    "date": "2024-01-20",
    "category": "preferences",
    "importance": "high",
    "verified": "2024-01-20"
  }
}'

updated_doc = client.memory_stores.update_document(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123",
    document_id="01J5DOCXYZ789",
    text="Customer strongly prefers email communication. Best contact window: 2-4 PM EST on weekdays. Premium support subscriber since Jan 2024. Also accepts scheduled video calls with 24h notice.",
    tags={
        "source": "support_ticket",
        "date": "2024-01-20",
        "category": "preferences",
        "importance": "high",
        "verified": "2024-01-20"
    }
)

const updatedDoc = await client.memoryStores.updateDocument({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123',
  document_id: '01J5DOCXYZ789',
  text: 'Customer strongly prefers email communication. Best contact window: 2-4 PM EST on weekdays. Premium support subscriber since Jan 2024. Also accepts scheduled video calls with 24h notice.',
  tags: {
    source: 'support_ticket',
    date: '2024-01-20',
    category: 'preferences',
    importance: 'high',
    verified: '2024-01-20',
  },
});

Delete Document

Remove a specific document from a memory.

curl --request DELETE \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123/documents/01J5DOCXYZ789 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <your_orq_key>'

client.memory_stores.delete_document(
    memory_store_key="customer_information",
    memory_id="01J5XYZABC123",
    document_id="01J5DOCXYZ789"
)

await client.memoryStores.deleteDocument({
  memory_store_key: 'customer_information',
  memory_id: '01J5XYZABC123',
  document_id: '01J5DOCXYZ789',
});

Best Practices

Entity ID Strategy

Use consistent, unique identifiers for your entities
Consider using prefixes for different entity types (e.g., user_123, session_456)
Keep entity IDs stable across your system

Tagging Strategy

Use consistent tag keys across your organization
Include timestamps in tags when relevant
Use tags for filtering and categorization, not for storing large data

Memory Store Organization

Create separate stores for different contexts (customers, products, sessions)
Use descriptive keys and descriptions to help agents understand the purpose
Consider data retention needs when designing your store structure

Common Use Cases

Customer Support Memory

# Create a store for customer interactions
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '{
  "key": "support_interactions",
  "description": "Customer support ticket history and resolutions",
  "path": "default",
  "embedding_config": {"model": "openai/text-embedding-3-small"}
}'

# Create memory for a customer
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores/support_interactions/memories \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '{
  "entity_id": "customer_789",
  "tags": {"tier": "premium", "product": "enterprise"}
}'

# Add interaction history (use the memory_id from previous response)
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores/support_interactions/memories/<memory_id>/documents \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '{
  "text": "Issue: Login problems. Resolution: Reset password and enabled 2FA. Customer satisfied with quick resolution.",
  "tags": {"ticket_id": "SUP-2024-001", "category": "authentication", "resolved": "true"}
}'

# Create a store for customer interactions
client.memory_stores.create(
    key="support_interactions",
    description="Customer support ticket history and resolutions",
    path="default",
    embedding_config={"model": "openai/text-embedding-3-small"}
)

# Create memory for a customer
memory = client.memory_stores.create_memory(
    memory_store_key="support_interactions",
    entity_id="customer_789",
    tags={"tier": "premium", "product": "enterprise"}
)

# Add interaction history
client.memory_stores.create_document(
    memory_store_key="support_interactions",
    memory_id=memory["_id"],
    text="Issue: Login problems. Resolution: Reset password and enabled 2FA. Customer satisfied with quick resolution.",
    tags={
        "ticket_id": "SUP-2024-001",
        "category": "authentication",
        "resolved": "true"
    }
)

// Create a store for customer interactions
await client.memoryStores.create({
  key: 'support_interactions',
  description: 'Customer support ticket history and resolutions',
  path: 'default',
  embedding_config: {
    model: 'openai/text-embedding-3-small',
  },
});

// Create memory for a customer
const memory = await client.memoryStores.createMemory({
  memory_store_key: 'support_interactions',
  entity_id: 'customer_789',
  tags: {
    tier: 'premium',
    product: 'enterprise',
  },
});

// Add interaction history
await client.memoryStores.createDocument({
  memory_store_key: 'support_interactions',
  memory_id: memory._id,
  text: 'Issue: Login problems. Resolution: Reset password and enabled 2FA. Customer satisfied with quick resolution.',
  tags: {
    ticket_id: 'SUP-2024-001',
    category: 'authentication',
    resolved: 'true',
  },
});

Session Context Memory

# Create ephemeral session memory
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '{
  "key": "chat_sessions",
  "description": "Temporary chat session context",
  "path": "default",
  "embedding_config": {"model": "openai/text-embedding-3-small"}
}'

# Store conversation context
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores/chat_sessions/memories \
     --header 'authorization: Bearer <your_orq_key>' \
     --header 'content-type: application/json' \
     --data '{
  "entity_id": "session_abc123",
  "tags": {"user_id": "user_456", "started_at": "2024-01-20T10:00:00Z"}
}'

import datetime

# Create ephemeral session memory
client.memory_stores.create(
    key="chat_sessions",
    description="Temporary chat session context",
    path="default",
    embedding_config={"model": "openai/text-embedding-3-small"}
)

# Store conversation context
session_memory = client.memory_stores.create_memory(
    memory_store_key="chat_sessions",
    entity_id=f"session_{session_id}",
    tags={
        "user_id": user_id,
        "started_at": datetime.datetime.now().isoformat()
    }
)

// Create ephemeral session memory
await client.memoryStores.create({
  key: 'chat_sessions',
  description: 'Temporary chat session context',
  path: 'default',
  embedding_config: {
    model: 'openai/text-embedding-3-small',
  },
});

// Store conversation context
const sessionMemory = await client.memoryStores.createMemory({
  memory_store_key: 'chat_sessions',
  entity_id: `session_${sessionId}`,
  tags: {
    user_id: userId,
    started_at: new Date().toISOString(),
  },
});

Error Handling

All methods can throw errors for various reasons:

try {
  await client.memoryStores.create({
    key: 'test_store',
    description: 'Test memory store',
    path: 'default',
    embedding_config: {
      model: 'openai/text-embedding-3-small',
    },
  });
} catch (error) {
  if (error.status === 409) {
    console.error('Memory store key already exists');
  } else if (error.status === 401) {
    console.error('Invalid API key');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Python SDK

The same functionality is available in Python:

from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

# Create a memory store
store = client.memory_stores.create(
    key="customer_information",
    description="Customer interaction history",
    path="default",
    embedding_config={"model": "openai/text-embedding-3-small"}
)

# Create a memory
memory = client.memory_stores.create_memory(
    memory_store_key="customer_information",
    entity_id="customer_456",
    tags={"type": "customer", "segment": "premium"}
)

# Add a document
document = client.memory_stores.create_document(
    memory_store_key="customer_information",
    memory_id=memory["_id"],
    text="Customer preferences and interaction notes",
    tags={"source": "crm", "date": "2024-01-15"}
)