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 <dragon@monstercode.com>
This commit is contained in:
Vineeth Voruganti
GitHub
parent
ee1ffada21
commit
2f895efb7f
|
|
@ -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"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<Note>
|
||||
**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.
|
||||
</Note>
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="GitHub Repository" icon="github" href="https://github.com/plastic-labs/reachy-mini-honcho">
|
||||
Full source code
|
||||
</Card>
|
||||
<Card title="Build Livestream" icon="youtube" href="https://www.youtube.com/watch?v=i6iijJnkxh0">
|
||||
Watch us build it live
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 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
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Honcho Architecture" icon="sitemap" href="/v3/documentation/core-concepts/architecture">
|
||||
Understand peers, sessions, and reasoning
|
||||
</Card>
|
||||
<Card title="Chat Endpoint" icon="comments" href="/v3/documentation/features/chat">
|
||||
Learn about Honcho's dialectic API
|
||||
</Card>
|
||||
<Card title="Get Context" icon="database" href="/v3/documentation/features/get-context">
|
||||
Retrieve formatted conversation history
|
||||
</Card>
|
||||
<Card title="Github code" icon="robot" href="https://github.com/plastic-labs/reachy-mini-honcho">
|
||||
Dig into the code
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
|
@ -24,8 +24,8 @@ Quick integration guides to get up and running:
|
|||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Application Interfaces
|
||||
Ready-to-use integration patterns for popular platforms:
|
||||
## Showcase
|
||||
Real-world examples of what you can build with Honcho:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Discord Bot" icon="discord" href="/v3/guides/discord">
|
||||
|
|
@ -34,4 +34,7 @@ Ready-to-use integration patterns for popular platforms:
|
|||
<Card title="Telegram Bot" icon="telegram" href="/v3/guides/telegram">
|
||||
Create a Telegram bot with persistent user understanding
|
||||
</Card>
|
||||
<Card title="Reachy Mini" icon="robot" href="v3/guides/integrations/reachy-mini.mdx">
|
||||
Build an embodied voice robot that remembers users across sessions
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
|
|
|||
Loading…
Reference in New Issue