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