VEvectorize
Memory

Retain memories

Changed on

Retain memory items with automatic fact extraction.

This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the async parameter.

Features:

  • Efficient batch processing
  • Automatic fact extraction from natural language
  • Entity recognition and linking
  • Document tracking with automatic upsert (when document_id is provided)
  • Temporal and semantic linking
  • Optional asynchronous processing

The system automatically:

  1. Extracts semantic facts from the content
  2. Generates embeddings
  3. Deduplicates similar facts
  4. Creates temporal, semantic, and entity links
  5. Tracks document metadata

When async=true: Returns immediately after queuing. Use the operations endpoint to monitor progress.

When async=false (default): Waits for processing to complete.

Note: If a memory item has a document_id that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).

post/v1/default/banks/{bank_id}/memories

Request

Path parameters

bank_idstring required

Headers

authorizationstring nullable

Request body

asyncboolean

If true, process asynchronously in background. If false, wait for completion (default: false)

document_tagsstring[] nullable

Deprecated. Use item-level tags instead.

operation_idstring nullable

Optional client-supplied UUID used as the identity of an async retain operation. Re-submitting with the same operation_id returns the original operation and creates no new work, so retrying after a lost or timed-out acknowledgement will not enqueue a duplicate. Reusing an id that belongs to a different operation returns HTTP 409. Ignored for synchronous retain.

Example request

{
  "async": false,
  "items": [
    {
      "content": "Alice works at Google",
      "context": "work",
      "document_id": "conversation_123"
    },
    {
      "content": "Bob went hiking yesterday",
      "document_id": "conversation_123",
      "timestamp": "2024-01-15T10:00:00Z"
    }
  ]
}

Response

Successful Response

successboolean required
bank_idstring required
items_countinteger required
asyncboolean required

Whether the operation was processed asynchronously

operation_idstring nullable

Operation ID for tracking async operations. Use GET /v1/default/banks/{bank_id}/operations to list operations. Only present when async=true. When items use different per-item strategies, use operation_ids instead.

operation_idsstring[] nullable

Operation IDs when items were submitted as multiple strategy groups (async=true with mixed per-item strategies). operation_id is set to the first entry for backward compatibility.

Example response

{
  "async": false,
  "bank_id": "user123",
  "items_count": 2,
  "success": true,
  "usage": {
    "input_tokens": 500,
    "output_tokens": 100,
    "total_tokens": 600
  }
}

Changes

  • 4fda98b75f63Revision changes
    • warning

      removed the optional property // from the response with the status

    • info

      added the new optional request property //

    • info

      added the new optional request property

    • info

      added the new shared enum value to the request property ///

    • info

      request property // list-of-types was widened by adding types array to media type application/json

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

  • 0d08f271b9dbRevision changes
    • info

      added the new optional request property //

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status