Skip to main content
If you’re using a coding agent (Claude Code, Cursor, etc.), the /honcho-integration skill walks you through these decisions interactively. It explores your codebase, interviews you about peers and sessions, and generates the integration code. The patterns below are the same ones the skill uses.

​
Quick Reference

DecisionRecommendation
How many workspaces?One per application. Separate per-agent if you need hard data isolation.
Who should be a peer?Any entity you want Honcho to reason about — users, agents, NPCs, students, customers.
How should I scope sessions?Flexible — per-conversation, per-channel, per-scene, etc. See Session Design below.
Should I set observe_me: false?Yes, for any peer you don’t need Honcho to build a representation of — typically assistants or bots with deterministic behavior.
Do I need observe_others?Only when different peers need distinct views of the same participant (e.g., games, multi-agent). Most apps can leave it at the default (false).

​
Workspace Design

Workspaces are the top-level container. Everything inside a workspace (peers, sessions, messages, and all reasoning) is fully isolated from other workspaces. One workspace per application is the most common pattern. Use separate workspaces when you need hard isolation:
PatternWhen to use
Single workspaceMost applications. One product, one environment.
Per-tenantMulti-tenant SaaS where each customer’s data must be completely isolated.
If you are using the SDK, it will create a workspace called default if no name is specified for workspace_id

​
Peer Design

A peer is any entity that participates in a session. Observation settings control which ones Honcho reasons about. What makes a good peer?
  • It participates in sessions (a user, an agent, a character, an NPC)
  • It persists across sessions
  • It changes over time (preferences shift, knowledge grows), or it produces messages you want Honcho to see
Naming conventions Give peers stable, unique identifiers scoped to your application: 
# Prefix with the source platform for multi-channel apps
peer = honcho.peer("discord_491827364")
peer = honcho.peer("slack_U04ABCDEF")

# Use your own user IDs for backend integrations
peer = honcho.peer("user_abc123")

# Use descriptive names for agents/assistants
peer = honcho.peer("assistant")
peer = honcho.peer("dungeon-master")
If your Peer represents an entity that may go by multiple different names, such as nicknames indicate that in the Peer Card: 
peer = honcho.peer("user_abc123")
peer.set_card([
    "Name: Alice. Also known as 'Ali' and 'A'.",
    "College student, prefers casual tone.",
])
When to disable reasoning Not every peer needs a representation. Set observe_me: false on peers that behave deterministically. 
from honcho import PeerConfig

# The assistant doesn't need a representation
assistant = honcho.peer("assistant", configuration=PeerConfig(observe_me=False))

# The user does--this is who you want to understand
user = honcho.peer("user-123", configuration=PeerConfig(observe_me=True))

​
Session Design

Sessions define the temporal boundaries of an interaction. How you scope sessions directly affects how summaries are generated and how context is retrieved. Common session patterns
PatternSession scoped toExample
Per-conversationEach new chat threadChatGPT-style UI where each thread is a session
Per-channelA persistent channel or roomDiscord channel, Slack thread
Per-interactionA bounded task or encounterA support ticket, a game encounter
Per-importA batch of external dataImporting emails or documents for a single peer
When to create new sessions vs reuse
  • New session when the context resets (new conversation, new day, new topic)
  • Reuse session when context should accumulate (ongoing channel, persistent thread)

​
Application Patterns

​
AI Companions

An assistant that remembers the user across sessions and platforms. The Honcho plugin for OpenClaw is a production example—one assistant with memory across WhatsApp, Telegram, Discord, and Slack. 
from honcho import Honcho
from honcho.api_types import PeerConfig, SessionPeerConfig

honcho = Honcho(workspace_id="my-companion-app")

owner = honcho.peer("owner")
agent = honcho.peer("agent-main", configuration=PeerConfig(observe_me=False))

# Session key = thread + platform → separate histories, shared user memory
session = honcho.session("general-discord")
session.add_peers([
    (owner, SessionPeerConfig(observe_me=True, observe_others=False)),
    (agent, SessionPeerConfig(observe_me=True, observe_others=True)),
])

session.add_messages([
    owner.message("I've been stressed about the move to Portland next month"),
    agent.message("Moving is a big deal. What's weighing on you the most?"),
    owner.message("Honestly just leaving my friend group behind"),
])

# Query from any session or platform
response = owner.chat("What's going on in this user's life right now?")
Key decisions (from the OpenClaw plugin):
  • Session key = thread + platform — general-discord and general-telegram are separate sessions but share a single owner representation, so Honcho learns from every channel
  • Dynamic agent peers — each agent gets its own peer (agent-{id}), resolved via a workspace-level map. Renaming an agent recovers the peer by metadata lookup
  • Subagent hierarchy — when a primary agent spawns a subagent, the parent joins the child’s session as a silent observer (observe_me: false, observe_others: true), giving Honcho visibility into the full agent tree
  • Asymmetric observation — both owner and agent are observed, but with different scopes: owner has observe_others: false (default view), while the agent has observe_others: true so it can build its own representation of the owner. Subagents get lighter context (peer card only, no session summary)
See the OpenClaw integration guide for the full plugin setup.

​
Coding Agents

Coding agents survive terminal restarts, editor switches, and project hops. The Honcho plugin for Claude Code is a production example of this pattern. 
from honcho import Honcho
from honcho.api_types import PeerConfig

honcho = Honcho(workspace_id="claude_code")

# Developer is observed; agent is not
developer = honcho.peer("user")
agent = honcho.peer("claude", configuration=PeerConfig(observe_me=False))

# Session per project directory -- stable across restarts
session = honcho.session("user-honcho-repo")
session.add_peers([developer, agent])

session.add_messages([
    developer.message("refactor the auth module to use dependency injection"),
    agent.message("I'll extract the auth dependencies into a provider pattern..."),
    developer.message("actually let's keep it simpler, just pass the config directly"),
])

# In a future session, query what Honcho learned
context = developer.chat("What are this developer's preferences for code architecture?")
# Honcho knows: prefers simplicity, reverses decisions when simpler approach exists
Key decisions (from the Claude Code plugin):
  • One workspace per tool — Claude Code and Cursor each get their own workspace, with optional cross-linking for read access
  • Asymmetric peers — developer is observed (memory formation), agent is not observed but still stores messages so Honcho sees both sides
  • Session-per-directory by default — each project accumulates its own memory. Prefix with peer name (user-honcho-repo) so multiple developers on the same workspace don’t collide. Alternative strategies: git-branch (session switches on branch change) or chat-instance (clean slate each time)
  • Filter what you store — user messages go in real-time; agent messages are filtered to skip trivial tool output and keep substantive explanations
  • Import external data with single-peer sessions to ingest READMEs, architecture docs, or commit history into a developer’s representation
See the Claude Code integration guide for the full plugin setup.

​
Games

Games introduce multi-peer scenarios where information asymmetry matters. An NPC should only know what it has witnessed, not the full game state. 
from honcho import Honcho
from honcho.api_types import SessionPeerConfig

honcho = Honcho(workspace_id="my-rpg")

# Every character is a peer
player = honcho.peer("player-one")
merchant = honcho.peer("merchant-grim")
thief = honcho.peer("thief-shadow")

# Scene 1: Player talks to the merchant
tavern = honcho.session("tavern-scene")
tavern.add_peers([player, merchant])

# Enable the merchant to build its own representation of the player
tavern.set_peer_configuration(merchant, SessionPeerConfig(observe_others=True))

tavern.add_messages([
    player.message("I'm looking for a rare gemstone. Money is no object."),
    merchant.message("I may know of one... but it won't come cheap."),
])

# Scene 2: Player talks to the thief (merchant isn't here)
alley = honcho.session("dark-alley")
alley.add_peers([player, thief])
alley.set_peer_configuration(thief, SessionPeerConfig(observe_others=True))

alley.add_messages([
    player.message("I need that gemstone stolen from the merchant. Quietly."),
    thief.message("Consider it done. Half up front."),
])

# The merchant's view of the player: wealthy buyer seeking a gemstone
merchant_view = merchant.chat("What do I know about this player?", target="player-one")

# The thief's view: someone willing to steal from the merchant
thief_view = thief.chat("What do I know about this player?", target="player-one")

# Honcho's global view: knows both sides of the story
full_view = player.chat("What is this player up to?")
Key decisions:
  • Every character (player, NPC) is a peer
  • observe_others: true lets NPCs build their own representations of the player based only on what they’ve witnessed
  • Session-per-scene or session-per-encounter so context scopes to specific interactions
  • Use target when querying to get a specific NPC’s perspective rather than Honcho’s omniscient view
  • See Representation Scopes for the full details

​
Common Mistakes

  • Leaving observe_me on for assistants — Wastes reasoning compute on a peer you control. Deterministic behavior doesn’t need to be modeled.
  • Not storing messages — Honcho reasons about messages asynchronously. If you don’t call add_messages(), there’s nothing to reason about — no messages means no memory. See Storing Data for details.
  • Creating a new workspace per user — Use peers within a single workspace instead. Workspaces are for isolation between applications, not between users.
  • Too many tiny sessions — Summaries and session.context() are scoped to a single session. If you split a continuous conversation across many sessions, context is fragmented and each session is too short to summarize. Reuse a session when context should flow continuously.
  • Blocking on processing — Messages are processed asynchronously in the background. Don’t poll or wait for reasoning to complete before continuing your application flow.

​
Next Steps

Get Context

Retrieve formatted context from sessions for your LLM

Chat Endpoint

Query Honcho about your peers with natural language

Reasoning Configuration

Fine-tune what gets reasoned about and how

Representation Scopes

Directional representations for multi-peer scenarios