Feature: freeze environment hints (date/CWD) to enable cross-session DeepSeek prefix caching

Feature Description

Add a config.yaml option to freeze the dynamic values in the system prompt at a stable, session-invariant value — enabling DeepSeek's server-side disk prefix cache to persist across sessions (not just within a session).

Motivation

The problem

DeepSeek's API uses disk-level prefix caching: request prefixes identical to a prior request are served from cache at 50–120× lower cost ($0.14/M → $0.003/M input tokens for v4-flash). Two values in Hermes' system prompt silently bust this cache across sessions:

Hermes already optimizes the date to day-level (%A, %B %d, %Y) which is great — but it still changes daily. The CWD changes every session.

Real-world impact

The Pi coding agent has an equivalent extension (@rohaquinlop/pi-deepseek-cache) that freezes date/CWD via before_agent_start hook. Users report:

• $0.45 for a 90-minute session with v4-pro (vs. ~$20 without)
• 99% cache hit rate across the entire session (62M cached tokens vs 223K fresh)
• Reddit: "The fact I only spent 4 bucks on this amount of tokens feels unreal"

Hermes users on DeepSeek are leaving the same savings on the table.

Why it fits Hermes' design

• The pre_llm_call hook exists — but it intentionally injects into the user message, not the system prompt (agent/turn_context.py:431-435). This is by design and should stay.
• This is not a new hook — it's a small config gate on existing code, aligning with "extend, don't duplicate."
• Not speculative infrastructure — Hermes' own hermes_time.py already supports a config-driven timezone freeze. This extends that pattern to CWD + date format stability.

Proposed Implementation

A single config flag:

# config.yaml
agent:
  freeze_environment_hints: false  # default: false (current behavior)

When true:

1. In agent/system_prompt.py:446-454 — instead of hermes_time.now(), use a stable value:

   • The date line becomes Conversation started: <frozen date> — frozen at the time the agent process started (or at config parse time).
   • Session ID, model, provider lines remain dynamic (they don't affect DeepSeek cache — the cached prefix is the system prompt start, and these are near the end).

2. In agent/prompt_builder.py:1086 — instead of resolve_agent_cwd(), use a frozen/fallback CWD like $HOME (DeepSeek caches the byte-identical prefix, not the full system prompt — a stable value anywhere past the first few KB is sufficient to preserve the disk cache hit for the identity + SOUL.md prefix).

Why not just freeze the whole system prompt?

The system prompt is layered: stable (identity, SOUL.md, environment hints) → context (AGENTS.md) → volatile (date, model, provider). DeepSeek's disk cache keys on the prefix — only the leading bytes need to be identical. Freezing just Conversation started and Current working directory in the stable layer suffices. The volatile layer (model, provider) can stay dynamic without busting the leading prefix.

Alternatives Considered

• Plugin monkeypatching hermes_time.now() — fragile, breaks on updates, not blessed by the plugin API
• New plugin hook (pre_system_prompt) — heavier change, higher bar for approval, and Hermes explicitly reserves the system prompt as "Hermes internals only"
• User manual fork — unsustainable for non-technical users

Existing Precedent

• Hermes already freezes the date to day-level (not minute-level) explicitly for cache reasons: "Date-only (not minute-precision) so the system prompt is byte-stable for the full day." (comment at system_prompt.py:448-452)
• hermes_time.py already supports config-driven timezone via HERMES_TIMEZONE env var or timezone in config.yaml — this is the same pattern
• The compression config section already has cache-awareness as a first-class concern

Related

• Pi extension that does this: @rohaquinlop/pi-deepseek-cache (pi.dev, GitHub)
• DeepSeek prefix caching docs: https://api-docs.deepseek.com/guides/kv_cache/