From 2f895efb7fcbd88d1c9fd0c3e83f94f9170853c1 Mon Sep 17 00:00:00 2001 From: Vineeth Voruganti <13438633+VVoruganti@users.noreply.github.com> Date: Thu, 5 Mar 2026 10:30:01 -0500 Subject: [PATCH] chore: (docs) update claude code plugin copy (#414) * chore: (docs) update claude code plugin copy * docs: adding reachy-mini * docs: adding openclaw multi-agent setup * docs: updating * chore: cr --------- Co-authored-by: ajspig --- docs/docs.json | 3 +- docs/v3/guides/integrations/claude-code.mdx | 204 +++++++++++++++++--- docs/v3/guides/integrations/openclaw.mdx | 12 +- docs/v3/guides/integrations/reachy-mini.mdx | 155 +++++++++++++++ docs/v3/guides/overview.mdx | 7 +- 5 files changed, 354 insertions(+), 27 deletions(-) create mode 100644 docs/v3/guides/integrations/reachy-mini.mdx diff --git a/docs/docs.json b/docs/docs.json index 86cb5375..2bf78973 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -99,12 +99,13 @@ { "group": "Integrations", "pages": [ + "v3/guides/integrations/claude-code", "v3/guides/integrations/crewai", "v3/guides/integrations/langgraph", "v3/guides/integrations/mcp", "v3/guides/integrations/n8n", "v3/guides/integrations/openclaw", - "v3/guides/integrations/claude-code" + "v3/guides/integrations/reachy-mini" ] }, { diff --git a/docs/v3/guides/integrations/claude-code.mdx b/docs/v3/guides/integrations/claude-code.mdx index d6a51a01..7b4511ed 100644 --- a/docs/v3/guides/integrations/claude-code.mdx +++ b/docs/v3/guides/integrations/claude-code.mdx @@ -26,7 +26,6 @@ export HONCHO_API_KEY="hch-your-api-key-here" # Optional (defaults shown) export HONCHO_PEER_NAME="$USER" # Your name/identity -export HONCHO_WORKSPACE="claude_code" # Workspace name ``` Then reload your shell: @@ -76,23 +75,171 @@ Claude will interview you about your personal preferences to kickstart a represe - **Persistent Memory** — Claude remembers your preferences, projects, and context across sessions - **Survives Context Wipes** — Even when Claude's context window resets, memory persists - **Git Awareness** — Detects branch switches, commits, and changes made outside Claude -- **Per-Project Sessions** — Each directory has its own conversation history +- **Flexible Sessions** — Map sessions per directory, per git branch, or per chat instance - **AI Self-Awareness** — Claude knows what it was working on, even after restarts +- **Cross-Tool Context** — Link workspaces across Claude Code, Cursor, and other hosts so context flows between tools +- **Team Support** — Multiple people can share a workspace and build context together - **MCP Tools** — Search memory, query knowledge about you, and save insights +## Configuration + +All configuration lives in a single global file at `~/.honcho/config.json`. You can edit it directly, use the `/honcho:config` skill interactively, or use the `set_config` MCP tool. Environment variables work for initial setup but the config file takes precedence once it exists. + +```jsonc +{ + // Required + "apiKey": "hch-v2-...", + + // Identity + "peerName": "alice", // Your name (default: $USER) + + // Host-specific settings — each tool gets its own workspace and AI peer + "hosts": { + "claude_code": { + "workspace": "claude_code", // Workspace for Claude Code sessions + "aiPeer": "claude", // AI identity in this workspace + "linkedHosts": ["cursor"] // Read context from other hosts (optional) + }, + "cursor": { + "workspace": "cursor", + "aiPeer": "cursor" + } + }, + + // Session mapping + "sessionStrategy": "per-directory", // "per-directory" | "git-branch" | "chat-instance" + "sessionPeerPrefix": true, // Prefix session names with peerName (default: true) + + // Message handling + "saveMessages": true, + "messageUpload": { + "maxUserTokens": null, // Truncate user messages (null = no limit) + "maxAssistantTokens": null, // Truncate assistant messages (null = no limit) + "summarizeAssistant": false // Summarize instead of sending full assistant text + }, + + // Context retrieval + "contextRefresh": { + "messageThreshold": 30, // Refresh context every N messages + "ttlSeconds": 300, // Cache TTL for context + "skipDialectic": false // Skip dialectic chat() calls in user-prompt hook + }, + + // Endpoint + "endpoint": { + "environment": "production" // "production" | "local" + // or: "baseUrl": "http://your-server:8000/v3" + }, + + // Miscellaneous + "localContext": { "maxEntries": 50 }, + "enabled": true, + "logging": true, + + // Advanced: force all hosts to use the same workspace + "globalOverride": false +} +``` + +### Session Strategies + +Session strategy controls how Honcho maps your conversations to sessions: + +| Strategy | Behavior | Best for | +| --- | --- | --- | +| `per-directory` (default) | One session per project directory. Stable across restarts. | Most users — each project accumulates its own memory | +| `git-branch` | Session name includes the current git branch. Switching branches switches sessions. | Feature-branch workflows where context per branch matters | +| `chat-instance` | Each Claude Code chat gets its own session. No continuity between restarts. | Ephemeral usage or when you want a clean slate each time | + +Session names are prefixed with your `peerName` by default (e.g., `alice-my-project`). Set `sessionPeerPrefix: false` if you're the only user and want shorter names. + +### Host-Aware Configuration + +The plugin auto-detects which tool is running it (Claude Code, Cursor, etc.) and reads the matching block from `hosts`. Each host gets its own workspace and AI peer name, so data stays separated by default. + +**Host detection priority:** +1. `HONCHO_HOST` env var (explicit override) +2. `cursor_version` in hook stdin (Cursor detected) +3. `CURSOR_PROJECT_DIR` env var (Cursor child process) +4. Default: `claude_code` + +### Linking Hosts for Cross-Tool Context + +If you use both Claude Code and Cursor, you can link them so context from one is readable in the other. Writes always stay in the current host's workspace — linking only adds read access. + +```jsonc +{ + "hosts": { + "claude_code": { + "workspace": "claude_code", + "aiPeer": "claude", + "linkedHosts": ["cursor"] // Claude Code can read Cursor's context + }, + "cursor": { + "workspace": "cursor", + "aiPeer": "cursor", + "linkedHosts": ["claude_code"] // Cursor can read Claude Code's context + } + } +} +``` + +Or use `/honcho:config` and select **Workspace > Linking** to set this up interactively. + +### Global Override + +If you want all hosts to share a single workspace (instead of per-host isolation), set `globalOverride: true` and a flat `workspace` field: + +```jsonc +{ + "globalOverride": true, + "workspace": "shared", + "hosts": { + "claude_code": { "aiPeer": "claude" }, + "cursor": { "aiPeer": "cursor" } + } +} +``` + +All tools will read and write to the `shared` workspace. Each tool still uses its own AI peer name. + ## Building with Teammates -Honcho works naturally for teams. Every team member contributes to and retrieves from a shared workspace, while Honcho models each person individually. Your sessions within a repo are scoped to your peer name (`HONCHO_PEER_NAME`), so your memory stays yours even though the workspace is shared. +Multiple people can share context by pointing to the same workspace. Each person uses their own `peerName` as identity, and sessions are automatically prefixed with it to avoid collisions. -- **Session naming** is automatic — set to `{user}-{repo}` by default so each team member gets their own session per project -- **Workspace** (`HONCHO_WORKSPACE`) groups all your team's sessions together. Set it to a shared value across the team -- **Peer name** (`HONCHO_PEER_NAME`) identifies you individually within the workspace +**Person A** (`~/.honcho/config.json`): +```json +{ + "apiKey": "hch-v2-team-key...", + "peerName": "alice", + "hosts": { + "claude_code": { + "workspace": "team-acme", + "aiPeer": "claude" + } + } +} +``` -This means Claude builds a distinct understanding of each team member's preferences and context while everyone operates in the same workspace. +**Person B** (`~/.honcho/config.json`): +```json +{ + "apiKey": "hch-v2-team-key...", + "peerName": "bob", + "hosts": { + "claude_code": { + "workspace": "team-acme", + "aiPeer": "claude" + } + } +} +``` + +Both Alice and Bob write to the `team-acme` workspace. Their sessions are namespaced (e.g., `alice-my-project`, `bob-my-project`) so data doesn't collide, but Honcho's dialectic reasoning can draw on context from both users. ## Logging -The plugin logs activity to `~/.honcho/` and to Claude Code's verbose mode, so you can see exactly how Honcho is being used — what context is loaded at session start, what messages are saved, and what context is injected into Claude's prompts. Set `HONCHO_LOGGING` to `false` to disable file logging. +The plugin logs activity to `~/.honcho/` and to Claude Code's verbose mode, so you can see exactly how Honcho is being used — what context is loaded at session start, what messages are saved, and what context is injected into Claude's prompts. Set `logging` to `false` in your config (or `HONCHO_LOGGING=false`) to disable file logging. ## MCP Tools @@ -103,25 +250,16 @@ The plugin provides these tools via MCP: | `search` | Semantic search across session messages | | `chat` | Query Honcho's knowledge about the user | | `create_conclusion` | Save insights about the user to memory | - -## Environment Variables Reference - -| Variable | Required | Default | Description | -| -------- | -------- | ------- | ----------- | -| `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev) | -| `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system | -| `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name (groups your sessions) | -| `HONCHO_CLAUDE_PEER` | No | `claude` | How the AI is identified | -| `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a custom URL | -| `HONCHO_ENABLED` | No | `true` | Set to `false` to disable | -| `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages | -| `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` | +| `get_config` | View current configuration and status | +| `set_config` | Change any configuration field programmatically | ## Skills (Slash Commands) | Command | Description | | ------- | ----------- | -| `/honcho:status` | Show current memory status and configuration | +| `/honcho:status` | Show current memory status and connection info | +| `/honcho:config` | Interactive configuration menu | +| `/honcho:setup` | First-time setup — validate API key and create config | | `/honcho:interview` | Interview to capture stable, cross-project user preferences | ### The Interview @@ -137,8 +275,30 @@ The `/honcho:interview` skill conducts a short interview to learn stable, cross- Each answer is saved as a conclusion in Honcho memory and persists across all your projects. +## Environment Variables + +Environment variables work for initial bootstrap (before a config file exists). Once `~/.honcho/config.json` is written, the config file takes precedence for host-specific fields like `workspace`. + +| Variable | Required | Default | Description | +| -------- | -------- | ------- | ----------- | +| `HONCHO_API_KEY` | **Yes** | — | Your Honcho API key from [app.honcho.dev](https://app.honcho.dev) | +| `HONCHO_PEER_NAME` | No | `$USER` | Your identity in the memory system | +| `HONCHO_WORKSPACE` | No | `claude_code` | Workspace name (used only when no config file exists) | +| `HONCHO_AI_PEER` | No | `claude` | AI peer name | +| `HONCHO_HOST` | No | auto-detected | Force host detection: `claude_code`, `cursor`, or `obsidian` | +| `HONCHO_ENDPOINT` | No | `production` | `production`, `local`, or a full URL | +| `HONCHO_ENABLED` | No | `true` | Set to `false` to disable | +| `HONCHO_SAVE_MESSAGES` | No | `true` | Set to `false` to stop saving messages | +| `HONCHO_LOGGING` | No | `true` | Set to `false` to disable file logging to `~/.honcho/` | + ### Using a local Honcho instance +Via config file: +```json +{ "endpoint": { "environment": "local" } } +``` + +Or via env var: ```bash export HONCHO_ENDPOINT="local" # Uses http://localhost:8000/v3 ``` diff --git a/docs/v3/guides/integrations/openclaw.mdx b/docs/v3/guides/integrations/openclaw.mdx index 6861f64a..7f7b9af5 100644 --- a/docs/v3/guides/integrations/openclaw.mdx +++ b/docs/v3/guides/integrations/openclaw.mdx @@ -67,8 +67,16 @@ Files are uploaded via `session.uploadFile()`. User/owner files go to the owner Once installed, the plugin runs automatically: * **Message Observation** — After every AI turn, the conversation is persisted to Honcho. Both user and agent messages are observed, allowing Honcho to build and refine its models. -* **Tool-Based Context Access** — The AI can query Honcho mid-conversation using tools like `honcho_recall`, `honcho_search`, and `honcho_analyze` to retrieve relevant context. -* **Dual Peer Model** — Honcho maintains separate representations: one for the user (preferences, facts, communication style) and one for the agent (personality, learned behaviors). +* **Tool-Based Context Access** — The AI can query Honcho mid-conversation using tools like `honcho_recall`, `honcho_search`, and `honcho_analyze` to retrieve relevant context. Context is injected during OpenClaw's `before_prompt_build` phase, ensuring accurate turn boundaries. +* **Dual Peer Model** — Honcho maintains separate representations: one for the user (preferences, facts, communication style) and one for the agent (personality, learned behaviors). Each OpenClaw agent gets its own Honcho peer (`agent-{id}`), so multi-agent workspaces maintain isolated memory. +* **Clean Persistence** — Platform metadata (conversation info, sender headers, thread context, forwarded messages) is stripped before saving to Honcho, ensuring only meaningful content is persisted. + +## Multi-Agent Support + +OpenClaw uses a multi-agent architecture where a primary agent can spawn **subagents** to handle specialized tasks. The Honcho plugin is fully aware of this hierarchy: + +* **Automatic Subagent Detection** — When OpenClaw spawns a subagent, the plugin tracks the parent→child relationship via the `subagent_spawned` hook. Each subagent session records its `parentPeerId` in metadata. +* **Parent Observer Peer** — The spawning agent is added as a silent observer in the subagent's Honcho session (`observeMe: false, observeOthers: true`). This gives Honcho visibility into the full agent tree — the parent can see what its subagents are doing without its own messages being attributed to the subagent session. ## AI Tools diff --git a/docs/v3/guides/integrations/reachy-mini.mdx b/docs/v3/guides/integrations/reachy-mini.mdx new file mode 100644 index 00000000..47a95510 --- /dev/null +++ b/docs/v3/guides/integrations/reachy-mini.mdx @@ -0,0 +1,155 @@ +--- +title: "Reachy Mini (speech)" +icon: 'robot' +description: "Build an embodied voice AI agent with long-term memory using Honcho" +sidebarTitle: 'Reachy Mini' +--- + + +[Reachy Mini](https://huggingface.co/blog/reachy-mini) is Hugging Face and Pollen Robotics' open-source robot for human-robot interaction. This guide integrates Honcho for persistent, multi-user memory with OpenAI's Realtime API for voice. + + +**Real-time memory**: Honcho's async API is designed for live voice interactions. Messages persist in the background without blocking audio, and the dialectic API returns user context fast enough for mid-conversation tool calls. + + + + + Full source code + + + Watch us build it live + + + +## What It Does + +- **Face recognition** identifies users and loads their personal memory +- **Honcho** stores conversations and reasons about each user over time +- **OpenAI Realtime** handles low-latency voice interaction +- **Gaze tracking** maintains eye contact during conversation + +When a user returns days later, the robot remembers their name, interests, and previous discussions. + +## Setup + +```bash +pip install reachy-mini honcho-ai openai python-dotenv numpy scipy mediapipe face-recognition +``` + +```bash +export OPENAI_API_KEY=your_openai_key +export HONCHO_API_KEY=your_honcho_key # get at app.honcho.dev +``` + +## Architecture + +``` +Reachy Mini (camera, mic, speaker) + ↓ +OpenAI Realtime API (voice + tools) + ↓ +Honcho (memory + reasoning per user) +``` + +## Honcho Integration + +Initialize Honcho with a robot peer (not observed) and dynamic user peers (observed): + +```python +from honcho import Honcho +from honcho.api_types import PeerConfig + +honcho = Honcho(api_key=api_key, workspace_id="reachy-mini") + +# Robot peer - stores messages but isn't reasoned about +robot_peer = await honcho.aio.peer( + "reachy", + configuration=PeerConfig(observe_me=False), +) + +# User peers - Honcho reasons about their preferences and history +user_peer = await honcho.aio.peer(user_id) +session = await honcho.aio.session(f"chat-{user_id}") +``` + +Store messages in the background without blocking the voice loop: + +```python +# Queue messages async - doesn't block audio playback +await session.aio.add_messages(user_peer.message(transcript)) +await session.aio.add_messages(robot_peer.message(response)) +``` + +## Memory Tools + +The robot calls Honcho mid-conversation via OpenAI function calling — fast enough for real-time voice: + +| Tool | Purpose | +|------|---------| +| `recall` | Query Honcho about the user ("What's their name?") | +| `create_conclusion` | Save important facts to long-term memory | +| `see` | Capture and analyze camera feed | + +```python +# Recall - ask Honcho's dialectic API (returns in ~200-500ms) +result = await user_peer.aio.chat( + "What do I know about this user?", + session=session, + reasoning_level="medium" +) + +# Create conclusion - save a fact +await user_peer.conclusions_of(user_id).aio.create([ + {"content": "Their name is Alice"} +]) +``` + +## Multi-User Support + +Face recognition identifies returning users. When a new face is detected, the agent: + +1. Flushes pending transcripts to the previous user's session +2. Switches Honcho context to the new user +3. Fetches a briefing from Honcho's dialectic API +4. Reconnects OpenAI with fresh context and triggers a greeting + +```python +# Get briefing when user is recognized +briefing = await user_peer.aio.chat( + "What should I know about this user? Name, interests, recent topics.", + session=session, + reasoning_level="low" +) +``` + +## System Prompt + +```python +SYSTEM_PROMPT = """You are Reachy, a friendly robot. Keep responses concise. + +You have a recall tool for memory. ALWAYS use it before claiming you don't +know something about the user. Never say "Nice to meet you" if you've met before.""" +``` + +## Run + +```bash +uv run python main.py +``` + +## Next Steps + + + + Understand peers, sessions, and reasoning + + + Learn about Honcho's dialectic API + + + Retrieve formatted conversation history + + + Dig into the code + + diff --git a/docs/v3/guides/overview.mdx b/docs/v3/guides/overview.mdx index a74d66c3..d029d811 100644 --- a/docs/v3/guides/overview.mdx +++ b/docs/v3/guides/overview.mdx @@ -24,8 +24,8 @@ Quick integration guides to get up and running: -## Application Interfaces -Ready-to-use integration patterns for popular platforms: +## Showcase +Real-world examples of what you can build with Honcho: @@ -34,4 +34,7 @@ Ready-to-use integration patterns for popular platforms: Create a Telegram bot with persistent user understanding + + Build an embodied voice robot that remembers users across sessions +