SDK Reference

The Honcho SDKs provide ergonomic interfaces for building agentic AI applications with Honcho in Python and TypeScript/JavaScript.

Installation

uv add honcho-ai

Quickstart

Without configuration, the SDK defaults to the demo server. For production use:

Get your API key at app.honcho.dev/api-keys
Set environment="production" and provide your api_key

from honcho import Honcho

# Initialize client (using the default workspace)
honcho = Honcho()

# Create peers
alice = honcho.peer("alice")
assistant = honcho.peer("assistant")

# Create a session for conversation
session = honcho.session("conversation-1")

# Add messages to conversation
session.add_messages([
    alice.message("What's the weather like today?"),
    assistant.message("It's sunny and 75°F outside!")
])

# Chat with Honcho about a peer
response = alice.chat("What did the assistant tell this user about the weather?")

# Get conversation context for LLM completions
context = session.context()
openai_messages = context.to_openai(assistant=assistant)

Core Concepts

Peers and Representations

Representations are how Honcho models what peers know. Each peer has a global representation (everything they know across all sessions) and local representations (what other specific peers know about them, scoped by session or globally).

# Query alice's global knowledge
response = alice.chat("What does the user know about weather?")

# Query what alice knows about the assistant (local representation)
response = alice.chat("What does the user know about the assistant?", target=assistant)

# Query scoped to a specific session
response = alice.chat("What happened in our conversation?", session=session.id)

Core Classes

Honcho Client

The main entry point for workspace operations:

from honcho import Honcho

# Basic initialization (uses environment variables)
honcho = Honcho(workspace_id="my-app-name")

# Full configuration
honcho = Honcho(
    workspace_id="my-app-name",
    api_key="my-api-key",
    environment="production",  # or "local", "demo"
    base_url="https://api.honcho.dev",
    timeout=30.0,
    max_retries=3
)

Environment Variables:

HONCHO_API_KEY - API key for authentication
HONCHO_BASE_URL - Base URL for the Honcho API
HONCHO_WORKSPACE_ID - Default workspace ID

Key Methods:

# Get or create a peer
peer = honcho.peer(id)

# Get or create a session
session = honcho.session(id)

# List all peers in workspace
peers = honcho.peers()

# List all sessions in workspace
sessions = honcho.sessions()

# Search across all content in workspace
results = honcho.search(query)

# Workspace metadata management
metadata = honcho.get_metadata()
honcho.set_metadata(dict)

# Get list of all workspace IDs
workspaces = honcho.workspaces()

peer() and session() always make a get-or-create API call, returning objects with cached metadata, configuration, and timestamps.

Peer

Represents an entity that can participate in conversations:

# Create peers (get-or-create API call)
alice = honcho.peer("alice")
assistant = honcho.peer("assistant")

# Create with immediate configuration
# This will make an API call to create the peer with the custom configuration and/or metadata
alice = honcho.peer("bob", config={"role": "user", "active": True}, metadata={"location": "NYC", "role": "developer"})

# Peer properties
print(f"Peer ID: {alice.id}")
print(f"Workspace: {alice.workspace_id}")
print(f"Created: {alice.created_at}")  # Available after API fetch

# Chat with peer's representations (supports streaming)
response = alice.chat("What did I have for breakfast?")
response = alice.chat("What do I know about Bob?", target="bob")
response = alice.chat("What happened in session-1?", session="session-1")
response = alice.chat("Summarize what matters most to me.", reasoning_level="high")

# Add content to a session with a peer
session = honcho.session("session-1")
session.add_messages([
  alice.message("I love Python programming"),
  alice.message("Today I learned about async programming"),
  alice.message("I prefer functional programming patterns")
])

# Get peer's sessions
sessions = alice.sessions()

# Search peer's messages
results = alice.search("programming")

# Metadata management
metadata = alice.get_metadata()
metadata["location"] = "Paris"
alice.set_metadata(metadata)

# Peer card management
card = alice.get_card()                          # Get peer card
card = alice.get_card(target="bob")              # Get card about another peer
updated = alice.set_card(["Likes Python", "Lives in NYC"])  # Set peer card
updated = alice.set_card(["Works at Acme"], target="bob")   # Set card about another peer

# Get peer context (representation + peer card in one call)
context = alice.context()
context = alice.context(target="bob")  # What alice knows about bob

# Get working representation with semantic search
rep = alice.representation(search_query="preferences", search_top_k=10)

# Access conclusions
self_conclusions = alice.conclusions.list()  # Self-conclusions
bob_conclusions = alice.conclusions_of("bob").list()  # Conclusions of bob

Peer Context

The context() method on peers retrieves both the working representation and peer card in a single API call:

# Get peer's own context
context = alice.context()
print(context.representation)  # Working representation
print(context.peer_card)       # Peer card as list of strings

# Get context about another peer (what alice knows about bob)
bob_context = alice.context(target="bob")

# Get context with semantic search
context = alice.context(
    target="bob",
    search_query="work preferences",
    search_top_k=10,
    search_max_distance=0.8,
    include_most_frequent=True,
    max_conclusions=50
)

Peer Card

The peer card contains stable biographical facts about a peer (name, preferences, background). Use get_card() / getCard() to retrieve it and set_card() / setCard() to overwrite it:

# Get peer's own card
card = alice.get_card()
print(card)  # ["Likes Python", "Lives in NYC", ...]

# Get card about another peer (local representation)
bob_card = alice.get_card(target="bob")

# Set peer's own card
updated = alice.set_card(["Likes Python", "Lives in NYC"])

# Set card about another peer
updated = alice.set_card(["Works at Acme", "Enjoys hiking"], target="bob")

Peer cards are automatically maintained by the dreaming agent during message processing. Use set_card() / setCard() when you need to manually override or seed the card — the peer will be created automatically if it doesn’t already exist.

Conclusions

Peers can access their conclusions (facts derived from messages) through the conclusions property and conclusions_of() method:

# Access self-conclusions (what honcho knows about alice)
self_conclusions = alice.conclusions

# List self-conclusions
conclusions_list = self_conclusions.list()

# Search self-conclusions semantically
results = self_conclusions.query("food preferences")

# Delete a conclusion
self_conclusions.delete("conclusion-id")

# Access conclusions of another peer (what alice knows about bob)
bob_conclusions = alice.conclusions_of("bob")
bob_conclusions_list = bob_conclusions.list()
bob_search = bob_conclusions.query("work history")

Creating Conclusions Manually

You can also create conclusions directly, which is useful for importing data or adding explicit facts:

# Create conclusions for what alice knows about bob
bob_conclusions = alice.conclusions_of("bob")

# Create a single conclusion
created = bob_conclusions.create([
    {"content": "User prefers dark mode", "session_id": "session-1"}
])

# Create multiple conclusions in batch
created = bob_conclusions.create([
    {"content": "User prefers dark mode", "session_id": "session-1"},
    {"content": "User works late at night", "session_id": "session-1"},
    {"content": "User enjoys programming", "session_id": "session-1"},
])

# Returns list of created Conclusion objects with IDs
for conclusion in created:
    print(f"Created conclusion: {conclusion.id} - {conclusion.content}")

Manually created conclusions are marked as “explicit” and are treated the same as system-derived conclusions. Each conclusion must be tied to a session and the content length is validated against the embedding token limit.

Session

Manages multi-party conversations:

# Create session (get-or-create API call)
session = honcho.session("conversation-1")

# Create with immediate configuration
# This will make an API call to create the session with the custom configuration and/or metadata
session = honcho.session("meeting-1", config={"type": "meeting", "max_peers": 10})

# Session properties
print(f"Session ID: {session.id}")
print(f"Workspace: {session.workspace_id}")
print(f"Created: {session.created_at}")  # Available after API fetch
print(f"Active: {session.is_active}")    # Available after API fetch

# Peer management
session.add_peers([alice, assistant])
session.add_peers([(alice, SessionPeerConfig(observe_others=True))])
session.set_peers([alice, bob, charlie])  # Replace all peers
session.remove_peers([alice])

# Get session peers and their configurations
peers = session.peers()
peer_config = session.get_peer_configuration(alice)
session.set_peer_configuration(alice, SessionPeerConfig(observe_me=False))

# Message management
session.add_messages([
    alice.message("Hello everyone!"),
    assistant.message("Hi Alice! How can I help today?")
])

# Get messages (with optional pagination)
messages = session.messages()
messages = session.messages(page=1, size=100, reverse=True)

# Get a single message by ID
message = session.get_message("message-id")

# Get conversation context
context = session.context(summary=True, tokens=2000)

# Get context with peer representation included
context = session.context(
    tokens=2000,
    peer_target="user",
    peer_perspective="assistant",
    search_query="What are my preferences?",
    limit_to_session=True,
    search_top_k=10,
    search_max_distance=0.8,
    include_most_frequent=True,
    max_conclusions=25
)

# Search session content
results = session.search("help")

# Working representation queries with semantic search
global_rep = session.representation("alice")
targeted_rep = session.representation(alice, target=bob)
searched_rep = session.representation(
    "alice",
    search_query="preferences",
    search_top_k=10,
    include_most_frequent=True
)

# Upload a file to create messages
messages = session.upload_file(
    file=open("document.pdf", "rb"),
    peer="user",
    metadata={"source": "upload"},
    created_at="2024-01-15T10:30:00Z"
)

# Clone a session (creates a copy with all data)
# Copies: messages, metadata, configuration, peers, and peer configurations
cloned = session.clone()

# Clone up to a specific message (inclusive)
# Only messages up to and including the specified message are copied
cloned_partial = session.clone(message_id="msg-123")

# Delete session (async - returns 202)
session.delete()

# Metadata management
session.set_metadata({"topic": "product planning", "status": "active"})
metadata = session.get_metadata()

Session-Level Theory of Mind Configuration:

Theory of Mind controls whether peers can form models of what other peers think. Use observe_others=False to prevent a peer from modeling others within a session, and observe_me=False to prevent others from modeling this peer within a session.

from honcho.api_types import SessionPeerConfig

# Configure peer observation settings
config = SessionPeerConfig(
    observe_others=False,  # Form theory-of-mind of other peers -- False by default
    observe_me=True        # Don't let others form theory-of-mind of me -- True by default
)

session.add_peers([(alice, config)])

SessionContext

Provides formatted conversation context for LLM integration:

# Get session context
context = session.context(summary=True, tokens=1500)

# Convert to LLM-friendly formats
openai_messages = context.to_openai(assistant=assistant)
anthropic_messages = context.to_anthropic(assistant=assistant)

The SessionContext object has the following structure:

{
  "id": "string",
  "messages": [
    {
      "id": "string",
      "content": "string",
      "peer_id": "string",
      "session_id": "string",
      "workspace_id": "string",
      "metadata": {},
      "created_at": "2024-01-15T10:30:00Z",
      "token_count": 42
    }
  ],
  "summary": {
    "content": "string",
    "message_id": 123,
    "summary_type": "short|long",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "peer_representation": "string (optional)",
  "peer_card": ["string"] // optional, included when peer_target is provided
}

Session Context Parameters:

Parameter	Type	Description
`summary`	`bool`	Whether to include summary (default: true)
`tokens`	`int`	Maximum tokens to include
`peer_target`	`str`	Peer ID to get representation for
`peer_perspective`	`str`	Peer ID for perspective (requires peer_target)
`limit_to_session`	`bool`	Limit representation to session only
`representationOptions.searchQuery`	`str` or `Message`	Query string or Message object for semantic search
`representationOptions.searchTopK`	`int`	Number of semantic search results (1-100)
`representationOptions.searchMaxDistance`	`float`	Max semantic distance (0.0-1.0)
`representationOptions.includeMostFrequent`	`bool`	Include most frequent conclusions
`representationOptions.maxConclusions`	`int`	Max conclusions to include (1-100)

Advanced Usage

Multi-Party Conversations

# Create multiple peers
users = [honcho.peer(f"user-{i}") for i in range(5)]
moderator = honcho.peer("moderator")

# Create group session
group_chat = honcho.session("group-discussion")
group_chat.add_peers(users + [moderator])

# Add messages from different peers
group_chat.add_messages([
    users[0].message("What's our agenda for today?"),
    moderator.message("We'll discuss the new feature roadmap"),
    users[1].message("I have some concerns about the timeline")
])

# Query different perspectives
user_perspective = users[0].chat("What are people's concerns?")
moderator_view = moderator.chat("What feedback am I getting?", session=group_chat.id)

LLM Integration

import openai

# Get conversation context
context = session.context(tokens=3000)
messages = context.to_openai(assistant=assistant)

# Call OpenAI API
response = openai.chat.completions.create(
    model="gpt-4",
    messages=messages + [
        {"role": "user", "content": "Summarize the key discussion points."}
    ]
)

Custom Message Timestamps

When creating messages, you can optionally specify a custom created_at timestamp instead of using the server’s current time:

curl -X POST "https://api.honcho.dev/v3/workspaces/{workspace_id}/sessions/{session_id}/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "peer_id": "user123",
        "content": "This message happened yesterday",
        "created_at": "2024-01-01T12:00:00Z",
        "metadata": {"source": "historical_data"}
      }
    ]
  }'

This is useful for:

Importing historical conversation data
Backfilling messages from other systems
Maintaining accurate timeline ordering when processing batch data

If created_at is not provided, messages will use the server’s current timestamp.

Metadata and Filtering

See Using Filters for more examples on how to use filters.

# Add messages with metadata
session.add_messages([
    alice.message("Let's discuss the budget", metadata={
        "topic": "finance",
        "priority": "high"
    }),
    assistant.message("I'll prepare the financial report", metadata={
        "action_item": True,
        "due_date": "2024-01-15"
    })
])

# Filter messages by metadata
finance_messages = session.messages(filters={"metadata": {"topic": "finance"}})
action_items = session.messages(filters={"metadata": {"action_item": True}})

Pagination

All list methods support page, size, and reverse parameters:

# Default pagination (page 1, size 50)
for session in honcho.sessions():
    print(f"Session: {session.id}")

# Custom page size
for message in session.messages(size=100):
    print(f"  {message.peer_id}: {message.content}")

# Start at a specific page
page3 = session.messages(page=3, size=25)

# Reverse ordering
recent_first = session.messages(reverse=True)

# Combine with filters
filtered = session.messages(filters={"peer_id": "alice"}, size=10)

Best Practices

Resource Management

# Peers and sessions are lightweight - create as needed
alice = honcho.peer("alice")
session = honcho.session("chat-1")

# Use descriptive IDs for better debugging
user_session = honcho.session(f"user-{user_id}-support-{ticket_id}")
support_agent = honcho.peer(f"agent-{agent_id}")

Performance Optimization

# Create peers (each makes a get-or-create call)
peers = [honcho.peer(f"user-{i}") for i in range(100)]

# Batch operations when possible
session.add_messages([peer.message(f"Message {i}") for i, peer in enumerate(peers)])

# Use context limits to control token usage
context = session.context(tokens=1500)  # Limit context size

Introduction

Core Concepts

Features

Reference

Installation

Quickstart

Core Concepts

Peers and Representations

Core Classes

Honcho Client

Peer

Peer Context

Peer Card

Conclusions

Creating Conclusions Manually

Session

SessionContext

Advanced Usage

Multi-Party Conversations

LLM Integration

Custom Message Timestamps

Metadata and Filtering

Best Practices

Resource Management

Performance Optimization

Introduction

Core Concepts

Features

Reference

​Installation

​Quickstart

​Core Concepts

​Peers and Representations

​Core Classes

​Honcho Client

​Peer

​Peer Context

​Peer Card

​Conclusions

​Creating Conclusions Manually

​Session

​SessionContext

​Advanced Usage

​Multi-Party Conversations

​LLM Integration

​Custom Message Timestamps

​Metadata and Filtering

​Pagination

​Best Practices

​Resource Management

​Performance Optimization

Installation

Quickstart

Core Concepts

Peers and Representations

Core Classes

Honcho Client

Peer

Peer Context

Peer Card

Conclusions

Creating Conclusions Manually

Session

SessionContext

Advanced Usage

Multi-Party Conversations

LLM Integration

Custom Message Timestamps

Metadata and Filtering

Pagination

Best Practices

Resource Management

Performance Optimization