docs(05-hindsight-memory-provider-01): complete hindsight memory provider activation plan

.planning/phases/05-hindsight-memory-provider/05-01-SUMMARY.md

@@ -0,0 +1,132 @@
+---
+phase: 05-hindsight-memory-provider
+plan: 01
+subsystem: memory
+tags: [hindsight, hermes, memory-provider, local-embedded, openrouter, qwen]
+requires:
+  - phase: 00-foundation
+    provides: Hermes v0.16.0 agent with hindsight plugin bundled
+provides:
+  - Active Hindsight memory provider in local_embedded mode with latency-optimized settings
+  - HINDSIGHT_LLM_API_KEY env var reusing existing OpenRouter key
+  - memory.provider set to hindsight in Hermes config
+affects: [phase-06, phase-07, phase-08]
+tech-stack:
+  added: [hindsight-all 0.8.2 (pre-installed), hindsight-embed daemon binary]
+  patterns: [Local embedded daemon managed by Hermes plugin, Async retain with 5-turn window]
+key-files:
+  created:
+    - ~/.hermes/hindsight/config.json
+  modified:
+    - ~/.hermes/.env
+    - ~/.hermes/config.yaml
+key-decisions:
+  - "local_embedded mode (D-01): local PostgreSQL daemon, no external data send"
+  - "recall_budget: low (D-04): fastest retrieval, minimal latency"
+  - "retain_async: true (D-08) + retain_every_n_turns: 5 (D-09): ~80% overhead reduction"
+  - "memory_mode: hybrid (D-02): auto-injection + all 3 hindsight tools available"
+  - "Reused existing OpenRouter key for LLM extraction (no new secrets needed)"
+patterns-established:
+  - "Memory provider config lives in ~/.hermes/hindsight/config.json (not tracked in project git)"
+  - "Latency-sensitive settings optimized for agent loop performance"
+requirements-completed:
+  - MEM-01
+duration: 3 min
+completed: 2026-06-14
+---
+
+# Phase 5 Plan 1: Hindsight Memory Provider Activation Summary
+
+**Activated Hindsight as the cross-session memory provider for ngn-agent in local_embedded mode with latency-optimized settings (recall_budget: low, retain_every_n_turns: 5, retain_async: true, memory_mode: hybrid)**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-06-14T12:26:00Z
+- **Completed:** 2026-06-14T12:29:00Z
+- **Tasks:** 2 (both type="auto")
+- **Files modified:** 3 (all Hermes system config outside git repo)
+
+## Accomplishments
+
+- Created `~/.hermes/hindsight/config.json` with all 13 locked configuration settings (D-01 through D-10)
+- Added `HINDSIGHT_LLM_API_KEY` to `~/.hermes/.env` reusing the existing OpenRouter API key
+- Set `memory.provider: hindsight` in `~/.hermes/config.yaml` and restarted the gateway
+- Verified hindsight provider is active via `hermes memory status` (shows `Provider: hindsight`, `Status: available`)
+- All acceptance criteria pass — provider active, config valid, env var matches, no provider conflicts, daemon binary present
+
+## Task Commits
+
+Note: All modified files reside outside the ngn-agent git repository (`~/.hermes/` and `~/.hindsight/`), so per-task git commits were not possible within the project repo. Changes are documented here for the record.
+
+1. **Task 1: Create Hindsight config.json and add HINDSIGHT_LLM_API_KEY to .env**
+   - Created `~/.hermes/hindsight/config.json` — 13 keys (mode, llm_provider, llm_base_url, llm_model, bank_id, recall_budget, recall_prefetch_method, auto_recall, recall_types, auto_retain, retain_async, retain_every_n_turns, memory_mode)
+   - Appended `HINDSIGHT_LLM_API_KEY` to `~/.hermes/.env` matching `OPENROUTER_API_KEY`
+   - Verified: all 13 config keys correct, JSON valid, env var matches
+
+2. **Task 2: Set memory.provider to hindsight, restart gateway, verify activation**
+   - Ran `hermes config set memory.provider hindsight`
+   - Ran `hermes gateway restart`
+   - Verified: `hermes memory status` shows hindsight as active provider
+   - Verified: no provider conflicts, daemon binary exists at `~/.hermes/hermes-agent/venv/bin/hindsight-embed`
+   - Verified: `hindsight-all` package at version 0.8.2
+
+## Files Created/Modified
+
+### Created
+- `~/.hermes/hindsight/config.json` — Full Hindsight configuration with all latency-optimized settings
+
+### Modified
+- `~/.hermes/.env` — Added `HINDSIGHT_LLM_API_KEY` env var (line: `HINDSIGHT_LLM_API_KEY=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`)
+- `~/.hermes/config.yaml` — Changed `memory.provider` from `""` to `hindsight`
+
+## Decisions Made
+
+- **Followed all locked decisions D-01 through D-10** exactly as specified in CONTEXT.md and the plan
+- No additional decisions needed — plan was fully specified and executed as written
+
+## Configuration Summary
+
+### `~/.hermes/hindsight/config.json`
+
+| Key | Value | Decision |
+|-----|-------|----------|
+| `mode` | `local_embedded` | D-01 |
+| `llm_provider` | `openrouter` | D-01 |
+| `llm_base_url` | `https://openrouter.ai/api/v1` | D-01 |
+| `llm_model` | `qwen/qwen3.5-9b` | D-01 |
+| `bank_id` | `hermes` | Discretion |
+| `recall_budget` | `low` | D-04 |
+| `recall_prefetch_method` | `recall` | D-05 |
+| `auto_recall` | `true` | D-06 |
+| `recall_types` | `observation` | D-07 |
+| `auto_retain` | `true` | D-10 |
+| `retain_async` | `true` | D-08 |
+| `retain_every_n_turns` | `5` | D-09 |
+| `memory_mode` | `hybrid` | D-02 |
+
+### New Environment Variables
+
+| Env Var | Value | Source |
+|---------|-------|--------|
+| `HINDSIGHT_LLM_API_KEY` | `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` | Same as `OPENROUTER_API_KEY` |
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+- Hindsight memory provider is fully activated and configured
+- Ready for Phase 6 (repo auto-clone) or Phase 7 (session lifecycle)
+- Daemon will start on first Hermes session access (lazy init)
+- Built-in MEMORY.md/USER.md continues as fallback (no changes to `memory_enabled`/`user_profile_enabled`)
+
+---
+
+*Phase: 05-hindsight-memory-provider*
+*Completed: 2026-06-14*