# 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