Quickstart

Start building with Honcho in under 5 minutes.

For production-level use, Honcho offers two powerful ways to leverage ambient personalization: our managed platform and our open source solution. Read further if you want to explore the quickstart demo.

Honcho Platform

Fully managed, hassle-free solution with one-click deployment

Honcho Open Source

Self-hosted, fully customizable, and open source

Getting Started

Have your project use Honcho’s ambient personalization capabilities in just a few steps. No signup required!

By default, the SDK uses the demo server hosted at demo.honcho.dev. The demo server is meant for quick experimentation and the data is cleared on a regular basis. Do not use for production applications.

For production use:

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

1. Install the SDK

Python (uv)

uv add honcho-ai

2. Initialize the Client

The Honcho client is the main entry point for interacting with Honcho’s API. By default, it uses the demo environment and a default workspace.

Demo Environment (Default)

Python

from honcho import Honcho

# Initialize client (uses demo environment and default workspace)
honcho = Honcho()

Production Environment

Python

import os
from honcho import Honcho

# Production environment with API key
honcho = Honcho(
    api_key=os.environ["HONCHO_API_KEY"],
    environment="production",
    # Create a workspace, otherwise set to "default"
    # workspaceId="your-workspace-id"
)

3. Create Peers

Peers represent individual users, AI agents, or any conversational entity in your system:

Python

alice = honcho.peer("alice")
bob = honcho.peer("bob")

4. Create a Session

Sessions are independent conversations that can include multiple peers:

Python

session = honcho.session("session_1")
session.add_peers([alice, bob])

5. Add Messages

Add some conversation messages. Honcho automatically learns from these interactions:

Python

session.add_messages([
    alice.message("Hi Bob, how are you?"),
    bob.message("I'm good, thank you!"),
    alice.message("What are you doing today after work?"),
    bob.message("I'm going to the gym! I've been trying to get back in shape."),
    alice.message("That's great! I should probably start exercising too."),
    bob.message("You should! I find that evening workouts help me relax."),
])

6. Query for Insights

Now ask Honcho what it’s learned - this is where the magic happens:

Python

# Ask what Bob is like
response = bob.chat("Tell me about Bob's interests and habits")
print(response)

# Returns rich context like:
# "Bob is health-conscious and has been working on getting back in shape.
# He regularly goes to the gym, particularly in the evenings, and finds
# exercise helps him relax. He's encouraging about fitness and willing
# to share advice about workout routines."

7. Putting it all together

Python

import os
from honcho import Honcho

# Create your client
honcho = Honcho(
    api_key=os.environ["HONCHO_API_KEY"],
    environment="production",
    # Create a workspace, otherwise set to "default"
    # workspaceId="your-workspace-id"
)

# Get your Peers
alice = honcho.peer("alice")
bob = honcho.peer("bob")

# Make a Session and add your Peers
session = honcho.session("session_1")
session.add_peers([alice, bob])

# Add messages sent by your Peers
session.add_messages([
    alice.message("Hi Bob, how are you?"),
    bob.message("I'm good, thank you!"),
    alice.message("What are you doing today after work?"),
    bob.message("I'm going to the gym! I've been trying to get back in shape."),
    alice.message("That's great! I should probably start exercising too."),
    bob.message("You should! I find that evening workouts help me relax."),
])

# Get insights about your Peers
response = bob.chat("Tell me about Bob's interests and habits")
print(response)

# Returns rich context like:
# "Bob is health-conscious and has been working on getting back in shape.
# He regularly goes to the gym, particularly in the evenings, and finds
# exercise helps him relax. He's encouraging about fitness and willing
# to share advice about workout routines."

What Just Happened?

You just got through building a simple conversation between two people, Alice and Bob. We:

1. Set up our connection to Honcho.
2. Setup who the participants of our conversation are, these are called Peers.
3. Made a Session and added our Peers to it.
4. Sent messages from our Peers
5. Chat with Honcho to get insights about one of the Peers in the conversation

As soon as you save a message in Honcho, it will start to reason about it to pull out insights and develop a profile of the user. This is the default behavior and can be toggled off via the configuration.

Next Steps

Architecture

Learn about the data primitives in Honcho and how they work together

Start Building

Sign up for Managed Honcho and get started building agents now.

Guides

Check out spellbooks to see different examples apps built with Honcho