Hindsight Cloud Docs

Appearance

Retain memories ​

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

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).

Authentication required — include an Authorization: Bearer hsk_... header. See Authentication for details.

Path Parameters ​

NameTypeRequiredDescription
bank_idstringYes

Request Body ​

Content-Type: application/json

json
{
  "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"
    }
  ]
}

Example Request ​

bash
curl -X POST 'https://api.hindsight.vectorize.io/v1/default/banks/your-bank-id/memories' \
  -H 'Authorization: Bearer hsk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "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"
      }
    ]
  }'

Responses ​

200 — Successful Response

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

422 — Validation Error

json
{
  "detail": [
    {
      "loc": [
        null
      ],
      "msg": "Message",
      "type": "Error Type",
      "input": null,
      "ctx": {},
      "url": "URL"
    }
  ]
}

Source: /v1/default/banks/{bank_id}/memories