Mental Models: Pre-Computed Reflections

Fresh

Source: docs.hindsight.vectorize.io/mental-models

Overview

Mental models are cached reflections that capture synthesized memory states. They are generated via Reflect queries and refresh automatically or manually as bank knowledge evolves.

Key benefits:

• Pre-computed retrieval — Instant reads without LLM calls
• Cached reflections — Synthesized information across multiple memories
• Automatic or manual refresh — Flexible update scheduling
• Hierarchical priority — Checked first during Reflect operations
• Tag-based organization — Filter and categorize models
• Eventually consistent — Asynchronous background updates

Use Cases

Use Case	Source Query Example
User Profile	"What do we know about this user's preferences and background?"
FAQ Bot	"What are the most common questions and their answers?"
Status Report	"What is the current status of the project?"
Team Directory	"Who works here and what do they do?"
Onboarding Guide	"What does a new team member need to know?"
Policy Summary	"What are the key policies and guidelines?"

Creating a Mental Model

Creation runs asynchronously, returning an operation_id for progress tracking.

Python

result = client.create_mental_model(
    bank_id="my-assistant",
    name="User Profile",
    source_query="What do we know about this user's preferences and background?"
)
print(f"Creating mental model (operation: {result.operation_id})")

TypeScript

const result = await client.createMentalModel(
  'my-assistant',
  'User Profile',
  'What do we know about this user\'s preferences and background?'
);
console.log(`Creating mental model (operation: ${result.operation_id})`);

cURL

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-assistant/mental-models \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Profile",
    "source_query": "What do we know about this user'\''s preferences and background?"
  }'

With Options

result = client.create_mental_model(
    bank_id="my-assistant",
    name="Team Directory",
    source_query="Who works here and what do they do?",
    tags=["team", "directory"],
    max_tokens=4096,
    trigger={"refresh_after_consolidation": True}
)

Create Parameters

Parameter	Type	Required	Description
name	string	Yes	Human-readable name
source_query	string	Yes	Query to run through Reflect
tags	string[]	No	Tags for filtering
max_tokens	integer	No	Max tokens (default: 2048, range: 256-8192)
trigger.refresh_after_consolidation	boolean	No	Auto-refresh after memory consolidation

Listing Mental Models

Python

models = client.list_mental_models(bank_id="my-assistant")
for model in models.items:
    print(f"{model.name}: {model.content[:100]}...")

# Filter by tags
models = client.list_mental_models(bank_id="my-assistant", tags=["team"])

TypeScript

const models = await client.listMentalModels('my-assistant');
models.items.forEach(model => {
  console.log(`${model.name}: ${model.content?.substring(0, 100)}...`);
});

Getting a Mental Model

model = client.get_mental_model(
    bank_id="my-assistant",
    mental_model_id="mm_abc123"
)
print(f"Name: {model.name}")
print(f"Content: {model.content}")
print(f"Last refreshed: {model.last_refreshed_at}")

Refreshing a Mental Model

Refreshing re-runs the source query through Reflect to update content.

result = client.refresh_mental_model(
    bank_id="my-assistant",
    mental_model_id="mm_abc123"
)
print(f"Refresh operation: {result.operation_id}")

Auto-Refresh Behavior

When trigger.refresh_after_consolidation is enabled, models automatically refresh after Retain consolidates new memories into observations.

When to Enable Auto-Refresh

• Models requiring current data (user preferences, status reports)
• Banks receiving regular memory updates

When to Keep Manual Refresh

• Models summarizing stable information (policy documents, onboarding guides)
• When controlling exact update timing is necessary
• To minimize token usage

How Mental Models Work with Reflect

When calling Reflect, the system automatically:

1. Retrieves relevant mental models based on query
2. Injects them as high-priority context alongside retrieved memories
3. Synthesizes an answer drawing from both models and raw memories

{
  "text": "Based on the stored memories...",
  "based_on": [],
  "mental_models": [
    {
      "id": "mm_abc123",
      "text": "The user is a software engineer who prefers..."
    }
  ]
}

Best Practices

Source Query Design

Write clear, specific queries:

• Good: "What are the user's communication preferences, including preferred channels, response times, and meeting styles?"
• Less Effective: "Tell me about the user"

Naming Conventions

• "Customer Support FAQ" instead of "FAQ"
• "Q2 Project Status" instead of "Status"
• "Engineering Team Directory" instead of "Team"

Organization with Tags

client.create_mental_model(
    bank_id="my-assistant",
    name="Team Skills Matrix",
    source_query="What skills does each team member have?",
    tags=["team", "skills"]
)

# Retrieve all team-related models
team_models = client.list_mental_models(bank_id="my-assistant", tags=["team"])

Token Usage

Operation	Description
Get Model	Lightweight lookup returning cached content
Refresh Model	Runs Reflect to regenerate content
Create Model	Same cost as refresh (runs Reflect internally)