docs: open spec for memory dynamics (decay, delta-writes, decision hi…

[navbytes]

…story)

Kimi K3-inspired spec covering four additive features: half_life/reviewed relevance decay, if_exists write steering on nt_note, a ## Decisions convention with nt decide + nt history over the git layer, and a recall escalation hint. All opt-in, byte-identical for untouched stores; builds on valid-windows, distill, tiers, and the note undo journal rather than duplicating them.

Claude-Session: https://claude.ai/code/session_01Ku62tzyPQMMbwQwywahtX1

[navbytes]

What this spec improves, in plain terms

Right now nt is a great filing cabinet: notes go in, they stay forever, and they all look equally trustworthy no matter how old they are. This spec adds four small behaviors that make it act less like a filing cabinet and more like a good memory.

1. Notes can age. A note can carry a shelf life (half_life: 90d). As it gets older without anyone re-confirming it, it slowly sinks in recall results — never hidden, just ranked lower and marked ~faded. A two-year-old gotcha about an old tool version stops outranking fresh, correct info. A quick nt touch says "still true" and resets the clock.

2. Agents stop creating duplicates. Today, when an AI learns something new about a topic, it tends to create a second note next to the first — and later searches surface both, including the wrong one. if_exists: "return" on nt_note lets the create call say "this note already exists — edit that one instead." One topic, one note, kept current.

3. Notes remember why they changed. Editing in place is good, but it erases the story. Each note gets a small ## Decisions list — one dated line per change ("switched X → Y because Z"). An agent reading the note sees not just the current answer but what was already tried and rejected, so it doesn't re-propose the old wrong idea. Full per-edit detail stays in git, readable on demand via nt history.

4. Search admits when it's unsure. When recall comes back with weak matches, the response says so and tells the agent exactly what to try next (full-text search including archived notes) instead of the agent trusting a bad answer or giving up.

Net effect: the store stays smaller and fresher, agents find the right note more often, trust it the right amount, and repeat past mistakes less. All of it is opt-in — a store that ignores these features behaves byte-identically to today.

(Design inspired by the two mechanisms behind Kimi K3's ~2.5× scaling-efficiency gain — delta-rule memory with learned decay, and attention residuals across depth — translated into plain-text policies. Full mapping in the spec.)