Skip to main content
Memory Stores are 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).

​
Prerequisite

  • A workspace with a Project and Folder.
  • An API Key ready to be used with the API.

​
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 <ORQ_API_KEY>'

​
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 <ORQ_API_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"
  }
}'
The key is immutable and must be unique within your workspace. 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 <ORQ_API_KEY>'

​
Update Memory Store

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

​
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 <ORQ_API_KEY>'
Warning: Deleting a memory store is permanent and will remove all memories and documents within it. This action cannot be undone.

​
Memories

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.
To access a memory, use the Memory Store Key previously created, we’ll be using customer_information from our example.

​
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 <ORQ_API_KEY>'

​
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 <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "entity_id": "customer_456",
  "tags": {
    "type": "customer",
    "segment": "premium",
    "region": "north_america",
    "status": "active"
  }
}'
The ID of the entity will be returned after created

​
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 <ORQ_API_KEY>'

​
Update Memory

Update tags and metadata for an existing memory by its ID 
curl --request PUT \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/01J5XYZABC123 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
  {
  "entity_id": "customer_456",
  "tags": {
    "type": "customer",
    "segment": "enterprise",
    "region": "north_america",
    "status": "vip",
    "last_contact": "2024-01-20"
  }
}'

​
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 <ORQ_API_KEY>'

​
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.
To access Documents we’ll be using the previously created Memory Store Key and Memory ID.

​
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 <ORQ_API_KEY>'

​
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 <ORQ_API_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"
  }
}'
The ID of the document will be returned.

​
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 <ORQ_API_KEY>'

​
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 <ORQ_API_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"
  }
}'

​
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 <ORQ_API_KEY>'

​
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 <ORQ_API_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 <ORQ_API_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 <ORQ_API_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"}
}'

​
Session Context Memory

# Create ephemeral session memory
curl --request POST \
     --url https://api.orq.ai/v2/memory-stores \
     --header 'authorization: Bearer <ORQ_API_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 <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '{
  "entity_id": "session_abc123",
  "tags": {"user_id": "user_456", "started_at": "2024-01-20T10:00:00Z"}
}'

​
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);
  }
}