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.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- covidence-full-text-reviewSkill
- covidence-full-text-retrievalSkill
- covidence-screeningSkill
- impeccableSkill
- ilearning-autoadvanceSkill
- oh-my-piSkill
- auditing-worktreesSkill
- camofox-browserSkill
- demo-runbookSkill
- i-have-adhdSkill
- memory-uiSkill
- multi-repo-pr-review-merge-roundSkill
- oh-my-ghosttySkill
- tldrSkill
- writing-reportsSkill
- sci-hub-accessSkill
- slack-mention-watchSkill
- slack-scanSkill
- superpowers-using-superpowersSkill
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
- Very specific: line 36
Follow references/migration-guide.md for the six hooks: F1 telemetry in agent/conversation_loop.py.
- Distinctive: line 47
If you already have the feature, skip to "When to use".
- Distinctive: line 58
Only active when BOTH hold:
≈ “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.
Files
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.pyis the full implementing module, andreferences/migration-guide.mdhas 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 detectedand 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)
- Copy
scripts/deepseek_cache.py→<your-hermes>/agent/deepseek_cache.py. - Follow
references/migration-guide.mdfor the six hooks: F1 telemetry inagent/conversation_loop.py; F2 status-bar incli.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 inagent/transports/chat_completions.py; F6 summary cache / temp-0 flash inagent/context_compressor.py. - Enable per your
config.yaml(deepseek_cache.enabled, default true). - 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-statsetc. 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.enabledis true inconfig.yaml(default: enabled; read at runtime viaload_config_readonly(), noDEFAULT_CONFIGentry needed).
Slash commands
| Command | Output |
/cache-stats | Hit rate %, cache-read / cache-miss / cache-write tokens, turn count, estimated $ saved |
/cache-graph | ASCII hit-rate trend chart over the turn history (≤100 points) |
/cache-reset | Zero all counters, clear the summary cache, delete the persisted files |
Config
deepseek_cache:
enabled: true # set false to fully disable for DeepSeek sessions tooInternals 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_pctin cli.py) — the F2 status-bar hook is superseded; do not re-add thecache_segmentsnapshot key. - Upstream removed pre-call aux route resolution in
_generate_summary(route is filled bycall_llmintoroute_info). The F6 temp-0 flash gate must readself.summary_model or self.modelpre-call instead of patching_resolve_task_provider_model; tests setcompressor.summary_model. - The same-provider credential-preservation fix (old local commit) is native in 0.21.0 — drop it when rebasing.
_close_cached_clientnow takesclose_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.
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
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.

