/hindsight-docs

SmolAgents

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

View Changelog →

Features

• Native Tool Subclasses - Each tool extends SmolAgents' Tool base class
• Memory Instructions - Pre-recall memories for injection into agent system prompt
• Three Memory Tools - Retain (store), Recall (search), Reflect (synthesize) — include any combination
• Factory Function - Create all tools in one call with shared configuration
• Simple Configuration - Configure once globally, or pass a client directly

Installation

pip install hindsight-smolagents

Quick Start

💡 Recommended: Hindsight Cloud

Sign up free and grab an API key — no self-hosting required.

from smolagents import CodeAgent, HfApiModel
from hindsight_smolagents import create_hindsight_tools

tools = create_hindsight_tools(
    bank_id="user-123",
    hindsight_api_url="https://api.hindsight.vectorize.io",
    api_key="hsk_...",  # or set HINDSIGHT_API_KEY env var
)

agent = CodeAgent(
    tools=tools,
    model=HfApiModel(),
)

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

The agent now has three tools it can call:

• hindsight_retain — Store information to long-term memory
• hindsight_recall — Search long-term memory for relevant facts
• hindsight_reflect — Synthesize a reasoned answer from memories

Self-hosting (local development)

If you're running Hindsight locally with ./scripts/dev/start-api.sh, swap the URL:

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

See the installation guide for self-hosting setup.

With Memory Instructions

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

from hindsight_smolagents import create_hindsight_tools, memory_instructions

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

memories = memory_instructions(
    bank_id="user-123",
    hindsight_api_url="https://api.hindsight.vectorize.io",
)

agent = CodeAgent(
    tools=tools,
    model=HfApiModel(),
    system_prompt=f"You are a helpful assistant.\n\n{memories}",
)

Individual Tools

You can also use the tool classes directly:

from hindsight_smolagents import HindsightRetainTool, HindsightRecallTool

agent = CodeAgent(
    tools=[
        HindsightRetainTool(
            bank_id="user-123",
            hindsight_api_url="https://api.hindsight.vectorize.io",
        ),
        HindsightRecallTool(
            bank_id="user-123",
            hindsight_api_url="https://api.hindsight.vectorize.io",
        ),
    ],
    model=HfApiModel(),
)

Selecting Tools

Include only the tools you need via the factory:

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

Global Configuration

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

from hindsight_smolagents import configure, create_hindsight_tools

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 tools without passing connection details
tools = create_hindsight_tools(bank_id="user-123")

Configuration Reference

create_hindsight_tools()

memory_instructions()

configure()

Requirements

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