Reflect: Reasoning Over Memories

Fresh

Source: docs.hindsight.vectorize.io/reflect

Overview

The Reflect operation performs agentic reasoning over stored memories, guided by the bank's mission, directives, and disposition traits. Unlike Recall which returns raw memories, Reflect synthesizes information and draws conclusions with confidence scores.

Reflect enables:

• Synthesis of insights from stored memories
• Reasoning influenced by disposition traits (skepticism, literalism, empathy)
• Confidence scores based on evidence strength
• Cited sources for transparency
• Automatic incorporation of relevant mental models as context

Basic Usage

Python

response = client.reflect(
    bank_id="your-bank-id",
    query="What are the key priorities for the project?"
)

print(response.text)
print("Based on:", response.based_on)

TypeScript

const response = await client.reflect(
  'your-bank-id',
  'What are the key priorities for the project?'
);

console.log(response.text);
console.log('Based on:', response.based_on);

cURL

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

How It Works

Request Parameters

Parameter	Type	Required	Description
bank_id	string	Yes	Memory bank to query (in URL path)
query	string	Yes	Question to answer
context	string	No	Additional context for the question
budget	string	No	Search depth: low, mid, high (default: low)
max_tokens	integer	No	Max tokens in response (default: 4096)
response_schema	object	No	JSON Schema for structured output

Response

{
  "text": "Based on the stored memories, the key priorities are...",
  "based_on": [],
  "mental_models": [
    {
      "id": "mm_abc123",
      "text": "The project is focused on building a modern web application..."
    }
  ],
  "structured_output": null,
  "usage": {
    "input_tokens": 3352,
    "output_tokens": 806,
    "total_tokens": 4158
  }
}

Reflect vs. Recall

Aspect	Recall	Reflect
Output	Raw memories	Synthesized answer
Processing	Search only	AI reasoning
Best for	Getting context	Answering questions
Token usage	Lower	Higher
Sources	The result IS the sources	Sources cited separately

When to Use Recall

• You need raw data to process yourself
• Building prompts for another AI system
• Debugging or inspecting stored memories
• Minimizing token usage

When to Use Reflect

• Answering user questions directly
• Generating summaries or insights
• Need synthesized information from multiple memories
• Want automatic source citation

Advanced Patterns

With Context

response = client.reflect(
    bank_id=bank_id,
    query="What should I know before our meeting?",
    context="We're meeting with the client to discuss the Q2 roadmap"
)

Conversational Context

resp1 = client.reflect(
    bank_id=bank_id,
    query="Who are the key stakeholders?"
)

resp2 = client.reflect(
    bank_id=bank_id,
    query="What are their main concerns?",
    context=f"We identified these stakeholders: {resp1.text}"
)

Structured Output

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/{bank_id}/reflect \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize the key points about this user",
    "response_schema": {
      "type": "object",
      "properties": {
        "summary": {"type": "string"},
        "key_points": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["summary", "key_points"]
    }
  }'

Error Handling

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 question	Provide a question

Performance Considerations

1. Reflect is more expensive — Uses more tokens than Recall
2. Limit sources — Use budget control to manage token consumption
3. Cache when possible — Store answers for frequently asked questions
4. Consider Recall first — If raw memories suffice, prefer Recall