112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
# 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
|