honcho
Self-hosted Honcho memory platform — Postgres + Redis + API + Worker. Workspace-scoped JWT auth (HS256). Alembic migrations via init container. Serves as persistent memory for OpenClaw and Hermes with
SKILL.mdskills/honcho/SKILL.md
GitHubHoncho Skill
¿Qué es Honcho?
plastic-labs/honcho — plataforma de memoria persistente para agentes IA.
Expone una API HTTP v3 con workspaces, sessions, messages y peers.
Cada agente tiene su propio workspace aislado. Auth via JWT HS256.
- API docs:
http://honcho.cluster.home/docs - SDK:
@honcho-ai/sdk(TypeScript) / Python client
Stack
| Componente | Imagen | Puerto interno | Notas |
|---|---|---|---|
| Postgres | postgres:16-alpine |
5432 | Persistence + Alembic schema |
| Redis | redis:7-alpine |
6379 | Cache + worker queue |
| API | plastlabs/honcho |
8000 | Service → port 80 → targetPort 8000 |
| Worker | plastlabs/honcho |
— | Deriver background tasks |
El servicio Kubernetes mapea 80 → 8000. Toda NetworkPolicy que deje entrar o salir hacia Honcho debe usar el targetPort 8000, no el port 80. Ver sección "Gotcha Cilium DNAT" más abajo.
Arquitectura en cluster
Namespace: honcho
┌─────────────────────────────────────────────────────┐
│ │
│ honcho-api (Deployment) │
│ ├─ initContainer: migrate-db │
│ │ python scripts/provision_db.py │
│ │ → alembic upgrade head (24 migraciones) │
│ └─ container: honcho API :8000 │
│ │
│ honcho-worker (Deployment) │
│ ├─ initContainer: wait-for-api │
│ │ espera hasta que /health responde │
│ └─ container: honcho worker (deriver tasks) │
│ │
│ honcho-postgres (Deployment) │
│ honcho-redis (Deployment) │
│ │
│ Service/honcho-api → ClusterIP :80 → pod :8000 │
│ HTTPRoute → honcho.cluster.home │
│ PVC: honcho-postgres-data (longhorn-nvme) │
└─────────────────────────────────────────────────────┘
Consumers:
OpenClaw (openclaw ns) → honcho-api.honcho.svc:80 → pod :8000
Hermes (ai ns) → honcho-api.honcho.svc:80 → pod :8000
Alembic — migraciones (init container)
Honcho tiene 24 migraciones Alembic que deben ejecutarse antes de que el API arranque. Sin ellas el worker crashea:
sqlalchemy.exc.ProgrammingError: relation "public.active_queue_sessions" does not exist
Solución: init container en el Deployment del API que ejecuta provision_db.py:
# charts/honcho/templates/api-deployment.yaml
initContainers:
- name: migrate-db
image: "{{ image }}"
command: ["python", "scripts/provision_db.py"]
workingDir: /app
envFrom:
- secretRef:
name: honcho-secrets
provision_db.py llama init_db() → alembic upgrade head. Se ejecuta en
cada deploy: es idempotente, solo aplica las migraciones faltantes.
NUNCA usar kubectl exec para ejecutar Alembic. Siempre via init container
(correcto, reproducible, no depende del estado de un pod en vivo).
Auth — JWT HS256 workspace-scoped
Honcho soporta dos modos:
AUTH_USE_AUTH=false→ cualquier key es aceptada (modo dev)AUTH_USE_AUTH=true→ valida JWT HS256 firmado conAUTH_JWT_SECRET
En producción usar AUTH_USE_AUTH=true con keys workspace-scoped.
Tipos de JWT
| Payload | Tipo | Uso |
|---|---|---|
{"t":"","w":"openclaw"} |
Workspace-scoped | Solo accede al workspace openclaw |
{"t":"","w":"hermes"} |
Workspace-scoped | Solo accede al workspace hermes |
{"t":"","ad":true} |
Admin | Accede a todos los workspaces |
Generar keys
# 1. Generar JWT secret (guardar en secrets.yml)
python3 -c "import secrets; print(secrets.token_hex(32))"
# 2. Generar workspace key para openclaw
SECRET="<tu-jwt-secret>"
python3 -c "import jwt; print(jwt.encode({'t':'','w':'openclaw'}, '$SECRET', 'HS256'))"
# 3. Generar workspace key para hermes
python3 -c "import jwt; print(jwt.encode({'t':'','w':'hermes'}, '$SECRET', 'HS256'))"
# 4. Generar admin key (solo para administración)
python3 -c "import jwt; print(jwt.encode({'t':'','ad':True}, '$SECRET', 'HS256'))"
Secrets por rol
Cada consumer guarda su workspace-scoped key en su propio secrets.yml:
# roles/install-openclaw/defaults/secrets.yml (gitignored)
openclaw_honcho_api_key: "eyJ..." # JWT con {"w":"openclaw"}
# roles/install-hermes-agent/defaults/secrets.yml (gitignored)
hermes_honcho_api_key: "eyJ..." # JWT con {"w":"hermes"}
La key de admin (honcho_admin_key) solo vive en roles/install-honcho/defaults/secrets.yml.
Verificar aislamiento
# JWT openclaw NO puede acceder al workspace hermes → 401
curl -H "Authorization: Bearer $OPENCLAW_KEY" \
http://honcho.cluster.home/v3/workspaces/hermes
# → 401 Unauthorized
# JWT hermes NO puede acceder al workspace openclaw → 401
curl -H "Authorization: Bearer $HERMES_KEY" \
http://honcho.cluster.home/v3/workspaces/openclaw
# → 401 Unauthorized
SDK Python — env vars oficiales
El Honcho Python SDK lee exactamente estas variables de entorno:
| Env var | Propósito | Ejemplo |
|---|---|---|
HONCHO_URL |
URL del API (primary) | http://honcho-api.honcho.svc.cluster.local |
HONCHO_BASE_URL |
URL del API (alias) | igual que HONCHO_URL |
HONCHO_API_KEY |
JWT o API key de autenticación | eyJ... |
HONCHO_WORKSPACE_ID |
Workspace ID (primary) | hermes |
HONCHO_WORKSPACE |
Workspace ID (alias, añadido por compatibilidad) | hermes |
Hermes usa el SDK Python y lee HONCHO_URL + HONCHO_WORKSPACE_ID.
Para garantizar compatibilidad, el deployment de Hermes setea los 5 nombres.
OpenClaw usa el plugin @honcho-ai/openclaw-honcho (TypeScript) con el SDK JS.
El SDK JS lee baseUrl de openclaw.json config (no env var).
API v3 — endpoints clave
# Health check (sin auth)
GET /health → {"status":"ok"}
# Crear workspace (POST /v3/workspaces con body {id: "..."})
POST /v3/workspaces
Authorization: Bearer <jwt>
{"id": "hermes"}
→ {"id":"hermes","created_at":"..."}
# GET workspace existente
POST /v3/workspaces # con id ya existente → devuelve el existente (idempotente)
PUT /v3/workspaces/{workspace_id} # update
# Listar workspaces
POST /v3/workspaces/list
{"filter": null}
# Crear peer
POST /v3/workspaces/{workspace_id}/peers
{"id": "user-123", "metadata": {}}
# Listar peers
POST /v3/workspaces/{workspace_id}/peers/list
{}
# Crear session para un peer
POST /v3/workspaces/{workspace_id}/peers/{peer_id}/sessions
{"metadata": {...}}
# Chat con contexto de memoria
POST /v3/workspaces/{workspace_id}/peers/{peer_id}/chat
Helm chart local (charts/honcho/)
El chart está en el repo, no en un registry externo.
charts/honcho/
├── Chart.yaml
├── values.yaml
└── templates/
├── api-deployment.yaml # API + init container migrate-db
├── worker-deployment.yaml # Worker + init container wait-for-api
├── postgres-deployment.yaml
├── redis-deployment.yaml
├── secret.yaml # DB password + JWT secret (AUTH_USE_AUTH, AUTH_JWT_SECRET)
├── service.yaml
└── httproute.yaml
Variables clave en values.yaml:
llm:
baseUrl: "http://litellm-proxy.ai.svc.cluster.local:4000/v1"
apiKey: "sk-hermes-internal"
model: "kimi-free" # ← CRÍTICO: debe soportar tool_choice:any (ver gotcha abajo)
embedMessages: "false"
auth:
useAuth: "true" # "false" = dev mode (any key accepted)
jwtSecret: "" # Injected from Ansible secrets.yml
postgresql:
dbPassword: "" # Injected from Ansible secrets.yml
llm.model se inyecta en el Secret (secret.yaml) como DERIVER_MODEL, SUMMARY_MODEL,
DREAM_MODEL y DIALECTIC_LEVELS. Cambiar el valor en values.yaml actualiza el Secret en el
próximo make honcho, pero no reinicia los pods automáticamente. Siempre hacer:
kubectl rollout restart deployment/honcho-worker deployment/honcho-api -n honcho
Deploy
# Prerequisitos: generar secrets primero
cp roles/install-honcho/defaults/secrets.yml.example \
roles/install-honcho/defaults/secrets.yml
# Editar: honcho_db_password, honcho_jwt_secret, honcho_admin_key
# Deploy
make honcho
# Equivalente
ansible-playbook playbooks/bootstrap.yml -i inventory/hosts.ini --tags ai-honcho
La primera vez, los init containers ejecutan las 24 migraciones Alembic (~30s extra).
Por qué Honcho (y no alternativas)
Honcho es la elección más opinionada de este stack. Hay alternativas más simples (mem0, LangChain memory, PostgreSQL propio). Mi opinión sobre por qué Honcho:
Honcho sí: tiene un modelo de dialectic reasoning — el deriver LLM sintetiza memorias en segundo plano sin bloquear la respuesta del usuario. La memoria no es solo "guardar el último mensaje" sino "inferir qué es importante y construir un user profile". Para un asistente personal de largo plazo (Tito hablando con el mismo usuario todos los días), esto marca diferencia real.
Honcho no: el dialectic usa un LLM extra (kimi-free), lo que añade latencia y un
punto de fallo. Si el LLM del deriver es lento (modelos :free) o no soporta tool_choice:any
(Nemotron), la memoria se "silencia" sin error visible. Honcho es complejo de debuggear.
Decisión: Honcho está bien para el caso de uso actual (agente personal conversacional a largo plazo). Si el stack fuera una API pública con miles de usuarios, usaría algo más simple. Pero para UN usuario conversando diario con Tito, el overhead vale.
Sobre el modelo del deriver: kimi-free (Moonshot kimi-k2.6:free) es el único
modelo :free que ha demostrado soportar tool_choice: any sin problemas. Si hay que
cambiar, elegir un modelo con soporte nativo de Anthropic tool use. Nemotron nunca.
Gotcha — tool_choice: "any" rechazado por Nemotron/OpenRouter
Síntoma: OpenClaw muestra "⚠️ Something went wrong while processing your request" en cada mensaje. Los logs del honcho-worker no tienen errores visibles, pero la memoria no se guarda ni se recupera.
Causa raíz: Honcho v3 envía tool_choice: "any" (convención Anthropic) en sus llamadas
de dialectic/deriver al LLM. Nemotron via OpenRouter solo acepta "none", "auto", "required" →
devuelve HTTP 400 → el worker de reasoning falla silenciosamente → la memoria se escribe pero
la síntesis de contexto no funciona → OpenClaw no puede recuperar contexto → error en respuesta.
Fix (aplicado 2026-06-01):
charts/honcho/values.yaml:llm.model: "kimi-free"— Moonshot kimi-k2.6:free soporta tool_choice correctamenteroles/install-litellm-proxy/tasks/main.yml:litellm_settings.modify_params: true— LiteLLM dropa params no soportados como fallback de seguridad
Regla: solo usar modelos como llm.model en Honcho que soporten tool_choice: "any" o "required".
Modelos confirmados como problemáticos: Nemotron (nvidia/nemotron-3-super-120b-a12b).
Modelos confirmados como funcionando: kimi-k2.6:free, Kimi, modelos con soporte nativo de Anthropic tool_choice.
Gotcha — Peer map de OpenClaw fuera del PVC (memoria "amnésica")
Síntoma: las memorias se guardan en Honcho (Postgres tiene los datos) pero después de cada restart del pod, Tito no recuerda nada y arranca de cero.
Causa raíz: el plugin openclaw-honcho guarda su peer map (mapeo
chat/usuario → peer/session IDs de Honcho) en /home/node/.honcho/openclaw-peers.json.
El PVC openclaw-data solo montaba /home/node/.openclaw → el peer map vivía
en el filesystem efímero del contenedor → en cada restart se perdía el mapeo
y el plugin creaba peers/sessions nuevos, dejando huérfanas las memorias viejas.
Fix (2026-06-10): openclaw-deployment.yaml.j2 monta además
/home/node/.honcho desde el mismo PVC con subPath: .honcho-state
(en gateway, sidecar y MCP bridge). El init container crea el directorio con
ownership 1000:1000. Las memorias pre-fix siguen en Postgres pero quedaron
asociadas a peers viejos — se reconstruyen con el uso.
Gotcha — Cilium evalúa NetworkPolicy POST-DNAT
Regla crítica: cuando Cilium aplica una NetworkPolicy de egress, evalúa el puerto DESPUÉS del DNAT (después de que el ClusterIP se traduce al pod IP).
El servicio honcho-api mapea: Service port 80 → pod targetPort 8000.
Cuando OpenClaw conecta a honcho-api.honcho.svc.cluster.local:80, Cilium ve
la conexión como destino port 8000 (el targetPort real del pod).
Por eso la NetworkPolicy de egress en OpenClaw debe usar 8000, no 80:
# roles/install-openclaw/templates/openclaw-network.yaml.j2
# CORRECTO:
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: honcho
ports:
- port: 8000 # ← targetPort del pod, no service port
protocol: TCP
# INCORRECTO (bloqueará aunque parezca lógico):
# ports:
# - port: 80 # ← service port → Cilium no lo ve así post-DNAT
Cómo detectarlo: debug pods sin el label de NetworkPolicy pueden conectar
(el NetworkPolicy no aplica a ellos). Solo los pods con app=openclaw son
afectados. Usar curl -s --max-time 8 ... EXIT:$? → EXIT:28 = timeout (bloqueado).
Aplica a cualquier servicio con service port ≠ targetPort:
- LiteLLM: service 4000 = targetPort 4000 → NetworkPolicy port 4000 ✅
- Honcho: service 80 ≠ targetPort 8000 → NetworkPolicy debe usar 8000
Troubleshooting
Worker crashea en startup
kubectl logs -n honcho deploy/honcho-worker --tail=30
# Si ves: "relation ... does not exist" → Alembic no corrió
# Si ves: init container "migrate-db" no está → actualizar chart y redeploy
# Verificar que el init container corrió las 24 migraciones
kubectl logs -n honcho <api-pod> -c migrate-db
# → "Running upgrade ... -> ..., Apply ..."
# → "INFO [alembic.runtime.migration] Running upgrade ..."
API retorna 500 / errores de schema
# Forzar re-run de migraciones: reiniciar el deployment
kubectl rollout restart deploy/honcho-api -n honcho
# → init container migrate-db corre de nuevo (idempotente)
OpenClaw no puede conectar a Honcho
# 1. Verificar que el servicio existe
kubectl get svc -n honcho
# 2. Verificar que el health check responde
kubectl run -n honcho curl-test --restart=Never --image=curlimages/curl \
--command -- curl -s http://honcho-api.honcho.svc.cluster.local/health
kubectl logs -n honcho curl-test; kubectl delete pod -n honcho curl-test
# 3. Verificar conectividad CON NetworkPolicy aplicada (usar label app=openclaw)
kubectl run -n openclaw nw-test --restart=Never --image=curlimages/curl \
--labels="app=openclaw" \
--command -- sh -c 'curl -s --max-time 8 http://honcho-api.honcho.svc.cluster.local/health; echo EXIT:$?'
sleep 12; kubectl logs -n openclaw nw-test; kubectl delete pod -n openclaw nw-test
# Si EXIT:28 → NetworkPolicy bloqueando → verificar que usa puerto 8000, no 80
kubectl get networkpolicy openclaw-egress -n openclaw -o yaml | grep -A5 "honcho"
# 4. Verificar en los logs de OpenClaw
kubectl logs -n openclaw deploy/openclaw -c openclaw-gateway --tail=30 | grep -i honcho
# → "Honcho memory ready" = OK
# → "Failed to initialize Honcho: ConnectionError" = NetworkPolicy o URL incorrecta
JWT inválido / 401
# Verificar que el JWT secret en Honcho coincide con el usado para generar las keys
# El secret está en el Secret de K8s:
kubectl get secret honcho-secrets -n honcho -o jsonpath='{.data.AUTH_JWT_SECRET}' | base64 -d
# Regenerar una key y verificarla
SECRET=$(kubectl get secret honcho-secrets -n honcho -o jsonpath='{.data.AUTH_JWT_SECRET}' | base64 -d)
python3 -c "import jwt; print(jwt.decode('$KEY', '$SECRET', algorithms=['HS256']))"
# → debe mostrar {"t":"","w":"openclaw"} o similar sin error
Verificación completa post-deploy
# 1. Todos los pods running
kubectl get pods -n honcho
# → honcho-api, honcho-worker, honcho-postgres, honcho-redis: Running
# 2. Health check
curl http://honcho.cluster.home/health
# → {"status":"ok"}
# 3. Crear workspace con key de admin
ADMIN_KEY=$(grep honcho_admin_key roles/install-honcho/defaults/secrets.yml | awk '{print $2}' | tr -d '"')
curl -X POST http://honcho.cluster.home/v3/workspaces/openclaw \
-H "Authorization: Bearer $ADMIN_KEY"
# → {"id":"openclaw",...}
# 4. Workspace-scoped key solo accede a su workspace
OPENCLAW_KEY=$(grep openclaw_honcho_api_key roles/install-openclaw/defaults/secrets.yml | awk '{print $2}' | tr -d '"')
curl http://honcho.cluster.home/v3/workspaces/openclaw \
-H "Authorization: Bearer $OPENCLAW_KEY"
# → 200 OK
curl http://honcho.cluster.home/v3/workspaces/hermes \
-H "Authorization: Bearer $OPENCLAW_KEY"
# → 401 Unauthorized (aislamiento correcto)
# 5. OpenClaw muestra "Honcho memory ready" en logs
kubectl logs -n openclaw deploy/openclaw -c openclaw-gateway | grep -i honcho
# → "Honcho memory ready — peer map: ..."
Workspaces configurados
| Workspace | Consumer | JWT en |
|---|---|---|
openclaw |
OpenClaw gateway | roles/install-openclaw/defaults/secrets.yml → openclaw_honcho_api_key |
hermes |
Hermes Agent | roles/install-hermes-agent/defaults/secrets.yml → hermes_honcho_api_key |
Repo Paths
charts/honcho/ # Helm chart local
roles/install-honcho/
├── defaults/main.yml # honcho_node_hostname, storage, auth
├── defaults/secrets.yml # gitignored: db_password, jwt_secret, admin_key
├── defaults/secrets.yml.example
└── tasks/main.yml # include_vars + helm deploy + rollout wait
roles/install-openclaw/templates/
└── openclaw-network.yaml.j2 # egress port 8000 (post-DNAT targetPort)
Makefile: make honcho