Hindsight Docs

<PageHero title="Best Practices" subtitle="Practical guidance for agents and developers integrating Hindsight memory into production systems." />

**Contents**
- [Core Concepts](#core-concepts) — Memory banks, taxonomy, memory types
- [Bank Configuration](#bank-configuration) — Missions, dispositions, entity labels
- [Retaining Data](#retaining-data) — Content format, context, document_id, [tags](#tags-naming-conventions), observation scopes
- [Recalling Memories](#recalling-memories) — Budget, tag filtering, entity label filtering, include options, query_timestamp
- [Reflecting](#reflecting) — Recall vs reflect, response_schema, auditing
- [Mental Models](#mental-models) — When to create, tag strategy, refresh
- [Anti-patterns](#anti-patterns)

---

## Core Concepts

### Memory Banks

A **memory bank** is an isolated memory store — the unit of separation between users, agents, or contexts. All operations (retain, recall, reflect) target a single bank. Banks do not share data.

- One bank per user is the most common pattern for multi-user applications
- One bank per agent is common for agent-specific long-term memory
- A shared bank with tags can work for cross-user analysis (see [Tags](#tags-naming-conventions))

Banks are auto-created on first use. Configure them before ingesting data to steer behavior.

---

### Taxonomy

| Operation | What it does | When to call it |
|-----------|-------------|-----------------|
| **Retain** | Ingests raw content (conversations, documents, notes). The LLM extracts facts, entities, and relationships — raw content is never stored verbatim. | After each conversation turn or session ends |
| **Recall** | Retrieves relevant memories using 4 parallel strategies: semantic search, BM25, graph traversal, and temporal ranking. Returns a ranked list of facts. | Before generating a response that benefits from past context |
| **Reflect** | Autonomous reasoning loop: searches memory, synthesizes an answer, and returns it directly. Uses mental models and observations hierarchically. | When you want Hindsight to answer a question, not just retrieve facts |
| **Observations** | Deduplicated, evidence-grounded knowledge consolidated from multiple facts. Each observation tracks its supporting memories with exact quotes, proof counts, and a computed freshness trend (stable/strengthening/weakening/stale). Refined — not overwritten — when new evidence supports, contradicts, or extends them. | Triggered automatically after retain — not part of the retain call itself |
| **Mental Models** | Pre-computed reflect responses stored for common queries. Return instantly and consistently. | Create for repeated high-traffic queries or slowly-changing user profiles |

---

### Memory Types

Facts extracted during retain are classified into three types:

| Type | Description | Example |
|------|-------------|---------|
| `world` | General knowledge, external facts | "The Eiffel Tower is in Paris" |
| `experience` | Personal events, user-specific facts | "User moved to Berlin in 2024" |
| `observation` | Consolidated belief grounded in multiple supporting facts; deduplicated and refined over time with tracked evidence and freshness | "User consistently prefers async communication (5 supporting memories, strengthening)" |

Use `types` filtering in recall to target specific memory types.

---

## Bank Configuration

Configure a bank before first use to steer memory behavior for your domain. Misconfigured missions are the single biggest cause of low-quality memories.

### Writing Effective Missions

All three missions accept plain language. Be specific about your domain — vague missions produce vague results.

#### `retain_mission`

Injected into the fact extraction prompt. Tells the LLM what to extract and what to ignore.

| Quality | Example |
|---------|---------|
| **Good** | `Always extract technical decisions, API design choices, architectural trade-offs, blockers, and error messages. Ignore greetings, small talk, and