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

pip install honcho-ai

npm install @honcho-ai/sdk

yarn add @honcho-ai/sdk

pnpm add @honcho-ai/sdk

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)

import { Honcho } from "@honcho-ai/sdk";

// Initialize client (using the default workspace)
const honcho = new Honcho({});

// Create peers
const alice = await honcho.peer("alice");
const assistant = await honcho.peer("assistant");

// Create a session for conversation
const session = await honcho.session("conversation-1");

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

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

// Get conversation context for LLM completions
const context = await session.context();
const openaiMessages = context.toOpenAI(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)

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

// Query what alice knows about the assistant (local representation)
const targetResponse = await alice.chat("What does the user know about the assistant?", {
  target: assistant
});

// Query scoped to a specific session
const sessionResponse = await alice.chat("What happened in our conversation?", {
  sessionId: 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
)

import { Honcho } from "@honcho-ai/sdk";

// Basic initialization (uses environment variables)
const honcho = new Honcho({
  workspaceId: "my-app-name"
});

// Full configuration
const honcho = new Honcho({
  workspaceId: "my-app-name",
  apiKey: "my-api-key",
  environment: "production",  // or "local", "demo"
  baseURL: "https://api.honcho.dev",
  timeout: 30000,
  maxRetries: 3,
  defaultHeaders: { "X-Custom-Header": "value" },
  defaultQuery: { "param": "value" }
});

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()

// Get or create a peer
const peer = await honcho.peer(id);

// Get or create a session
const session = await honcho.session(id);

// List all peers in workspace (returns Page<Peer>)
const peers = await honcho.peers();

// List with pagination and filtering
const filtered = await honcho.peers({
  filters: { metadata: { role: "user" } },
  page: 1,
  size: 25,
  reverse: true
});

// List all sessions in workspace (returns Page<Session>)
const sessions = await honcho.sessions();

// Search across all content in workspace (returns Page<any>)
const results = await honcho.search(query);

// Workspace metadata management
const metadata = await honcho.getMetadata();
await honcho.setMetadata(metadata);

// Get list of all workspace IDs
const workspaces = await 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

// Create peers (returns Promise<Peer>)
const alice = await honcho.peer("alice");
const assistant = await honcho.peer("assistant");

// Peer properties
console.log(`Peer ID: ${alice.id}`);
console.log(`Created: ${alice.createdAt}`);  // Available after API fetch

// Chat with peer's representations (supports streaming)
const response = await alice.chat("What did I have for breakfast?");
const targetResponse = await alice.chat("What do I know about Bob?", { target: "bob" });
const sessionResponse = await alice.chat("What happened in session-1?", {
  sessionId: "session-1"
});
const deeperResponse = await alice.chat("Summarize what matters most to me.", {
  reasoningLevel: "high"
});

// Chat with streaming support
const streamResponse = await alice.chat("Tell me a story", { stream: true });

// Add content to a session with a peer
const session = await honcho.session("session-1");
await session.addMessages([
  alice.message("I love TypeScript programming"),
  alice.message("Today I learned about async programming"),
  alice.message("I prefer functional programming patterns")
]);

// Get peer's sessions
const sessions = await alice.sessions();

// Search peer's messages
const results = await alice.search("programming");

// Metadata management
const metadata = await alice.getMetadata();
await alice.setMetadata({
  ...metadata,
  location: "Paris"
});

// Peer card management
const card = await alice.getCard();                              // Get peer card
const targetCard = await alice.getCard("bob");                   // Get card about another peer
const updated = await alice.setCard(["Likes TypeScript", "Lives in NYC"]);  // Set peer card
const updatedTarget = await alice.setCard(["Works at Acme"], "bob");        // Set card about another peer

// Get peer context (representation + peer card in one call)
const context = await alice.context();
const targetContext = await alice.context({ target: "bob" });  // What alice knows about bob

// Get working representation with semantic search
const rep = await alice.representation({
  searchQuery: "preferences",
  searchTopK: 10
});

// Access conclusions
const selfConclusions = await alice.conclusions.list();  // Self-conclusions
const bobConclusions = await alice.conclusionsOf("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
)

// Get peer's own context
const context = await alice.context();
console.log(context.representation);  // Working representation
console.log(context.peerCard);        // Peer card as array of strings

// Get context about another peer (what alice knows about bob)
const bobContext = await alice.context({ target: "bob" });

// Get context with semantic search
const searchedContext = await alice.context({
  target: "bob",
  searchQuery: "work preferences",
  searchTopK: 10,
  searchMaxDistance: 0.8,
  includeMostFrequent: true,
  maxConclusions: 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")

// Get peer's own card
const card = await alice.getCard();
console.log(card);  // ["Likes TypeScript", "Lives in NYC", ...]

// Get card about another peer (local representation)
const bobCard = await alice.getCard("bob");

// Set peer's own card
const updated = await alice.setCard(["Likes TypeScript", "Lives in NYC"]);

// Set card about another peer
const updatedBob = await alice.setCard(["Works at Acme", "Enjoys hiking"], "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")

// Access self-conclusions (what honcho knows about alice)
const selfConclusions = alice.conclusions;

// List self-conclusions
const conclusionsList = await selfConclusions.list();

// Search self-conclusions semantically
const results = await selfConclusions.query("food preferences");

// Delete a conclusion
await selfConclusions.delete("conclusion-id");

// Access conclusions of another peer (what alice knows about bob)
const bobConclusions = alice.conclusionsOf("bob");
const bobConclusionsList = await bobConclusions.list();
const bobSearch = await bobConclusions.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}")

// Create conclusions for what alice knows about bob
const bobConclusions = alice.conclusionsOf("bob");

// Create a single conclusion
const created = await bobConclusions.create([
    { content: "User prefers dark mode", sessionId: "session-1" }
]);

// Create multiple conclusions in batch
const batchCreated = await bobConclusions.create([
    { content: "User prefers dark mode", sessionId: "session-1" },
    { content: "User works late at night", sessionId: "session-1" },
    { content: "User enjoys programming", sessionId: "session-1" },
]);

// Returns array of created Conclusion objects with IDs
for (const conclusion of batchCreated) {
    console.log(`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()

// Create session (returns Promise<Session>)
const session = await honcho.session("conversation-1");

// Session properties
console.log(`Session ID: ${session.id}`);
console.log(`Created: ${session.createdAt}`);  // Available after API fetch
console.log(`Active: ${session.isActive}`);    // Available after API fetch

// Peer management
await session.addPeers([alice, assistant]);
await session.addPeers("single-peer-id");
await session.setPeers([alice, bob, charlie]);  // Replace all peers
await session.removePeers([alice]);
await session.removePeers("single-peer-id");

// Get session peers
const peers = await session.peers();

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

// Get messages (with optional pagination)
const messages = await session.messages();
const paged = await session.messages({ page: 1, size: 100, reverse: true });

// Get a single message by ID
const message = await session.getMessage("message-id");

// Get conversation context
const context = await session.context({ summary: true, tokens: 2000 });

// Get context with peer representation included
const richContext = await session.context({
  tokens: 2000,
  peerTarget: "user",
  peerPerspective: "assistant",
  limitToSession: true,
  representationOptions: {
    searchQuery: "What are my preferences?",
    searchTopK: 10,
    searchMaxDistance: 0.8,
    includeMostFrequent: true,
    maxConclusions: 25
  }
});

// Search session content
const results = await session.search("help");

// Working representation queries with semantic search
const globalRep = await session.representation("alice");
const targetedRep = await session.representation(alice, { target: bob });
const searchedRep = await session.representation("alice", {
  searchQuery: "preferences",
  searchTopK: 10,
  includeMostFrequent: true
});

// Upload a file to create messages
const messages = await session.uploadFile(
  fileBuffer,
  "user",
  {
    metadata: { source: "upload" },
    createdAt: "2024-01-15T10:30:00Z"
  }
);

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

// Clone up to a specific message (inclusive)
// Only messages up to and including the specified message are copied
const clonedPartial = await session.clone("msg-123");

// Delete session (async - returns 202)
await session.delete();

// Metadata management
await session.setMetadata({
  topic: "product planning",
  status: "active"
});
const metadata = await session.getMetadata();

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

// Configure peer observation settings
const config = new SessionPeerConfig({
    observeOthers: false,  // Form theory-of-mind of other peers -- False by default
    observeMe: true        // Don't let others form theory-of-mind of me -- True by default
});

await session.addPeers([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)

// Get session context
const context = await session.context({ summary: true, tokens: 1500 });

// Convert to LLM-friendly formats
const openaiMessages = context.toOpenAI(assistant);
const anthropicMessages = context.toAnthropic(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)

// Create multiple peers
const users = await Promise.all(
  Array.from({ length: 5 }, (_, i) => honcho.peer(`user-${i}`))
);
const moderator = await honcho.peer("moderator");

// Create group session
const groupChat = await honcho.session("group-discussion");
await groupChat.addPeers([...users, moderator]);

// Add messages from different peers
await groupChat.addMessages([
  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
const userPerspective = await users[0].chat("What are people's concerns?");
const moderatorView = await moderator.chat("What feedback am I getting?", {
  sessionId: groupChat.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."}
    ]
)

import OpenAI from 'openai';

const openai = new OpenAI();

// Get conversation context
const context = await session.context({ tokens: 3000 });
const messages = context.toOpenAI(assistant);

// Call OpenAI API
const response = await 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}})

// Add messages with metadata
await session.addMessages([
  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
const financeMessages = await session.messages({
  filters: { metadata: { topic: "finance" } }
});
const actionItems = await 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)

// Default pagination (page 1, size 50)
const peersPage = await honcho.peers();

// Custom page size and filtering
const filtered = await honcho.peers({
  filters: { metadata: { role: "user" } },
  size: 25
});

// Start at a specific page
const page3 = await session.messages({ page: 3, size: 25 });

// Reverse ordering
const recent = await session.messages({ reverse: true });

// Iterate through all items (auto-paginates)
for await (const peer of await honcho.peers()) {
  console.log(`Peer: ${peer.id}`);
}

// Manual pagination
let currentPage = peersPage;
while (currentPage) {
  const data = await currentPage.data();
  console.log(`Processing ${data.length} items`);
  currentPage = await currentPage.nextPage();
}

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

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

// Use descriptive IDs for better debugging
const userSession = await honcho.session(`user-${userId}-support-${ticketId}`);
const supportAgent = await honcho.peer(`agent-${agentId}`);

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

// Create peers (each makes a get-or-create call)
const peers = await Promise.all(
  Array.from({ length: 100 }, (_, i) => honcho.peer(`user-${i}`))
);

// Batch operations when possible
await session.addMessages(
  peers.map((peer, i) => peer.message(`Message ${i}`))
);

// Use context limits to control token usage
const context = await session.context({ tokens: 1500 }); // Limit context size

// Iterate efficiently with async iteration
for await (const peer of await honcho.peers()) {
  // Process one peer at a time without loading all into memory
}

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

​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