Memory API

Store and retrieve long-term knowledge with semantic search capabilities.

Node.js SDK Support

Create and get operations are available in the SDK. List, update, and delete operations are currently available via REST API only. Full SDK support coming soon.

Overview

The Memory API enables persistent storage of facts, preferences, and knowledge that should be retained across dialogues. Unlike dialogue state (which is ephemeral), memories are designed for long-term retention and semantic retrieval.

Key characteristics:

Stored indefinitely until explicitly deleted
Automatically vectorized for semantic search
Can store strings, numbers, booleans, objects, or arrays
Scoped to your project with optional namespace isolation

Create Memory

Store a new piece of information.

Endpoint

http

POST /memory

Authentication

Bearer token (via Authorization header)

Request Body

Field	Type	Required	Description
`value`	string \| number \| boolean \| object \| array	Yes	The memory content to store
`id`	string	No	Custom identifier - auto-generated if not provided
`namespace`	string	No	Optional namespace for isolation (e.g., userId)
`label`	string	No	Human-readable label
`description`	string	No	Detailed description of this memory
`tags`	string[]	No	Tags for categorization
`metadata`	object	No	Custom metadata (immutable after creation)

Response

typescript

{
  id: string;              // Unique identifier
  projectId: string;        // Your project ID
  namespace?: string;       // Namespace if provided
  label?: string;
  description?: string;
  value: any;              // The stored value
  type: "string" | "number" | "boolean" | "object" | "array";
  tags: string[];
  metadata: Record<string, any>;
  created: string;         // ISO 8601 timestamp
  modified: string;        // ISO 8601 timestamp
}

Behavior

Memory id is auto-generated if not provided
Custom IDs allow you to use your own identifiers (e.g., user_123_preferences)
ID uniqueness: Same ID can exist in different namespaces without collision. Creating with same ID + namespace as existing memory returns DUPLICATE_ID error (no upsert)
Value type is automatically detected and indexed
Content is vectorized for semantic search
Namespace enables multi-tenant isolation

Field Mutability

Can be set on creation:

id (optional, user-defined or auto-generated)
namespace (optional)
label
description
value
tags
metadata

Can be updated:

tags - Can be updated via PUT /memory/

Immutable after creation:

id - Cannot be changed
namespace - Cannot be changed
value - Cannot be modified after creation
description - Cannot be modified after creation
label - Cannot be modified after creation
metadata - Cannot be modified
type - Automatically set based on value

System-managed (read-only):

projectId
created
modified

Value Type Handling

DialogueDB automatically detects and indexes the value type:

typescript

// String memory
{ value: "User prefers dark mode" }
// → type: "string"

// Number memory
{ value: 42 }
// → type: "number"

// Boolean memory
{ value: true }
// → type: "boolean"

// Object memory
{ value: { theme: "dark", language: "en" } }
// → type: "object"

// Array memory
{ value: ["feature_a", "feature_b"] }
// → type: "array"

Use Cases

User preferences: Store settings across sessions
Facts and knowledge: Remember information mentioned in conversations
Entity relationships: Store structured data about users, products, etc.
Feature flags: Per-user or per-namespace configuration
Historical context: Long-term information that persists beyond individual conversations

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required `value` field
400	`INVALID_INPUT`	Invalid value format or type
400	`DUPLICATE_ID`	Memory with this id already exists
401	N/A	Unauthorized - invalid or missing API key
429	`RATE_LIMIT_EXCEEDED`	Too many requests - retry with backoff
500	`INTERNAL_ERROR`	Server error - contact support with requestId

See Error Handling for complete error reference.

Examples

cURL - SimplecURL - With Custom KeyTypeScriptNode.js SDK

bash

curl -X POST https://api.dialoguedb.com/memory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "User prefers email notifications",
    "label": "Notification Preference",
    "tags": ["preferences", "notifications"]
  }'

bash

curl -X POST https://api.dialoguedb.com/memory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_789_theme",
    "value": { "theme": "dark", "fontSize": 16 },
    "label": "UI Preferences",
    "namespace": "user_789"
  }'

typescript

const response = await fetch('https://api.dialoguedb.com/memory', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    value: 'User is allergic to peanuts',
    label: 'Dietary Restriction',
    description: 'Critical health information',
    tags: ['health', 'dietary'],
    metadata: {
      severity: 'critical',
      verified: true
    }
  })
});

const memory = await response.json();
console.log('Memory id:', memory.id);

typescript

import { api } from 'dialoguedb';

const memory = await api.memory.create({
  value: {
    firstName: 'Jane',
    lastName: 'Doe',
    company: 'Acme Corp'
  },
  label: 'User Profile',
  namespace: 'user_456',
  tags: ['profile', 'customer']
});

Get Memory

Retrieve a memory by its id.

Endpoint

http

GET /memory/{id}

Authentication

Bearer token (via Authorization header)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Memory identifier

Response

typescript

{
  id: string;
  projectId: string;
  namespace?: string;
  label?: string;
  description?: string;
  value: any;
  type: string;
  tags: string[];
  metadata: Record<string, any>;
  created: string;
  modified: string;
}

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required parameter
401	N/A	Unauthorized - invalid or missing API key
404	`MEMORY_NOT_FOUND`	Memory does not exist
429	`RATE_LIMIT_EXCEEDED`	Too many requests - retry with backoff
500	`INTERNAL_ERROR`	Server error - contact support with requestId

Examples

cURLTypeScriptNode.js SDK

bash

curl -X GET https://api.dialoguedb.com/memory/user_789_theme \
  -H "Authorization: Bearer YOUR_API_KEY"

typescript

const response = await fetch(
  `https://api.dialoguedb.com/memory/${memoryId}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const memory = await response.json();

typescript

import { api } from 'dialoguedb';

const memory = await api.memory.get('user_789_theme');
console.log(memory.value); // { theme: "dark", fontSize: 16 }

List Memories

Retrieve memories with filtering and pagination.

Endpoint

http

GET /memory

Authentication

Bearer token (via Authorization header)

Query Parameters

Parameter	Type	Required	Description
`namespace`	string	No	Filter by namespace
`limit`	number	No	Maximum items per page (default: 50)
`order`	string	No	Sort order: "asc" or "desc" (default: "desc")
`next`	string	No	Pagination token from previous response
`created`	string	No	Filter by exact creation date (ISO 8601)
`startDate`	string	No	Filter memories created after this date
`endDate`	string	No	Filter memories created before this date

Response

typescript

{
  items: Memory[];
  next?: string;  // Pagination token if more results exist
}

Behavior

Results sorted by creation date
Automatically scoped to your project
Use namespace for multi-tenant filtering
Paginated - use next token for additional pages

Errors

Status	Error Code	Description
400	`INVALID_PARAMETER`	Invalid filter or pagination parameters
401	N/A	Unauthorized - invalid or missing API key
429	`RATE_LIMIT_EXCEEDED`	Too many requests - retry with backoff
500	`INTERNAL_ERROR`	Server error - contact support with requestId

Examples

cURL - BasiccURL - With NamespaceTypeScriptNode.js SDK

bash

curl -X GET "https://api.dialoguedb.com/memory?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

bash

curl -X GET "https://api.dialoguedb.com/memory?namespace=user_789&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

typescript

const response = await fetch(
  'https://api.dialoguedb.com/memory?limit=20&order=desc',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const { items, next } = await response.json();

// Paginate if needed
if (next) {
  const nextPage = await fetch(
    `https://api.dialoguedb.com/memory?limit=20&next=${next}`,
    { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
  );
}

typescript

// SDK list support coming soon - use REST API
const response = await fetch(
  'https://api.dialoguedb.com/memory?namespace=user_789&limit=50',
  {
    headers: {
      'Authorization': `Bearer ${process.env.DIALOGUE_DB_API_KEY}`
    }
  }
);

const { items, next } = await response.json();
console.log(`Found ${items.length} memories`);

Update Memory

Update an existing memory's tags.

Endpoint

http

PUT /memory/{id}

Authentication

Bearer token (via Authorization header)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Memory identifier

Request Body

Field	Type	Required	Description
`tags`	string[]	Yes	Updated tags (replaces existing)

Response

typescript

{
  id: string;
  projectId: string;
  id: string;
  namespace?: string;
  label?: string;
  description?: string;
  value: any;
  type: string;
  tags: string[];
  metadata: Record<string, any>;
  created: string;
  modified: string;
}

Behavior

Only tags can be updated after creation
Tags are replaced entirely (not merged)
Value, description, label, id, and metadata are immutable after creation

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required id or tags parameter
400	`INVALID_INPUT`	Invalid tags format
401	N/A	Unauthorized - invalid or missing API key
404	`MEMORY_NOT_FOUND`	Memory does not exist
429	`RATE_LIMIT_EXCEEDED`	Too many requests - retry with backoff
500	`INTERNAL_ERROR`	Server error - contact support with requestId

Examples

cURLTypeScriptNode.js SDK

bash

curl -X PUT https://api.dialoguedb.com/memory/01HX5ZQXQY9J8K7F6E5D4C3B2A \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["preferences", "ui-settings", "active"]
  }'

typescript

const response = await fetch(
  `https://api.dialoguedb.com/memory/${memoryId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tags: ['preferences', 'ui-settings', 'active']
    })
  }
);

const memory = await response.json();

typescript

// SDK update support coming soon - use REST API
const response = await fetch(
  `https://api.dialoguedb.com/memory/${memoryId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.DIALOGUE_DB_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tags: ['preferences', 'ui-settings', 'active']
    })
  }
);

const memory = await response.json();

Delete Memory

Permanently remove a memory.

Endpoint

http

DELETE /memory/{id}

Authentication

Bearer token (via Authorization header)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Memory identifier

Response

typescript

{
  success: boolean;
  id: string;
}

Behavior

Permanently deletes the memory
Removes from vector search index
This operation cannot be undone

Warnings

Irreversible: Deleted memories cannot be recovered
Search impact: Memory immediately removed from semantic search results
Consider soft deletion: Use metadata flags instead if you need audit trails

Errors

Status	Error Code	Description
400	`MISSING_PARAMETER`	Missing required value parameter
401	N/A	Unauthorized - invalid or missing API key
404	`MEMORY_NOT_FOUND`	Memory does not exist
429	`RATE_LIMIT_EXCEEDED`	Too many requests - retry with backoff
500	`INTERNAL_ERROR`	Server error - contact support with requestId

Examples

cURLTypeScriptNode.js SDK

bash

curl -X DELETE https://api.dialoguedb.com/memory/user_789_theme \
  -H "Authorization: Bearer YOUR_API_KEY"

typescript

const response = await fetch(
  `https://api.dialoguedb.com/memory/${memoryId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const result = await response.json();

typescript

// SDK delete support coming soon - use REST API
const response = await fetch(
  `https://api.dialoguedb.com/memory/user_789_theme`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${process.env.DIALOGUE_DB_API_KEY}`
    }
  }
);

const result = await response.json();

Semantic Search

Search memories using natural language queries. See the Search API documentation for details.

typescript

// Search for memories semantically
const results = await fetch(
  'https://api.dialoguedb.com/search?query=user%20preferences&object=memory',
  {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

Best Practices

Namespace for Multi-Tenancy

Use namespaces to isolate memories by user or organization:

typescript

// Store user-specific memory
await createMemory({
  value: 'Prefers morning appointments',
  namespace: 'user_456',
  label: 'Scheduling Preference'
});

// Retrieve only this user's memories
const { items } = await listMemories({
  namespace: 'user_456'
});

Custom Keys for Predictable Access

Use custom ids when you need deterministic identifiers:

typescript

// Instead of random ULID
await createMemory({
  id: `user_${userId}_theme`,
  value: { theme: 'dark' }
});

// Easy retrieval without database lookup
const theme = await getMemory(`user_${userId}_theme`);

Updating Memory Values

Memory values can be updated directly via PUT endpoint:

typescript

// Update memory value
await updateMemory(memoryId, {
  value: 'New preference value',
  description: 'Updated description'
});

Tagging for Organization

Use tags for categorization and filtering:

typescript

await createMemory({
  value: 'Vegetarian diet',
  tags: ['dietary', 'preferences', 'health'],
  label: 'Dietary Restriction'
});

// Search by tags using semantic search
const results = await fetch(
  'https://api.dialoguedb.com/search?query=dietary%20preferences&object=memory',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

Metadata for Context

Store immutable context with metadata:

typescript

await createMemory({
  value: 'Enterprise account',
  metadata: {
    tier: 'enterprise',
    signupDate: '2025-01-15',
    verified: true
  }
});

Memory vs. State vs. Messages

Understanding when to use each storage type:

Feature	Memory	State	Messages
Lifespan	Indefinite	Per-dialogue	Per-dialogue
Search	Semantic vector search	Not searchable	Semantic vector search
Updates	Mutable (PUT)	Full replace (PUT)	Immutable
Use Case	Long-term facts	Conversation context	Turn-by-turn dialogue
Scope	Global or namespace	Dialogue-specific	Dialogue-specific

Use Memory when:

Information should persist across multiple dialogues
You need semantic search capabilities
Storing facts, preferences, or knowledge

Use State when:

Tracking conversation-specific context
Need to update frequently
Temporary session data

Use Messages when:

Recording actual conversation turns
Need chronological conversation history
Building context for LLM prompts

Search API - Semantic search across memories
State API - Dialogue-specific state management
Dialogues API - Conversation management

Memory API ​

Overview ​

Create Memory ​

Endpoint ​

Authentication ​

Request Body ​

Response ​

Behavior ​

Field Mutability ​

Value Type Handling ​

Use Cases ​

Errors ​

Examples ​

Get Memory ​

Endpoint ​

Authentication ​

Path Parameters ​

Response ​

Errors ​

Examples ​

List Memories ​

Endpoint ​

Authentication ​

Query Parameters ​

Response ​

Behavior ​

Errors ​

Examples ​

Update Memory ​

Endpoint ​

Authentication ​

Path Parameters ​

Request Body ​

Response ​

Behavior ​

Errors ​

Examples ​

Delete Memory ​

Endpoint ​

Authentication ​

Path Parameters ​

Response ​

Behavior ​

Warnings ​

Errors ​

Examples ​

Semantic Search ​

Best Practices ​

Namespace for Multi-Tenancy ​

Custom Keys for Predictable Access ​

Updating Memory Values ​

Tagging for Organization ​

Metadata for Context ​

Memory vs. State vs. Messages ​

Related Endpoints ​

Memory API

Overview

Create Memory

Endpoint

Authentication

Request Body

Response

Behavior

Field Mutability

Value Type Handling

Use Cases

Errors

Examples

Get Memory

Endpoint

Authentication

Path Parameters

Response

Errors

Examples

List Memories

Endpoint

Authentication

Query Parameters

Response

Behavior

Errors

Examples

Update Memory

Endpoint

Authentication

Path Parameters

Request Body

Response

Behavior

Errors

Examples

Delete Memory

Endpoint

Authentication

Path Parameters

Response

Behavior

Warnings

Errors

Examples

Semantic Search

Best Practices

Namespace for Multi-Tenancy

Custom Keys for Predictable Access

Updating Memory Values

Tagging for Organization

Metadata for Context

Memory vs. State vs. Messages

Related Endpoints