honcho/skills/honcho-integration/references/bot-frameworks.md

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	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:

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

TypeScript: Add @honcho-ai/sdk:

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

If the framework supports optional peer dependencies:

{
  "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:

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:

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 can call to query user context via peer.chat()

Key patterns (Python):

• from __future__ import annotations + TYPE_CHECKING for all honcho imports
• Runtime imports inside functions (never top-level) so the bot doesn't crash without honcho-ai
• Wrap in try/except ImportError for graceful degradation

Key patterns (TypeScript):

• Use dynamic import() for honcho SDK (never top-level import ... from) so the bot doesn't crash without @honcho-ai/sdk
• Use import type { ... } for type-only imports that are erased at runtime
• Wrap in try/catch for graceful degradation when the SDK is missing

Key patterns (shared):

• IDs sanitized to ^[a-zA-Z0-9_-]+ (Honcho requirement)
• User peer: observe_me=True, observe_others=True
• Assistant/bot peer: observe_others=True; set observe_me=False only for deterministic bots (scripted output — nothing to model). AI-assistant bots can keep observe_me=True.

If references exist for this framework, use them directly from {baseDir}/references/bot-frameworks/<framework>/.

Step 4: Wire into the agent loop

Add these integration points to the agent loop:

1. Tool registration (at startup): If honcho.enabled and HONCHO_API_KEY set, initialize client + register Honcho tools.

   Python: Wrap in try/except ImportError for graceful degradation. TypeScript: Use dynamic import() inside a try/catch block.

2. Context setup (per message): Set session context on Honcho tools, ensure Honcho session exists.

3. Prefetch (per message): Call session.context() to get user representation and inject into system prompt before the LLM call.

4. Sync (after response): After saving to local session, sync the user+assistant message pair to Honcho.

   Python:

   session.add_messages([
       user_peer.message(user_input),
       assistant_peer.message(assistant_response),
   ])
   

   TypeScript:

   await session.addMessages([
       userPeer.message(userInput),
       assistantPeer.message(assistantResponse),
   ]);
   

5. Migration (on first activation): If Honcho session is empty but local session has history, upload prior messages as a file via session.upload_file() (Python) or session.uploadFile() (TypeScript). Also upload MEMORY.md and HISTORY.md if they exist (from frameworks with local memory consolidation). Archive originals after successful upload.

Step 5: Pass config through CLI

Pass honcho_config to every agent loop instantiation in the CLI commands.

Step 6: Migration support

When Honcho activates on an instance with existing local data, migrate automatically:

• Session messages (JSONL files): Format as XML transcript, upload via session.upload_file() (Python) or session.uploadFile() (TypeScript)
• Consolidated memory (MEMORY.md, HISTORY.md): Upload as tagged files with context annotations
• Archive originals: Move to migrated/ subdirectory after successful upload
• Idempotent: Skip if Honcho session already has messages

Phase 4: Verify (bot-specific)

After integration, verify:

• Bot starts normally without the Honcho SDK installed (no import errors)
• Bot starts normally with the SDK but without HONCHO_API_KEY (graceful skip)
• With both present and enabled=true, logs show "Honcho tools registered"
• User context is prefetched and visible in system prompts
• Messages sync to Honcho after each exchange
• Local session migration works on first Honcho activation
• Memory file migration works for MEMORY.md/HISTORY.md (if applicable)

Bot-Specific Patterns

• Lazy imports everywhere:
  • Python: from __future__ import annotations + TYPE_CHECKING for type hints, runtime imports inside functions
  • TypeScript: import type { ... } for type-only imports, dynamic import() for runtime access
• Feature flag gating: Always check config.enabled AND HONCHO_API_KEY / process.env.HONCHO_API_KEY before touching Honcho
• Graceful degradation:
  • Python: try/except ImportError and generic Exception catches with logger warnings, never crash the bot
  • TypeScript: try/catch around dynamic import() with logger warnings, never crash the bot
• Sanitize IDs: Honcho requires ^[a-zA-Z0-9_-]+ — replace colons, dots, spaces with dashes
• Sync after success: Only mark messages as synced after the API call succeeds, not before
• Cache consistency: When creating aliased sessions, store under both original and derived keys