# Feature Research

**Domain:** Platform engineering agent (Hermes Agent-based configuration/adoption)
**Project:** ngn-agent v1.1 — Session Workspace, Hindsight Memory & Cron Reporting
**Researched:** 2026-06-14
**Overall Confidence:** HIGH

---

## Feature Landscape

### Table Stakes (Users Expect These)

Features users assume exist. Missing = product feels incomplete.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Default repos cloned in new sessions | Every session needs project repos (rai-ops, rai-deployment, rai-devtools). Manual clone every session is friction. | LOW | `on_session_start` plugin hook or shell hook. Needs git credentials in Docker container. |
| Cross-session persistent memory | Agent forgets everything between sessions without it. Built-in MEMORY.md is too small (2.2k chars) and frozen at session start. | LOW | Hindsight memory provider. `hermes memory setup` → select hindsight. |
| Daily operational report | Any agent managing infrastructure must report daily. Invisible work erodes trust. | MEDIUM | Cron job + custom skill. Telegram delivery already works. |
| Stale session cleanup | Sessions pile up indefinitely without lifecycle management. | MEDIUM | No built-in archiving. Custom `export_session()` + `delete_session()` script. |

### Differentiators (Competitive Advantage)

Features that set the product apart from a bare Hermes install.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| Knowledge graph memory (Hindsight) | Entity-aware, cross-session recall with LLM synthesis (`hindsight_reflect`). Not just text search — entities, relationships, consolidated observations. | LOW | Hindsight provides this automatically once active. Local embedded mode = zero cloud dependency. |
| On-demand repo cloning during session | User says "clone rai-pipeline" mid-session, agent does it without leaving the conversation. | LOW | Hermes skill or just telling the agent. Trivial once git credentials are mounted. |
| Jira-integrated daily report | Report includes Jira ticket status and session→ticket correlations, not just session summaries. | MEDIUM | `ngn-jira` skill already exists. Add Jira query to daily-report skill prompt. |
| Zero-cost stale cleanup | Archive operations use `no_agent: true` cron mode — zero LLM token cost. | LOW | Deterministic script. No LLM needed for export+delete. |

### Anti-Features (Commonly Requested, Often Problematic)

| Feature | Why Requested | Why Problematic | What to Do Instead |
|---------|---------------|-----------------|-------------------|
| Custom scheduler for reports | "I need more control over timing" | Hermes cron already does intervals, cron expressions, and ISO timestamps. Building another scheduler is waste. | Use `hermes cron create` with cron expressions. |
| Custom memory provider implementation | "I want memory tailored to my needs" | Hindsight is already bundled, production-ready, and has all the features (KG, entities, reflect). Building from scratch is months of work. | Activate hindsight via `hermes memory setup`. Configure via `~/.hermes/hindsight/config.json`. |
| Persistent Docker image with pre-cloned repos | "Cloning at session start is slow" | Image would be large, stale quickly, and need regular rebuilding. The current `nikolaik/python-nodejs` image is sufficient. | Clone at session start via `on_session_start` hook. Container persistence (`container_persistent: true`) means clones survive across sessions. |
| Cloud-only hindsight mode | "Local setup is complicated" | Local embedded mode is already managed by Hermes (auto-daemon, auto-stop). Cloud adds third-party API dependency and cost. | Use local embedded mode. Hermes handles the PostgreSQL daemon. |

---

## Feature Dependencies

```
Default Repos
    └──requires──> Git credentials mounted into Docker container
                       └──requires──> Security review of credential exposure
                   
Hindsight Memory
    └──requires──> OpenRouter API key for LLM extraction (already in .env)
    └──requires──> ~500MB free disk for local embedded PostgreSQL daemon
    └──enhances──> Every other feature (better cross-session context)
                   
Daily Cron Report
    └──requires──> Cron system active (✓ v1.0)
    └──requires──> Telegram delivery channel (✓ v1.0)
    └──requires──> Session querying script or skill
                       └──requires──> Read access to ~/.hermes/state.db
    └──enhances──> Jira skill (✓ v1.0) for ticket data in reports
                   
Stale Session Archive
    └──requires──> SessionDB.export_session() API
    └──requires──> Archive storage location (~/.hermes/archive/sessions/)
    └──requires──> Cron job to trigger weekly (cron active ✓)
    └──enhances──> Daily report (report can mention what will be archived)
```

### Dependency Notes

- **Default Repos requires git credentials:** The Docker container has no SSH keys or GitHub tokens. Must mount either `~/.ssh/` (read-only, scoped deploy key only) or a GitHub token via `docker_forward_env`.
- **Hindsight enhances everything:** Once hindsight is active, every session's facts feed the knowledge graph. This enriches daily reports with cross-session context.
- **Stale Archive enhances Daily Report:** The report can include "N sessions will be archived this week" as an early warning. Implement archive after report so the user sees what's coming.

---

## MVP Recommendation

### Prioritize (v1.1 Launch)

1. **Hindsight memory provider** — Config + env var. Quickest win, immediately useful in every session. Pure configuration, no code.
2. **Default repos auto-clone** — Plugin hook + git credential mount. Fills the biggest UX gap. Security review of credential mounting is the gating item.
3. **Daily report cron** — Skill-backed cron job. Needs prompt iteration to get right but delivers immediate operational visibility.
4. **Stale session archive** — No-agent script. Lowest priority because it's destructive and benefits from having reporting working first.

### Defer (v1.2+)

| Feature | Reason to Defer |
|---------|----------------|
| On-demand repo cloning skill | Nice-to-have once default cloning works. The user can already ask the agent to clone a repo manually. |
| Jira integration in daily report | Additive to basic report. Wait until report format is stable. |
| Archive restore script | Archive files are text-searchable JSON. Restore is low urgency. |
| Custom ngn-agent plugin package | Only worth it if the agent is shared across a team. |

### Ordering Rationale

Hindsight first because it's zero-risk and makes everything else better. Default repos second because they're needed for productive sessions but require security-sensitive credential mounting. Reporting third because it depends on having active sessions to report on. Archiving last because it's destructive and should only run after the user can verify through reports what will be affected.

---

## Implementation Notes

### Default Repos — Technical Approach

**Mechanism:** Hermes plugin hook `on_session_start` or shell hook `pre_llm_call` with `is_first_turn=True`.

```python
def clone_default_repos(session_id, model, platform, **kwargs):
    import subprocess, os
    repos = ["rai-ops", "rai-deployment", "rai-devtools"]
    for repo in repos:
        path = f"/workspace/{repo}"
        if not os.path.exists(path):
            subprocess.run(["git", "clone", f"git@github.com:rai-apps/{repo}.git", path])

def register(ctx):
    ctx.register_hook("on_session_start", clone_default_repos)
```

**Git credential mount options (in order of security preference):**
1. **Read-only deploy key per repo** — Most secure. Mount only the deploy key, not full `~/.ssh/`.
2. **GitHub fine-grained token** via `docker_forward_env` — Scoped to `contents:read` on exactly 3 repos. Easy to rotate.
3. **SSH agent socket forwarding** — Keys never enter container filesystem. Requires `SSH_AUTH_SOCK` to be active.
4. **Full `~/.ssh:ro` mount** — Least secure but simplest. Exposes ALL SSH keys to container.

### Hindsight — Configuration Blueprint

```
1. hermes memory setup        # interactive — select "hindsight"
2. Set mode: local_embedded
3. Set LLM provider: openrouter (uses existing .env key)
4. Verify: hermes memory status
5. Tune config at ~/.hermes/hindsight/config.json:
   {
     "mode": "local_embedded",
     "bank_id_template": "ngn-agent-{profile}",
     "recall_budget": "mid",
     "memory_mode": "hybrid",
     "auto_retain": true,
     "auto_recall": true,
     "recall_types": "observation"
   }
```

### Daily Report — Skills Blueprint

Create `~/.hermes/skills/daily-report/SKILL.md` instructing the agent to:
1. Query sessions started in the last 24h from state.db
2. For each active session: get title, last message preview, token count
3. Query sessions inactive >30d (for archive warning)
4. Format as Telegram-friendly summary (3-5 bullet points per session)
5. Use `[SILENT]` if nothing to report

### Stale Archive — Script Pattern

```python
from hermes_state import SessionDB
from pathlib import Path
import json, datetime

db = SessionDB()
archive_dir = Path.home() / ".hermes" / "archive" / "sessions"
archive_dir.mkdir(parents=True, exist_ok=True)

cutoff = datetime.datetime.now() - datetime.timedelta(days=30)

for session in db.get_all_sessions():
    last_active = session.get("ended_at") or session.get("started_at")
    if last_active and last_active < cutoff.timestamp():
        data = db.export_session(session["id"])
        if data:
            tmp = archive_dir / f"{session['id']}.tmp"
            tmp.write_text(json.dumps(data, indent=2))
            final = archive_dir / f"{session['id']}.json"
            tmp.rename(final)
            # Verify
            verified = json.loads(final.read_text())
            if verified.get("id") == session["id"]:
                db.delete_session(session["id"])
```

Run as weekly no-agent cron:
```bash
hermes cron create "0 6 * * 0" \
  --no-agent \
  --script archive-stale-sessions.py \
  --deliver telegram \
  --name "Weekly Session Archive"
```

---

## Feature Prioritization Matrix

| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| Hindsight memory provider | HIGH | LOW | P1 |
| Default repo cloning | HIGH | LOW-MEDIUM | P1 |
| Daily Telegram report | MEDIUM | LOW-MEDIUM | P1 |
| Stale session archive | MEDIUM | MEDIUM | P1 |
| On-demand repo cloning | MEDIUM | LOW | P2 |
| Jira integration in report | MEDIUM | MEDIUM | P2 |
| Archive restore | LOW | LOW | P3 |
| Custom ngn-agent plugin | MEDIUM | HIGH | P3 |

**Priority key:**
- P1: Must have for v1.1 launch
- P2: Should have, add when scope allows
- P3: Nice to have, future milestone

---

## Sources

- Hermes Agent memory docs: `~/.hermes/hermes-agent/website/docs/user-guide/features/memory.md`
- Hermes Agent memory providers: `~/.hermes/hermes-agent/website/docs/user-guide/features/memory-providers.md` (Hindsight section)
- Hindsight README: `~/.hermes/hermes-agent/plugins/memory/hindsight/README.md`
- Hermes hook system: `~/.hermes/hermes-agent/website/docs/user-guide/features/hooks.md`
- Hermes cron system: `~/.hermes/hermes-agent/website/docs/user-guide/features/cron.md`
- Cron internals: `~/.hermes/hermes-agent/website/docs/developer-guide/cron-internals.md`
- Session storage: `~/.hermes/hermes-agent/website/docs/developer-guide/session-storage.md`
- SessionDB source: `~/.hermes/hermes-agent/hermes_state.py`
- Curator (skills only, not sessions): `~/.hermes/hermes-agent/agent/curator.py`
- ngn-agent PROJECT.md and initial-plan.md
- Current Hermes config: `~/.hermes/config.yaml`

---
*Feature research for: ngn-agent v1.1*
*Researched: 2026-06-14*
*Confidence: HIGH — based on documented Hermes APIs and existing ngn-agent codebase*