Memories

Memories serve as the foundational data layer for maintaining context and storing information across conversations and interactions. They enable bots and applications to recall previous information, maintain user preferences, and provide personalized experiences based on historical data.

Unlike bot memories which are automatically created during conversations, general memories can be manually created, updated, and managed through the API, providing explicit control over what information is stored and how it is organized. This makes them ideal for importing external data, storing structured information, or maintaining application-specific context.

Creating Memories

Creating a memory allows you to store arbitrary text content along with optional metadata, enabling you to build custom knowledge bases or maintain contextual information for your applications. Each memory can be associated with a specific bot or contact, providing scoped access and organization.

To create a memory, you need to provide the text content and optionally specify a name, description, and resource associations. The memory will be stored with a unique identifier that can be used for future retrieval, updates, or deletion.

POST /api/v1/memory/create
Content-Type: application/json

{
  "name": "Customer Preference",
  "description": "Preferred communication style",
  "text": "Customer prefers email communication and detailed explanations",
  "botId": "bot_123",
  "contactId": "contact_456"
}

http

The text field contains the actual content of the memory and is required. The name and description fields help organize and identify memories when browsing or searching. The botId and contactId fields allow you to associate the memory with specific resources, making it easier to filter and retrieve relevant memories later.

Listing Memories

Listing memories enables you to retrieve all stored memories in your account, with support for pagination and filtering by associated resources. This is essential for browsing your memory collection, auditing stored information, and managing your data at scale.

The list endpoint returns memories in reverse chronological order by default, showing the most recently created memories first. You can control pagination using cursor-based navigation, which ensures consistent results even as new memories are created during iteration.

GET /api/v1/memory/list?take=20&order=desc

http

To filter memories by bot or contact, use query parameters:

GET /api/v1/memory/list?botId=bot_123&take=50

http

The response includes all memory details such as id, name, description, text content, associated bot and contact IDs, metadata, and timestamps. Use the cursor parameter from the response to fetch the next page of results:

GET /api/v1/memory/list?cursor=eyJpZCI6ImN1cnNvcl92YWx1ZSJ9&take=20

http

Parameters:

  • take - Number of memories to retrieve (default varies by endpoint)
  • order - Sort order: asc or desc (default: desc)
  • cursor - Pagination cursor from previous response
  • botId - Filter by associated bot ID
  • contactId - Filter by associated contact ID

The listing operation is optimized for performance and supports filtering through query parameters, making it easy to retrieve specific subsets of memories without loading your entire collection.

Fetching a Memory

Fetching a specific memory retrieves all details for a single memory by its unique identifier. This operation is useful when you need to access the complete information for a particular memory, whether for display purposes, verification, or as part of a larger workflow.

To fetch a memory, you need its unique ID which is returned when the memory is created or can be obtained from listing operations. The fetch operation returns the complete memory object including all fields and metadata.

GET /api/v1/memory/{memoryId}/fetch

http

For example, to fetch a memory with ID mem_123abc:

GET /api/v1/memory/mem_123abc/fetch

http

The response includes all memory properties:

  • id - Unique memory identifier
  • name - Memory name for organization
  • description - Detailed description
  • text - The actual content stored in the memory
  • botId - Associated bot ID (if any)
  • contactId - Associated contact ID (if any)
  • meta - Additional metadata as JSON
  • createdAt - Creation timestamp
  • updatedAt - Last modification timestamp

Updating a Memory

Updating a memory allows you to modify any aspect of an existing memory, including its content, name, description, associations, and metadata. This is essential for maintaining accurate information as requirements change or new information becomes available.

The update operation supports partial updates, meaning you only need to include the fields you want to modify. Fields not included in the request will remain unchanged. This makes it easy to update specific aspects without having to resend the entire memory object.

POST /api/v1/memory/{memoryId}/update
Content-Type: application/json

{
  "text": "Updated memory content with new information",
  "description": "Updated description reflecting changes"
}

http

You can update any combination of fields in a single request:

POST /api/v1/memory/mem_123abc/update
Content-Type: application/json

{
  "name": "Updated Preference",
  "text": "Customer now prefers phone calls for urgent matters",
  "botId": "bot_456",
  "meta": {
    "lastModifiedBy": "automation",
    "priority": "high"
  }
}

http

Available Fields:

  • name - Update the memory's name
  • description - Update the description
  • text - Update the memory content
  • botId - Change or set the associated bot
  • contactId - Change or set the associated contact
  • meta - Update or merge metadata

Deleting a Memory

Deleting a memory permanently removes it from your account, including all associated content and metadata. This operation is irreversible, so ensure you have appropriate backups or confirmations before proceeding with deletion.

To delete a memory, you need its unique identifier. The operation will immediately remove the memory from storage and return the ID of the deleted memory as confirmation.

POST /api/v1/memory/{memoryId}/delete
Content-Type: application/json

{}

http

For example, to delete a memory with ID mem_123abc:

POST /api/v1/memory/mem_123abc/delete
Content-Type: application/json

{}

http

The response will confirm the deletion by returning the ID of the deleted memory:

{
  "id": "mem_123abc"
}

json

Important Considerations:

  • Deletion is permanent and cannot be undone
  • The memory will be immediately unavailable for all operations
  • Associated bot or contact references will be removed
  • Any searches or listings will no longer include the deleted memory

Note: Deleting a memory does not affect the bots or contacts it was associated with. Only the memory itself is removed. If you need to maintain a history of deletions, consider implementing a soft delete pattern using metadata fields instead of permanent deletion.

Searching Memories

Searching memories enables you to find relevant information using semantic similarity matching, going beyond simple keyword searches to understand the meaning and context of your query. This powerful search capability helps you discover memories that are conceptually related, even when they don't contain exact matching terms.

The search operation uses vector embeddings to find semantically similar content, making it ideal for natural language queries and fuzzy matching scenarios. This is particularly useful when you need to find information but don't remember the exact wording, or when searching for conceptually related content across your memory collection.

POST /api/v1/memory/search
Content-Type: application/json

{
  "search": "customer refund policy"
}

http

To narrow your search to memories associated with specific resources, use optional filter parameters:

POST /api/v1/memory/search
Content-Type: application/json

{
  "search": "payment preferences",
  "botId": "bot_123",
  "contactId": "contact_456"
}

http

The search returns up to 50 of the most relevant memories, ordered by similarity score. Each result includes the memory ID, full text content, and associated metadata, allowing you to access complete memory details without additional API calls.

Search Parameters:

  • search (required) - The query text to search for
  • botId (optional) - Filter results to memories associated with this bot
  • contactId (optional) - Filter results to memories associated with this contact

The semantic search understands context and relationships between concepts, making it more effective than traditional text matching for finding relevant information in natural language scenarios. Results are automatically limited to 50 memories to ensure performance while providing comprehensive coverage of relevant matches.

Note: For bot-specific or contact-specific memory searches, use the dedicated routes at /api/v1/bot/{botId}/memory/search and /api/v1/contact/{contactId}/memory/search which are scoped to those specific resources.

Exporting Memories

Exporting memories allows you to retrieve your entire memory collection in various formats suitable for backup, data migration, or integration with external systems. The export endpoint supports multiple output formats including JSON, JSONL (JSON Lines), and CSV, providing flexibility for different use cases and downstream processing requirements.

Unlike the standard list endpoint, the export operation is optimized for bulk data retrieval and includes special handling for metadata serialization, making it ideal for creating complete backups or transferring data between systems. The endpoint supports the same pagination and filtering capabilities as the list operation, allowing you to export specific subsets of your memory collection.

GET /api/v1/memory/export?take=1000&order=desc
Accept: application/json

http

To export memories in different formats, specify the appropriate Accept header:

JSON Format (default):

GET /api/v1/memory/export
Accept: application/json

http

JSONL Format (one memory per line):

GET /api/v1/memory/export
Accept: application/jsonl

http

CSV Format (spreadsheet compatible):

GET /api/v1/memory/export
Accept: text/csv

http

The export includes all memory fields with proper formatting for each output type. Metadata is serialized to YAML format when exported to CSV for better readability, while JSON and JSONL formats preserve the native JSON structure.

Export Parameters:

  • take - Number of memories per page (for pagination)
  • order - Sort order: asc or desc
  • cursor - Pagination cursor for fetching subsequent pages

Use Cases:

  • Creating regular backups of your memory collection
  • Migrating data between ChatBotKit accounts
  • Integrating with external data processing systems
  • Generating reports from memory data
  • Archiving historical information

For large memory collections, use pagination to retrieve data in manageable chunks, which helps prevent timeouts and reduces memory usage during export operations.

Go to cbk.ai