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!")
])

# Query peer representations in natural language
response = alice.chat("What did the assistant tell this user about the weather?")

# Get conversation context for LLM completions
context = session.get_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.get_peers()

# List all sessions in workspace
sessions = honcho.get_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.get_workspaces()

Peer and session creation is lazy - no API calls are made until you actually use the peer or session.

Peer

Represents an entity that can participate in conversations:

# Create peers (lazy creation - no API call yet)
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}")

# 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")

# 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.get_sessions()

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

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

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

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

# Access observations
self_observations = alice.observations.list()  # Self-observations
bob_observations = alice.observations_of("bob").list()  # Observations of bob

Peer Context

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

# Get peer's own context
context = alice.get_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.get_context(target="bob")

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

Observations

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

# Access self-observations (what honcho knows about alice)
self_obs = alice.observations

# List self-observations
obs_list = self_obs.list()

# Search self-observations semantically
results = self_obs.query("food preferences")

# Delete an observation
self_obs.delete("observation-id")

# Access observations of another peer (what alice knows about bob)
bob_obs = alice.observations_of("bob")
bob_obs_list = bob_obs.list()
bob_search = bob_obs.query("work history")

Peer Context

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

# Get peer's own context
context = alice.get_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.get_context(target="bob")

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

Observations

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

# Access self-observations (what honcho knows about alice)
self_obs = alice.observations

# List self-observations
obs_list = self_obs.list()

# Search self-observations semantically
results = self_obs.query("food preferences")

# Delete an observation
self_obs.delete("observation-id")

# Access observations of another peer (what alice knows about bob)
bob_obs = alice.observations_of("bob")
bob_obs_list = bob_obs.list()
bob_search = bob_obs.query("work history")

Creating Observations Manually

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

# Create observations for what alice knows about bob
bob_obs = alice.observations_of("bob")

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

# Create multiple observations in batch
created = bob_obs.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 Observation objects with IDs
for obs in created:
    print(f"Created observation: {obs.id} - {obs.content}")

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

Session

Manages multi-party conversations:

# Create session (like peers, lazy creation)
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}")

# 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.get_peers()
peer_config = session.get_peer_config(alice)
session.set_peer_config(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
messages = session.get_messages()

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

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

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

# Working representation queries with semantic search
global_rep = session.working_rep("alice")
targeted_rep = session.working_rep(alice, target=bob)
searched_rep = session.working_rep(
    "alice",
    search_query="preferences",
    search_top_k=10,
    include_most_derived=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 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.get_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)
`last_user_message`	`str`	Most recent message for semantic search
`limit_to_session`	`bool`	Limit representation to session only
`search_top_k`	`int`	Number of semantic search results (1-100)
`search_max_distance`	`float`	Max semantic distance (0.0-1.0)
`include_most_derived`	`bool`	Include most derived observations
`max_observations`	`int`	Max observations 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.get_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/v2.6.0-alpha/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.get_messages(filters={"metadata": {"topic": "finance"}})
action_items = session.get_messages(filters={"metadata": {"action_item": True}})

Pagination

# Iterate through all sessions
for session in honcho.get_sessions():
    print(f"Session: {session.id}")

    # Iterate through session messages
    for message in session.get_messages():
        print(f"  {message.peer_id}: {message.content}")

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

# Lazy creation - no API calls until needed
peers = [honcho.peer(f"user-{i}") for i in range(100)]  # Fast

# 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.get_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

Observations

Peer Context

Observations

Creating Observations 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

​Observations

​Peer Context

​Observations

​Creating Observations 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

Observations

Peer Context

Observations

Creating Observations Manually

Session

SessionContext

Advanced Usage

Multi-Party Conversations

LLM Integration

Custom Message Timestamps

Metadata and Filtering

Pagination

Best Practices

Resource Management

Performance Optimization