x402agent/SolanaOS / .agents/skills/honcho-integration
honcho-integration
VerifiedIntegrate Honcho memory and social cognition into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, implementing the dialectic chat endpoint for AI agents, or wiring Honcho into bot frameworks (nanobot, openclaw, picoclaw, etc).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.1 KB |
| references/bot-frameworks.md | markdown | 8.2 KB |
| references/bot-frameworks/nanobot/client.py | script | 2.1 KB |
| references/bot-frameworks/nanobot/honcho_tool.py | script | 2.6 KB |
| references/bot-frameworks/nanobot/session.py | script | 20.4 KB |
references/bot-frameworks.md
View on GitHub# 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 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 peer: `observe_me=False, observe_others=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:**
```python
session.add_messages([
user_peer.message(user_input),
assistant_peer.message(assistant_response),
])
```
**TypeScript:**
```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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |