From 731f66a7eb7cbfe673b96303979f037e14979eb0 Mon Sep 17 00:00:00 2001
From: Hex <hex@sat.bolverker.com>
Date: Tue, 3 Feb 2026 10:43:03 -0700
Subject: [PATCH] docs: add reflector guidance to README and skill

---
 README.md | 10 ++++++++++
 SKILL.md  | 10 ++++++++++
 2 files changed, 20 insertions(+)

diff --git a/README.md b/README.md
index 0c016a7..c66174f 100644
--- a/README.md
+++ b/README.md
@@ -122,6 +122,16 @@ hexmem_session_end "Session ended" "Key outcomes and next steps"
 hexmem_heartbeat_check
 ```
 
+### Reflector (Metabolic Loop)
+
+HexMem uses **tiered memory**: high‑fidelity working logs + curated core memory. The Reflector is an **agentic** sleep-cycle that distills signal from raw logs.
+
+- Working logs: `memory/YYYY-MM-DD.md`
+- Core memory: `MEMORY.md` + HexMem DB
+- Triggered hooks: log core updates immediately on significant state changes (deploys, config, incidents)
+
+See: **docs/REFLECTOR.md** for full guidance and a reminder-only cron template.
+
 # Access a fact (bumps to hot tier)
 hexmem_access_fact 42
 
diff --git a/SKILL.md b/SKILL.md
index ec3a9fc..fa4be96 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -199,6 +199,16 @@ hexmem_goal_progress <goal_id> <new_percentage>
 hexmem_session_end "Session ended" "Key outcomes, decisions, and next steps"
 ```
 
+### Reflector (Metabolic Loop)
+
+Run a periodic **agentic** distillation cycle (not every message). It reads recent working logs and updates core memory.
+
+- Working logs: `memory/YYYY-MM-DD.md`
+- Core memory: `MEMORY.md` + HexMem DB
+- Triggered hooks: log core updates immediately on significant state changes (config changes, deploys, incidents)
+
+See: `docs/REFLECTOR.md` for the full pattern + reminder-only cron template.
+
 ### Heartbeat Check
 
 ```bash