Memory & Search Reference

Memories are persistent, searchable storage for information that should be recalled across conversations. Unlike dialogue state (scoped to a single conversation), memories persist independently and can be found via semantic search.

Memory Management

All memory operations are on the DialogueDB class.

createMemory

const memory = await db.createMemory({
  value: 'User prefers dark mode',
  label: 'UI Preference',
  description: 'Stores user display preferences',
  namespace: 'user_123',
  tags: ['preferences'],
  metadata: { source: 'settings-page' }
});

Parameters: CreateMemoryInput

Field	Type	Required	Description
value	string | number | boolean | object | any[]	Yes	The stored value
id	string	No	Custom ID (auto-generated if omitted)
namespace	string	No	Namespace for isolation
label	string	No	Human-readable label
description	string	No	Description of the memory
tags	string[]	No	Categorization tags
metadata	Record<string, string | number | boolean>	No	Custom metadata

Returns: Promise<Memory>

getMemory

Retrieve a memory by ID. Returns null if not found.

const memory = await db.getMemory('user-preferences');
const memory = await db.getMemory('user-preferences', 'user_123'); // with namespace

Parameters: id: string, namespace?: string

Returns: Promise<Memory | null>

listMemories

List memories with pagination.

const { items, next } = await db.listMemories({
  limit: 20,
  namespace: 'user_123'
});

Parameters: ListMemoriesFilters (all optional)

Returns: Promise<ListResponse<Memory>>

deleteMemory

Permanently delete a memory.

await db.deleteMemory('memory-id');

Parameters: id: string

Returns: Promise<void>

---

Memory Class

A Memory instance is returned by db.createMemory(), db.getMemory(), db.listMemories(), and db.searchMemories().

Properties

Property	Type	Mutable	Description
id	string	No	Unique identifier
namespace	string?	No	Multi-tenancy namespace
label	string?	No	Human-readable label
description	string?	No	Description
value	string | number | boolean | object | any[]	No	The stored value (deep-cloned for objects)
metadata	Record<string, string | number | boolean>	No	Custom metadata
created	string	No	Creation timestamp (ISO 8601)
modified	string	No	Last modification timestamp
isDirty	boolean	No	true if tags have unsaved changes
tags	string[]	Yes	Categorization tags

saveTags

Set tags and persist immediately.

await memory.saveTags(['archived', 'outdated']);

Parameters: tags: string[]

Returns: Promise<void>

save

Persist any batched changes (currently just tags).

memory.tags = ['archived'];
await memory.save();

Returns: Promise<void>

remove

Delete this memory from the API.

await memory.remove();

Returns: Promise<void>

---

Search Methods

The SDK provides search across dialogues, messages, and memories. Search finds content by meaning, not just keywords.

searchDialogues

const dialogues = await db.searchDialogues('billing questions', {
  limit: 10,
  filter: {
    tags: ['support'],
    createdYear: 2025,
    createdMonth: 6
  },
  metadata: { channel: 'web' }
});

Parameters: query: string, options?: SearchOptions

Returns: Promise<Dialogue[]>

searchMessages

const messages = await db.searchMessages('password reset instructions', {
  limit: 20,
  filter: { tags: ['faq'] }
});

Parameters: query: string, options?: SearchOptions

Returns: Promise<Message[]>

searchMemories

const memories = await db.searchMemories('user preferences', {
  limit: 5,
  filter: { tags: ['settings'] }
});

Parameters: query: string, options?: SearchOptions

Returns: Promise<Memory[]>

SearchOptions

type SearchOptions = {
  limit?: number;
  filter?: SearchFilterOptions;
  metadata?: Record<string, any>;
};

SearchFilterOptions

type SearchFilterOptions = {
  tags?: string[];
  created?: string;
  createdYear?: number;
  createdMonth?: number;   // 1-12
  createdDay?: number;     // 1-31
  modified?: string;
  modifiedYear?: number;
  modifiedMonth?: number;
  modifiedDay?: number;
};

---

Direct API Reference

The api object provides low-level access that maps 1:1 with REST endpoints. Returns plain data objects (not class instances).

import { api, createConfig } from 'dialogue-db';

createConfig({ apiKey: process.env.DIALOGUE_DB_API_KEY });

Namespace	Method	Description
api.dialogue	.create(input)	Create dialogue
api.dialogue	.get(id)	Get dialogue
api.dialogue	.list(filters)	List dialogues
api.dialogue	.update(input)	Update dialogue
api.dialogue	.remove(id)	Delete dialogue
api.dialogue	.end(input)	End dialogue
api.dialogue	.action(input)	Perform dialogue action
api.message	.create(input)	Create single message
api.message	.remove(input)	Delete message
api.messages	.create(input)	Create multiple messages
api.messages	.list(input)	List messages
api.memory	.create(input)	Create memory
api.memory	.get(id)	Get memory
api.memory	.update(input)	Update memory tags
api.memory	.remove(id)	Delete memory
api.search	(input)	Semantic search

Example

// Create a dialogue
const dialogue = await api.dialogue.create({
  messages: [{ role: 'user', content: 'Hello' }]
});

// Add messages
const messages = await api.messages.create({
  id: dialogue.id,
  messages: [{ role: 'assistant', content: 'Hi!' }]
});

// Search
const results = await api.search({
  query: 'billing',
  object: 'message'
});

---

TypeScript Types

import type {
  IMemory,
  CreateMemoryInput,
  ListMemoriesFilters,
  SearchOptions,
  SearchFilterOptions
} from 'dialogue-db';

IMemory

interface IMemory {
  id: string;
  value: string | number | boolean | object | any[];
  metadata: Record<string, string | number | boolean>;
  tags: string[];
  created: string;
  modified: string;
  namespace?: string;
  label?: string;
  description?: string;
}

CreateMemoryInput

type CreateMemoryInput = {
  value: string | number | boolean | object | any[];
  id?: string;
  namespace?: string;
  label?: string;
  description?: string;
  tags?: string[];
  metadata?: Record<string, string | number | boolean>;
};