---
id: retain-memories
title: "Retain memories"
description: "Retain memory items with automatic fact extraction."
sidebar_label: "Retain memories"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api-reference/endpoints/hindsight-http-api
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retain memories"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/v1/default/banks/{bank_id}/memories"}
  context={"endpoint"}
>
  
</MethodEndpoint>



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 on items)
    - 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 the task
    - Processing happens in the background
    - Use the operations endpoint to monitor progress

    When async=false (default):
    - Waits for processing to complete
    - Returns after all memories are stored

    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). Items with the same document_id are grouped together for efficient processing.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"bank_id","in":"path","required":true,"schema":{"type":"string","title":"Bank Id"}}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"properties":{"items":{"items":{"properties":{"content":{"type":"string","title":"Content"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp"},"context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Context"},"metadata":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metadata"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id","description":"Optional document ID for this memory item."}},"type":"object","required":["content"],"title":"MemoryItem","description":"Single memory item for retain.","example":{"content":"Alice mentioned she's working on a new ML model","context":"team meeting","document_id":"meeting_notes_2024_01_15","metadata":{"channel":"engineering","source":"slack"},"timestamp":"2024-01-15T10:30:00Z"}},"type":"array","title":"Items"},"async":{"type":"boolean","title":"Async","description":"If true, process asynchronously in background. If false, wait for completion (default: false)","default":false}},"type":"object","required":["items"],"title":"RetainRequest","description":"Request model for retain endpoint.","example":{"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"}]}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"success":{"type":"boolean","title":"Success"},"bank_id":{"type":"string","title":"Bank Id"},"items_count":{"type":"integer","title":"Items Count"},"async":{"type":"boolean","title":"Async","description":"Whether the operation was processed asynchronously"}},"type":"object","required":["success","bank_id","items_count","async"],"title":"RetainResponse","description":"Response model for retain endpoint.","example":{"async":false,"bank_id":"user123","items_count":2,"success":true}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"}}}}}}
>
  
</StatusCodes>