Design Patterns

​

Quick Reference

Workspaces isolate, peers persist, and sessions scope the active context.

​

Workspace Design

A workspace is a hard isolation boundary. Default to one workspace per application, and split only at a real privacy, compliance, or product boundary (e.g. per-tenant SaaS, or a tool that needs intentionally isolated memory). Agents that collaborate over the same product, user, or game state belong in the same workspace so each can retrieve what the others produced. Honcho plugins default to one workspace per host (hermes, claude_code, cursor, opencode). To unify memory across them, point each at the same workspace — see Unified Memory Setup.

---

​

Peer Design

Give each real-world entity one stable peer ID and reuse it everywhere — splitting one entity across user-web, user-discord, and user-slack builds three separate representations. Prefix IDs by source for multi-channel apps (discord_491827364), and if a peer goes by multiple names, store the aliases in its peer card with set_card() / setCard().

---

​

Session Design

Sessions define the temporal boundaries of an interaction. How you scope them affects how summaries are generated, how context is retrieved, and when reasoning fires. Common session patterns Create a new session when context resets (new conversation, new day, new topic); reuse one when context should keep accumulating (ongoing channel, persistent thread). How cross-session reasoning works

• Session memory is local to an interaction — summaries and recent-message context describe only what happened there.
• Peer memory (representations) accumulates reasoning across every session the peer is part of.

So you can start a session fresh or pull in a peer’s long-term memory. session.context() returns the current session’s summary and recent messages; add a peer target to fold in that peer’s cross-session history.

---

​

Common Mistakes

• Splitting one identity across peer IDs — If the same user is alice, alice-discord, and alice-cursor, Honcho builds separate representations. Use one stable peer ID when you want unified memory.
• Too many tiny sessions — Summaries and recent messages are session-scoped, and reasoning only fires past ~1,000 tokens per session. Splitting a continuous conversation across many sessions fragments local context and can stall reasoning. Reuse a session when context should flow continuously.
• Separating agents that should collaborate — If agents need shared product, customer, or team context, put them in the same workspace. Separate workspaces are hard isolation boundaries.
• Leaving observe_me on for assistants — Wastes reasoning compute on a peer you control. Deterministic behavior doesn’t need to be modeled.
• Turning on observe_others everywhere — Directional representations are powerful, but they add complexity. Use them when peers need distinct perspectives, not just because a session has multiple peers.
• Forgetting peer_target on session context — session.context() defaults to the active session’s summary and recent messages, which are session-scoped. It becomes cross-session only through adding a peer_target which includes the peer representation.
• 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