Retain: Storing Memories

Fresh

Source: docs.hindsight.vectorize.io/retain

Overview

The Retain operation processes natural language content, extracts and categorizes memories automatically, stores world facts and observations, and builds 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"
)

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'
});

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

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 memory
async	boolean	No	Process asynchronously (default: false)

Response Format

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

Content Best Practices

Be Specific

Good

"During our March 15 meeting, the client mentioned they need the report by April 1st and prefer PDF format. Sarah is the project lead and prefers Slack communication."

Less Effective

"User likes coding"

Use Natural Language

Good

Conversational text describing location, industry, and communication preferences

Less Effective

Structured format with colons and abbreviations

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

Type	Description	Example
World Facts	Objective facts from external sources	"The project uses PostgreSQL"
Experience	Events and interactions	"User signed up for premium plan"
Observations	Auto-synthesized consolidated knowledge	"User is growing comfortable with async Python"

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 account
404 Not Found	Invalid bank_id	Verify bank exists
400 Bad Request	Empty content	Provide non-empty content