Daniele
7e3fa3caad
Nightly Build / build (push) Successful in 3m48s
Against a self-hosted Honcho 3.0.11 every read path came back empty while the server was healthy and full of derived facts: the plugin parsed a `conclusions`/`summary` shape the API no longer emits. - honcho-client: typed models for the real schema — `PeerContext` (`representation` markdown + `peer_card`), `SessionContext` (`summary` as an object, `peer_representation`), wrapped `PeerCard` (a bare array on PUT is a 422, which also broke `honcho_profile` writes). - plugin: the turn-time injection and `honcho_context` read the representation; `honcho_search` and the page's /search now use `conclusions/query` (observer/observed scoping inside `filters`) — a real ranked semantic search with fact ids, which `peer_context?search_query` never provided; /overview returns card + representation + conclusions. - compose: pin the Honcho image by digest (3.0.11) — ghcr publishes no v3 semver tags, and an untracked `:latest` pull is what drifted the schema. - tests: fixture tests from payloads captured on the live server, plus an env-gated live smoke test (HONCHO_E2E_URL/_WS/_PEER, `cargo test -p honcho-client -- --ignored`) — run it before any future Honcho bump.
192 lines
5.5 KiB
Markdown
192 lines
5.5 KiB
Markdown
# Honcho — self-hosted Docker package
|
|
|
|
This folder contains a ready-to-run Docker Compose setup for [Honcho](https://honcho.dev),
|
|
the memory server used by the Honcho plugin
|
|
([`crates/plugin-honcho/`](../crates/plugin-honcho/)).
|
|
|
|
---
|
|
|
|
## What runs
|
|
|
|
| Service | Image | Port | Role |
|
|
| --- | --- | --- | --- |
|
|
| `api` | `ghcr.io/plastic-labs/honcho@sha256:59f0…8c6b` (**3.0.11**, digest-pinned) | **8000** | REST API (the endpoint the app 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 |
|
|
|
|
> The Honcho image is **pinned by digest** because ghcr publishes no v3 semver
|
|
> tags (only `latest`), and the plugin parses a version-specific API schema —
|
|
> a silent `:latest` bump already changed response shapes once. Upgrade
|
|
> deliberately: pick the new digest, verify the plugin against it, then edit.
|
|
|
|
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](#llm-providers))
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```http
|
|
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)
|
|
|
|
```dotenv
|
|
LLM_OPENAI_API_KEY=sk-...
|
|
```
|
|
|
|
Defaults to `gpt-4o-mini` for text generation and `text-embedding-3-small` for embeddings.
|
|
|
|
### OpenRouter
|
|
|
|
```dotenv
|
|
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](https://ollama.com) running on the host with a function-calling model
|
|
and an embedding model:
|
|
|
|
```sh
|
|
ollama pull llama3.3:70b
|
|
ollama pull nomic-embed-text
|
|
```
|
|
|
|
```dotenv
|
|
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
|
|
|
|
```sh
|
|
# 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 Honcho: bump the pinned digest in docker-compose.yml (deliberately —
|
|
# the plugin's API parsing is verified against the pinned version), then
|
|
docker compose pull
|
|
docker compose up -d
|
|
```
|
|
|
|
---
|
|
|
|
## Build from source (alternative)
|
|
|
|
If the published image is unavailable or you want to run unreleased code:
|
|
|
|
```sh
|
|
# 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](https://github.com/plastic-labs/honcho)
|
|
- [Honcho docs](https://docs.honcho.dev)
|
|
- [Self-hosting guide (official)](https://docs.honcho.dev/v3/contributing/self-hosting)
|
|
- [Honcho plugin docs](../docs/plugins/honcho.md)
|
|
- [Memory architecture](../docs/memory.md)
|