Use this file to discover all available pages before exploring further.
The retain endpoint ingests raw content into a memory bank and transforms it into structured, queryable memories. Hindsight runs LLM-based fact extraction on the content, resolves entities against the existing knowledge graph, and stores the resulting facts — not the original text. A single retain call can produce many memories depending on how much information the content contains.
To learn about fact extraction, entity resolution, and graph construction in depth, see the Retain Architecture guide.
One or more content items to retain. Each item is a piece of raw content — a conversation, document, or note — that Hindsight will analyze and decompose into structured memories.
When the event described in the content occurred. Accepts ISO 8601 strings (e.g. "2024-01-15T10:30:00Z"), null to default to the current ingestion time, or "unset" to store the content without any timestamp. Use "unset" for timeless reference material such as books or documentation.
A short label describing the source or situation — for example "team meeting", "slack", or "support ticket". Injected directly into the LLM extraction prompt, so it actively shapes how facts are interpreted. Providing context consistently is one of the highest-leverage things you can do to improve memory quality.
Arbitrary key-value string pairs that provide context about this item. For example: {"source": "slack", "channel": "engineering", "thread_id": "T123"}. Metadata is included in the extraction prompt and stored on each extracted memory, so it is returned with every recall result.
A caller-supplied string that groups one or more items under a logical document and makes retain idempotent. When provided, Hindsight upserts the document: if a document with that ID already exists, it and all its associated memories are deleted before the new content is processed. Omit to assign a random UUID per request, which will create duplicate memories on re-ingestion.
Controls how Hindsight handles an existing document when retaining with a document_id that already exists. "replace" deletes the old document and all its memories, then processes the new content from scratch. "append" concatenates the new content onto the existing document and reprocesses the combined document — only new chunks trigger LLM extraction. Append mode requires a document_id.
Tags that scope which memories are visible during recall. A memory is only returned if its tags intersect with the tags filter provided in the recall or reflect request. Use consistent naming patterns: user:<id>, session:<id>, room:<id>.
A list of entities you want guaranteed recognition for, merged with any entities the LLM extracts automatically. Each entry has a text field (the entity name) and an optional type (e.g. "PERSON", "ORG", "CONCEPT" — defaults to "CONCEPT" if omitted).
Controls which observation scopes this memory contributes to during consolidation. Accepted values: "combined" (default — one pass using all tags together), "per_tag" (one pass per individual tag), "all_combinations" (one pass per subset of tags), or a custom list of tag sets (e.g. [["student:alice"], ["teacher:bob"]]).
When true, the call returns immediately with an operation_id and processing runs in the background via the worker service. No usage metrics are returned for async operations. Recommended for large batches or when combined with the provider Batch API for 50% cost reduction.
Tags applied to all items in this request batch (merged with per-item tags). Useful for tagging an entire batch with shared metadata such as a session ID.
Submit multiple items in a single request to reduce network overhead. Hindsight processes the batch and can optimize extraction across related content.
curl -X POST "https://your-hindsight-host/v1/default/banks/my-bank/retain" \ -H "Authorization: Bearer $HINDSIGHT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "items": [ { "content": "Alice prefers async communication.", "context": "slack", "tags": ["user:alice"] }, { "content": "Bob joined the engineering team in Q1 2024.", "context": "hr-system", "tags": ["user:bob"] } ] }'
Enable provider Batch API support for 50% cost reduction on async retain by setting HINDSIGHT_API_RETAIN_BATCH_ENABLED=true. OpenAI and Groq both offer this discount in exchange for a processing window of up to 24 hours.
