Memory Banks

Memory Banks are the core organizational unit in Hindsight. Each bank is an isolated container for memories, with its own profile, settings, and data.

Accessing Memory Banks

1. Log in to Hindsight Cloud
2. Use the Memory Bank Selector dropdown in the top navigation
3. Select a bank to view its details, or click Create New to create one

Memory Bank Views

When you select a memory bank, a sidebar appears on the left with several views:

Profile

The Profile view lets you configure your memory bank's identity:

• Name - Display name for the bank
• Background - Contextual information about the bank's purpose
• Disposition Traits - Characteristics that influence how the agent reasons:
  • Skepticism - How readily the agent accepts new information
  • Literalism - How flexibly the agent interprets statements
  • Empathy - How much weight given to emotional context

Recall (Search Debug)

The Recall view provides a debugging interface for memory retrieval using Hindsight's TEMPR strategy:

• Test search queries across all retrieval methods (semantic, keyword, graph, temporal)
• View retrieval traces showing which methods found which memories
• Analyze relevance scores
• Debug why certain memories are or aren't being retrieved

Reflect

The Reflect view enables reasoning over stored memories using the bank's disposition traits:

• Synthesize insights from stored memories
• See confidence scores based on evidence strength
• Understand how disposition traits influence reasoning
• View the memories that informed each reflection

Memories

The Memories view displays all stored memories organized by fact type:

Type	Description	Example
World Facts	Objective facts received from external sources	"The project deadline is March 15th"
Experience	Events and interactions that have occurred	"User signed up for the premium plan last week"
Observations	Automatically synthesized knowledge — consolidated from facts with evidence tracking	"User is growing comfortable with async Python"

Each memory entry shows:

• Memory content
• Timestamp
• Source (if applicable)

You can switch between two layouts:

• Data view — a tabular list with full-text search, tag filtering, and a fact-type filter
• Constellation view — an interactive graph that lays out memories as nodes and renders their relationships as edges, color-coded by fact type

Mental Models

The Mental Models view displays user-curated mental models for the bank:

• Create, edit, and delete mental models
• Refresh models to regenerate from current memories
• Toggle auto-refresh to keep models up to date after consolidation
• View source memories used to build each model
• RBAC enforced: members have read-only access

See Mental Models for full API documentation.

Documents

The Documents view lets you add source documents to a memory bank. Hindsight extracts text from each document and stores it as memories.

Adding Documents

There are two ways to add a document:

• Text input — Paste or type text directly into the Add Document dialog
• File upload — Upload a file from your computer. Supported file types include:
  • PDF (.pdf)
  • Word (.docx, .doc)
  • PowerPoint (.pptx, .ppt)
  • Excel (.xlsx, .xls)
  • Images (.jpg, .jpeg, .png)
  • Text (.txt, .md, .csv)

Extraction Methods

When uploading a file, you choose an extraction method:

Method	Cost	Best For
Standard	Free (no additional charge)	Most text-based documents — Word, Excel, PowerPoint, text files, and digitally-created PDFs
Enhanced (Iris)	Additional per-token charge	Images, scanned PDFs, and documents with complex layouts or embedded figures

Standard extraction uses Markitdown to pull text from the file. Enhanced extraction uses an AI-powered vision pipeline (Iris) that understands page layouts, tables, and images — producing higher-quality output for visually complex documents.

Tracking Document Processing

After uploading, open the Document Operations panel to track processing status:

Status	Meaning
Pending	Document is queued or currently being processed
Completed	Extraction finished and memories have been stored
Cancelled	The operation was cancelled before it completed
Failed	Extraction encountered an error — review the error message and Retry from the row, or cancel pending operations directly from the dialog

Click any document row to view its extracted text and metadata.

Entities

The Entities view displays extracted entities across two tabs:

• Entities tab — a list of people, organizations, places, and other extracted entities, with usage counts and metadata
• Relations tab — an interactive Constellation graph that visualizes how entities are connected to each other and to the memories they appear in

Creating a Memory Bank

1. Click the Memory Bank Selector in the navigation
2. Click Create New Bank
3. Enter the required information:
   • Name - A unique identifier for the bank
4. Optionally configure:
   • Background - Context about the bank's purpose
   • Traits - Disposition characteristics
5. Click Create

Adding Memories

Via the UI

1. Navigate to the Memories view
2. Click Add Document or Add Memory
3. Enter the memory content
4. Select the appropriate memory type
5. Click Save

Via the API

client.retain(
    bank_id="your-bank-id",
    content="The user prefers concise responses."
)

See Retain for detailed API documentation.

Searching Memories

Via the UI

1. Navigate to the Recall tab
2. Enter your search query
3. View matching memories with relevance scores

Via the API

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

See Recall for detailed API documentation.

Best Practices

Organizing Memory Banks

• One bank per context - Create separate banks for different users, projects, or agents
• Meaningful names - Use descriptive names that identify the bank's purpose
• Configure backgrounds - Provide context that helps the system understand the domain

Memory Quality

• Be specific - Store concrete, actionable information
• Include context - Add relevant details that aid retrieval
• Include temporal references - Dates and times enable temporal search queries

Performance

• Batch operations - Use bulk APIs when storing many memories
• Limit recall scope - Use filters to narrow search when possible
• Monitor usage - Check the Usage page of your deployment's console

Using Mental Models for Frequently Accessed Data

If your application repeatedly queries the same type of information — such as user preferences, project status, or team context — use mental models instead of calling Recall or Reflect each time. Mental models are pre-computed reflections that return cached content in a single lookup with no LLM call at read time.

• Identify frequent queries - Look for Reflect or Recall calls that run the same (or similar) query on every request. These are strong candidates for a mental model.
• Enable auto-refresh for volatile data - Set trigger.refresh_after_consolidation to true so the model stays current as new memories are consolidated. This is ideal for data that changes often, such as user preferences or active project status.
• Keep manual refresh for stable data - For information that rarely changes (e.g., onboarding guides, policy summaries), skip auto-refresh to avoid unnecessary token usage and refresh on your own schedule.
• Use descriptive source queries - A specific query like "What are the user's communication preferences and response time expectations?" produces a more useful model than a broad query like "Tell me about the user."
• Combine with Reflect - Mental models are automatically injected as high-priority context during Reflect calls, so you get the benefit of pre-computed summaries alongside live reasoning over raw memories.

See Mental Models for full API documentation and examples.