ngn-agent/.planning/research/STACK.md

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

# 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