Design Patterns

Design your workspace, peers, and sessions for common application patterns

This page covers how to structure workspaces, peers, and sessions for real applications. For the conceptual model behind them, start with Architecture.

Ready to add Honcho to your codebase? The /honcho-integration skill applies these patterns for you — it explores your code, asks how your peers and sessions should map to your app, and wires in the Honcho SDK. Run it in any coding agent that supports skills (Claude Code, Cursor, and others).

Quick Reference

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

Decision	Recommendation
How many workspaces?	One workspace per application, tool, tenant, or collaboration boundary. Split workspaces only when you need hard isolation between products, customers, environments, or agents.
When should agents share a workspace?	When agents collaborate over the same product, project, team, user, customer, or game state. Separate them when they should not see or influence each other’s memory.
Who should be a peer?	Any persistent participant whose messages should be attributed or reasoned about: users, agents, assistants, NPCs, students, or customers. Use one peer for the same entity across sessions and platforms.
How should I divide sessions?	Match each session to the active interaction: per-conversation, per-channel, per-task run, per-project, per-import, or other bounded context. Reuse a session when local context should keep accumulating.
How does cross-session reasoning work?	Session memory stays local to one session. Peer representations accumulate across every session where the peer is included, and session.context() becomes cross-session when you include a peer target.
Should I set observe_me: false?	Yes, for deterministic peers Honcho does not need to model, like bots or tool agents. Still save their messages so other peers have session context. Keep it enabled for users and evolving agents.
Do I need observe_others?	Only when a peer needs its own perspective on another participant, such as in games, multi-agent systems, or parent/subagent workflows.
When do I need a scope?	When one peer’s history spans contexts that must not leak into each other’s recall — but you still want one workspace and one unified peer. Group the confidential sessions into a scope and pass it at query time.
Perspectives or scopes?	observe_others gives a participant its own view of another peer. A scope bounds recall to where things were said, for a reader that isn’t a participant. If the reader is in the session, use perspectives; if you’re fencing off a set of sessions, use a scope.

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.

If what you actually need is “this part of a peer’s history shouldn’t inform that assistant,” don’t split the workspace — that severs the peer’s identity too. Use a scope instead: the peer stays whole, and recall through the scope sees only its member sessions.

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.

The SDK creates a workspace called default when no workspace_id is specified.

---

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

For unified context across Honcho plugins, set the same user peer ID (peerName) everywhere — that shared ID is what connects memory across Claude Code, Cursor, OpenCode, and your own app. See Unified Memory Setup.

---

Session Design

Sessions define the temporal boundaries of an interaction. Where you draw those boundaries affects how summaries are generated and how context is retrieved.

Common session patterns

Pattern	Session covers	Example
Per-conversation	Each new chat thread	ChatGPT or Claude Code 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-project	A persistent work area	Coding agent memory for one repository
Per-import	A batch of external data	Importing emails or documents for a single peer

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.

---

Choosing an Isolation Boundary

Honcho gives you three boundaries at different strengths. Pick the weakest one that solves your problem:

Boundary	Strength	Use when
Workspace	Hard isolation — nothing crosses, including the peer itself	Different products, tenants, or environments
Scope	Recall boundary — one peer, but queries through the scope see only its sessions	One peer’s contexts must not leak into each other (clinical vs. billing, per-reseller support)
Session allowlist (sessions=[...])	Ad-hoc recall restriction, decided per request	The session set varies per query, or you need a quick boundary without provisioning anything

Two things scopes are not:

• Not authorization. A workspace key reads any session, scoped or not. A scope constrains queries that name it; it doesn’t protect data from queries that don’t.
• Not topic filtering. Scopes bound recall by where something was said, not what it’s about. A therapy detail mentioned in a billing session lands in the billing scope. If you might ever need a scope boundary, align your session boundaries with your confidentiality boundaries from the start — the session is the unit scopes can enforce.

---

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 local to one session. Splitting a continuous conversation across many sessions fragments that local context. 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.
• A scope per reader — Scopes should map to real confidentiality boundaries, not to consumers. If every assistant gets its own scope, you’ve rebuilt workspace fragmentation inside one workspace, and each projection reasons over a thin slice. Fewer, boundary-shaped scopes; many readers can share one.
• Treating scopes as access control — A scope bounds recall, not access. Enforce who may query what in your application layer; use scopes to keep the answers themselves from drawing on out-of-bounds sessions.
• Forgetting peer_target on session context — session.context() defaults to the active session’s summary and recent messages, which are local to that session. 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

Unified Memory Setup

Wire these patterns into one shared workspace across four integrations

Get Context

Retrieve formatted context from sessions for your LLM

Scopes

Bound recall to named sets of sessions

Chat Endpoint

Query Honcho about your peers with natural language

Reasoning Configuration

Fine-tune what gets reasoned about and how