vectorize-io__hindsight/hindsight-docs/docs-integrations/strands.md

sidebar_position, title, description

sidebar_position	title	description
13	Strands Agents Persistent Memory with Hindsight | Integration	Add long-term memory to Strands Agents SDK agents with Hindsight. Retain, recall, and reflect tools using Strands' native @tool pattern for persistent memory across sessions.

Strands Agents

Persistent memory tools for Strands Agents SDK agents via Hindsight. Give your agents long-term memory with retain, recall, and reflect — using Strands' native @tool pattern.

View Changelog →

Features

• Native @tool Functions - Tools are plain Python functions, compatible with Agent(tools=[...])
• Memory Instructions - Pre-recall memories for injection into agent system prompt
• Three Memory Tools - Retain (store), Recall (search), Reflect (synthesize) — include any combination
• Simple Configuration - Configure once globally, or pass a client directly

Installation

pip install hindsight-strands

Quick Start

:::tip Recommended: Hindsight Cloud Sign up free and grab an API key — no self-hosting required. :::

from strands import Agent
from hindsight_strands 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 = Agent(tools=tools)
agent("Remember that I prefer dark mode")
agent("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="http://localhost:8888",
)

See the installation guide for self-hosting setup.

With Memory Instructions

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

from hindsight_strands import create_hindsight_tools, memory_instructions

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

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

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

FastAPI Lifecycle (Recommended)

Prefer creating one shared Hindsight client in app lifespan and passing client=.... This gives explicit ownership and clean shutdown via await client.aclose().

from contextlib import asynccontextmanager

from fastapi import FastAPI
from hindsight_client import Hindsight
from hindsight_strands import create_hindsight_tools, memory_instructions


@asynccontextmanager
async def lifespan(app: FastAPI):
    client = Hindsight(base_url="https://api.hindsight.vectorize.io", api_key="hsk_...")
    app.state.hindsight_client = client
    try:
        yield
    finally:
        await client.aclose()


app = FastAPI(lifespan=lifespan)


@app.post("/chat")
async def chat():
    client = app.state.hindsight_client
    tools = create_hindsight_tools(bank_id="user-123", client=client)
    memories = memory_instructions(bank_id="user-123", client=client)
    ...

If you pass hindsight_api_url/api_key directly to create_hindsight_tools(), hindsight-strands creates the client internally. In that case call await tools.aclose() (or tools.close()) during shutdown.

Selecting Tools

Include only the tools you need:

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

Global Configuration

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

from hindsight_strands import configure, create_hindsight_tools

configure(
    hindsight_api_url="http://localhost:8888",
    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()

Parameter	Default	Description
bank_id	required	Hindsight memory bank ID
client	None	Pre-configured Hindsight client
hindsight_api_url	None	API URL (used if no client provided)
api_key	None	API key (used if no client provided)
budget	"mid"	Recall/reflect budget level (low/mid/high)
max_tokens	4096	Maximum tokens for recall results
tags	None	Tags applied when storing memories
recall_tags	None	Tags to filter when searching
recall_tags_match	"any"	Tag matching mode
enable_retain	True	Include the retain (store) tool
enable_recall	True	Include the recall (search) tool
enable_reflect	True	Include the reflect (synthesize) tool

memory_instructions()

Parameter	Default	Description
bank_id	required	Hindsight memory bank ID
client	None	Pre-configured Hindsight client
hindsight_api_url	None	API URL (used if no client provided)
api_key	None	API key (used if no client provided)
query	"relevant context about the user"	Recall query for memory injection
budget	"low"	Recall budget level
max_results	5	Maximum memories to inject
max_tokens	4096	Maximum tokens for recall results
prefix	"Relevant memories:\n"	Text prepended before memory list
tags	None	Tags to filter recall results
tags_match	"any"	Tag matching mode

configure()

Parameter	Default	Description
hindsight_api_url	Hindsight Cloud (https://api.hindsight.vectorize.io)	Hindsight API URL
api_key	HINDSIGHT_API_KEY env	API key for authentication
budget	"mid"	Default recall budget level
max_tokens	4096	Default max tokens for recall
tags	None	Default tags for retain operations
recall_tags	None	Default tags to filter recall
recall_tags_match	"any"	Default tag matching mode
verbose	False	Enable verbose logging

Requirements

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