Hindsight Cloud Docs

Appearance

Recall memory ​

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

Recall memory using semantic similarity and spreading activation.

The type parameter is optional and must be one of:

  • world: General knowledge about people, places, events, and things that happen
  • experience: Memories about experience, conversations, actions taken, and tasks performed

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

Path Parameters ​

NameTypeRequiredDescription
bank_idstringYes

Request Body ​

Content-Type: application/json

json
{
  "budget": "mid",
  "include": {
    "entities": {
      "max_tokens": 500
    }
  },
  "max_tokens": 4096,
  "query": "What did Alice say about machine learning?",
  "query_timestamp": "2023-05-30T23:40:00",
  "tags": [
    "user_a"
  ],
  "tags_match": "any",
  "trace": true,
  "types": [
    "world",
    "experience"
  ]
}

Example Request ​

bash
curl -X POST 'https://api.hindsight.vectorize.io/v1/default/banks/your-bank-id/memories/recall' \
  -H 'Authorization: Bearer hsk_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "budget": "mid",
    "include": {
      "entities": {
        "max_tokens": 500
      }
    },
    "max_tokens": 4096,
    "query": "What did Alice say about machine learning?",
    "query_timestamp": "2023-05-30T23:40:00",
    "tags": [
      "user_a"
    ],
    "tags_match": "any",
    "trace": true,
    "types": [
      "world",
      "experience"
    ]
  }'

Responses ​

200 — Successful Response

json
{
  "chunks": {
    "456e7890-e12b-34d5-a678-901234567890": {
      "chunk_index": 0,
      "id": "456e7890-e12b-34d5-a678-901234567890",
      "text": "Alice works at Google on the AI team. She's been there for 3 years..."
    }
  },
  "entities": {
    "Alice": {
      "canonical_name": "Alice",
      "entity_id": "123e4567-e89b-12d3-a456-426614174001",
      "observations": [
        {
          "mentioned_at": "2024-01-15T10:30:00Z",
          "text": "Alice works at Google on the AI team"
        }
      ]
    }
  },
  "results": [
    {
      "chunk_id": "456e7890-e12b-34d5-a678-901234567890",
      "context": "work info",
      "entities": [
        "Alice",
        "Google"
      ],
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "occurred_end": "2024-01-15T10:30:00Z",
      "occurred_start": "2024-01-15T10:30:00Z",
      "text": "Alice works at Google on the AI team",
      "type": "world"
    }
  ],
  "trace": {
    "num_results": 1,
    "query": "What did Alice say about machine learning?",
    "time_seconds": 0.123
  }
}

422 — Validation Error

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

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