Skald-Circle/honcho

Honcho — self-hosted Docker package

This folder contains a ready-to-run Docker Compose setup for Honcho, the memory server used by the personal-agent's Honcho plugin (src/plugin/honcho/).

---

What runs

Service	Image	Port	Role
api	ghcr.io/plastic-labs/honcho:latest	8000	REST API (the endpoint personal-agent talks to)
deriver	same image	—	Background worker: extracts conclusions, summaries, peer representations
db	pgvector/pgvector:pg17	5432 (internal)	PostgreSQL + pgvector (vector search)
redis	redis:7-alpine	6379 (internal)	Cache for session context

Data is stored in named Docker volumes (honcho_db, honcho_redis) and survives container restarts.

---

Prerequisites

• Docker ≥ 24 with Compose plugin (docker compose version)
• An LLM API key (OpenAI by default; OpenRouter and Ollama also supported — see LLM providers)

---

Quick start

# 1. Copy the env template
cp .env.example .env

# 2. Set your LLM key (minimum required)
#    Open .env and fill in LLM_OPENAI_API_KEY=sk-...

# 3. Start all services (detached)
docker compose up -d

# 4. Verify the API is up
curl http://localhost:8000/health
# → {"status":"ok"}

# 5. Open interactive API docs
open http://localhost:8000/docs

The first startup takes ~30 s while Docker pulls the images and the database runs migrations.

---

Connect personal-agent

Enable the Honcho plugin in personal-agent by asking the main agent or using the REST API:

PUT /api/plugins/honcho
Content-Type: application/json

{
  "enabled": true,
  "config": {
    "base_url":     "http://localhost:8000",
    "api_key":      "",
    "workspace_id": "personal-agent"
  }
}

• api_key — leave empty when HONCHO_AUTH_TOKEN is not set in .env.
• workspace_id — any string; used to namespace workspaces inside Honcho.

---

LLM providers

Honcho needs an LLM to run the deriver (background memory extraction). The API itself works without it, but no long-term conclusions will be built.

OpenAI (default)

LLM_OPENAI_API_KEY=sk-...

Defaults to gpt-4o-mini for text generation and text-embedding-3-small for embeddings.

OpenRouter

LLM_OPENAI_API_KEY=sk-or-...
DERIVER_MODEL_CONFIG__TRANSPORT=openai
DERIVER_MODEL_CONFIG__MODEL=openai/gpt-4o-mini
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1

Gives access to many models (Anthropic, Mistral, Gemini, …) on a single key.

Ollama (fully local — no data leaves the machine)

Requires Ollama running on the host with a function-calling model and an embedding model:

ollama pull llama3.3:70b
ollama pull nomic-embed-text

LLM_OPENAI_API_KEY=ollama
DERIVER_MODEL_CONFIG__TRANSPORT=openai
DERIVER_MODEL_CONFIG__MODEL=llama3.3:70b
DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=http://host.docker.internal:11434/v1
LLM_EMBEDDING_API_KEY=ollama
LLM_EMBEDDING_BASE_URL=http://host.docker.internal:11434/v1
LLM_EMBEDDING_MODEL=nomic-embed-text

host.docker.internal resolves to the host machine from inside the container (works on macOS and Windows; on Linux add --add-host=host.docker.internal:host-gateway to the compose service if needed).

---

Useful commands

# Start / stop
docker compose up -d
docker compose down

# Follow logs
docker compose logs -f api
docker compose logs -f deriver

# Restart only the API after a config change
docker compose restart api

# Stop and wipe all data (destructive!)
docker compose down -v

# Upgrade to a newer Honcho image
docker compose pull
docker compose up -d

---

Build from source (alternative)

If the published image is unavailable or you want to run unreleased code:

# Clone the official Honcho repository next to this folder
git clone https://github.com/plastic-labs/honcho honcho-src

# In docker-compose.yml, replace the api/deriver `image:` lines with:
#   build:
#     context: ./honcho-src

docker compose up -d --build

---

Troubleshooting

Symptom	Likely cause	Fix
api container exits immediately	DB not ready	Check docker compose logs db; wait for "database system is ready"
deriver keeps restarting	Invalid LLM key or unreachable endpoint	Check docker compose logs deriver; verify .env
curl http://localhost:8000/health returns connection refused	Wrong port or container not started	Run docker compose ps; check HONCHO_PORT in .env
personal-agent logs honcho: session_context failed	API unreachable	Verify base_url in plugin config; check firewall / VPN
Conclusions not appearing after several chats	Deriver not running	Run docker compose logs deriver; check LLM key

---

References

• Honcho GitHub
• Honcho docs
• Self-hosting guide (official)
• personal-agent Honcho plugin docs
• personal-agent Memory architecture