Honcho Integration

# Honcho Integration for Bot Frameworks

This reference extends the main honcho-integration skill for **bot frameworks** — applications built around an agent loop, session manager, tool registry, and message bus (e.g., nanobot, openclaw, picoclaw).

## Supported Frameworks

When a known framework is detected, use concrete reference implementations from `{baseDir}/references/bot-frameworks/<framework>/`.

| Framework | Status | Reference Dir |
|-----------|--------|---------------|
| [nanobot](https://github.com/HKUDS/nanobot) | concrete references | `bot-frameworks/nanobot/` |
| openclaw | planned | -- |
| picoclaw | planned | -- |

For unknown frameworks, adapt the general pattern below to the codebase's architecture.

## Phase 1: Explore (bot-specific)

In addition to the main skill's Phase 1, identify these bot-specific components:

1. **Agent loop**: Where messages are processed (look for `while` loops calling an LLM)
2. **Session manager**: How conversation history is stored (JSONL files, database, in-memory)
3. **Tool registry**: How tools/functions are registered for the LLM to call
4. **Message bus**: How inbound/outbound messages are routed between channels and the agent
5. **Config system**: How the bot loads configuration (JSON, YAML, env vars, pydantic models, zod schemas)
6. **CLI entry points**: How the bot is started (commands, gateway, agent modes)

If the framework matches a known one (e.g., nanobot), pull the concrete references from `{baseDir}/references/bot-frameworks/<framework>/` and use them as the implementation target.

## Phase 2: Interview (bot-specific)

In addition to the main skill's interview questions, ask about:

- **Peer model**: Who are the participants? (typically: one user peer per channel:chat_id, one shared assistant peer)
- **Session granularity**: One session per chat? Per user? Per channel?
- **Workspace ID**: What namespace for this bot's Honcho data?
- **Feature flag**: Should Honcho be opt-in (default `false`) or opt-out (default `true`)?

## Phase 3: Implement (bot-specific)

### Step 1: Add dependency

**Python:** Add `honcho-ai>=2.0.1`. If the framework supports optional dependencies, make it optional:

```toml
[project.optional-dependencies]
honcho = ["honcho-ai>=2.0.1"]
```

**TypeScript:** Add `@honcho-ai/sdk`:

```bash
bun add @honcho-ai/sdk
# or npm install @honcho-ai/sdk
```

If the framework supports optional peer dependencies:

```json
{
  "peerDependencies": {
    "@honcho-ai/sdk": ">=2.0.1"
  },
  "peerDependenciesMeta": {
    "@honcho-ai/sdk": { "optional": true }
  }
}
```

### Step 2: Add config schema

Add a Honcho config section to the bot's configuration system:

**Python:**

```python
class HonchoConfig(BaseModel):
    """Honcho AI-native memory integration (optional feature flag)."""
    enabled: bool = False  # or True for Honcho-first deployments
    workspace_id: str = "default"
    prefetch: bool = True  # inject user context into system prompts
    context_tokens: int | None = None
    environment: str = "production"
```

**TypeScript:**

```typescript
interface HonchoConfig {
  /** Honcho AI-native memory integration (optional feature flag). */
  enabled: boolean;        // default: false, or true for Honcho-first deployments
  workspaceId: string;     // default: "default"
  prefetch: boolean;       // default: true — inject user context into system prompts
  contextTokens?: number;
  environment: string;     // default: "production"
}

const defaultHonchoConfig: HonchoConfig = {
  enabled: false,
  workspaceId: "default",
  prefetch: true,
  environment: "production",
};
```

### Step 3: Create the honcho package

Create a honcho integration package with:

- **Client singleton** (`client.py` / `client.ts`): Lazy initialization, deferred imports, `getHonchoClient()` factory
- **Session manager** (`session.py` / `session.ts`): Maps bot sessions to Honcho sessions with peer configuration
- **Agent tool** (`honcho_tool.py` / `honchoTool.ts`): Tool the agent