hindsight-agno

Persistent memory tools for Agno agents via Hindsight. Give your agents long-term memory with retain, recall, and reflect — using Agno's native Toolkit pattern.

Features

• Native Toolkit - Extends Agno's Toolkit base class, just like Mem0Tools
• Memory Instructions - Pre-recall memories for injection into Agent(instructions=[...])
• Three Memory Tools - Retain (store), Recall (search), Reflect (synthesize) — include any combination
• Flexible Bank Resolution - Static bank ID, RunContext.user_id, or custom resolver
• Simple Configuration - Configure once globally, or pass a client directly

Installation

pip install hindsight-agno

Quick Start

✨ Recommended: Hindsight Cloud — free tier, no self-hosting required. Sign up and grab an API key in under a minute.

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from hindsight_agno import HindsightTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        bank_id="user-123",
        hindsight_api_url="https://api.hindsight.vectorize.io",
        api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
    )],
)

agent.print_response("Remember that I prefer dark mode")
agent.print_response("What are my preferences?")

The agent now has three tools it can call:

• retain_memory — Store information to long-term memory
• recall_memory — Search long-term memory for relevant facts
• reflect_on_memory — Synthesize a reasoned answer from memories

Self-hosting (local development)

If you're running Hindsight locally with ./scripts/dev/start-api.sh, point at your local server instead:

tools=[HindsightTools(
    bank_id="user-123",
    hindsight_api_url="https://api.hindsight.vectorize.io",
)]

See the Hindsight installation guide for self-hosting setup.

With Memory Instructions

Pre-recall relevant memories and inject them into the system prompt:

from hindsight_agno import HindsightTools, memory_instructions

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        bank_id="user-123",
        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
    instructions=[memory_instructions(
        bank_id="user-123",
        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
)

Selecting Tools

Include only the tools you need:

tools = [HindsightTools(
    bank_id="user-123",
    hindsight_api_url="https://api.hindsight.vectorize.io",
    enable_retain=True,
    enable_recall=True,
    enable_reflect=False,  # Omit reflect
)]

Bank Resolution

The bank ID is resolved in order:

1. bank_resolver — Custom callable (RunContext) -> str
2. bank_id — Static bank ID passed to constructor
3. run_context.user_id — Automatic per-user banks

# Per-user banks from RunContext
agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(hindsight_api_url="https://api.hindsight.vectorize.io")],
    user_id="user-123",  # Used as bank_id
)

# Custom resolver
def resolve_bank(ctx):
    return f"team-{ctx.user_id}"

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    tools=[HindsightTools(
        bank_resolver=resolve_bank,
        hindsight_api_url="https://api.hindsight.vectorize.io",
    )],
)

Global Configuration

Instead of passing connection details to every toolkit, configure once:

from hindsight_agno import configure, HindsightTools

configure(
    hindsight_api_url="https://api.hindsight.vectorize.io",
    api_key="your-api-key",       # Or set HINDSIGHT_API_KEY env var
    budget="mid",                  # Recall budget: low/mid/high
    max_tokens=4096,               # Max tokens for recall results
    tags=["env:prod"],             # Tags for stored memories
    recall_tags=["scope:global"],  # Tags to filter recall
    recall_tags_match="any",       # Tag match mode: any/all/any_strict/all_strict
)

# Now create toolkit without passing connection details
tools = [HindsightTools(bank_id="user-123")]

Configuration Reference

HindsightTools()

memory_instructions()

configure()

Requirements

• Python >= 3.10
• agno
• hindsight-client >= 0.4.0
• A running Hindsight API server

License

MIT