Honcho

https://honcho.dev/docs
Admin
Honcho is an open source memory library with a managed service for building stateful agents that...
Tokens:247,908
Snippets:1,813
Trust Score:6.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install honcho-cli and start local stack with --setup basic

Source: https://honcho.dev/docs/v3/contributing/self-hosting

Installs the Honcho CLI and runs the setup wizard for a local stack. The wizard prompts for an LLM provider and key, then starts Docker. `honcho start` pulls `ghcr.io/plastic-labs/honcho:latest`, pins its digest, and starts API + deriver + Postgres + Redis. Stack files live under `~/.honcho/profiles/local/`.

```bash
uv tool install honcho-cli
honcho start --setup basic   # prompts for LLM provider + key, then starts Docker
```

--------------------------------

### Install and initialize honcho CLI

Source: https://honcho.dev/docs/v3/documentation/introduction/vibecoding

Install the honcho CLI and run the initial setup commands: init for API key/browser login, start --setup basic for a local stack with LLM provider key and Docker, and doctor to verify connectivity. The start command pulls the published GHCR image and does not rewrite environmentUrl in the shared config file; prefix commands with HONCHO_BASE_URL=http://127.0.0.1:8000 to talk to local.

```bash
uv tool install honcho-cli
honcho init                  # Honcho API key / browser login (talk *to* a server)
honcho start --setup basic   # local stack: LLM provider key + Docker
honcho doctor                # verify connectivity
```

--------------------------------

### Install OpenCode plugin with bunx

Source: https://honcho.dev/docs/v3/documentation/introduction/vibecoding

Installs the OpenCode plugin for persistent memory. Run this command, then execute /honcho:setup inside OpenCode.

```bash
bunx @honcho-ai/opencode-honcho install
```

--------------------------------

### Quick start: init, start, doctor, banner

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Quick start commands. honcho init authenticates against a Honcho server but does not configure the LLM key needed by a local stack; honcho start --setup basic does that. honcho doctor verifies configuration and connectivity, and bare honcho shows the banner and command list.

```bash
honcho init                 # Honcho API key or browser login + server URL (talk *to* Honcho)
honcho start --setup basic  # local stack: LLM provider key + Docker (not set by init)
honcho doctor               # verify your config + connectivity
honcho                      # show banner + command list
```

--------------------------------

### Clone and Install Dependencies

Source: https://honcho.dev/docs/v3/contributing/self-hosting

Clone the Honcho repository, install dependencies with uv, and activate the virtual environment. Use this as the first step in the manual setup process.

```bash
git clone https://github.com/plastic-labs/honcho.git
cd honcho

# Install dependencies using uv (this will also set up Python if needed)
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

--------------------------------

### Install and configure Honcho plugin

Source: https://honcho.dev/docs/v3/guides/integrations/openclaw

Installs the Honcho plugin, runs the setup command to prompt for an API key and write the config, and forces a gateway restart.

```bash
openclaw plugins install @honcho-ai/openclaw-honcho
openclaw honcho setup
openclaw gateway --force
```

--------------------------------

### Run Honcho quickstart full script (Python and TypeScript)

Source: https://honcho.dev/docs/v3/documentation/introduction/quickstart

Full working quickstart script that sets up a workspace with user and assistant peers, ingests messages from multiple sessions, and queries insights about the user. Run with `uv sync` and `uv run python test.py` (Python) or `npm install` and `npx ts-node test.ts` (TypeScript). Requires a `conversation.json` file with session and message data.

```python
# uv sync
# uv run python test.py

import json
import time
import uuid

from honcho import Honcho
from dotenv import load_dotenv

load_dotenv()

# Initialize Honcho client with a unique workspace
workspace_id = f"docs-example-{uuid.uuid4().hex[:8]}"
honcho = Honcho(environment="production", workspace_id=workspace_id)

# Create peers to represent the user and assistant
user = honcho.peer("user")
assistant = honcho.peer("assistant")

# Load conversation data from JSON file
with open("conversation.json", "r") as f:
    conversation_data = json.load(f)

# Import historical conversation sessions
for session_data in conversation_data["sessions"]:
    session = honcho.session(session_data["id"])
    session.add_peers([user, assistant])

    # Convert messages to peer messages with correct attribution
    messages = []
    for msg in session_data["messages"]:
        if msg["role"] == "user":
            messages.append(user.message(msg["content"]))
        elif msg["role"] == "assistant":
            messages.append(assistant.message(msg["content"]))

    session.add_messages(messages)

# Query insights about the user based on conversation history
response = user.chat("What should I know about this user? 3 sentences max")
print(response)
```

```typescript
// npm install
// npx ts-node test.ts

import * as fs from 'fs';
import { randomUUID } from 'crypto';
import * as dotenv from 'dotenv';
import { Honcho } from '@honcho-ai/sdk';

dotenv.config();

// Initialize Honcho client with a unique workspace
const workspaceId = `docs-example-${randomUUID().slice(0, 8)}`;
const honcho = new Honcho({
  environment: "production",
  workspaceId,
});

// Create peers to represent the user and assistant
const user = await honcho.peer("user");
const assistant = await honcho.peer("assistant");

// Load conversation data from JSON file
const conversationData = JSON.parse(fs.readFileSync("conversation.json", "utf-8"));

// Import historical conversation sessions
for (const sessionData of conversationData.sessions) {
  const session = await honcho.session(sessionData.id);
  await session.addPeers([user, assistant]);

  // Convert messages to peer messages with correct attribution
  const messages = [];
  for (const msg of sessionData.messages) {
    if (msg.role === "user") {
      messages.push(user.message(msg.content));
    } else if (msg.role === "assistant") {
      messages.push(assistant.message(msg.content));
    }
  }

  await session.addMessages(messages);
}


// Query insights about the user based on conversation history
const response = await user.chat("What should I know about this user? 3 sentences max");
console.log(response);
```

--------------------------------

### Quickstart with Honcho SDK (Python)

Source: https://honcho.dev/docs/v3/documentation/reference/sdk

Initialize the Honcho client, create peers and a session, add messages, chat with Honcho, and get conversation context for LLM completions. Without configuration, the SDK defaults to the demo server; for production, set environment='production' and provide your API key.

```python
from honcho import Honcho

# Initialize client (using the default workspace)
honcho = Honcho()

# Create peers
alice = honcho.peer("alice")
assistant = honcho.peer("assistant")

# Create a session for conversation
session = honcho.session("conversation-1")

# Add messages to conversation
session.add_messages([
    alice.message("What's the weather like today?"),
    assistant.message("It's sunny and 75°F outside!")
])

# Chat with Honcho about a peer
response = alice.chat("What did the assistant tell this user about the weather?")

# Get conversation context for LLM completions
context = session.context()
openai_messages = context.to_openai(assistant=assistant)
```

--------------------------------

### Quickstart with Honcho SDK (TypeScript)

Source: https://honcho.dev/docs/v3/documentation/reference/sdk

Initialize the Honcho client, create peers and a session, add messages, chat with Honcho, and get conversation context for LLM completions. Without configuration, the SDK defaults to the demo server; for production, set environment='production' and provide your API key.

```typescript
import { Honcho } from "@honcho-ai/sdk";

// Initialize client (using the default workspace)
const honcho = new Honcho({});

// Create peers
const alice = await honcho.peer("alice");
const assistant = await honcho.peer("assistant");

// Create a session for conversation
const session = await honcho.session("conversation-1");

// Add messages to conversation
await session.addMessages([
  alice.message("What's the weather like today?"),
  assistant.message("It's sunny and 75°F outside!")
]);

// Chat with Honcho about a peer
const response = await alice.chat("What did the assistant tell this user about the weather?");

// Get conversation context for LLM completions
const context = await session.context();
const openaiMessages = context.toOpenAI(assistant);
```

--------------------------------

### Start local Honcho stack with honcho start

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Starts a local Honcho stack (API, deriver, Postgres, Redis) using Docker and cloud LLM providers. Does not change the CLI's configured server URL; pass HONCHO_BASE_URL to connect to this stack. Use --setup basic or --setup advanced to run an interactive config wizard.

```bash
honcho start
```

--------------------------------

### Configure Environment Variables

Source: https://honcho.dev/docs/v3/contributing/self-hosting

Example environment variables for the .env file: database connection URI, authentication disabled, and debug logging. Adjust these to match your setup.

```bash
DB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@localhost:5432/postgres
AUTH_USE_AUTH=false
LOG_LEVEL=DEBUG
```

--------------------------------

### Install honcho-cli with uv or uvx

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Install the honcho CLI. The first command installs it persistently via uv; the second runs it ephemerally without installing. Neither starts a server.

```bash
uv tool install honcho-cli
```

```bash
uvx honcho-cli
```

--------------------------------

### Install via ClawHub skill

Source: https://honcho.dev/docs/v3/guides/integrations/openclaw

Alternative installation using the honcho-setup skill, which handles installation and migration interactively from a chat session.

```bash
npx clawhub install honcho-setup
# Restart OpenClaw, then invoke the skill from a session
openclaw plugins install @honcho-ai/openclaw-honcho
openclaw gateway restart
```

--------------------------------

### Survey the workspace

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Start by surveying the workspace and listing peers to get an overview of the environment.

```bash
honcho workspace inspect --json
honcho peer list --json
```

--------------------------------

### Telegram Bot Application Setup

Source: https://honcho.dev/docs/v3/guides/telegram

Sets up the Telegram bot application, including token validation, adding command and message handlers, and starting the polling service. Ensure the BOT_TOKEN environment variable is set.

```python
def main():
    """Start the bot"""
    if not BOT_TOKEN:
        logger.error("BOT_TOKEN not found in environment variables")
        return

    # Create the Application
    application = Application.builder().token(BOT_TOKEN).build()

    # Add handlers
    application.add_handler(CommandHandler("start", start_command))
    application.add_handler(CommandHandler("dialectic", dialectic_command))
    application.add_handler(
        MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message)
    )

    # Start the bot
    logger.info("Starting Telegram bot...")
    application.run_polling(allowed_updates=Update.ALL_TYPES)
```

--------------------------------

### Start the Development Server

Source: https://honcho.dev/docs/v3/contributing/self-hosting

Start the Honcho development server. The server will be available at http://localhost:8000.

```bash
# Start the development server
uv run fastapi dev src/main.py
```

--------------------------------

### Local stack lifecycle: start, status, stop

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Manage the local stack. honcho start --setup basic or advanced runs an interactive wizard (TTY-only) that writes LLM/feature overrides into the profile .env; re-running while the stack is up recreates API and deriver containers. Setting LLM_OPENAI_API_KEY in the environment skips the wizard. honcho status shows stack state; honcho stop keeps data, honcho stop --wipe also deletes volumes.

```bash
honcho start --setup basic
honcho start --setup advanced
LLM_OPENAI_API_KEY=sk-... honcho start   # skip the wizard if the key is already in the env
honcho status
honcho stop            # keep data
honcho stop --wipe     # also delete volumes
```

--------------------------------

### Install Honcho SDK with uv (Python)

Source: https://honcho.dev/docs/v3/documentation/reference/sdk

Install the Python SDK using uv. This is one of the installation options for Python.

```bash
uv add honcho-ai
```

--------------------------------

### Talk to local stack: HONCHO_BASE_URL and honcho init --base-url

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Point the CLI at a local stack. The first command sets the base URL for one invocation; the second persists it as the CLI default. This is needed because honcho start --setup does not change environmentUrl in the shared config file.

```bash
HONCHO_BASE_URL=http://127.0.0.1:8000 honcho workspace list
honcho init --base-url http://127.0.0.1:8000   # persist local as the CLI default
```

--------------------------------

### Install pre-commit hooks with uv run pre-commit install

Source: https://honcho.dev/docs/v3/contributing/guidelines

Installs pre-commit hooks locally. CI runs the same checks, so installing them locally catches issues faster. The hooks run linting and formatting at commit time and tests at push time.

```bash
uv run pre-commit install \
    --hook-type pre-commit \
    --hook-type commit-msg \
    --hook-type pre-push
```

--------------------------------

### Install Honcho Plugin

Source: https://honcho.dev/docs/v3/guides/integrations/claudecode

Installs the Honcho plugin from the added marketplace.

```bash
/plugin install honcho@honcho

```

--------------------------------

### Install dependencies with uv or pip

Source: https://honcho.dev/docs/v3/guides/granola

Install the honcho-ai and httpx packages. The uv variant uses uv's pip interface; the pip variant uses the standard pip command. Both install the same dependencies.

```bash
uv pip install honcho-ai httpx
```

```bash
pip install honcho-ai httpx
```

--------------------------------

### Install agent skills via npx

Source: https://honcho.dev/docs/v3/documentation/introduction/vibecoding

Recommended way to install agent skills via npx.

```bash
npx skills add plastic-labs/honcho
```

--------------------------------

### Tiered Model Setup with OpenRouter

Source: https://honcho.dev/docs/v3/contributing/configuration

Assign different models per feature using OpenRouter as a base URL to balance cost and quality across light, medium, and heavy tiers.

```bash
LLM_OPENAI_API_KEY=sk-or-v1-...

# All features route through OpenRouter via overrides.base_url
# (You can set this on each feature's MODEL_CONFIG)

# Light tier — high throughput, cheap
DERIVER_MODEL_CONFIG__TRANSPORT=openai
DERIVER_MODEL_CONFIG__MODEL=google/gemini-2.5-flash-lite
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
SUMMARY_MODEL_CONFIG__TRANSPORT=openai
SUMMARY_MODEL_CONFIG__MODEL=google/gemini-2.5-flash
DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORT=openai
DIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODEL=google/gemini-2.5-flash-lite
DIALECTIC_LEVELS__low__MODEL_CONFIG__TRANSPORT=openai
DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL=google/gemini-2.5-flash-lite

# Medium tier — better reasoning
DIALECTIC_LEVELS__medium__MODEL_CONFIG__TRANSPORT=openai
DIALECTIC_LEVELS__medium__MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5
DIALECTIC_LEVELS__high__MODEL_CONFIG__TRANSPORT=openai
DIALECTIC_LEVELS__high__MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5
DIALECTIC_LEVELS__max__MODEL_CONFIG__TRANSPORT=openai
DIALECTIC_LEVELS__max__MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5

# Heavy tier — best quality for complex tasks
DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORT=openai
DREAM_DEDUCTION_MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5
DREAM_INDUCTION_MODEL_CONFIG__TRANSPORT=openai
DREAM_INDUCTION_MODEL_CONFIG__MODEL=anthropic/claude-haiku-4-5
```

--------------------------------

### Create or get workspace

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Creates or gets a workspace. Accepts --metadata to associate JSON metadata.

```bash
honcho workspace create <workspace_id>
```

--------------------------------

### Persisted config file example

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Example of the shared config file at ~/.honcho/config.json. The CLI owns apiKey and environmentUrl at the top level; other keys like hosts are written by sibling tools and left untouched on save. On managed servers, honcho init can store OAuth tokens under oauth without deleting a shared apiKey.

```json
{
  "apiKey": "hch-v3-...",
  "environmentUrl": "https://api.honcho.dev",
  "hosts": { "claude_code": { "...": "..." } }
}
```

--------------------------------

### Install Honcho plugin in Claude Code

Source: https://honcho.dev/docs/v3/guides/integrations/claude-code

Add the plastic-labs/claude-honcho marketplace and install the honcho plugin inside Claude Code. Requires Node.js on your PATH.

```text
/plugin marketplace add plastic-labs/claude-honcho
```

```text
/plugin install honcho@honcho
```

--------------------------------

### honcho peer create

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Create or get a peer. Requires a peer ID. Options include --observe-me and --metadata.

```bash
honcho peer create <peer_id>
```

--------------------------------

### honcho session create

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Create or get a session. Requires session_id. Optional --peers (comma-separated peer IDs) and --metadata (JSON metadata).

```bash
honcho session create <session_id>
```

--------------------------------

### Initialize development environment with uv sync and alembic upgrade

Source: https://honcho.dev/docs/v3/contributing/guidelines

Sets up the repository for development: creates the virtual environment, installs dependencies, and applies database migrations. Run from the repo root after cloning.

```bash
uv sync                          # create the venv and install dependencies
uv run alembic upgrade head      # apply migrations
```

--------------------------------

### honcho session context

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Get session context (what an agent would see). Optional session_id, --tokens for token budget, --summary (default true) to include summary, negate with --no-summary.

```bash
honcho session context [<session_id>]
```

--------------------------------

### Pipe to jq and use env vars for CI/CD

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Use these commands to pipe JSON output into jq for inline transforms, get a machine-parseable health check with honcho doctor --json (exit code for CI, details for logs), and set HONCHO_* env vars for CI/CD without a config file.

```bash
# Pipe to jq
honcho peer list --json | jq '.[].id'
honcho workspace inspect --json | jq '.peers'

# Machine-parseable health check — exit code for CI, details for logs
honcho doctor --json

# CI/CD — env vars only, no ~/.honcho/config.json
export HONCHO_API_KEY=hch-v3-xxx
export HONCHO_BASE_URL=https://api.honcho.dev
honcho workspace list
```

--------------------------------

### Runtime overrides for workspace, peer, and session targeting

Source: https://honcho.dev/docs/v3/documentation/reference/cli

Shows runtime overrides for workspace, peer, and session targeting. These are per-command only and not persisted as CLI defaults; pass flags or HONCHO_* env vars on every invocation. Includes examples for per-command flags, exporting env vars once per shell, a one-off server override, and CI/CD usage with env vars only.

```bash
# Per-command flags
honcho peer card -w prod -p user

# Or export once per shell
export HONCHO_WORKSPACE_ID=prod
export HONCHO_PEER_ID=user
honcho peer card

# One-off against a different server
HONCHO_BASE_URL=http://localhost:8000 honcho workspace list

# CI/CD — env vars only, no config file needed
export HONCHO_API_KEY=hch-v3-xxx
export HONCHO_BASE_URL=https://api.honcho.dev
honcho workspace list
```

--------------------------------

### Handle /start Command for User Onboarding

Source: https://honcho.dev/docs/v3/guides/telegram

Implements the /start command to greet new users and provide instructions on how to interact with the bot. It outlines available features like direct chat, mentions, and the /dialectic command.

```python
async def start_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Handle the /start command"""
    await update.message.reply_text(
        "Hello! I'm your AI assistant. You can:\n"
        "• Chat with me directly in private messages\n"
        "• Mention me (@username) in groups to get my attention\n"
        "• Use /dialectic <query> to search our conversation history\n\n"
        "Let's start chatting!"
    )
```

--------------------------------

### Run deriver manually

Source: https://honcho.dev/docs/v3/contributing/troubleshooting

Start the deriver process manually in a non-Docker setup.

```bash
uv run python -m src.deriver
```

--------------------------------

### Streaming responses with peer.chat

Source: https://honcho.dev/docs/v3/documentation/features/chat

Use streaming to get incremental responses for longer answers. The Python example uses peer.chat(query, stream=True) and iterates over response_stream.iter_text(); the TypeScript example uses peer.chat(query, { stream: true }) and iterates over responseStream.iter_text().

```python
query = "What do we know about the user?"
response_stream = peer.chat(query, stream=True)

for chunk in response_stream.iter_text():
    print(chunk, end="", flush=True)
```

```typescript
const query = "What do we know about the user?";
const responseStream = await peer.chat(query, { stream: true });

for await (const chunk of responseStream.iter_text()) {
    process.stdout.write(chunk);
}
```

--------------------------------

### Copy environment template

Source: https://honcho.dev/docs/v3/contributing/self-hosting

Copies the example environment file to .env for configuration.

```bash
cp .env.template .env
```

--------------------------------

### Initialize Honcho client (Python)

Source: https://honcho.dev/docs/v3/documentation/reference/sdk

Shows basic initialization using environment variables and full configuration with explicit parameters.

```python
from honcho import Honcho

# Basic initialization (uses environment variables)
honcho = Honcho(workspace_id="my-app-name")

# Full configuration
honcho = Honcho(
    workspace_id="my-app-name",
    api_key="my-api-key",
    environment="production",  # or "local", "demo"
    base_url="https://api.honcho.dev",
    timeout=30.0,
    max_retries=3
)
```

--------------------------------

### Read and write directional peer cards with target parameter

Source: https://honcho.dev/docs/v3/documentation/features/advanced/peer-card

Use the `target` parameter to read and write directional peer cards. When `observe_others` is enabled, a peer can have a different card for each peer it observes. The example shows getting Honcho's view of Alice, getting Alice's view of Bob, and setting Alice's card for Bob.

```python
alice = honcho.peer("alice")

# Get Alice's own peer card (Honcho's view of Alice)
alice_card = alice.get_card()

# Get Alice's card for Bob (Alice's view of Bob)
alice_bob_card = alice.get_card(target="bob")

# Set Alice's card for Bob
alice.set_card(
    ["Bob mentioned he's allergic to peanuts."],
    target="bob"
)
```

```typescript
const alice = await honcho.peer("alice");

// Get Alice's own peer card (Honcho's view of Alice)
const aliceCard = await alice.getCard();

// Get Alice's card for Bob (Alice's view of Bob)
const aliceBobCard = await alice.getCard({ target: "bob" });

// Set Alice's card for Bob
await alice.setCard(
    ["Bob mentioned he's allergic to peanuts."],
    { target: "bob" }
);
```
Tokens:
Raw