Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vectorize-io/hindsight/llms.txt

Use this file to discover all available pages before exploring further.

When you call reflect(), Hindsight does more than retrieve facts — it runs an agentic loop that autonomously gathers evidence, reasons through it using the bank’s disposition, and generates a synthesized response with citations. Where recall() returns a ranked list of memories for your code to act on, reflect() produces a finished answer shaped by the bank’s identity and hard rules.

​
How reflect differs from recall

Use recall() when…Use reflect() when…
You need raw facts to process yourselfYou need a reasoned, written response
You are building your own reasoning layerYou want the bank to reason independently
You need maximum control over outputYou want disposition-consistent character
Simple fact lookup or context injectionForming recommendations or interpretations
Example: recall("Alice") returns all facts and observations about Alice, scored by relevance. reflect("Should we hire Alice?") returns a written recommendation grounded in those facts, shaped by the bank’s skepticism level and any directives like “Always cite sources.”

​
The agentic loop

reflect() runs an agent with access to four tools. The agent calls them autonomously until it has enough evidence to answer, then calls done with the final response.
ToolPurpose
search_mental_modelsCheck user-curated summaries first
search_observationsQuery consolidated knowledge
recallRetrieve raw facts as ground truth
expandGet additional context for a specific memory
The agent follows a strict retrieval hierarchy:
1

Mental Models

User-curated summaries you have pre-computed for common queries. Checked first — if a mental model exists, it represents explicitly managed knowledge and takes priority.
2

Observations

Automatically consolidated beliefs built from multiple facts. Each observation carries a freshness trend. If an observation is marked stale, the agent automatically verifies it against current raw facts before using it.
3

Raw Facts

Individual world and experience facts from retain(). Used as ground truth and as the fallback when observations do not cover the query.
The agent must gather evidence before answering — a guardrail prevents empty responses. It runs up to 10 iterations and only cites memory IDs that were actually retrieved during the loop.

​
Mission, disposition, and directives

Three bank-level settings shape how reflect() reasons and responds. All three only affect reflect() — they have no effect on retain() or recall().

​
Mission

A first-person narrative that gives the agent its identity and reasoning context. It is injected at the start of every reflect call to ground the agent’s perspective. 
e.g. You are a senior engineering assistant.
     Always ground answers in documented decisions and rationale.
     Ignore speculation. Be direct and precise.

​
Disposition traits

Three numeric traits (scale 1–5) that shape how the agent interprets information and frames its response.
TraitLow (1)Default (3)High (5)
SkepticismTrusting — accepts claims at face valueBalancedSkeptical — questions and doubts claims
LiteralismFlexible — reads between the linesBalancedLiteral — takes things exactly as stated
EmpathyDetached — focuses on facts and logicBalancedEmpathetic — weighs emotional context
Two banks given identical facts about remote work produce different responses based on their disposition:
  • Low skepticism, high empathy: “Remote work enables flexibility and work-life balance. The team seems happier and more productive when they can choose their environment.”
  • High skepticism, low empathy: “Remote work claims need verification. What are the actual productivity metrics? The anecdotal benefits may not translate to measurable outcomes.”

​
Directives

Hard rules injected into every reflect prompt that the agent must follow. Unlike disposition traits, which influence tone and interpretation, directives are enforced strictly. Use directives for compliance guardrails that must never be violated:
  • “Never recommend specific stocks or financial products”
  • “Always respond in formal English”
  • “Never share personal data with third parties”
  • “Always cite sources when making factual claims”
Use disposition for personality and character. Use directives for compliance and guardrails. Directives are strict — responses that violate them are rejected.

​
Parameters

​
query
string
required
The question or prompt the agent should answer.
​
include_facts
boolean
default:"false"
When true, the response includes a based_on field listing the memories, mental models, and directives the agent actually used. Useful for transparency and citation tracking.
​
response_schema
object
JSON Schema for structured output. When provided, the agent produces a response that conforms to the schema and it is returned in structured_output.

​
Code examples

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

# Basic reflect
result = client.reflect(
    bank_id="my-agent",
    query="Should we hire Alice for the research team lead position?",
)
print(result.text)

# Reflect with facts (citations)
result = client.reflect(
    bank_id="my-agent",
    query="Summarize what we know about Alice's career trajectory.",
    include_facts=True,
)
print(result.text)
for memory in (result.based_on.memories if result.based_on else []):
    print(f"  Source: {memory.text}")

# Reflect with structured output
result = client.reflect(
    bank_id="my-agent",
    query="What are Alice's top three technical strengths?",
    response_schema={
        "type": "object",
        "properties": {
            "strengths": {
                "type": "array",
                "items": {"type": "string"},
            }
        },
    },
)
print(result.structured_output["strengths"])

​
Response structure

{
  "text": "Based on Alice's ML expertise and her work on Google's search ranking, she would be an excellent fit for the research team lead position...",
  "based_on": {
    "memories": [
      { "id": "mem-123", "text": "Alice has 5 years of ML experience", "type": "world" },
      { "id": "mem-456", "text": "Alice worked at Google on search ranking", "type": "experience" }
    ],
    "mental_models": [],
    "directives": [
      { "id": "dir-001", "name": "Formal language", "rules": ["Always respond in formal English"] }
    ]
  },
  "usage": { "input_tokens": 1500, "output_tokens": 500, "total_tokens": 2000 }
}
reflect_mission, disposition traits, and directives only affect reflect(). To steer what gets extracted during retain(), set retain_mission on the bank. To control what gets synthesized into observations, set observations_mission. See Memory banks for all configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us