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

Release files for honcho-ai 2.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for honcho-ai 2.4.0
File	Size	Uploaded
honcho_ai-2.4.0.tar.gz	61.9 kB	Aug 27, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for honcho-ai 2.4.0
File	Interpreter	ABI	Platform	Reset
honcho_ai-2.4.0-py3-none-any.whl 72.5 kB Aug 27, 2026	Python 3	none	any	Details

Total release size: 134.5 kB

Release files / honcho_ai-2.4.0.tar.gz

Download URL	honcho_ai-2.4.0.tar.gz
Size	61.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`474addb5974834ff6ab3303f6bd18ba2074c78e41a7ae160acffd94dd52131d3`
BLAKE2b-256 checksum How to use checksums	`47f2445e684deecfcda9a22d9e8803e152f8bc30e26d4b4fbf9d387dc7b29574`
Upload date	Aug 27, 2026
Uploaded using Trusted Publishing? What is 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}`

Release files / honcho_ai-2.4.0-py3-none-any.whl

Download URL	honcho_ai-2.4.0-py3-none-any.whl
Size	72.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a84312a7cbfebc7dafc4a3816877af8f0396a793d487407338da4b2b71921ffe`
BLAKE2b-256 checksum How to use checksums	`9e9b0cf7480ccd1278f00e8cca2625bbe8ed67755fb0be89652dd604c09bd483`
Upload date	Aug 27, 2026
Uploaded using Trusted Publishing? What is 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}`