Honcho Python SDK

The official Python library for the Honcho conversational memory platform. Honcho provides tools for managing peers, sessions, and conversation context across multi-party interactions, enabling advanced conversational AI applications with persistent memory and theory-of-mind capabilities.

Installation

pip install honcho-ai

Quick Start

from honcho import Honcho

# Initialize client
client = Honcho(api_key="your-api-key")

# Create peers (participants in conversations)
alice = client.peer("alice")
bob = client.peer("bob")

# Create a session for group conversations
session = client.session("conversation-1")

# Add messages to the session
session.add_messages([
    alice.message("Hello, Bob!"),
    bob.message("Hi Alice, how are you?")
])

# Query conversation context
response = alice.chat("What did Bob say to the user?")
print(response)

Core Concepts

Peers

Peers represent participants in conversations.

# Create peers
assistant = client.peer("assistant")
user = client.peer("user-123")

# Chat with global context
response = user.chat("What did I talk about yesterday?")

# Chat with perspective of another peer
response = user.chat("Does the assistant know my preferences?", target=assistant)

Sessions

Sessions group related conversations and messages:

# Create a session
session = client.session("project-discussion")

# Add peers to session
session.add_peers([alice, bob])

# Add messages
session.add_messages([
    alice.message("Let's discuss the project timeline"),
    bob.message("I think we need two more weeks")
])

# Get conversation context
context = session.context()

Messages and Context

Retrieve and use conversation history:

# Get messages from a session
messages = session.messages()

# Convert to OpenAI format for further prompting
openai_messages = context.to_openai(assistant="assistant")

# Convert to Anthropic format for further prompting
anthropic_messages = context.to_anthropic(assistant="assistant")

Async Support

The SDK provides async access via the .aio accessor on any instance:

from honcho import Honcho

async def main():
    client = Honcho(api_key="your-api-key")

    # Async peer and session creation
    peer = await client.aio.peer("user-123")
    session = await client.aio.session("conversation-1")

    # Async chat
    response = await peer.aio.chat("What does this user prefer?")

    # Async iteration
    async for p in client.aio.peers():
        print(p.id)

Metadata Management

# Set peer metadata
user.set_metadata({"location": "San Francisco", "preferences": {"theme": "dark"}})

# Session metadata
session.set_metadata({"topic": "project-planning", "priority": "high"})

Multi-Perspective Queries

# Alice's view of what Bob knows
response = alice.chat("Does Bob remember our discussion about the budget?", target=bob)

# Session-specific perspective
response = alice.chat("What does Bob think about this project?",
                     target=bob,
                     session=session)

Configuration

Environment Variables

export HONCHO_API_KEY="your-api-key"
export HONCHO_BASE_URL="https://api.honcho.dev"  # Optional
export HONCHO_WORKSPACE_ID="your-workspace"  # Optional

Client Options

client = Honcho(
    api_key="your-api-key",
    environment="production",  # or "local"
    workspace_id="custom-workspace",
    base_url="https://api.honcho.dev"
)

License

Apache 2.0 - see LICENSE for details.

Support

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

honcho_ai-2.3.0.tar.gz (51.8 kB view details)

Uploaded Aug 11, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

honcho_ai-2.3.0-py3-none-any.whl (61.1 kB view details)

Uploaded Aug 11, 2026 Python 3

File details

Details for the file honcho_ai-2.3.0.tar.gz.

File metadata

Download URL: honcho_ai-2.3.0.tar.gz
Upload date: Aug 11, 2026
Size: 51.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.9.24 {"installer":{"name":"uv","version":"0.9.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for honcho_ai-2.3.0.tar.gz
Algorithm	Hash digest
SHA256	`748e11924043aea121e364e9465cddd2d37209b62e661c02d61e00bdbffa51f6`
MD5	`08bddd13c76fd294f91054f90069dcd5`
BLAKE2b-256	`94db778084201211218d2499693eb803d7556a050562eaf10c7ef833e2f7562d`

See more details on using hashes here.

File details

Details for the file honcho_ai-2.3.0-py3-none-any.whl.

File metadata

Download URL: honcho_ai-2.3.0-py3-none-any.whl
Upload date: Aug 11, 2026
Size: 61.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.9.24 {"installer":{"name":"uv","version":"0.9.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for honcho_ai-2.3.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`92e01ee2bb6600489b7ed9d44a9b59f23069911f809cc2e413de76d62893fed2`
MD5	`29d551afa7754127a733dbd5255865ef`
BLAKE2b-256	`c40752a99b050243fb42b8271e9ba29a24d52d5ed8079d948149b0e1b9f471a4`