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', { namespace: 'user_123' });

Parameters: id: string, options?: { namespace?: string }

Returns: Promise<Memory | null>

listMemories

List memories with pagination.

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

Parameters: ListMemoriesFilters (all optional)

Returns: Promise<ListResponse<Memory>>

deleteMemory

Permanently delete a memory.

await db.deleteMemory('memory-id');
await db.deleteMemory('memory-id', { namespace: 'user_123' });

Parameters: id: string, options?: { namespace?: string }

Returns: Promise<void>

---

Memory Class

A Memory instance is returned by db.createMemory(), db.getMemory(), and db.listMemories(). Search methods like db.searchMemories() return Memory instances wrapped in result envelopes — see Search Methods.

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.

All search methods return a SearchResponse object containing a results array and a request echo. Each result wraps the matched item in an envelope with relevance and item:

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

for (const result of response.results) {
  console.log(result.relevance);      // ranking score (higher = more relevant)
  console.log(result.item.content);   // the message content
  console.log(result.item.id);        // the message ID
}

searchDialogues

const response = await db.searchDialogues('billing questions', {
  limit: 10,
  tags: ['support'],
  filter: { created: 'March 2025' },
  metadata: { channel: 'web' }
});

// Each result contains the dialogue in result.item
const dialogues = response.results.map(r => r.item);

Parameters: query: string, options?: SearchOptions

Returns: Promise<SearchResponse<Dialogue>>

searchMessages

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

// Access message data through result.item
response.results.forEach(result => {
  console.log(result.relevance);      // number
  console.log(result.item.content);   // message text
  console.log(result.item.dialogueId); // parent dialogue
});

Parameters: query: string, options?: SearchOptions

Returns: Promise<SearchResponse<Message>>

searchMemories

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

// Access memory data through result.item
const memories = response.results.map(r => r.item);

Parameters: query: string, options?: SearchOptions

Returns: Promise<SearchResponse<Memory>>

SearchOptions

type SearchOptions = {
  limit?: number;
  namespace?: string;
  timezone?: string; // IANA name, e.g. "America/Chicago"; defaults to UTC
  tags?: string[] | { $in?: string[]; $all?: string[]; $nin?: string[] };
  metadata?: Record<
    string,
    | string | number | boolean
    | string[] | number[] | boolean[]
    | {
        $eq?: string | number | boolean;
        $ne?: string | number | boolean;
        $in?: string[] | number[] | boolean[];
        $nin?: string[] | number[] | boolean[];
        $gt?: number | string;
        $gte?: number | string;
        $lt?: number | string;
        $lte?: number | string;
      }
  >;
  filter?: SearchFilterOptions;
  orderBy?: "relevance" | "created" | "modified"; // defaults to "relevance"
  order?: "asc" | "desc";                         // defaults to "desc"
};

SearchFilterOptions

Filter by created or modified time. Each accepts a natural-language string ("last 30 days", "March 2025", "2025") that DialogueDB expands into a range, or a range object for exact boundaries.

type SearchFilterOptions = {
  created?: string | { gte?: string; gt?: string; lte?: string; lt?: string };
  modified?: string | { gte?: string; gt?: string; lte?: string; lt?: string };
};

For the full set of accepted date phrases, tag/metadata operators, and ordering semantics, see the Search API reference.

SearchResponse

All search methods return a SearchResponse containing result envelopes and a request echo:

interface SearchResponse<T> {
  results: Array<{
    object: "message" | "dialogue" | "memory";
    relevance: number;
    item: T;
    matches?: Array<{
      object: "message";
      relevance: number;
      item: Message;
    }>;
  }>;
  request: {
    orderBy: "relevance" | "created" | "modified";
    order: "asc" | "desc";
    candidateOrderBy: "relevance";
    filter?: {
      created?: { gte?: string; gt?: string; lte?: string; lt?: string };
      modified?: { gte?: string; gt?: string; lte?: string; lt?: string };
    };
  };
}

• relevance orders results within one response. Higher means more relevant. Do not treat it as a percentage or compare across searches.
• item is the full Message, Dialogue, or Memory instance.
• matches appears on dialogue results when supporting message evidence is available.

---

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.message	.create(input)	Create single message
api.message	.get(input)	Get single message
api.message	.update(input)	Update 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	.list(filters)	List memories
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 — returns { results, request }
const { results } = await api.search({
  query: 'billing',
  object: 'message'
});
// results[0].relevance — ranking score
// results[0].item — the matched message

---

TypeScript Types

import type {
  IMemory,
  CreateMemoryInput,
  ListMemoriesFilters,
  SearchOptions,
  SearchFilterOptions,
  SearchResponse,
  SearchResultEnvelope,
  SearchMatchEnvelope
} 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>;
};