First Version

2026-07-10 15:02:09 +01:00
commit 38494a85a9
562 changed files with 196313 additions and 0 deletions
@@ -0,0 +1,72 @@
+# Honcho — environment configuration
+# Copy this file to .env and fill in the values.
+#
+#   cp .env.example .env
+#
+# Lines marked [REQUIRED] must be set before starting.
+# Lines marked [OPTIONAL] have sensible defaults and can be left empty.
+
+# ── LLM Provider ─────────────────────────────────────────────────────────────
+#
+# Honcho uses an LLM internally for:
+#   - extracting conclusions from conversation turns  (deriver)
+#   - building peer representations / user cards       (deriver)
+#   - session summarisation                            (deriver)
+#   - dialectic/peer_chat queries                      (api)
+#
+# The deriver will fail silently (no memory extraction) if no key is provided.
+# The API itself will still respond; only background memory-building stops.
+
+# Option A — OpenAI (default)
+# All model slots default to gpt-4o-mini / text-embedding-3-small.
+LLM_OPENAI_API_KEY=sk-...                    # [REQUIRED for default setup]
+
+# Option B — OpenRouter (OpenAI-compatible, access to many models)
+# Uncomment and set DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL in the section below.
+# LLM_OPENAI_API_KEY=sk-or-...
+
+# Option C — Ollama (fully local, no data leaves the machine)
+# Requires Ollama running on the host and a model that supports function calling.
+# Uncomment the OLLAMA block below.
+
+# ── Model overrides (optional) ────────────────────────────────────────────────
+#
+# Leave empty to use the defaults (OpenAI gpt-4o-mini / text-embedding-3-small).
+# Uncomment and edit to point at a different provider or model.
+
+# OpenRouter example:
+# DERIVER_MODEL_CONFIG__TRANSPORT=openai
+# DERIVER_MODEL_CONFIG__MODEL=openai/gpt-4o-mini
+# DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1
+
+# Ollama example (fully local):
+# 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
+
+# ── Database ──────────────────────────────────────────────────────────────────
+# Credentials for the built-in PostgreSQL container.
+# Change these if you connect an external DB.
+
+POSTGRES_USER=honcho
+POSTGRES_PASSWORD=honcho          # [RECOMMENDED] change in production
+POSTGRES_DB=honcho
+
+# ── Redis ─────────────────────────────────────────────────────────────────────
+# No configuration needed for the built-in Redis container.
+# To use an external Redis, override CACHE_URL in docker-compose.yml.
+
+# ── API exposure ──────────────────────────────────────────────────────────────
+# Port the Honcho API listens on. Default: 8000.
+HONCHO_PORT=8000
+
+# API auth token. Leave empty for unauthenticated local access.
+# If set, pass it as Bearer token from personal-agent's plugin config (api_key field).
+# HONCHO_AUTH_TOKEN=
+
+# ── Sentry / observability (optional) ────────────────────────────────────────
+# SENTRY_DSN=
@@ -0,0 +1,185 @@
+# 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 personal-agent's Honcho plugin
+([`src/plugin/honcho/`](../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](#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 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:
+
+```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)
+- [personal-agent Honcho plugin docs](../docs/honcho.md)
+- [personal-agent Memory architecture](../docs/memory.md)
@@ -0,0 +1,113 @@
+# Honcho — self-hosted memory server
+#
+# Runs four services:
+#   api       — HTTP API on :8000
+#   deriver   — background worker: extracts conclusions, builds peer representations
+#   db        — PostgreSQL 17 + pgvector (needed for embedding search)
+#   redis     — fast cache for session context
+#
+# Usage:
+#   cp .env.example .env
+#   # edit .env and set at least LLM_OPENAI_API_KEY (or another provider)
+#   docker compose up -d
+#
+# The API will be available at http://localhost:8000
+# Interactive docs: http://localhost:8000/docs
+
+services:
+
+  # ── Migrate (run-once) ────────────────────────────────────────────────────
+  # Applies Alembic migrations before the API starts.
+  # Exits with code 0 when done; Docker Compose marks it "completed".
+  migrate:
+    image: ghcr.io/plastic-labs/honcho:latest
+    env_file: .env
+    environment:
+      DB_CONNECTION_URI: postgresql+psycopg://${POSTGRES_USER:-honcho}:${POSTGRES_PASSWORD:-honcho}@db:5432/${POSTGRES_DB:-honcho}
+      CACHE_URL: redis://redis:6379/0?suppress=true
+    command: ["/app/.venv/bin/alembic", "upgrade", "head"]
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: "no"
+
+  # ── API ────────────────────────────────────────────────────────────────────
+  api:
+    image: ghcr.io/plastic-labs/honcho:latest
+    restart: unless-stopped
+    ports:
+      - "${HONCHO_PORT:-8000}:8000"
+    env_file: .env
+    environment:
+      DB_CONNECTION_URI: postgresql+psycopg://${POSTGRES_USER:-honcho}:${POSTGRES_PASSWORD:-honcho}@db:5432/${POSTGRES_DB:-honcho}
+      CACHE_URL: redis://redis:6379/0?suppress=true
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      migrate:
+        condition: service_completed_successfully
+    healthcheck:
+      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+
+  # ── Deriver (background worker) ───────────────────────────────────────────
+  # Processes incoming messages to:
+  #   - extract observations (conclusions) about users
+  #   - build peer representations / user cards
+  #   - generate session summaries
+  #   - run "dream" consolidation passes
+  #
+  # Without a working LLM key this service will fail to process messages;
+  # the API itself will still work but no long-term memory will be built.
+  deriver:
+    image: ghcr.io/plastic-labs/honcho:latest
+    restart: unless-stopped
+    command: ["/app/.venv/bin/python", "-m", "src.deriver"]
+    env_file: .env
+    environment:
+      DB_CONNECTION_URI: postgresql+psycopg://${POSTGRES_USER:-honcho}:${POSTGRES_PASSWORD:-honcho}@db:5432/${POSTGRES_DB:-honcho}
+      CACHE_URL: redis://redis:6379/0?suppress=true
+    depends_on:
+      api:
+        condition: service_healthy
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+  # ── PostgreSQL + pgvector ─────────────────────────────────────────────────
+  db:
+    image: pgvector/pgvector:pg17
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER:     ${POSTGRES_USER:-honcho}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-honcho}
+      POSTGRES_DB:       ${POSTGRES_DB:-honcho}
+    volumes:
+      - honcho_db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-honcho} -d ${POSTGRES_DB:-honcho}"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  # ── Redis ─────────────────────────────────────────────────────────────────
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    volumes:
+      - honcho_redis:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+volumes:
+  honcho_db:
+  honcho_redis: