tune-temperature-policy
Skill125 starsChanged 7 months agoMITView on GitHub
Use when changing any field in `pkg/temperature/Config` (`DecayRate`, `AccessBoost`, `ColdThreshold`, `NotifyThreshold`, `TickInterval`) or modifying `decayFactor` / `Score` / cold-node notification logic — symptoms include "tune the decay rate", "make notifications less noisy", "change the cold cutoff", "adjust the temperature window", "raise/lower the boost". Prevents silent docs drift in `skills/remind/SKILL.md` (mental-model numerics) and `skills/memorize/references/lifecycle.md` (summarization workflow triggered by the notification).
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-bench-scenarioSkill
- add-fuzz-targetSkill
- add-integration-testSkill
- add-mcp-toolSkill
- add-parserSkill
- add-store-querySkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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
- Distinctive: line 15
If the numbers or the workflow drift from the code, agents will reason from stale defaults.
- Distinctive: line 29
Every tune touches four surfaces minimum.
- Very specific: line 39
If the change is structural (new knob, new threshold), also add a note to pkg/temperature/cold.go and re-read pkg/mcp/server.go:60-98 …
- Distinctive: line 82
Every hit is a candidate for an update.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Tune the temperature policy
remindb's temperature system has five knobs in pkg/temperature/config.go. They're tightly coupled — changing one shifts the behavior of search ranking, the cold-set query, and the client-facing notification stream. Tuning is rarely a one-file change.
The skill exists because two public skills document this policy for agents:
skills/remind/SKILL.md— owns the numerics in the mental model (decay rate, access boost, cold/notify thresholds, tick interval, ranking score formula, notification payload shape). These stay in the SKILL.md router, not a reference.skills/memorize/references/lifecycle.md— owns the summarization workflow the notification triggers (MemoryFetch→MemorySummarize). ThememorizeSKILL.md router only points at it.
If the numbers or the workflow drift from the code, agents will reason from stale defaults.
What the knobs do
| Knob | Default | Affects |
DecayRate | 0.05 | decayFactor = exp(-rate × elapsed_hours) — applied each tick to every node |
AccessBoost | 0.15 | Added to a node's temperature on read; capped at 1.0 by SQL min(1.0, …) |
ColdThreshold | 0.1 | Below this, nodes are "cold" — used by GetColdNodes and the search relevance floor (score = relevance × (0.3 + 0.7 × temperature) × recency) |
NotifyThreshold | 0.1 | Below this, the server pushes an MCP notification (level: "warning", logger: "remindb.temperature") — gated by per-node hysteresis dedup |
TickInterval | 5 * time.Minute | How often Tracker.Run decays + queries cold nodes |
Where the change ripples
Every tune touches four surfaces minimum.
| File | Why |
pkg/temperature/config.go | The knob itself (the DefaultConfig literal) |
pkg/temperature/*_test.go | Tests that assert specific numeric outcomes (tracker_test.go, cold_test.go, decay_test.go) — they'll fail if defaults shift |
pkg/mcp/server_test.go | If NotifyThreshold semantics change, the dedup/hysteresis tests need updating |
skills/remind/SKILL.md | Public-facing mental-model docs (numerics, ranking score, notification payload, threshold descriptions) — the easy one to forget |
skills/memorize/references/lifecycle.md | Public-facing summarization workflow triggered by the notification (MemoryFetch → MemorySummarize) — touch when the trigger or the recommended response shape changes |
If the change is structural (new knob, new threshold), also add a note to pkg/temperature/cold.go and re-read pkg/mcp/server.go:60-98 (NotifyColdNodes / selectNewNotifications) to confirm the hysteresis logic still makes sense.
Tuning rationales — what to tune for what symptom
| Symptom | Knob to consider | Direction |
| Cold notifications too noisy | NotifyThreshold | Lower (e.g., 0.05) — only the very coldest get pushed; widens the hysteresis band so re-notifications are rarer |
| Cold notifications too rare | NotifyThreshold | Raise toward ColdThreshold |
| Hot nodes lingering at the top of search | DecayRate | Raise (e.g., 0.1) — decay is faster, ranking turnover is quicker |
| Recent reads not boosting enough | AccessBoost | Raise (e.g., 0.25) — fewer reads needed to keep a node warm |
| Tick storms (decay bursts visible in logs) | TickInterval | Raise (e.g., 15 min) — fewer, larger decays per tick (factor stays the same since it's based on elapsed hours) |
| Cold-set query returning too much / too little | ColdThreshold | Adjust to match what GetColdNodes should return |
Note the asymmetry: ColdThreshold and NotifyThreshold can be different. Currently they're both 0.1 so the cold-set and the notify-set are the same; setting NotifyThreshold < ColdThreshold gives you a "cold but not yet alertable" zone.
The docs-sync step
The two public skills carry different surfaces of the policy. Walk both:
skills/remind/SKILL.md — mental-model numerics
- Frontmatter description — mentions "warning-level cold-node notifications"
- Mental model → Nodes — quotes
+0.15,exp(-0.05 × elapsed_hours),~5% per hour, the two thresholds, and0.1defaults - Mental model → Ranking —
score = relevance × (0.3 + 0.7 × temperature) × recency - Mental model → Notifications — quotes the message string, hysteresis behavior, payload shape
- Anti-patterns — the dedup-and-rearm note, the
ColdThresholdvsNotifyThresholddistinction
skills/memorize/references/lifecycle.md — workflow that follows the notification
- Summarize a cold node — the notification handoff — the
MemoryFetch→MemorySummarizeflow. Touch when the trigger semantics, the recommended summary shape, orMemorySummarize's preserved-fields contract changes. (memorize/SKILL.mdonly carries the one-line playbook row + the pointer.) - Maintenance cadence — the "on a
remindb.temperaturewarning → summarize" entry that frames when to reach for the workflow.
Walking the change
Every numeric or behavioral change requires a pass through both skills. If you change DecayRate from 0.05 to 0.1, every 0.05 and "5% per hour" must update in remind's SKILL.md. If you decouple ColdThreshold and NotifyThreshold, the threshold paragraphs in remind's SKILL.md need updating. If you change what MemorySummarize preserves, memorize's references/lifecycle.md summarize section needs updating.
The fast check (grep recursively — depth lives in references/):
grep -rnE '0\.05|0\.15|0\.1|5 min' skills/remind/
grep -rnE 'MemorySummarize|NotifyThreshold|ColdThreshold' skills/remind/ skills/memorize/Every hit is a candidate for an update.
Quick reference
1. pkg/temperature/config.go (the knob)
2. pkg/temperature/*_test.go (assertions on numerics)
3. pkg/mcp/server_test.go (only if NotifyThreshold semantics change)
4. skills/remind/SKILL.md (mental-model numerics + behavioral descriptions)
5. skills/memorize/references/lifecycle.md (only if the summarization workflow or MemorySummarize contract changes)
6. go test ./pkg/temperature/... ./pkg/mcp/... (must pass)Common mistakes
- Changing the default but not the test that asserts it.
tracker_test.go:103andcold_test.gocheck specific decay outcomes from the default config. If you bumpDecayRate, the expected post-tick temperatures must change too. - Expecting
NotifyThreshold > ColdThresholdto alert on warmer nodes. It doesn't. The cold set is gated upstream atColdThresholdinTracker.Tick;NotifyThresholdonly filters within that set vian.Temperature >= s.notifyThresholdinselectNewNotifications. SettingNotifyThresholdaboveColdThresholdjust disables the filter — every node already in the cold set passes through. To widen the alerting set, raiseColdThreshold. To narrow it, lowerNotifyThresholdbelowColdThreshold(creates a "cold but not alertable" hysteresis band). - Skipping the public-skill docs sync. Drift between the code and either
skills/remind/SKILL.md(numerics) orskills/memorize/references/lifecycle.md(summarization workflow) means a future Claude reasons from a stale baseline. Both skills are part of the deployed surface; treat drift as a bug. - Leaving
boostResultNodescalls in mutating MCP tools. Boost is for read tools (the read is the access). If you raiseAccessBoostand a write tool also boosts, mutations look like accesses and skew temperatures up. Auditpkg/mcp/tools/after raising the boost. - Bumping
TickIntervalwithout thinking about hysteresis. Notifications dedup per-node-per-cold-state. A longer tick means longer between dedup-eviction opportunities; a node oscillating aroundNotifyThresholdmay go quieter than expected.
Cross-references
.claude/rules/go-concise.md— error handling, named locals.claude/skills/add-mcp-tool/SKILL.md— for theboostResultNodesrule when adding new tools (so the boost contract stays clean)skills/remind/SKILL.md— read-side docs target (numerics, ranking score, notification payload, threshold descriptions)skills/memorize/references/lifecycle.md— write-side docs target (the cold-node summarization workflow andMemorySummarizecontract)pkg/temperature/decay.go— theScoreformula constants (coldFloor = 0.3,tempWeight = 0.7); these are not inConfigbut they shape ranking and may need to move there if you tune them
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.

