From 4e1df2a77f8f1ae039613c9334ff60c23b28ea16 Mon Sep 17 00:00:00 2001
From: Toby <toby@example.com>
Date: Wed, 1 Jul 2026 03:41:10 +0000
Subject: [PATCH] docs: add configuration and environment variable examples

---
 .env.example | 37 +++++++++++++++++++++++++++++++++++++
 README.md    | 20 +++++++++++++++++++-
 2 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..63eb77c
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,37 @@
+# --- PostgreSQL Credentials ---
+# Password for the postgres user (used by docker-compose)
+HEXUS_DB_PASS=postgres_secret
+
+# --- Hexus MCP Server Config ---
+# If you run the MCP server manually (outside of docker-compose), 
+# you'll need this so it knows how to connect.
+# NOTE: If running via `docker compose --profile mcp up`, the compose file
+# already sets this to host=pg internally, but you can override here.
+HEXUS_DSN="dbname=hermes_test user=postgres password=postgres_secret host=localhost"
+
+# (Optional) Pre-load the embedding model at startup
+# HEXUS_EMBED_EAGER_LOAD="1"
+
+# (Optional) Transport for MCP server: "stdio" or "http"
+# HEXUS_TRANSPORT="stdio"
+
+# (Optional) Webhook integration
+# HEXUS_WEBHOOK_URL="https://your-webhook.url/..."
+# HEXUS_WEBHOOK_SECRET="your_hmac_secret"
+
+
+# ==============================================================================
+# Hexus Plugin Configuration (for hermes.yaml)
+# ==============================================================================
+# If you are using Hexus directly as a Hermes Agent plugin (rather than MCP),
+# you don't use this .env file to configure the database connection. Instead, 
+# you configure it in your `hermes.yaml` under the memory plugin settings:
+#
+# plugins:
+#   memory:
+#     provider: hexus
+#     config:
+#       # Point this to your docker postgres instance:
+#       dsn: "dbname=hermes_test user=postgres password=postgres_secret host=localhost"
+#       # Optional: configure embedding method
+#       embed_provider: "local"  # or "openai", "ollama"
diff --git a/README.md b/README.md
index 7ebac5d..244ce90 100644
--- a/README.md
+++ b/README.md
@@ -64,14 +64,32 @@ pip install hexus
 ```
 *Note: Once installed, just point Hermes to it! You can also just drop the `hexus` module files straight into your `~/.hermes/plugins/hexus/` directory. Hermes's discovery system will automatically pick it up and initialize it on startup!*
 
+**Configuration (`hermes.yaml`):**
+When running as a Hermes plugin, configure it directly in your `hermes.yaml` file (not via environment variables):
+
+```yaml
+plugins:
+  memory:
+    provider: hexus
+    config:
+      # The Postgres connection string (required)
+      dsn: "dbname=hermes_memory user=postgres password=postgres_secret host=localhost"
+```
+
 ### Option 2: Docker & MCP Server (Claude, Cursor, etc.)
 The easiest way to run the standalone MCP server is via Docker (GHCR). 
 
 > **Note:** The Docker MCP server requires a running PostgreSQL database with `pgvector` enabled. You can reference or use our provided `docker/compose.yml` file as a quick example to spin one up!
 
+**Environment Variables:**
+When running via Docker or as a standalone MCP server, you can pass the following environment variables:
+* `HEXUS_DSN` - The Postgres connection string (e.g., `dbname=hermes_memory user=postgres password=secret host=pg`).
+* `HEXUS_DB_PASS` - Used by our `compose.yml` to automatically set up the Postgres password.
+* `HEXUS_EMBED_EAGER_LOAD` - Set to `"1"` to pre-load the local embedding model at startup (saves ~1-2s on first use).
+
 ```bash
 # Run the MCP server via HTTP streamable transport on port 8000
-docker run -d --name hexus -p 8000:8000 ghcr.io/codenamekt/hexus:latest
+docker run -d --name hexus -p 8000:8000 -e HEXUS_DSN="dbname=hermes_memory user=postgres host=host.docker.internal" ghcr.io/codenamekt/hexus:latest
 ```
 
 **Using it with Claude Code / Claude Desktop:**