fleet-memory/hindsight-docs/docs/developer/api/reflect.md

sidebar_position
3

Think

Generate personality-aware responses using retrieved memories.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Basic Usage

from hindsight_client import Hindsight

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

answer = client.think(
    agent_id="my-agent",
    query="What should I know about Alice?"
)

print(answer["text"])

import { OpenAPI, ReasoningService } from '@hindsight/client';

OpenAPI.BASE = 'http://localhost:8888';

const response = await ReasoningService.thinkApiThinkPost({
    agent_id: 'my-agent',
    query: 'What should I know about Alice?'
});

console.log(response.text);

hindsight memory think my-agent "What should I know about Alice?"

# Verbose output shows reasoning and sources
hindsight memory think my-agent "What should I know about Alice?" -v

Response Format

{
    "text": "Alice is a software engineer at Google who joined last year...",
    "based_on": {
        "world": [
            {"text": "Alice works at Google", "weight": 0.95, "id": "..."}
        ],
        "agent": [],
        "opinion": [
            {"text": "Alice is very competent", "weight": 0.82, "id": "..."}
        ]
    },
    "new_opinions": [
        {"text": "Alice would be good for the ML project", "confidence": 0.75}
    ]
}

Field	Description
text	Generated response
based_on	Memories used, grouped by type
new_opinions	New opinions formed during reasoning

Parameters

Parameter	Type	Default	Description
query	string	required	Question or prompt
budget	Budget	LOW	Budget level: LOW (100), MID (300), HIGH (600) nodes
top_k	int	10	Max memories to retrieve

from hindsight_api.engine.memory_engine import Budget

answer = client.reflect(
    bank_id="my-agent",
    query="What do you think about remote work?",
    budget=Budget.MID
)

What Think Does

sequenceDiagram
    participant C as Client
    participant A as Hindsight API
    participant M as Memory Store
    participant L as LLM

    C->>A: think("What about Alice?")
    A->>M: Search all networks
    M-->>A: World + Memory bank + Opinion facts
    A->>A: Load memory bank personality
    A->>L: Generate with personality context
    L-->>A: Response + new opinions
    A->>M: Store new opinions
    A-->>C: Response + sources + new opinions

1. Retrieves relevant memories from all three networks
2. Loads memory bank personality (Big Five traits + background)
3. Generates response influenced by personality
4. Forms opinions if the query warrants it
5. Returns response with sources and any new opinions

Opinion Formation

Think can form new opinions based on evidence:

answer = client.think(
    agent_id="my-agent",
    query="What do you think about Python vs JavaScript for data science?"
)

# Response might include:
# text: "Based on what I know about data science workflows..."
# new_opinions: [
#     {"text": "Python is better for data science", "confidence": 0.85}
# ]

New opinions are automatically stored and influence future responses.

Personality Influence

The memory bank's personality affects Think responses:

Trait	Effect on Think
High Openness	More willing to consider new ideas
High Conscientiousness	More structured, methodical responses
High Extraversion	More collaborative suggestions
High Agreeableness	More diplomatic, harmony-seeking
High Neuroticism	More risk-aware, cautious

# Create a memory bank with specific personality
client.create_agent(
    agent_id="cautious-advisor",
    background="I am a risk-aware financial advisor",
    personality={
        "openness": 0.3,
        "conscientiousness": 0.9,
        "neuroticism": 0.8,
        "bias_strength": 0.7
    }
)

# Think responses will reflect this personality
answer = client.think(
    agent_id="cautious-advisor",
    query="Should I invest in crypto?"
)
# Response will likely emphasize risks and caution

Using Sources

The based_on field shows which memories informed the response:

answer = client.think(agent_id="my-agent", query="Tell me about Alice")

print("Response:", answer["text"])
print("\nBased on:")
for fact in answer["based_on"]["world"]:
    print(f"  - {fact['text']} (relevance: {fact['weight']:.2f})")

This enables:

• Transparency — users see why the memory bank said something
• Verification — check if the response is grounded in facts
• Debugging — understand retrieval quality