From ee3598db5bb06bb50807b84d0f5e27d453cdeea7 Mon Sep 17 00:00:00 2001 From: ajspig Date: Wed, 15 Jul 2026 17:39:13 -0400 Subject: [PATCH] docs: fixing core language --- README.md | 2 +- skills/honcho-integration/SKILL.md | 6 ++-- .../references/agent-patterns.md | 10 +++--- .../references/bot-frameworks.md | 2 +- .../bot-frameworks/nanobot/session.py | 5 ++- .../references/core-patterns.md | 35 ++++++++++++------- skills/honcho-mcp/SKILL.md | 2 +- skills/honcho-memory/SKILL.md | 2 +- 8 files changed, 39 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 582f01aa..cfadf651 100644 --- a/README.md +++ b/README.md @@ -226,7 +226,7 @@ For wiring the Honcho SDK into an existing application, install the integration npx skills add plastic-labs/honcho ``` -Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs `honcho-memory` — the runtime counterpart that teaches an already-connected agent how to *use* Honcho as memory (recall/record loop, session and peer strategy). Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding). +Then invoke `/honcho-integration` in Claude Code (or `/honcho-dev:integrate` via the plugin marketplace). The same command also installs the memory skills — `honcho-memory` (concepts: the recall/record loop, session and peer strategy) plus its path skills `honcho-mcp` and `honcho-cli` that teach an already-connected agent how to actually drive the tools. Details: [agentic development guide](https://honcho.dev/docs/v3/documentation/introduction/vibecoding). ### Other MCP clients diff --git a/skills/honcho-integration/SKILL.md b/skills/honcho-integration/SKILL.md index ade9ff4a..c88f5673 100644 --- a/skills/honcho-integration/SKILL.md +++ b/skills/honcho-integration/SKILL.md @@ -1,6 +1,6 @@ --- name: honcho-integration -description: Integrate Honcho memory and social cognition into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, implementing the dialectic chat endpoint for AI agents, or wiring Honcho into bot frameworks (nanobot, openclaw, picoclaw, etc). +description: Integrate Honcho memory into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, and accessing Honcho's representation. allowed-tools: Read, Glob, Grep, Bash(uv:*), Bash(bun:*), Bash(npm:*), Edit, Write, WebFetch, AskUserQuestion --- @@ -10,7 +10,7 @@ allowed-tools: Read, Glob, Grep, Bash(uv:*), Bash(bun:*), Bash(npm:*), Edit, Wri Honcho is an open source memory library for building stateful agents. It works with any model, framework, or architecture. You send Honcho the messages from your conversations, and custom reasoning models process them in the background — extracting premises, drawing conclusions, and building rich representations of each participant over time. Your agent can then query those representations on-demand ("What does this user care about?", "How technical is this person?") and get grounded, reasoned answers. -The key mental model: **Peers** are any participant — human or AI. Both are represented the same way. Observation settings (`observe_me`, `observe_others`) control which peers Honcho reasons about. Typically you want Honcho to model your users (`observe_me=True`) but not your AI assistant (`observe_me=False`). **Sessions** scope conversations between peers. **Messages** are the raw data you feed in — Honcho reasons about them asynchronously and stores the results as the peer's **representation**. No messages means no reasoning means no memory. +The key mental model: **Peers** are any participant — human or AI. Both are represented the same way. Observation settings (`observe_me`, `observe_others`) control which peers Honcho reasons about. Typically you want Honcho to model your users (`observe_me=True`) but not anything with deterministic behavior (`observe_me=False`). **Sessions** scope conversations between peers. **Messages** are the raw data you feed in — Honcho reasons about them asynchronously and stores the results as the peer's **representation**. No messages means no reasoning means no memory. Your agent accesses this memory through `peer.chat(query)` (ask a natural language question, get a reasoned answer — a few seconds of live reasoning) or `session.context()` (near-instant read of formatted history + representation). Prefer `context()` for per-turn grounding; use `chat()` when you need a reasoned answer. @@ -118,7 +118,7 @@ Based on interview responses, implement the integration: 2. **Get an API key** ask the user to get a Honcho API key from and add it to the environment. -3. **Verify with the CLI** (optional but recommended). If the user has the Honcho CLI installed (`pip install honcho-cli`), they can validate their setup before writing any integration code: +3. **Verify with the CLI** (optional but recommended). If the user has the Honcho CLI installed (`uv install honcho-cli`), they can validate their setup before writing any integration code: ```bash honcho init # persist API key + URL to ~/.honcho/config.json diff --git a/skills/honcho-integration/references/agent-patterns.md b/skills/honcho-integration/references/agent-patterns.md index 021df64f..ca1865d9 100644 --- a/skills/honcho-integration/references/agent-patterns.md +++ b/skills/honcho-integration/references/agent-patterns.md @@ -2,13 +2,13 @@ How your AI accesses Honcho's user context. Pick based on the interview answer to Question Set 2. These build on the client/peer/session setup in `core-patterns.md`. -- **Pattern A — Dialectic chat as a tool call** (recommended for agents): the agent decides when to query context on-demand. +- **Pattern A — Dialectic chat as a tool call**: the agent decides when to query context on-demand. - **Pattern B — Pre-fetch with targeted queries**: fetch a fixed set of attributes before each LLM call. - **Pattern C — `context()` for LLM integration**: inject conversation history + representation into the prompt. > **Speed note.** `chat()` runs live dialectic reasoning (a few seconds) — Patterns A and B call it. `context()` (Pattern C) is a near-instant read. Prefer `context()` for per-turn grounding; reach for `chat()` when you genuinely need a reasoned answer. -## Pattern A: Dialectic Chat as a Tool Call (Recommended for Agents) +## Pattern A: Dialectic Chat as a Tool Call Make Honcho's chat endpoint available as a **tool** for your AI agent. This lets the agent query user context on-demand. @@ -152,7 +152,7 @@ async function getUserContextForPrompt(userId: string): Promise/`. diff --git a/skills/honcho-integration/references/bot-frameworks/nanobot/session.py b/skills/honcho-integration/references/bot-frameworks/nanobot/session.py index b5ebc081..f340f2a8 100644 --- a/skills/honcho-integration/references/bot-frameworks/nanobot/session.py +++ b/skills/honcho-integration/references/bot-frameworks/nanobot/session.py @@ -137,7 +137,10 @@ class HonchoSessionManager: session = self.honcho.session(session_id) - # Configure peer observation settings + # Configure peer observation settings. + # observe_me=False on the assistant skips modeling it — optional for an + # AI assistant (fine to leave observation on); it's really only needed + # for deterministic bots, where there's nothing meaningful to model. from honcho.api_types import SessionPeerConfig user_config = SessionPeerConfig(observe_me=True, observe_others=True) ai_config = SessionPeerConfig(observe_me=False, observe_others=True) diff --git a/skills/honcho-integration/references/core-patterns.md b/skills/honcho-integration/references/core-patterns.md index 16f172ab..2c6a84df 100644 --- a/skills/honcho-integration/references/core-patterns.md +++ b/skills/honcho-integration/references/core-patterns.md @@ -70,23 +70,31 @@ Create peers for **every entity** in your business logic - users AND AI assistan ```python from honcho.api_types import PeerConfig -# Human users +# Human users (observed by default) user = honcho.peer("user-123") -# AI assistants - set observe_me=False so Honcho doesn't model the AI -assistant = honcho.peer("assistant", configuration=PeerConfig(observe_me=False)) -support_bot = honcho.peer("support-bot", configuration=PeerConfig(observe_me=False)) +# AI assistants can be observed too — leave observe_me on (the default) if you +# want a model of the assistant. +assistant = honcho.peer("assistant") + +# Deterministic bots (scripted/rule-based) - set observe_me=False; there's +# nothing meaningful for Honcho to model. +notification_bot = honcho.peer("notification-bot", configuration=PeerConfig(observe_me=False)) ``` **TypeScript:** ```typescript -// Human users +// Human users (observed by default) const user = await honcho.peer("user-123"); -// AI assistants - set observeMe=false so Honcho doesn't model the AI -const assistant = await honcho.peer("assistant", { configuration: { observeMe: false } }); -const supportBot = await honcho.peer("support-bot", { configuration: { observeMe: false } }); +// AI assistants can be observed too — leave observeMe on (the default) if you +// want a model of the assistant. +const assistant = await honcho.peer("assistant"); + +// Deterministic bots (scripted/rule-based) - set observeMe=false; there's +// nothing meaningful for Honcho to model. +const notificationBot = await honcho.peer("notification-bot", { configuration: { observeMe: false } }); ``` ## 3. Multi-Peer Sessions @@ -103,12 +111,13 @@ session = honcho.session("conversation-123") # User is observed (Honcho builds a model of them) user_config = SessionPeerConfig(observe_me=True, observe_others=True) -# AI is NOT observed (no model built of the AI) -ai_config = SessionPeerConfig(observe_me=False, observe_others=True) +# A deterministic bot is NOT observed (no model built of it). An AI assistant +# could stay observed instead — observe_me defaults to True. +bot_config = SessionPeerConfig(observe_me=False, observe_others=True) session.add_peers([ (user, user_config), - (assistant, ai_config) + (notification_bot, bot_config) ]) ``` @@ -118,8 +127,10 @@ session.add_peers([ const session = await honcho.session("conversation-123"); await session.addPeers([ + // A deterministic bot isn't observed; an AI assistant could stay observed + // instead (observeMe defaults to true). [user, { observeMe: true, observeOthers: true }], - [assistant, { observeMe: false, observeOthers: true }] + [notificationBot, { observeMe: false, observeOthers: true }] ]); ``` diff --git a/skills/honcho-mcp/SKILL.md b/skills/honcho-mcp/SKILL.md index 5d6927c6..c9369a66 100644 --- a/skills/honcho-mcp/SKILL.md +++ b/skills/honcho-mcp/SKILL.md @@ -34,7 +34,7 @@ add_messages_to_session session_id: "" - peer_id: "Assistant" content: "" ``` -**Reuse the same `session_id` for the whole continuous conversation** (don't mint a new one per turn) — that's what lets the user's messages accumulate past the ~1,000-token reasoning threshold so Honcho actually reasons over them. And use **one stable `peer_id` per real person**, reused across every session and channel; a fresh or per-channel ID (`user-web` vs `user-discord`) builds separate, weaker representations instead of one. Set `observe_me: false` on the assistant peer — you want a model of the user, not of yourself. Reasoning is asynchronous; don't poll or wait for it. +**Reuse the same `session_id` for the whole continuous conversation** (don't mint a new one per turn) — that's what lets the user's messages accumulate past the ~1,000-token reasoning threshold so Honcho actually reasons over them. And use **one stable `peer_id` per real person**, reused across every session and channel; a fresh or per-channel ID (`user-web` vs `user-discord`) builds separate, weaker representations instead of one. Setting `observe_me: false` on the assistant peer skips building a model of it — reserve that for deterministic bots (nothing meaningful to model) or whenever you simply don't need a representation of the assistant; for an AI assistant it's perfectly fine to leave observation on. Reasoning is asynchronous; don't poll or wait for it. ## Other useful tools diff --git a/skills/honcho-memory/SKILL.md b/skills/honcho-memory/SKILL.md index cba8ebfd..2bc749e3 100644 --- a/skills/honcho-memory/SKILL.md +++ b/skills/honcho-memory/SKILL.md @@ -65,7 +65,7 @@ You need a Honcho API key — get one free at (starts w ## Rules of thumb - **Always record turns.** Memory only grows from messages you feed in. Recording is the one non-optional step. -- **Don't observe yourself.** The assistant peer should be `observe_me: false` — you want a model of the user, not of the agent. +- **Modeling the assistant is optional.** Setting `observe_me: false` on the assistant peer skips building a model of it — required only for deterministic bots (scripted output, nothing meaningful to model). For an AI assistant it's fine to leave observation on if you also want a model of the agent. - **One stable peer ID per entity.** Reuse the same `peer_id` for a person across every session and channel; splitting them (`user`, `user-web`, `user-discord`) builds separate representations and fragments memory. - **Scope sessions so reasoning actually fires.** Reasoning is token-batched per peer (~1,000 tokens within a session). Scope a session to one active interaction (per-conversation, per-channel, per-task, per-project); create a new one when context genuinely resets (new topic, new day), reuse it while context should keep accumulating. Many tiny sessions each stall below the threshold and never get reasoned over. - **Don't block on reasoning.** It's asynchronous. Respond now; the representation will be richer next time.