
migrate-honcho
Migrates Honcho Python SDK code from v1.6.0 to v2.1.1. Use when upgrading honcho package, fixing breaking changes after upgrade, or when errors mention AsyncHoncho, observations, Representation class, .core property, or getconfig methods.
- Installs
- 332
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/plastic-labs/honcho --skill migrate-honcho- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads migrate-honcho automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Honcho Python SDK Migration (v1.6.0 → v2.1.1)
Overview
This skill migrates code from honcho Python SDK v1.6.0 to v2.1.1 (required for Honcho 3.0.0+).
Key breaking changes:
AsyncHoncho/AsyncPeer/AsyncSessionremoved → use.aioaccessor- "Observation" → "Conclusion" terminology
Representationclass removed (returnsstrnow)get_config/set_config→get_configuration/set_configuration- Streaming via
chat_stream()instead ofchat(stream=True) poll_deriver_status()removed.coreproperty removed
Quick Migration
1. Update async architecture
# Before
from honcho import AsyncHoncho, AsyncPeer, AsyncSession
async_client = AsyncHoncho()
peer = await async_client.peer("user-123")
response = await peer.chat("query")
# After
from honcho import Honcho
client = Honcho()
peer = await client.aio.peer("user-123")
response = await peer.aio.chat("query")
# Async iteration
async for p in client.aio.peers():
print(p.id)
2. Replace observations with conclusions
# Before
from honcho import Observation, ObservationScope, AsyncObservationScope
scope = peer.observations
scope = peer.observations_of("other-peer")
rep = scope.get_representation()
# After
from honcho import Conclusion, ConclusionScope, ConclusionScopeAio
scope = peer.conclusions
scope = peer.conclusions_of("other-peer")
rep = scope.representation() # Returns str
3. Update representation handling
# Before
from honcho import Representation, ExplicitObservation, DeductiveObservation
rep: Representation = peer.working_rep()
print(rep.explicit)
print(rep.deductive)
if rep.is_empty():
print("No observations")
# After
rep: str = peer.representation()
print(rep) # Just a string now
if not rep:
print("No conclusions")
4. Rename configuration methods
# Before
config = peer.get_config()
peer.set_config({"observe_me": False})
session.get_config()
client.get_config()
# After
from honcho.api_types import PeerConfig, SessionConfiguration, WorkspaceConfiguration
config = peer.get_configuration()
peer.set_configuration(PeerConfig(observe_me=False))
session.get_configuration()
client.get_configuration()
5. Update method names
# Before
peer.working_rep()
peer.get_context()
peer.get_sessions()
session.get_context()
session.get_summaries()
session.get_messages()
session.get_peers()
session.get_peer_config()
client.get_peers()
client.get_sessions()
client.get_workspaces()
# After
peer.representation()
peer.context()
peer.sessions()
session.context()
session.summaries()
session.messages()
session.peers()
session.get_peer_configuration()
client.peers()
client.sessions()
client.workspaces()
6. Update streaming
# Before
response = peer.chat("query", stream=True)
for chunk in response:
print(chunk, end="")
# After
stream = peer.chat_stream("query")
for chunk in stream:
print(chunk, end="")
7. Update queue status (formerly deriver)
# Before
from honcho_core.types import DeriverStatus
status = client.get_deriver_status()
status = client.poll_deriver_status(timeout=300.0) # Removed!
# After
from honcho.api_types import QueueStatusResponse
status = client.queue_status()
# poll_deriver_status removed - implement polling manually if needed
8. Update representation parameters
# Before
rep = peer.working_rep(
include_most_derived=True,
max_observations=50
)
# After
rep = peer.representation(
include_most_frequent=True,
max_conclusions=50
)
9. Move update_message to session
# Before
updated = client.update_message(message=msg, metadata={"key": "value"}, session="sess-id")
# After
updated = session.update_message(message=msg, metadata={"key": "value"})
10. Update card() return type and method name
# Before
card: str = peer.card() # Returns str
# After (v2.0.0+)
card: list[str] | None = peer.get_card() # Returns list[str] | None
if card:
print("\n".join(card))
# peer.card() still works but is deprecated — use get_card()
# New in v2.0.1: set_card()
peer.set_card(["Prefers dark mode", "Located in US"])
11. Strict input validation (v2.0.2+)
All input models now reject unknown fields via extra="forbid" Pydantic validation. Previously, misspelled or extraneous fields were silently ignored.
# Before (v2.0.1 and earlier) — silently ignored
peer = client.peer("user-1", configuration=PeerConfig(observe_mee=True)) # typo silently ignored
# After (v2.0.2+) — raises ValidationError
peer = client.peer("user-1", configuration=PeerConfig(observe_mee=True)) # ValidationError!
12. peer() and session() always make API calls (v2.1.0+)
Breaking: peer() and session() now always make a get-or-create API call. Previously, calling without metadata/configuration returned a lazy object with no API call.
# Before (v2.0.x) — no API call without options
peer = client.peer("user-123") # Lazy, no network request
# After (v2.1.0+) — always hits the API
peer = client.peer("user-123") # Makes POST to /peers (get-or-create)
# Async
peer = await client.aio.peer("user-123") # Also always hits API
13. New properties and methods (v2.1.0+)
# created_at on Peer and Session
peer = client.peer("user-123")
print(peer.created_at) # datetime | None
session = client.session("sess-1")
print(session.created_at) # datetime | None
# is_active on Session
print(session.is_active) # bool | None
# get_message() on Session
msg = session.get_message("msg-id")
# Async: msg = await session.aio.get_message("msg-id")
14. Pagination parameters on list methods (v2.1.0+)
All list methods now accept page, size, and reverse parameters:
# Before (v2.0.x) — only filters
peers_page = client.peers(filters={"metadata": {"role": "admin"}})
# After (v2.1.0+) — pagination controls
peers_page = client.peers(
filters={"metadata": {"role": "admin"}},
page=2,
size=25,
reverse=True
)
# Works on: client.peers(), client.sessions(), peer.sessions(),
# session.messages(), scope.list()
15. Broader HTTP retry logic (v2.1.1+)
The SDK now retries on httpx.TimeoutException, httpx.NetworkError, and httpx.RemoteProtocolError (previously only httpx.TimeoutException and httpx.ConnectError). These are mapped to the SDK's TimeoutError and ConnectionError respectively. No code changes needed — this is transparent.
Quick Reference Table
| v1.6.0 | v2.0.0 |
|---|---|
AsyncHoncho() | Honcho() + .aio accessor |
AsyncPeer | Peer + .aio accessor |
AsyncSession | Session + .aio accessor |
Observation | Conclusion |
ObservationScope | ConclusionScope |
AsyncObservationScope | ConclusionScopeAio |
Representation | str |
.observations | .conclusions |
.observations_of() | .conclusions_of() |
.get_config() | .get_configuration() |
.set_config() | .set_configuration() |
.working_rep() | .representation() |
.get_context() | .context() |
.get_sessions() | .sessions() |
.get_peers() | .peers() |
.get_messages() | .messages() |
.get_summaries() | .summaries() |
.get_deriver_status() | .queue_status() |
.poll_deriver_status() | (removed) |
.get_peer_config() | .get_peer_configuration() |
.set_peer_config() | .set_peer_configuration() |
client.update_message() | session.update_message() |
peer.card() | peer.get_card() (card() deprecated) |
| (new) | peer.set_card(list[str]) |
chat(stream=True) | chat_stream() |
include_most_derived= | include_most_frequent= |
max_observations= | max_conclusions= |
last_user_message= | search_query= |
config= | configuration= |
PeerContext | PeerContextResponse |
DeriverStatus | QueueStatusResponse |
client.core | (removed) |
| (new v2.1.0) | peer.created_at / session.created_at |
| (new v2.1.0) | session.is_active |
| (new v2.1.0) | session.get_message(id) |
| (new v2.1.0) | page=, size=, reverse= on list methods |
Detailed Reference
For comprehensive details on each change, see:
- DETAILED-CHANGES.md - Full API change documentation
- MIGRATION-CHECKLIST.md - Step-by-step checklist
New Exception Types
from honcho import (
HonchoError,
APIError,
BadRequestError,
AuthenticationError,
PermissionDeniedError,
NotFoundError,
ConflictError,
UnprocessableEntityError,
RateLimitError,
ServerError,
TimeoutError,
ConnectionError,
)
New Import Locations
# Configuration types
from honcho.api_types import (
PeerConfig,
SessionConfiguration,
WorkspaceConfiguration,
SessionPeerConfig,
QueueStatusResponse,
PeerContextResponse,
)
# Async type hints
from honcho import HonchoAio, PeerAio, SessionAio
# Message types (note: Params is plural now)
from honcho import Message, MessageCreateParams
FAQ
What does the migrate-honcho skill do?
Migrates Honcho Python SDK code from v1.6.0 to v2.1.1. Use when upgrading honcho package, fixing breaking changes after upgrade, or when errors mention AsyncHoncho, observations, Representation class, .core property, or getconfig methods.
How do I install migrate-honcho?
Run npx skills add https://github.com/plastic-labs/honcho --skill migrate-honcho in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/migrate-honcho/ (personal) or .claude/skills/migrate-honcho/ (project).
Which AI agents can use migrate-honcho?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is migrate-honcho safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains migrate-honcho?
It is published by plastic-labs in plastic-labs/honcho. It has 332 recorded installs.
More from plastic-labs/honcho
honcho-integration
plastic-labs/honcho
Integrate Honcho memory into existing Python or TypeScript codebases. Use when adding Honcho SDK, setting up peers, configuring sessions, and accessing Honcho's representation.
honcho-cli
plastic-labs/honcho
Inspect and debug Honcho workspaces via the honcho CLI. Use when investigating peer representations, memory state, session context, or dialectic quality — any task that requires introspection of a Honcho deployment, including verifying that a recall/record memory loop is actually working.
migrate-honcho-ts
plastic-labs/honcho
Migrates Honcho TypeScript SDK code from v1.6.0 to v2.1.1. Use when upgrading @honcho-ai/sdk, fixing breaking changes after upgrade, or when errors mention removed APIs like .core, getConfig, observations, or snakecase properties.
honcho-memory
plastic-labs/honcho
Concepts and strategy for using a connected Honcho as persistent memory of the user — the recall/record loop and session and peer design. Start here to understand how Honcho memory works, then connect — via a first-class integration for your environment if one exists (preferred), or raw MCP tools (covered here) or the honcho-cli skill (CLI). For embedding the SDK into a codebase, use honcho-integration.
verify
plastic-labs/honcho
Build, launch, and drive a local Honcho stack to verify a change at its runtime surface (the /v3 HTTP API and the deriver queue). Use when verifying a diff or confirming a change works in the running app.
pre-pr
plastic-labs/honcho
Prepare a Honcho change for a pull request to plastic-labs/honcho. Invoke before opening a PR, when drafting a PR body, when asked if a branch is PR-ready, or when filling the pull request template. Checks required tests and docs, then writes Description / Proofs / Fixes.
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.