Skip to main content

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

Metadata

Release files for honcho-ai 2.8.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.8.0
File Size Uploaded Provenance Actions
honcho_ai-2.8.0.tar.gz 71.0 kB Without provenance Details for honcho_ai-2.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for honcho-ai 2.8.0
File Interpreter ABI Platform Actions
honcho_ai-2.8.0-py3-none-any.whl Python 3 none any Details for honcho_ai-2.8.0-py3-none-any.whl

Total release size: 153.0 kB

Release files / honcho_ai-2.8.0.tar.gz

Download URL honcho_ai-2.8.0.tar.gz
Size 71.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ec9b64be041cba94d152a85cfb55a6a70a885591d2ce004a9a9701102c47c037
BLAKE2b-256 checksum
How to use checksums
2fe7b2b44757e8d77dea405c1bbc4f4b23c909115f03162b2b2a187b9d523712
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","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.8.0-py3-none-any.whl

Download URL honcho_ai-2.8.0-py3-none-any.whl
Size 82.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
74bf885b3d86c111b6a574e695d50b861a080e20f10beecfe60336eecfd9237e
BLAKE2b-256 checksum
How to use checksums
34a175eae570d39ec98a4db3dd8f42d6c80b36dfc02139d0ef025f51ff52750e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","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}

Security for honcho-ai 2.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.8.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page