agentleFS
LaansDoleLaansDole/my-hermes-skills/skills/productivity/hermes-deepseek-cache/SKILL.md

hermes-deepseek-cache

Skill3 starsChanged 10 days agoMITView on GitHub

Use when running Hermes Agent with a DeepSeek-family model (deepseek, or deepseek-v4-flash/pro via an aggregator like opencode-go) and want to see, graph, or reset DeepSeek's prefix-cache hit rate, diagnose cache misses, or confirm the deepseek_cache.enabled config — OR when you want to port/apply the deepseek_cache.py module (DeepSeek prefix-cache telemetry, /cache-stats /cache-graph /cache-reset, prefix-break diagnostics, stable tool ordering, cache-friendly compaction) into a Hermes source tree. Covers use + integration.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Follow references/migration-guide.md for the six hooks: F1 telemetry in agent/conversation_loop.py.

    line 36
  2. Distinctive:

    If you already have the feature, skip to "When to use".

    line 47
  3. Distinctive:

    Only active when BOTH hold:

    line 58

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Hermes DeepSeek Prefix-Cache (ported from pi-deepseek-cache)

Hermes has a DeepSeek prefix-cache feature, ported from the ruanbw/pi-deepseek-cache pi extension (2026-08-25). For DeepSeek-family providers it tracks cumulative cache-hit telemetry, warns on prefix rewrites (which break DeepSeek's byte-exact KV prefix cache), keeps tool order stable, and reuses compaction summaries. Non-DeepSeek sessions are untouched.

IMPORTANT — this skill is self-contained. scripts/deepseek_cache.py is the full implementing module, and references/migration-guide.md has the six wiring hooks. Upstream Hermes does NOT ship this feature — if you cloned this skill, you must drop the module in and wire the hooks before any of the commands below exist. See "Port into your Hermes".

When to use

  • You're running Hermes on a DeepSeek model and want to see/persist its cache hit rate (/cache-stats, /cache-graph, /cache-reset).
  • A turn logs deepseek-cache: prefix rewrite detected and you want to know why the cache missed.
  • You want to zero out accumulated cache stats.
  • You want to add this feature to your own Hermes (no upstream support).

Port into your Hermes (first-time setup on any install)

  1. Copy scripts/deepseek_cache.py → <your-hermes>/agent/deepseek_cache.py.
  2. Follow references/migration-guide.md for the six hooks: F1 telemetry in agent/conversation_loop.py; F2 status-bar in cli.py; F3 /cache-* commands on all four surfaces (hermes_cli/commands.py, hermes_cli/slash_exec.py, cli.py, gateway/run.py, tui_gateway/server.py, acp_adapter/server.py); F4 prefix-break diagnostics + F5 stable tool ordering in agent/transports/chat_completions.py; F6 summary cache / temp-0 flash in agent/context_compressor.py.
  3. Enable per your config.yaml (deepseek_cache.enabled, default true).
  4. Verify: scripts/run_tests.sh tests/agent/test_deepseek_cache.py tests/hermes_cli/test_cache_slash_commands.py -q.

If you already have the feature, skip to "When to use".

Where it lives (when installed)

  • Module: agent/deepseek_cache.py.
  • Persisted telemetry: $HERMES_HOME/deepseek-cache/ → stats.json, history.json, summary-cache.json.
  • Slash-command surfaces: cli.py, gateway/run.py, tui_gateway/server.py, acp_adapter/server.py. (On Slack these are namespaced /hermes cache-stats etc. to respect the 50-native-slash cap.)

Gating

Only active when BOTH hold:

  • the active provider AND/OR model is DeepSeek-family — is_deepseek_family(provider, model) matches the substring "deepseek" in either, so aggregator-routed models (opencode-go + deepseek-v4-flash) count too;
  • deepseek_cache.enabled is true in config.yaml (default: enabled; read at runtime via load_config_readonly(), no DEFAULT_CONFIG entry needed).

Slash commands

CommandOutput
/cache-statsHit rate %, cache-read / cache-miss / cache-write tokens, turn count, estimated $ saved
/cache-graphASCII hit-rate trend chart over the turn history (≤100 points)
/cache-resetZero all counters, clear the summary cache, delete the persisted files

Config

deepseek_cache:
  enabled: true    # set false to fully disable for DeepSeek sessions too

Internals worth knowing

  • Hit rate = cacheRead / (cacheRead + input) * 100.
  • Cost estimate (display only): DeepSeek pricing $0.027/MTok cache-read vs $0.27/MTok input.
  • Prefix-break detection: stable SHA-256 of every message except the last (deterministic key-sorted JSON — no key-order jitter). A rewrite (not a pure append) logs a warning once per break; the payload is never mutated.
  • Tool ordering: tools are sorted lexicographically by name before send so tool-order jitter can't bust the byte-exact prefix.
  • Compaction: summaries are keyed on the redacted serialized input (SHA-256) in a persistent LRU (cap 64) so identical conversation state across sessions is not re-summarized; a DeepSeek-flash aux model prefers temperature 0.

Files

  • scripts/deepseek_cache.py — full implementing module (571 lines, drop-in).
  • references/migration-guide.md — six wiring hooks + constraints + verification.

Hermes ≥0.21.0 adaptation notes (rebased 2026-09-04)

  • Upstream 0.21.0 ships its OWN status-bar cache hit-rate display (_cache_hit_rate / cache_hit_pct in cli.py) — the F2 status-bar hook is superseded; do not re-add the cache_segment snapshot key.
  • Upstream removed pre-call aux route resolution in _generate_summary (route is filled by call_llm into route_info). The F6 temp-0 flash gate must read self.summary_model or self.model pre-call instead of patching _resolve_task_provider_model; tests set compressor.summary_model.
  • The same-provider credential-preservation fix (old local commit) is native in 0.21.0 — drop it when rebasing.
  • _close_cached_client now takes close_async= keyword; keep upstream call shape and only swap the return to _compat_model(client, model, default_model).

Verification

  • Unit tests: scripts/run_tests.sh tests/agent/test_deepseek_cache.py tests/hermes_cli/test_cache_slash_commands.py -q.
  • Live spot-check: run a few DeepSeek turns, then /cache-stats, /cache-graph, /cache-reset; watch the status-bar segment; force a prefix break and check agent.log.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.