hindsight-pydantic-ai

Persistent memory tools for Pydantic AI agents via Hindsight. Give your agents long-term memory with retain, recall, and reflect — all async-native with no thread-pool hacks.

Features

• Async-Native Tools - Uses Pydantic AI's async tool interface directly (aretain, arecall, areflect)
• Memory Instructions - Auto-inject relevant memories into every agent run via instructions=[...]
• Three Memory Tools - Retain (store), Recall (search), Reflect (synthesize) — include any combination
• Simple Configuration - Configure once globally, or pass a client directly
• Lightweight - Depends on pydantic-ai-slim to avoid pulling in all model providers

Installation

pip install hindsight-pydantic-ai

Quick Start

from hindsight_client import Hindsight
from hindsight_pydantic_ai import create_hindsight_tools, memory_instructions
from pydantic_ai import Agent

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

agent = Agent(
    "openai:gpt-4o",
    tools=create_hindsight_tools(client=client, bank_id="user-123"),
    instructions=[memory_instructions(client=client, bank_id="user-123")],
)

result = await agent.run("What do you remember about my preferences?")
print(result.output)

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

The memory_instructions callable automatically recalls relevant memories and injects them into the system prompt on every run.

Tools Only (No Auto-Injection)

If you want the agent to decide when to use memory (rather than always injecting context):

agent = Agent(
    "openai:gpt-4o",
    tools=create_hindsight_tools(client=client, bank_id="user-123"),
)

Instructions Only (No Tools)

If you just want memories auto-injected without giving the agent explicit memory tools:

agent = Agent(
    "openai:gpt-4o",
    instructions=[memory_instructions(client=client, bank_id="user-123")],
)

Selecting Tools

Include only the tools you need:

tools = create_hindsight_tools(
    client=client,
    bank_id="user-123",
    include_retain=True,
    include_recall=True,
    include_reflect=False,  # Omit reflect
)

Global Configuration

Instead of passing a client to every call, configure once:

from hindsight_pydantic_ai 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 client — uses global config
tools = create_hindsight_tools(bank_id="user-123")

Per-Tool Overrides

Constructor arguments override global configuration:

tools = create_hindsight_tools(
    bank_id="user-123",
    budget="high",             # Override global budget
    max_tokens=8192,           # Override global max_tokens
    tags=["session:abc"],      # Override global tags
)

Memory Instructions Options

Customize what memories get injected and how:

instructions_fn = memory_instructions(
    client=client,
    bank_id="user-123",
    query="relevant context about the user",  # What to search for
    budget="low",                              # Keep it fast
    max_results=5,                             # Limit injected memories
    max_tokens=4096,                           # Max recall tokens
    prefix="Relevant memories:\n",             # Text before the memory list
    tags=["scope:global"],                     # Filter by tags
    tags_match="any",                          # Tag match mode
)

Configuration Reference

create_hindsight_tools()

memory_instructions()

configure()

Requirements

• Python >= 3.10
• pydantic-ai-slim >= 1.0.0
• hindsight-client >= 0.4.0
• A running Hindsight API server

License

MIT