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
| Decision | Recommendation |
|---|
| 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:
| Pattern | When to use |
|---|
| Single workspace | Most applications. One product, one environment. |
| Per-tenant | Multi-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")
peer = honcho.peer("user_abc123")
peer.set_card([
"Name: Alice. Also known as 'Ali' and 'A'.",
"College student, prefers casual tone.",
])
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
| Pattern | Session scoped to | Example |
|---|
| Per-conversation | Each new chat thread | ChatGPT-style UI where each thread is a session |
| Per-channel | A persistent channel or room | Discord channel, Slack thread |
| Per-interaction | A bounded task or encounter | A support ticket, a game encounter |
| Per-import | A batch of external data | Importing emails or documents for a single peer |
- 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?")
- 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
- 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?")
- 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
