docs: complete v1.1 research synthesis for session lifecycle, memory & reporting

.planning/research/STACK.md

@@ -0,0 +1,111 @@
+# Technology Stack
+
+**Project:** ngn-agent v1.1 — Session Workspace, Hindsight & Cron Reporting
+**Researched:** 2026-06-14
+
+## Recommended Stack
+
+### New Dependencies
+
+| Technology | Version | Purpose | Why |
+|------------|---------|---------|-----|
+| `hindsight-client` | >=0.4.22 | Hindsight Cloud API client (MemoryProvider plugin) | Already bundled in Hermes; only needs pip install |
+| SSH key (existing) | N/A | Git clone auth inside Docker container | Private repos need auth; `~/.ssh:ro` mount is simplest |
+
+### Runtime Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `session-init.sh` | `~/.hermes/scripts/session-init.sh` | Clone DEFAULT_REPOS into `/workspace/repos/` at shell start |
+| `daily-report.md` skill | `~/.hermes/skills/daily-report.md` | Instructions for the daily cron report LLM agent |
+| `stale-cleanup.sh` script | `~/.hermes/scripts/stale-cleanup.sh` | Archive sessions >30d inactive (no_agent cron) |
+| `jira-sync.sh` script (optional) | `~/.hermes/scripts/jira-sync.sh` | Update Jira with session progress (no_agent cron) |
+| `clone-repo.md` skill | `~/.hermes/skills/clone-repo.md` | On-demand repo cloning during a session |
+
+### Config Changes
+
+| Config | Location | Value |
+|--------|----------|-------|
+| `memory.provider` | config.yaml | `hindsight` |
+| `terminal.shell_init_files` | config.yaml | `["/usr/local/bin/session-init.sh"]` |
+| `terminal.docker_volumes` | config.yaml | Add `~/.ssh:/root/.ssh:ro` and `~/Projects:/workspace/repos:rw` |
+| `HINDSIGHT_API_KEY` | `~/.hermes/.env` | API key from https://ui.hindsight.vectorize.io |
+| `DEFAULT_REPOS` | `~/.hermes/.env` | Space-separated `org/repo` list |
+
+### Cron Jobs
+
+| Name | Schedule | Type | Purpose |
+|------|----------|------|---------|
+| `daily-report` | `0 9 * * *` | skill-backed | Daily session summary via Telegram |
+| `stale-cleanup` | `0 2 * * *` | `no_agent` script | Archive sessions >30d inactive |
+| `jira-sync` | `0 10 * * *` | `no_agent` script | Update Jira with session progress |
+
+## Alternatives Considered
+
+| Category | Recommended | Alternative | Why Not |
+|----------|-------------|-------------|---------|
+| Hindsight mode | **Cloud** | Local Embedded | ~200MB download + 2-4GB RAM overhead; cloud is zero-infrastructure |
+| Git auth method | **SSH key mount** (`~/.ssh:ro`) | SSH agent forwarding | Agent forwarding needs host socket access; key file mount is simpler and more reliable |
+| Session init method | **`shell_init_files`** | Plugin `on_session_start` hook | `shell_init_files` runs before agent starts, guaranteeing repos exist; plugin hook requires custom code |
+| Cron reporting | **Hermes skill + cron** | Custom Python script | Hermes cron + delivery already exists; skill approach lets LLM compose the report flexibly |
+
+## Installation
+
+```bash
+# 1. Install Hindsight client
+uv pip install "hindsight-client>=0.4.22"
+
+# 2. Configure Hindsight API key
+echo "HINDSIGHT_API_KEY=hs_..." >> ~/.hermes/.env
+
+# 3. Set DEFAULT_REPOS
+echo "DEFAULT_REPOS=razer-ops/rai-ops razer-ops/rai-deployment razer-ops/rai-devtools" >> ~/.hermes/.env
+
+# 4. Create session init script
+cat > ~/.hermes/scripts/session-init.sh << 'SCRIPT'
+#!/bin/bash
+# Auto-clone DEFAULT_REPOS into the workspace
+REPOS_DIR="/workspace/repos"
+mkdir -p "$REPOS_DIR"
+
+for REPO in $DEFAULT_REPOS; do
+  REPO_NAME=$(basename "$REPO" .git)
+  TARGET="$REPOS_DIR/$REPO_NAME"
+  if [ ! -d "$TARGET/.git" ]; then
+    echo "Cloning $REPO..."
+    git clone --depth 1 "git@github.com:${REPO}.git" "$TARGET" 2>/dev/null || \
+    git clone --depth 1 "https://github.com/${REPO}.git" "$TARGET"
+  else
+    echo "Updating $REPO..."
+    git -C "$TARGET" pull --ff-only 2>/dev/null
+  fi
+done
+SCRIPT
+chmod +x ~/.hermes/scripts/session-init.sh
+
+# 5. Create cron report skill
+cat > ~/.hermes/skills/daily-report.md << 'SKILL'
+# daily-report
+
+[Skill content as documented in ARCHITECTURE.md]
+SKILL
+
+# 6. Create stale cleanup script
+cat > ~/.hermes/scripts/stale-cleanup.sh << 'SCRIPT'
+[Script to find & archive sessions >30d]
+SCRIPT
+chmod +x ~/.hermes/scripts/stale-cleanup.sh
+
+# 7. Update config.yaml (add volumes, shell_init_files, memory.provider)
+# 8. Restart gateway
+hermes gateway restart
+```
+
+## Sources
+
+- Hermes v0.16.0 source: `plugins/memory/hindsight/__init__.py` — Hindsight MemoryProvider
+- Hermes v0.16.0 source: `agent/memory_manager.py` — MemoryManager orchestration
+- Hermes v0.16.0 source: `cron/scheduler.py` — Cron execution engine
+- Hermes v0.16.0 source: `cron/jobs.py` — Job definition & delivery
+- Hermes v0.16.0 source: `gateway/hooks.py` — Event hook system
+- Hindsight documentation: https://hindsight.vectorize.io