---
name: tune-temperature-policy
description: 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).
---

# 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

| 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, 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