diff --git a/docs/docs.json b/docs/docs.json index 2bf78973..c5356b35 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -19,21 +19,14 @@ }, "favicon": "/favicon.svg", "contextual": { - "options": [ - "copy", - "view", - "chatgpt", - "claude" - ] + "options": ["copy", "view", "chatgpt", "claude"] }, "navigation": { "versions": [ { "version": "v3.0.3", "api": { - "openapi": [ - "v3/openapi.json" - ] + "openapi": ["v3/openapi.json"] }, "tabs": [ { @@ -52,12 +45,14 @@ "pages": [ "v3/documentation/core-concepts/architecture", "v3/documentation/core-concepts/reasoning", - "v3/documentation/core-concepts/representation" + "v3/documentation/core-concepts/representation", + "v3/documentation/core-concepts/design-patterns" ] }, { "group": "Features", "pages": [ + "v3/documentation/features/storing-data", "v3/documentation/features/get-context", "v3/documentation/features/chat", { @@ -71,7 +66,8 @@ "v3/documentation/features/advanced/summarizer", "v3/documentation/features/advanced/search", "v3/documentation/features/advanced/using-filters", - "v3/documentation/features/advanced/streaming-response" + "v3/documentation/features/advanced/streaming-response", + "v3/documentation/features/advanced/file-uploads" ] } ] @@ -90,11 +86,7 @@ "groups": [ { "group": "Overview", - "pages": [ - "v3/guides/overview", - "v3/guides/file-uploads", - "v3/guides/storing-data" - ] + "pages": ["v3/guides/overview"] }, { "group": "Integrations", @@ -104,22 +96,27 @@ "v3/guides/integrations/langgraph", "v3/guides/integrations/mcp", "v3/guides/integrations/n8n", - "v3/guides/integrations/openclaw", + "v3/guides/integrations/openclaw" + ] + }, + { + "group": "Tutorials", + "pages": [ + "v3/guides/discord", + "v3/guides/telegram", "v3/guides/integrations/reachy-mini" ] }, { - "group": "Migrations", + "group": "Community Integrations", "pages": [ - "v3/guides/migrations/mem0" + "v3/guides/community/agent0", + "v3/guides/community/hermes" ] }, { - "group": "Chatbots", - "pages": [ - "v3/guides/discord", - "v3/guides/telegram" - ] + "group": "Migrations", + "pages": ["v3/guides/migrations/mem0"] } ] }, @@ -147,9 +144,7 @@ "groups": [ { "group": "API Documentation", - "pages": [ - "v3/api-reference/introduction" - ] + "pages": ["v3/api-reference/introduction"] }, { "group": "workspaces", @@ -227,9 +222,7 @@ }, { "group": "miscellaneous", - "pages": [ - "v3/api-reference/endpoint/keys/create-key" - ] + "pages": ["v3/api-reference/endpoint/keys/create-key"] } ] }, @@ -250,9 +243,7 @@ { "version": "v2.5.1", "api": { - "openapi": [ - "v2/openapi.json" - ] + "openapi": ["v2/openapi.json"] }, "tabs": [ { @@ -299,15 +290,11 @@ "groups": [ { "group": "Getting Started", - "pages": [ - "v2/guides/overview" - ] + "pages": ["v2/guides/overview"] }, { "group": "Migrations", - "pages": [ - "v2/migrations/from-mem0" - ] + "pages": ["v2/migrations/from-mem0"] }, { "group": "Integrations", @@ -320,10 +307,7 @@ }, { "group": "Application Interfaces", - "pages": [ - "v2/guides/discord", - "v2/guides/telegram" - ] + "pages": ["v2/guides/discord", "v2/guides/telegram"] } ] }, @@ -332,9 +316,7 @@ "groups": [ { "group": "API Documentation", - "pages": [ - "v2/api-reference/introduction" - ] + "pages": ["v2/api-reference/introduction"] }, { "group": "workspaces", @@ -438,9 +420,7 @@ { "version": "v1.1.0", "api": { - "openapi": [ - "openapi.json" - ] + "openapi": ["openapi.json"] }, "tabs": [ { @@ -470,23 +450,15 @@ "groups": [ { "group": "Getting Started", - "pages": [ - "v1/guides/overview", - "v1/guides/streaming-response" - ] + "pages": ["v1/guides/overview", "v1/guides/streaming-response"] }, { "group": "Application Interfaces", - "pages": [ - "v1/guides/discord", - "v1/guides/honcho-mcp" - ] + "pages": ["v1/guides/discord", "v1/guides/honcho-mcp"] }, { "group": "Personal Memory", - "pages": [ - "v1/guides/dialectic-endpoint" - ] + "pages": ["v1/guides/dialectic-endpoint"] } ] }, @@ -495,9 +467,7 @@ "groups": [ { "group": "API Documentation", - "pages": [ - "v1/api-reference/introduction" - ] + "pages": ["v1/api-reference/introduction"] }, { "group": "apps", @@ -545,9 +515,7 @@ }, { "group": "keys", - "pages": [ - "v1/api-reference/endpoint/keys/create-key" - ] + "pages": ["v1/api-reference/endpoint/keys/create-key"] }, { "group": "metamessages", diff --git a/docs/v3/documentation/core-concepts/design-patterns.mdx b/docs/v3/documentation/core-concepts/design-patterns.mdx new file mode 100644 index 00000000..9f871cd0 --- /dev/null +++ b/docs/v3/documentation/core-concepts/design-patterns.mdx @@ -0,0 +1,378 @@ +--- +title: Design Patterns +description: "Design your workspace, peers, and sessions for common application patterns" +icon: "cubes" +--- + + +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](#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: + + +```python Python +# 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") +``` + +```typescript TypeScript +// Prefix with the source platform for multi-channel apps +const peer = await honcho.peer("discord_491827364"); +const peer = await honcho.peer("slack_U04ABCDEF"); + +// Use your own user IDs for backend integrations +const peer = await honcho.peer("user_abc123"); + +// Use descriptive names for agents/assistants +const peer = await honcho.peer("assistant"); +const peer = await honcho.peer("dungeon-master"); +``` + + +If your Peer represents an entity that may go by multiple different names, such as nicknames indicate that in the Peer Card: + + +```python Python +peer = honcho.peer("user_abc123") +peer.set_card([ + "Name: Alice. Also known as 'Ali' and 'A'.", + "College student, prefers casual tone.", +]) +``` + +```typescript TypeScript +const peer = await honcho.peer("user_abc123"); +await peer.setCard([ + "Name: Alice. Also known as 'Ali' and 'A'.", + "College student, prefers casual tone.", +]); +``` + + +**When to disable reasoning** + +Not every peer needs a representation. Set `observe_me: false` on peers that behave deterministically. + + +```python Python +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)) +``` + +```typescript TypeScript +const assistant = await honcho.peer("assistant", { configuration: { observeMe: false } }); +const user = await honcho.peer("user-123", { configuration: { observeMe: 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 | + +**When to create new sessions vs reuse** + +- **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](/v3/guides/integrations/openclaw) is a production example--one assistant with memory across WhatsApp, Telegram, Discord, and Slack. + + +```python Python +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?") +``` + +```typescript TypeScript +const honcho = new Honcho({ workspaceId: "my-companion-app" }); + +const owner = await honcho.peer("owner"); +const agent = await honcho.peer("agent-main", { configuration: { observeMe: false } }); + +const session = await honcho.session("general-discord"); +await session.addPeers([ + ["owner", { observeMe: true, observeOthers: false }], + ["agent-main", { observeMe: true, observeOthers: true }], +]); + +await session.addMessages([ + 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"), +]); + +const response = await owner.chat("What's going on in this user's life right now?"); +``` + + +**Key decisions (from the [OpenClaw plugin](/v3/guides/integrations/openclaw)):** +- **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](/v3/guides/integrations/openclaw) for the full plugin setup. + +--- + +### Coding Agents + +Coding agents survive terminal restarts, editor switches, and project hops. The [Honcho plugin for Claude Code](/v3/guides/integrations/claude-code) is a production example of this pattern. + + +```python Python +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 +``` + +```typescript TypeScript +const honcho = new Honcho({ workspaceId: "claude_code" }); + +const developer = await honcho.peer("user"); +const agent = await honcho.peer("claude", { configuration: { observeMe: false } }); + +const session = await honcho.session("user-honcho-repo"); +await session.addPeers([developer, agent]); + +await session.addMessages([ + 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"), +]); + +const context = await developer.chat("What are this developer's preferences for code architecture?"); +``` + + +**Key decisions (from the Claude Code plugin):** +- **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](/v3/guides/integrations/claude-code) 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. + + +```python Python +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?") +``` + +```typescript TypeScript +const honcho = new Honcho({ workspaceId: "my-rpg" }); + +const player = await honcho.peer("player-one"); +const merchant = await honcho.peer("merchant-grim"); +const thief = await honcho.peer("thief-shadow"); + +const tavern = await honcho.session("tavern-scene"); +await tavern.addPeers([player, merchant]); +await tavern.setPeerConfiguration(merchant, { observeOthers: true }); + +await tavern.addMessages([ + 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."), +]); + +const alley = await honcho.session("dark-alley"); +await alley.addPeers([player, thief]); +await alley.setPeerConfiguration(thief, { observeOthers: true }); + +await alley.addMessages([ + player.message("I need that gemstone stolen from the merchant. Quietly."), + thief.message("Consider it done. Half up front."), +]); + +const merchantView = await merchant.chat("What do I know about this player?", { target: "player-one" }); +const thiefView = await thief.chat("What do I know about this player?", { target: "player-one" }); +const fullView = await player.chat("What is this player up to?"); +``` + + +**Key decisions:** +- 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](/v3/documentation/features/advanced/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](/v3/documentation/features/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 + + + + Retrieve formatted context from sessions for your LLM + + + Query Honcho about your peers with natural language + + + Fine-tune what gets reasoned about and how + + + Directional representations for multi-peer scenarios + + diff --git a/docs/v3/guides/file-uploads.mdx b/docs/v3/documentation/features/advanced/file-uploads.mdx similarity index 100% rename from docs/v3/guides/file-uploads.mdx rename to docs/v3/documentation/features/advanced/file-uploads.mdx diff --git a/docs/v3/guides/storing-data.mdx b/docs/v3/documentation/features/storing-data.mdx similarity index 100% rename from docs/v3/guides/storing-data.mdx rename to docs/v3/documentation/features/storing-data.mdx diff --git a/docs/v3/guides/community/agent0.mdx b/docs/v3/guides/community/agent0.mdx new file mode 100644 index 00000000..1eb8ea24 --- /dev/null +++ b/docs/v3/guides/community/agent0.mdx @@ -0,0 +1,33 @@ +--- +title: "Agent Zero" +icon: 'triangle' +description: "Add AI-native memory to Agent Zero" +sidebarTitle: 'Agent Zero' +--- + +[Agent Zero](https://github.com/agent0ai/agent-zero) is a general AI agent framework with a plugin-first architecture. The Honcho plugin gives Agent Zero persistent memory across chat sessions — users are remembered with their preferences, context, and behavioral patterns, even after sessions end and new ones begin. + +## Getting Started + +The Honcho plugin is a community integration. See the [plugin README](https://github.com/alogotron/a0-plugin-honcho) for full installation and configuration instructions. + +The integration requires: +1. A Honcho API key from [app.honcho.dev](https://app.honcho.dev) +2. Cloning the plugin into your Agent Zero plugins directory +3. Enabling it via **Settings > Plugins** in Agent Zero's UI + +## How It Works + +The plugin hooks into Agent Zero's extension system. It syncs user and assistant messages to Honcho after every turn, prefetches user context into the system prompt on each new turn, and maintains separate peer models for the user and agent. If Honcho is unavailable, the agent continues normally. + +## Next Steps + + + + Source code, installation, and full documentation. + + + + Learn about peers, sessions, and dialectic reasoning. + + diff --git a/docs/v3/guides/community/hermes.mdx b/docs/v3/guides/community/hermes.mdx new file mode 100644 index 00000000..d22cb2e4 --- /dev/null +++ b/docs/v3/guides/community/hermes.mdx @@ -0,0 +1,33 @@ +--- +title: "Hermes Agent" +icon: 'bolt' +description: "Add AI-native memory to Hermes Agent" +sidebarTitle: 'Hermes Agent' +--- + +[Hermes Agent](https://github.com/NousResearch/hermes-agent) is an open-source AI agent from Nous Research with advanced tool-calling capabilities, terminal access, a skills system, and multi-platform deployment (Telegram, Discord, Slack, WhatsApp). The Honcho integration gives Hermes persistent cross-session memory and user modeling. + +## Getting Started + +Honcho support is built into Hermes Agent. See the [Hermes Agent README](https://github.com/NousResearch/hermes-agent) for full installation and configuration instructions. + +The integration is opt-in and requires: +1. A Honcho API key from [app.honcho.dev](https://app.honcho.dev) +2. The `honcho-ai` package (`pip install hermes-agent[honcho]`) +3. Enabling Honcho in your Hermes config + +## How It Works + +The integration runs alongside Hermes's existing `USER.md` memory system. Honcho adds cross-session reasoning — prefetching user context into each turn, syncing exchanges for ongoing modeling, and exposing a dialectic tool (`query_user_context`) for the agent to query its understanding mid-conversation. + +## Next Steps + + + + Source code, installation, and full documentation. + + + + Learn about peers, sessions, and dialectic reasoning. + + diff --git a/docs/v3/guides/integrations/claude-code.mdx b/docs/v3/guides/integrations/claude-code.mdx index 7b4511ed..cdec3237 100644 --- a/docs/v3/guides/integrations/claude-code.mdx +++ b/docs/v3/guides/integrations/claude-code.mdx @@ -393,7 +393,7 @@ Claude will then query for insights before responding and write your messages to Source code, issues, and README. - + Learn about peers, sessions, and dialectic reasoning. diff --git a/docs/v3/guides/integrations/reachy-mini.mdx b/docs/v3/guides/integrations/reachy-mini.mdx index 47a95510..8ce40ec6 100644 --- a/docs/v3/guides/integrations/reachy-mini.mdx +++ b/docs/v3/guides/integrations/reachy-mini.mdx @@ -1,8 +1,8 @@ --- -title: "Reachy Mini (speech)" +title: "Voice Agent - Reachy Mini" icon: 'robot' description: "Build an embodied voice AI agent with long-term memory using Honcho" -sidebarTitle: 'Reachy Mini' +sidebarTitle: 'Voice Agent' --- diff --git a/docs/v3/guides/overview.mdx b/docs/v3/guides/overview.mdx index d029d811..d6f4454a 100644 --- a/docs/v3/guides/overview.mdx +++ b/docs/v3/guides/overview.mdx @@ -34,7 +34,7 @@ Real-world examples of what you can build with Honcho: Create a Telegram bot with persistent user understanding - + Build an embodied voice robot that remembers users across sessions