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

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.

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

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:

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