Retain: Storing Memories

The Retain operation stores new information in a memory bank. Hindsight processes the content, extracts structured memories, and indexes them for efficient retrieval.

Overview

Retain is the primary way to add information to Hindsight:

• Process natural language content
• Extract and categorize memories automatically
• Store world facts, experience, and observations
• Build a searchable knowledge base indexed for TEMPR retrieval

Basic Usage

Python

from hindsight_client import Hindsight

client = Hindsight(
    base_url="https://api.hindsight.vectorize.io",
    api_key="your-api-key"
)

# Simple retain
client.retain(
    bank_id="your-bank-id",
    content="The user's favorite color is blue and they work as a software engineer."
)

TypeScript

import { HindsightClient } from '@vectorize-io/hindsight-client';

const client = new HindsightClient({
  baseUrl: 'https://api.hindsight.vectorize.io',
  apiKey: 'your-api-key'
});

// Simple retain
await client.retain(
  'your-bank-id',
  "The user's favorite color is blue and they work as a software engineer."
);

cURL

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/{bank_id}/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "The user'\''s favorite color is blue and they work as a software engineer."
      }
    ]
  }'

How It Works

When you call Retain:

1. Content Analysis - Hindsight processes your text using AI
2. Memory Extraction - Individual memories are identified
3. Categorization - Each memory is classified by type:
   • World Facts (objective facts from external sources)
   • Experience (events and interactions)
   • Observations (automatically synthesized knowledge consolidated from facts)
4. Indexing - Memories are indexed for TEMPR retrieval (semantic, keyword, graph, temporal)
5. Storage - Data is persisted in the memory bank

Request Parameters

Parameter	Type	Required	Description
bank_id	string	Yes	Target memory bank ID (in URL path)
items	array	Yes	Array of memory items to store
items[].content	string	Yes	Text content to process
items[].context	string	No	Context about the content
items[].timestamp	string	No	ISO 8601 timestamp for the memory
async	boolean	No	Process asynchronously (default: false)

Response

{
  "success": true,
  "bank_id": "my-assistant",
  "items_count": 1,
  "async": false,
  "operation_id": null,
  "usage": {
    "input_tokens": 2684,
    "output_tokens": 511,
    "total_tokens": 3195
  }
}

Field	Description
success	Whether the operation succeeded
bank_id	The memory bank ID
items_count	Number of items processed
async	Whether processed asynchronously
operation_id	ID for tracking async operations
usage	Token consumption breakdown

Content Best Practices

Be Specific

Good

client.retain(
    bank_id=bank_id,
    content="Alice prefers Python over JavaScript for backend development. She has 5 years of experience with FastAPI."
)

Less Effective

client.retain(
    bank_id=bank_id,
    content="User likes coding."
)

Include Context

Good

client.retain(
    bank_id=bank_id,
    content="During our March 15 meeting, the client mentioned they need the report by April 1st and prefer PDF format."
)

Less Effective

client.retain(
    bank_id=bank_id,
    content="Report needed by April 1st."
)

Use Natural Language

Good

client.retain(
    bank_id=bank_id,
    content="The customer is based in Tokyo, Japan and operates in the financial services sector. They typically respond faster to emails than phone calls."
)

Less Effective

client.retain(
    bank_id=bank_id,
    content="Location: Tokyo. Industry: Finance. Preference: Email."
)

Batch Operations

contents = [
    "User completed onboarding on January 10th.",
    "User's team has 5 members.",
    "User prefers weekly check-ins over daily standups."
]

for content in contents:
    client.retain(bank_id=bank_id, content=content)

With Metadata

client.retain(
    bank_id=bank_id,
    content="Meeting notes from Q1 review...",
    source="meeting_transcript",
    metadata={
        "meeting_date": "2024-03-15",
        "attendees": ["alice", "bob", "charlie"]
    }
)

Memory Types Explained

Hindsight automatically categorizes memories into four types:

World Facts

Objective facts received from external sources:

• "Paris is the capital of France"
• "The project uses PostgreSQL for the database"
• "The company was founded in 2020"
• "The user's email is alice@example.com"

Experience

Events and interactions that have occurred:

• "User signed up for the premium plan last week"
• "We had a productive call with the design team"
• "The deployment completed successfully at 2 PM"
• "I sent a welcome email on January 10th"

Observations

Automatically synthesized knowledge — new facts are analyzed and consolidated into observations with evidence tracking. Observations are created and refined automatically in the background after each retain call:

• "User is growing comfortable with async Python"
• "Traffic peaks on Tuesday mornings"
• "Support tickets decrease after documentation updates"

Mental Model Auto-Refresh

When memories are stored via Retain, Hindsight consolidates new facts into observations. Mental models that have trigger.refresh_after_consolidation enabled will be automatically refreshed after this consolidation completes, keeping them up to date with the latest knowledge. See Mental Models for more details.

Token Usage

Retain operations consume tokens based on:

• Input content length
• Processing complexity
• Number of memories extracted

Monitor usage on the Usage Analytics page.

Error Handling

Python

try:
    client.retain(bank_id=bank_id, content=content)
    print("Memory stored successfully")
except Exception as e:
    print(f"Error: {e}")

TypeScript

try {
  await client.retain(bankId, content);
  console.log('Memory stored successfully');
} catch (error) {
  console.error('Error:', error.message);
}

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid API key	Check your API key
402 Payment Required	Insufficient credits	Add credits to your account
404 Not Found	Invalid bank_id	Verify the bank exists
400 Bad Request	Empty content	Provide non-empty content