diff --git a/docs/v3/documentation/core-concepts/architecture.mdx b/docs/v3/documentation/core-concepts/architecture.mdx index 29702c59..52968ae6 100644 --- a/docs/v3/documentation/core-concepts/architecture.mdx +++ b/docs/v3/documentation/core-concepts/architecture.mdx @@ -20,25 +20,21 @@ Honcho has a hierarchical data model centered around the entities below. P <-.->|many-to-many| S - SC[Scopes] -.->|group| S - style W fill:#B6DBFF,stroke:#333,color:#000 style P fill:#B6DBFF,stroke:#333,color:#000 style S fill:#B6DBFF,stroke:#333,color:#000 style SM fill:#B6DBFF,stroke:#333,color:#000 - style SC fill:#FFE0B2,stroke:#333,color:#000 ``` - A Workspace has Peers & Sessions - A Peer can be in multiple Sessions and can send Messages in a Session - A Session can have many Peers and stores Messages sent by its Peers -- A Scope is a named set of Sessions that bounds recall to just those Sessions ### Workspaces Workspaces are the top-level containers in Honcho. They provide complete isolation between different applications or environments, essentially serving as a namespace to keep different workloads separate. You might use separate workspaces for development, staging, and production environments, or to isolate different product lines. They also enable multi-tenant SaaS applications where each customer gets their own isolated workspace with complete data separation. -Authentication is scoped to the workspace level, and configuration settings can be applied workspace-wide to control behavior across all peers and sessions within that workspace. +Authentication is issued at the workspace level, and configuration settings can be applied workspace-wide to control behavior across all peers and sessions within that workspace. --- @@ -54,19 +50,13 @@ You can use peers for any entity that persists over time--individual users in ch ### Sessions -Sessions represent interaction threads or contexts between peers. A session can involve multiple peers and provides temporal boundaries for when a set of interactions starts and ends. This lets you scope context and memory to specific interactions while still maintaining longer-term peer representations that span sessions. +Sessions represent interaction threads or contexts between peers. A session can involve multiple peers and provides temporal boundaries for when a set of interactions starts and ends. This lets you confine context and memory to specific interactions while still maintaining longer-term peer representations that span sessions. -Use sessions to scope things like support tickets, meeting transcripts, learning sessions, or conversations. You can also use single-peer sessions as a way to import external data--create a session with just one peer and structure emails, documents, or files as messages to enrich that peer's representation. +Use sessions for things like support tickets, meeting transcripts, learning sessions, or conversations. You can also use single-peer sessions as a way to import external data--create a session with just one peer and structure emails, documents, or files as messages to enrich that peer's representation. Session-level configuration gives you fine-grained control over perspective-taking behavior. You can configure whether a peer should form representations of other peers in the session, and whether other peers should form representations of them. ---- - -### Scopes - -Scopes are named sets of sessions that act as visibility boundaries for recall. When a query names a scope, Honcho answers only from what happened in that scope's sessions, while the peer keeps its single unified representation across everything. Use them when one peer's history spans contexts that shouldn't leak into each other--clinical sessions that must not inform a billing assistant, or one human working across multiple tenants. - -A session can belong to any number of scopes (or none), and queries that don't name a scope still see everything. See [Scopes](/v3/documentation/features/advanced/scopes) for how to create them and read through them. +Sessions are also the unit of visibility: when one peer's history spans contexts that shouldn't inform each other, you can group sessions into named [scopes](/v3/documentation/features/advanced/scopes) that bound recall to just those sessions. --- diff --git a/docs/v3/documentation/core-concepts/design-patterns.mdx b/docs/v3/documentation/core-concepts/design-patterns.mdx index c10c427d..f12ee6a5 100644 --- a/docs/v3/documentation/core-concepts/design-patterns.mdx +++ b/docs/v3/documentation/core-concepts/design-patterns.mdx @@ -12,14 +12,14 @@ Ready to add Honcho to your codebase? The **`/honcho-integration` skill** applie ## Quick Reference -**Workspaces isolate, peers persist, and sessions scope the active context.** +**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 scope sessions? | Scope sessions 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 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. | @@ -52,11 +52,11 @@ For unified context across Honcho plugins, set the same user peer ID (`peerName` ## 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. +Sessions define the temporal boundaries of an interaction. Where you draw those boundaries affects how summaries are generated, how context is retrieved, and when reasoning fires. **Common session patterns** -| Pattern | Session scoped to | Example | +| 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 | @@ -67,7 +67,7 @@ Sessions define the temporal boundaries of an interaction. How you scope them af Create a **new** session when context resets (new conversation, new day, new topic); **reuse** one when context should keep accumulating (ongoing channel, persistent thread). -**Don't scope sessions too thin.** Honcho batches reasoning until a peer accumulates ~1,000 tokens *within a single session*, with a default age-based flush for quiet tails ([token batching](/v3/documentation/core-concepts/reasoning#token-batching)). Low-volume or trickle inputs should still append to one ongoing session rather than fragment across many, so reasoning runs with useful context instead of many small delayed batches. +**Don't slice sessions too thin.** Honcho batches reasoning until a peer accumulates ~1,000 tokens *within a single session*, with a default age-based flush for quiet tails ([token batching](/v3/documentation/core-concepts/reasoning#token-batching)). Low-volume or trickle inputs should still append to one ongoing session rather than fragment across many, so reasoning runs with useful context instead of many small delayed batches. **How cross-session reasoning works** @@ -99,13 +99,13 @@ Two things scopes are **not**: ## 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. +- **Too many tiny sessions** -- Summaries and recent messages are local to one session, 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. - **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 session-scoped. It becomes cross-session only through adding a peer_target which includes the peer representation. +- **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 diff --git a/docs/v3/documentation/features/advanced/directional-representations.mdx b/docs/v3/documentation/features/advanced/directional-representations.mdx index 12e9329b..7a0c9562 100644 --- a/docs/v3/documentation/features/advanced/directional-representations.mdx +++ b/docs/v3/documentation/features/advanced/directional-representations.mdx @@ -214,7 +214,7 @@ Most applications don't need directional representations. Start with the default Under the hood, Honcho stores representations as (observer, observed) pairs in internal collections: - **Collection**: A unique (observer, observed, workspace) tuple containing documents -- **Documents**: Individual conclusions and artifacts (deductive, inductive, abductive conclusions, summaries, peer cards) with session scoping +- **Documents**: Individual conclusions and artifacts (deductive, inductive, abductive conclusions, summaries, peer cards) with per-session filtering When you retrieve with `target`, Honcho fetches documents from the specific (observer, observed) collection. When you retrieve without `target`, it fetches from the (peer, peer) collection—the peer's self-representation. @@ -225,7 +225,7 @@ This architecture enables: ## Semantic Search Parameters -Both `representation()` and `chat()` support semantic filtering to retrieve a subset of relevant conclusions. You can optionally filter by session — pass `session` to scope to a single session, or use the REST-only [session allowlist](/v3/documentation/features/advanced/using-filters#scoping-recall-to-sessions) to scope to a set of sessions: +Both `representation()` and `chat()` support semantic filtering to retrieve a subset of relevant conclusions. You can optionally filter by session — pass `session` to restrict to a single session, or use the REST-only [session allowlist](/v3/documentation/features/advanced/using-filters#scoping-recall-to-sessions) to restrict to a set of sessions: | Parameter | Type | Description | |-----------|------|-------------| @@ -265,7 +265,7 @@ Directional representations update automatically through the reasoning pipeline 2. The message sender has `observe_me=true` (or session-level equivalent) 3. Other peers in the session have `observe_others=true` -The pipeline respects scoping—Honcho's representations reason over messages across all sessions, while directional representations only reason over messages from sessions where the observer was an active participant. +The pipeline respects these boundaries—Honcho's representations reason over messages across all sessions, while directional representations only reason over messages from sessions where the observer was an active participant. ### Peer Join Order Matters diff --git a/docs/v3/documentation/features/advanced/queue-status.mdx b/docs/v3/documentation/features/advanced/queue-status.mdx index 7c4d363c..44e9a045 100644 --- a/docs/v3/documentation/features/advanced/queue-status.mdx +++ b/docs/v3/documentation/features/advanced/queue-status.mdx @@ -95,7 +95,7 @@ not the total number of items ever processed. The `queue_status` method can take additional -parameters to scope the status to a specific work unit: +parameters to narrow the status to a specific work unit: ```python Python diff --git a/docs/v3/documentation/features/advanced/using-filters.mdx b/docs/v3/documentation/features/advanced/using-filters.mdx index 3af0fdbe..e28096ab 100644 --- a/docs/v3/documentation/features/advanced/using-filters.mdx +++ b/docs/v3/documentation/features/advanced/using-filters.mdx @@ -727,7 +727,7 @@ messages = session.messages(filters={ ### Filtering Conclusions -Conclusions are scoped to an observer/observed peer pair (accessed via +Conclusions belong to an observer/observed peer pair (accessed via `peer.conclusions` for self-conclusions or `peer.conclusions_of(target)` for conclusions about another peer). The observer and observed are filled in automatically by the scope, so the `filters` you pass add to them. @@ -843,7 +843,7 @@ a **session allowlist**, restricting what the request can recall to the sessions you name — conclusions on both endpoints, and on chat the messages the agent reads as well. -This is how you scope recall to more than one session. The `session_id` +This is how you restrict recall to more than one session. The `session_id` parameter pins a request to exactly one session; an allowlist accepts a set. Only the `session_id` key is supported here, in three shapes: @@ -931,7 +931,7 @@ can only narrow. ### What Changes Under an Allowlist -Scoping recall by session narrows what the reasoning agent can draw on: +Restricting recall by session narrows what the reasoning agent can draw on: - **Only `explicit` conclusions are recalled.** Dream-derived conclusions (`deductive`, `inductive`) are synthesized across sessions, so they can't be diff --git a/docs/v3/documentation/features/chat.mdx b/docs/v3/documentation/features/chat.mdx index b6e7e96c..dc58b144 100644 --- a/docs/v3/documentation/features/chat.mdx +++ b/docs/v3/documentation/features/chat.mdx @@ -110,7 +110,7 @@ const answer = await peer.chat("What did the user ask about?", { session: sessio ``` -To scope a request to a *set* of sessions, use the session allowlist — a +To restrict a request to a *set* of sessions, use the session allowlist — a constrained `filters` body on the endpoint. See [Scoping Recall to Sessions](/v3/documentation/features/advanced/using-filters#scoping-recall-to-sessions) for the accepted shapes and for what an allowlist changes about the answer. diff --git a/docs/v3/documentation/reference/cli.mdx b/docs/v3/documentation/reference/cli.mdx index 9686199d..74b5fb34 100644 --- a/docs/v3/documentation/reference/cli.mdx +++ b/docs/v3/documentation/reference/cli.mdx @@ -89,14 +89,14 @@ and are stored under `oauth` without deleting a shared `apiKey`. } ``` -Per-command scoping (workspace / peer / session) is handled via `-w` / `-p` / `-s` +Per-command targeting (workspace / peer / session) is handled via `-w` / `-p` / `-s` flags or `HONCHO_*` env vars. **Not** persisted as CLI defaults. This is deliberate: every invocation is explicit about what it operates on. ### Runtime overrides -Workspace, peer, and session scoping are **per-command only** — pass flags or +Workspace, peer, and session targeting are **per-command only** — pass flags or `HONCHO_*` env vars on every invocation. ```bash diff --git a/docs/v3/guides/community/pi-honcho-memory.mdx b/docs/v3/guides/community/pi-honcho-memory.mdx index 7974a94b..6ef1c5e0 100644 --- a/docs/v3/guides/community/pi-honcho-memory.mdx +++ b/docs/v3/guides/community/pi-honcho-memory.mdx @@ -23,7 +23,7 @@ The Honcho plugin is a community integration. See the [plugin README](https://gi ## How It Works -The extension hooks into pi's extension system. It automatically syncs user and assistant messages to Honcho after each agent response, injects cached user profile and project context into the system prompt with zero network latency, and exposes LLM tools (`honcho_search`, `honcho_chat`, `honcho_remember`) for active memory operations. Session scoping is configurable — memory can be shared per repo, per git branch, or per directory. If Honcho is unavailable, pi continues working normally. +The extension hooks into pi's extension system. It automatically syncs user and assistant messages to Honcho after each agent response, injects cached user profile and project context into the system prompt with zero network latency, and exposes LLM tools (`honcho_search`, `honcho_chat`, `honcho_remember`) for active memory operations. Session mapping is configurable — memory can be shared per repo, per git branch, or per directory. If Honcho is unavailable, pi continues working normally. ## Next Steps diff --git a/docs/v3/guides/integrations/paperclip.mdx b/docs/v3/guides/integrations/paperclip.mdx index d5c216a4..bbda60f3 100644 --- a/docs/v3/guides/integrations/paperclip.mdx +++ b/docs/v3/guides/integrations/paperclip.mdx @@ -61,11 +61,11 @@ In practice, that means agent peers can both be observed by Honcho and form repr ## How It Works -### Identity And Scope +### Identity And Mapping The integration breaks down into four parts: -- **Identity and scope** - each Paperclip company maps to a Honcho workspace, agents and human actors map to peers, and issues map to sessions. +- **Identity and mapping** - each Paperclip company maps to a Honcho workspace, agents and human actors map to peers, and issues map to sessions. - **What gets copied into Honcho** - issue comments and document revisions sync into Honcho, with document content sectioned and normalized message content capped before ingestion. - **What operators get** - operators get a plugin settings page, migration preview/status data, including a per-issue migration mapping preview, repair tools, and an issue-level `Memory` tab. - **What agents get** - agents get Honcho retrieval and peer-chat tools inside Paperclip. diff --git a/docs/v3/guides/recipes/unified-memory-setup.mdx b/docs/v3/guides/recipes/unified-memory-setup.mdx index ea921cc3..21b6d0f1 100644 --- a/docs/v3/guides/recipes/unified-memory-setup.mdx +++ b/docs/v3/guides/recipes/unified-memory-setup.mdx @@ -109,7 +109,7 @@ and `aiPeer` there. See the [Hermes guide](/v3/guides/integrations/hermes) for t A scheduled job feeds external data (emails, meeting notes, CRM records) into Honcho. Attribute the messages to the peer the data is *about* — not to an agent — and group -them into a session. **How you scope that session is the main decision here**, because +them into a session. **How you bound that session is the main decision here**, because it controls when Honcho reasons over the data (more on that below). ```python @@ -133,7 +133,7 @@ for i in range(0, len(messages), 100): Honcho batches reasoning until a peer accumulates ~1,000 tokens *within a single session*, with a default age-based flush for quiet tails -([token batching](/v3/documentation/core-concepts/reasoning#token-batching)). Scope the +([token batching](/v3/documentation/core-concepts/reasoning#token-batching)). Match the session to the volume you ingest: - **High-volume runs** (a day of emails, a CRM export) clear the threshold easily — a