honcho/examples/agno/python/README.md

Honcho Agno Integration

Give your Agno agents persistent memory with Honcho.

Installation

pip install honcho-agno

Or with uv:

uv add honcho-agno

Quick Start

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from honcho import Honcho
from honcho_agno import HonchoTools

# Initialize Honcho client
honcho = Honcho(workspace_id="my-app")

# Create Honcho tools for the agent
honcho_tools = HonchoTools(honcho_client=honcho)

# Create an agent with memory tools
agent = Agent(
    name="Memory Agent",
    model=OpenAIChat(id="gpt-4o"),
    tools=[honcho_tools],
)

# Create peers and session for message persistence
user_peer = honcho.peer("user-123")
assistant_peer = honcho.peer("assistant")
session = honcho.session("session-123")

# Save user message (orchestration handles persistence)
session.add_messages([user_peer.message("I prefer Python over JavaScript")])

# Run the agent - user_id and session_id flow through RunContext to tools
response = agent.run(
    "What programming language does the user prefer?",
    user_id="user-123",
    session_id="session-123",
)

# Save assistant response
session.add_messages([assistant_peer.message(str(response.content))])

How It Works

HonchoTools maps to Agno's user/assistant architecture:

Agno Concept	Honcho Concept	Description
user_id (from RunContext)	Peer	The human user being queried about
session_id (from RunContext)	Session	The conversation context

Key insight: Tools query Honcho about the USER, not the agent. When the agent asks "What does this user prefer?", Honcho returns insights about the human user identified by run_context.user_id.

Message Persistence

This toolkit is read-only - it provides tools for querying Honcho's memory but does not automatically save messages. Your orchestration code handles message persistence using the Honcho client directly:

# Save messages using the Honcho client (not the toolkit)
session.add_messages([
    user_peer.message("User's message"),
    assistant_peer.message("Assistant's response"),
])

This separation gives you explicit control over what gets saved to memory.

Features

The HonchoTools toolkit provides three memory tools:

Tool	Description
honcho_get_context	Retrieve conversation context within token limits
honcho_search_messages	Semantic search through past messages
honcho_chat	Query Honcho for synthesized insights about the user

Configuration

Basic Configuration

from honcho import Honcho
from honcho_agno import HonchoTools

# Create shared Honcho client
honcho = Honcho(workspace_id="my-app")

# Create toolkit
tools = HonchoTools(honcho_client=honcho)

Without Pre-configured Client

from honcho_agno import HonchoTools

# Creates its own Honcho client internally
tools = HonchoTools(workspace_id="my-app")

Note: When honcho_client is provided, workspace_id is ignored since the client already has its workspace configured.

Environment Variables

Honcho Settings:

• HONCHO_ENVIRONMENT: local or production (default: production)
• HONCHO_API_KEY: API key for production environment
• HONCHO_WORKSPACE_ID: Default workspace ID

OpenAI Settings (for examples):

• OPENAI_API_KEY: OpenAI API key
• OPENAI_MODEL: Model to use (default: gpt-4o)

Tool Details

honcho_get_context

Retrieve recent conversation context. Uses session_id from RunContext.

# Called by the agent automatically with RunContext
# Or call directly with a mock context for testing

honcho_search_messages

Search through past messages semantically. Uses session_id from RunContext.

# Called by the agent automatically with RunContext
# Query example: "programming preferences"

honcho_chat

Ask questions about the user using Honcho's reasoning. Uses both user_id and session_id from RunContext.

# Called by the agent automatically with RunContext
# Query example: "What programming languages does the user prefer?"

Multi-Agent Systems (Teams)

Agno Teams share context within a run, but what about across runs? What if Agent A needs to remember what Agent B learned last week? That's where Honcho comes in.

from agno.agent import Agent
from agno.team import Team
from agno.models.openai import OpenAIChat
from honcho import Honcho
from honcho_agno import HonchoTools

# Shared Honcho client - all agents share the same memory
honcho = Honcho(workspace_id="advisory-app")
honcho_tools = HonchoTools(honcho_client=honcho)

# Tech advisor with Honcho memory
tech_agent = Agent(
    name="Tech Advisor",
    model=OpenAIChat(id="gpt-4o"),
    tools=[honcho_tools],
)

# Business advisor with Honcho memory
biz_agent = Agent(
    name="Business Advisor",
    model=OpenAIChat(id="gpt-4o"),
    tools=[honcho_tools],
)

# Create team
team = Team(
    name="Advisory Team",
    agents=[tech_agent, biz_agent],
)

# Run with shared user_id and session_id
# Both agents query Honcho about the same user
response = team.run(
    "How should I scale my startup?",
    user_id="founder-123",
    session_id="strategy-session",
)

Architecture Notes

• Read-only toolkit: HonchoTools provides read access to Honcho (context, search, chat)
• Orchestration pattern: Message saving is handled by your orchestration code using honcho.session().add_messages()
• RunContext integration: user_id and session_id flow through Agno's RunContext automatically
• Cross-run memory: Unlike Agno Teams (context within a run), Honcho persists memory across runs

Examples

See the examples directory for complete working examples:

• simple_example.py: Basic usage with HonchoTools demonstrating memory persistence and context retrieval

Development

Setup

cd examples/agno/python
uv sync

Run Tests

uv run pytest

Run Examples

uv run python examples/simple_example.py

License

AGPL-3.0-or-later