radimsem / tune-temperature-policy

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). The memorize SKILL.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

Where the change ripples

Every tune touches four surfaces minimum.

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

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, and 0.1 defaults
• 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 ColdThreshold vs NotifyThreshold distinction

skills/memorize/references/lifecycle.md — workflow that follows the notification

• Summarize a cold node — the notification handoff — the MemoryFetch → MemorySummarize flow. Touch when the trigger semantics, the recommended summary shape, or MemorySummarize's preserved-fields contract changes. (memorize/SKILL.md only carries the one-line playbook row + the pointer.)
• Maintenance cadence — the "on a remindb.temperature warning → 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:103 and cold_test.go check specific decay outcomes from the default config. If you bump DecayRate, the expected post-tick temperatures must change too.
• Expecting NotifyThreshold > ColdThreshold to alert on warmer nodes. It doesn't. The cold set is gated upstream at ColdThreshold in Tracker.Tick; NotifyThreshold only filters within that set via n.Temperature >= s.notifyThreshold in selectNewNotifications. Setting NotifyThreshold above ColdThreshold just disables the filter — every node already in the cold set passes through. To widen the alerting set, raise ColdThreshold. To narrow it, lower NotifyThreshold below ColdThreshold (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) or skills/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 boostResultNodes calls in mutating MCP tools. Boost is for read tools (the read is the access). If you raise AccessBoost and a write tool also boosts, mutations look like accesses and skew temperatures up. Audit pkg/mcp/tools/ after raising the boost.
• Bumping TickInterval without thinking about hysteresis. Notifications dedup per-node-per-cold-state. A longer tick means longer between dedup-eviction opportunities; a node oscillating around NotifyThreshold may go quieter than expected.

Cross-references

• .claude/rules/go-concise.md — error handling, named locals
• .claude/skills/add-mcp-tool/SKILL.md — for the boostResultNodes rule 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 and MemorySummarize contract)
• pkg/temperature/decay.go — the Score formula constants (coldFloor = 0.3, tempWeight = 0.7); these are not in Config but they shape ranking and may need to move there if you tune them