Recall: Retrieving Memories

Fresh

Source: docs.hindsight.vectorize.io/recall

Overview

The Recall operation enables intelligent memory retrieval using TEMPR multi-strategy search (semantic, keyword, graph, temporal). It provides relevance-ranked results with configurable limits and memory type filtering.

Basic Usage

Python

result = client.recall(
    bank_id="your-bank-id",
    query="What are the user's preferences?"
)

for memory in result.results:
    print(f"[{memory.type}] {memory.text}")

TypeScript

const result = await client.recall(
  'your-bank-id',
  "What are the user's preferences?"
);

result.results.forEach(memory => {
  console.log(`[${memory.type}] ${memory.text}`);
});

cURL

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/{bank_id}/memories/recall \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the user'\''s preferences?"}'

How It Works

Request Parameters

Parameter	Type	Required	Description
bank_id	string	Yes	Memory bank to search (in URL path)
query	string	Yes	Search query (natural language)
types	array	No	Filter by memory types
budget	string	No	Search depth: low, mid, high (default: mid)
max_tokens	integer	No	Max tokens in response (default: 4096)
trace	boolean	No	Include debug trace (default: false)
query_timestamp	string	No	Reference time for temporal queries (ISO 8601)

Response Structure

{
  "results": [
    {
      "id": "mem_abc123",
      "text": "User prefers dark mode interfaces",
      "type": "observation",
      "entities": ["user"],
      "context": "",
      "mentioned_at": "2024-03-15T10:30:00Z"
    }
  ],
  "entities": {
    "user": {
      "entity_id": "ent_456",
      "canonical_name": "user",
      "observations": []
    }
  }
}

Query Best Practices

Use Natural Language

Good

client.recall(query="What programming languages does the user know?")

Less Effective

client.recall(query="programming languages")

Ask Questions

Frame queries as questions for better results:

client.recall(query="What are the user's hobbies?")
client.recall(query="When does the client prefer to have meetings?")
client.recall(query="What technology stack is the project using?")

Filtering Results

By Memory Type

result = client.recall(
    bank_id=bank_id,
    query="Tell me about the user",
    types=["world_fact", "observation"]
)

By Budget (Search Depth)

result = client.recall(
    bank_id=bank_id,
    query="project deadlines",
    budget="high"  # "low", "mid", or "high"
)

Understanding Relevance Scores

Score Range	Interpretation
0.9 - 1.0	Excellent match, directly relevant
0.8 - 0.9	Strong match, highly relevant
0.7 - 0.8	Good match, relevant
0.6 - 0.7	Moderate match, somewhat relevant
< 0.6	Weak match, may not be useful

Advanced Patterns

Contextual Search

context = "We're discussing the new mobile app feature"
question = "What design preferences have been mentioned?"
result = client.recall(
    bank_id=bank_id,
    query=f"{context} {question}"
)

Combining with Retain

# Store user input
client.retain(bank_id=bank_id, content=f"User said: {user_message}")

# Recall relevant context
context = client.recall(bank_id=bank_id, query=user_message, limit=5)

Performance Tips

1. Limit results — Only request needed memories
2. Filter by type — Narrow scope when type is known
3. Use min_score — Filter out low-relevance matches
4. Cache results — Store frequently-needed memories locally