Honcho

https://honcho.dev/docs/v3/
Admin
Honcho is an open source memory library with a managed service for building stateful agents that...
Tokens:227,088
Snippets:1,587
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
```

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

### 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 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 Honcho CLI commands

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

Initialize, start a local stack, verify configuration, and show the banner and command list. The init command authenticates against a Honcho server and does not configure the LLM key; use honcho start --setup basic for that.

```bash
honcho init                 # Honcho API key or browser login + server URL (talk *to* Honcho)
```

```bash
honcho start --setup basic  # local stack: LLM provider key + Docker (not set by init)
```

```bash
honcho doctor               # verify your config + connectivity
```

```bash
honcho                      # show banner + command list
```

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

### 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
```

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

### Install honcho-cli with uv tool

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

Install the Honcho CLI globally using uv. This only installs the honcho command and does not start a server.

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

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

### 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
```

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

### Start a local Honcho stack with honcho start

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

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

```bash
honcho start
```

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

### 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
```

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

### Complete Example

Source: https://honcho.dev/docs/v3/guides/integrations/vercel-ai-sdk

Complete example using the Vercel AI SDK with Honcho middleware and tools.

```typescript
import { createHoncho } from '@honcho-ai/vercel-ai-sdk';
import { wrapLanguageModel, generateText, stepCountIs } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const honcho = createHoncho({
  defaultAssistantId: 'assistant',
});

const userId = 'user-abc';
const sessionId = 'session-123';

const model = wrapLanguageModel({
  model: anthropic('claude-sonnet-4-6'),
  middleware: honcho.middleware({ userId, sessionId }),
});

const { text } = await generateText({
  model,
  tools: honcho.tools({ userId, sessionId }),
  stopWhen: stepCountIs(3),
  prompt: 'What should we work on today?',
});

console.log(text);
```

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

### 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
```

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

### Install Codex Honcho from GitHub

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

Clone the repository and execute the installation script to set up the environment using Bun.

```bash
git clone https://github.com/plastic-labs/codex-honcho
cd codex-honcho
./install.sh              # bun install + bun run bin/codex-honcho.ts install
```

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

### Install Honcho plugin

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

Install the Honcho plugin after adding the marketplace.

```bash
/plugin install honcho@honcho

```

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

### Install dependencies with uv

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

Install the required Python packages using uv. This is the uv variant of the installation command.

```bash
uv pip install google-api-python-client google-auth-oauthlib honcho-ai
```

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

### 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 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
```

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

### Install @honcho-ai/vercel-ai-sdk

Source: https://honcho.dev/docs/v3/guides/integrations/vercel-ai-sdk

Install the @honcho-ai/vercel-ai-sdk package using your preferred package manager. Choose one of these commands based on your environment.

```bash
npm install @honcho-ai/vercel-ai-sdk
```

```bash
pnpm add @honcho-ai/vercel-ai-sdk
```

```bash
yarn add @honcho-ai/vercel-ai-sdk
```

```bash
bun add @honcho-ai/vercel-ai-sdk
```

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

### Install honcho-cli with uvx (ephemeral)

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

Run the Honcho CLI ephemerally using uvx. This installation method does not persist the CLI.

```bash
uvx honcho-cli
```

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

### 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
```

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

### 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
```

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

### Full Configuration

Source: https://honcho.dev/docs/v3/guides/integrations/deepseek-harness

Full configuration example for the Honcho Dev CLI, showing global settings and host-specific configuration for the dsh host.

```jsonc
{
  "peerName": "your-name",
  "workspace": "honcho",
  "baseUrl": "https://api.honcho.dev", // bare host or …/v3 both fine
  "timeoutMs": 30000,
  "auth": { "apiKey": "${HONCHO_API_KEY}" },
  "enabled": true, // global kill switch

  "hosts": {
    "dsh": {
      "workspace": "dsh",
      "aiPeer": "dsh", // defaults to the host name
      "observationMode": "unified", // unified | directional
      "sessionStrategy": "per-directory",
      "sessionPeerPrefix": true, // session names are <peer>-<dir>
      "sessions": { "/path/to/repo": "pinned-session-name" },

      "injection": {
        "sessionStart": ["directives", "summary", "peerCard"],
        "perTurn": 0.6,
        "maxConclusions": 15, // how many conclusions Honcho RETURNS
        "maxRenderedConclusions": 4
      }
    }
  }
}
```

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

### 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
```

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

### Manually symlink the skill from npm package

Source: https://honcho.dev/docs/v3/guides/integrations/vercel-ai-sdk

Alternative to the npx command if you've already installed @honcho-ai/vercel-ai-sdk via npm. Example shown is for Claude Code; restart the session after symlinking.

```bash
mkdir -p ~/.claude/skills/honcho-vercel-ai-sdk
ln -sf "$(pwd)/node_modules/@honcho-ai/vercel-ai-sdk/skills/honcho-vercel-ai-sdk/SKILL.md" \
       ~/.claude/skills/honcho-vercel-ai-sdk/SKILL.md
```

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

### 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" }
);
```

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

### Copy configuration templates

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

Use these commands to copy the example configuration files into place before editing. The .env file is for secrets and overrides, while config.toml holds base settings.

```bash
cp .env.template .env
cp config.toml.example config.toml
```

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

### Query representations with target parameter (Python and TypeScript)

Source: https://honcho.dev/docs/v3/documentation/features/advanced/directional-representations

Use the `representation` method with the `target` parameter to retrieve conclusions from different perspectives. The Python example sets up sessions with peers and messages, then queries Alice's view across all sessions and her targeted views of Bob and Charlie. The TypeScript example mirrors this setup and queries using the same `target` option.

```python
from honcho import Honcho
from honcho.api_types import SessionPeerConfig

honcho = Honcho()
session = honcho.session("game-session")

alice = honcho.peer("alice")
bob = honcho.peer("bob")
charlie = honcho.peer("charlie")

# Add peers to session
session.add_peers([alice, bob, charlie])

# Enable Alice to form representations of others
session.set_peer_configuration(alice, SessionPeerConfig(observe_others=True))

# Add messages
session.add_messages([
    bob.message("I had pancakes for breakfast."),
    charlie.message("I prefer waffles.")
])

# Different sessions with different participants
session2 = honcho.session("game-session-2")
session2.add_peers([alice, charlie])
session2.set_peer_configuration(alice, SessionPeerConfig(observe_others=True))

session2.add_messages([
    charlie.message("I didn't have breakfast. I lied to Bob.")
])

# Retrieve conclusions from different perspectives
honcho_view = session.representation("alice")  # Across all sessions
bob_view = session.representation("alice", target="bob")  # Alice's view of Bob
charlie_view = session2.representation("alice", target="charlie")  # Alice's view of Charlie
```

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

const honcho = new Honcho({});
const session = await honcho.session("game-session");

const alice = await honcho.peer("alice");
const bob = await honcho.peer("bob");
const charlie = await honcho.peer("charlie");

await session.addPeers([alice, bob, charlie]);

await session.setPeerConfiguration(alice, { observeOthers: true });

await session.addMessages([
    bob.message("I had pancakes for breakfast."),
    charlie.message("I prefer waffles.")
]);

const session2 = await honcho.session("game-session-2");
await session2.addPeers([alice, charlie]);
await session2.setPeerConfiguration(alice, { observeOthers: true });

await session2.addMessages([
    charlie.message("I didn't have breakfast. I lied to Bob.")
]);

// Retrieve conclusions from different perspectives
const honchoView = await session.representation("alice");  // Across all sessions
const bobView = await session.representation("alice", { target: "bob" });  // Alice's view of Bob
const charlieView = await session2.representation("alice", { target: "charlie" });  // Alice's view of Charlie
```

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

### Use memory with a CrewAI crew

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

Use the memory instance with a CrewAI crew. This example defines an agent, a task, and a crew with sequential process, passing the memory object to the crew and kicking it off to get a result.

```python
from crewai import Agent, Crew, Process, Task

agent = Agent(
    role="Programming Mentor",
    goal="Help users learn programming by remembering their interests and progress",
    backstory="You are a patient programming mentor.",
)

task = Task(
    description="Suggest a Python web project that matches the user's interests.",
    expected_output="A specific project suggestion with a brief explanation",
    agent=agent,
)

crew = Crew(
    agents=[agent],
    tasks=[task],
    process=Process.sequential,
    memory=memory,
    verbose=True,
)

result = crew.kickoff()
print(result.raw)
```

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

### Set up Honcho client and session for streaming (Python/TypeScript)

Source: https://honcho.dev/docs/v3/documentation/features/advanced/streaming-response

Prerequisites for streaming with the chat endpoint: initialize the Honcho client, create or get peers, create a session, add peers, and optionally store messages for context. The Python and TypeScript examples are equivalent and shown as interchangeable tabs.

```python
from honcho import Honcho

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

# Create or get peers
user = honcho.peer("demo-user")
assistant = honcho.peer("assistant")

# Create a new session
session = honcho.session("demo-session")

# Add peers to the session
session.add_peers([user, assistant])

# Store some messages for context (optional)
session.add_messages([
    user.message("Hello, I'm testing the streaming functionality")
])
```

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

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

    // Create or get peers
    const user = await honcho.peer('demo-user');
    const assistant = await honcho.peer('assistant');

    // Create a new session
    const session = await honcho.session('demo-session');

    // Add peers to the session
    await session.addPeers([user, assistant]);

    // Store some messages for context (optional)
    await session.addMessages([
      user.message("Hello, I'm testing the streaming functionality")
    ]);
})();
```

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

### Quick start usage of save_memory, query_memory, get_context

Source: https://honcho.dev/docs/v3/guides/integrations/zo-computer

Demonstrates the core workflow: saving messages, querying memory, and retrieving context for an LLM call.

```python
from tools.save_memory import save_memory
from tools.query_memory import query_memory
from tools.get_context import get_context

# Save conversation turns
save_memory("alice", "I love hiking in the mountains", "user", "session-1")
save_memory("alice", "That sounds wonderful!", "assistant", "session-1")

# Query what Honcho remembers
answer = query_memory("alice", "What are my hobbies?", "session-1")
print(answer)  # "Alice enjoys hiking in the mountains."

# Get context ready for an LLM call
messages = get_context("alice", "session-1", "assistant", tokens=4000)
# Returns [{"role": "user", "content": "..."}, ...]
```

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

### Install dependencies with pip

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

Install the required Python packages using pip. This is the pip variant of the installation command.

```bash
pip install google-api-python-client google-auth-oauthlib honcho-ai
```

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

### Start services with Docker Compose

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

Copies the compose file and starts the services in detached mode with build. The first build takes a few minutes.

```bash
cp docker-compose.yml.example docker-compose.yml
docker compose up -d --build
```

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

### Install Honcho AI Plugin for OpenCode

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

Install the Honcho AI plugin globally for OpenCode. Ensure the OpenCode CLI is installed and on your PATH.

```bash
opencode plugin "@honcho-ai/opencode-honcho" --global
```

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

### Run the agent

Source: https://honcho.dev/docs/v3/guides/integrations/reachy-mini

Runs the main application using uv.

```bash
uv run python main.py
```

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

### Initialize Honcho and OpenAI Clients

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

Sets up the main Honcho client, an assistant peer, and configures the OpenAI client to use OpenRouter.

```python
honcho_client = Honcho()
assistant = honcho_client.peer(id="assistant", config={"observe_me": False})
openai = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=MODEL_API_KEY)
```

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

### Full Honcho Vercel AI SDK chat script (honcho_vercel_chat.ts)

Source: https://honcho.dev/docs/v3/guides/integrations/vercel-ai-sdk

Complete multi-turn chat example using Honcho memory with the Vercel AI SDK. Requires installing @honcho-ai/vercel-ai-sdk, ai, @ai-sdk/anthropic, and dotenv, plus setting HONCHO_API_KEY, HONCHO_WORKSPACE_ID, and ANTHROPIC_API_KEY in .env. Run with npx tsx honcho_vercel_chat.ts; pass a stable userId and sessionId for persistence and context injection.

```typescript
  /**
   * Multi-turn chat with Honcho memory + Vercel AI SDK.
   *
   * Prerequisites:
   * 1. Install dependencies:
   *    npm install @honcho-ai/vercel-ai-sdk ai @ai-sdk/anthropic dotenv
   * 2. Set environment variables in `.env`:
   *    HONCHO_API_KEY=your-honcho-api-key
   *    HONCHO_WORKSPACE_ID=your-workspace-id
   *    ANTHROPIC_API_KEY=your-anthropic-api-key
   * 3. Run with: npx tsx honcho_vercel_chat.ts
   *
   * Pass a stable userId from your auth system and a sessionId for the conversation
   * thread; Honcho handles persistence and context injection on every turn.
   */

  import 'dotenv/config';
  import { createHoncho } from '@honcho-ai/vercel-ai-sdk';
  import { wrapLanguageModel, generateText, stepCountIs } from 'ai';
  import { anthropic } from '@ai-sdk/anthropic';
  import * as readline from 'node:readline/promises';
  import { stdin as input, stdout as output } from 'node:process';

  const honcho = createHoncho({
    defaultAssistantId: 'assistant',
  });

  const userId = process.env.USER_ID ?? 'demo-user';
  const sessionId = process.env.SESSION_ID ?? `session-${Date.now()}`;

  const model = wrapLanguageModel({
    model: anthropic('claude-sonnet-4-6'),
    middleware: honcho.middleware({ userId, sessionId }),
  });

  async function chat(prompt: string): Promise<string> {
    const { text } = await generateText({
      model,
      tools: honcho.tools({ userId, sessionId }),
      stopWhen: stepCountIs(3),
      prompt,
    });
    return text;
  }

  async function main() {
    const rl = readline.createInterface({ input, output });
    console.log(`Honcho session: ${sessionId} (user: ${userId})`);
    console.log('Type a message, or "exit" to quit.\n');

    while (true) {
      const userMessage = (await rl.question('you > ')).trim();
      if (!userMessage || userMessage === 'exit') break;
      const reply = await chat(userMessage);
      console.log(`bot > ${reply}\n`);
    }

    rl.close();
  }

  main().catch((err) => {
    console.error(err);
    process.exit(1);
  });
```
Tokens:
Raw