Active Memory Reminder

Loopkit splits shift-notes across two files on purpose:

• claude-progress.txt, free-form prose. Human-readable narrative of what the last session did, what is in flight, what to pick up next. Wins for context and intent. Loses when the model needs to decide whether a decision was made.
• claude-decisions.json, machine-readable array of {ts, decision} entries, appended by the loopkit pre-compact hook every time the transcript is about to be compacted. Wins for durability of specific choices ("chose Postgres over SQLite because…", "rejected the polling approach", "tried htmx and switched to Alpine").

Compaction is where reasoning dies. The summarizer keeps the shape of the work but strips the why. claude-decisions.json is the durable side-channel that survives that. This is the same pattern Meta's NapMem paper calls out for behavioral-state-decay in long-running agents: prose degrades faster than structured facts because the model rewrites prose freely and edits structured data carefully (also why loopkit uses JSON for feature_list.json; see [[feature-list-json]]).

When to apply

• Session start / post-/clear / post-compact. Read claude-decisions.json right after claude-progress.txt and before you look at code. If both files disagree, the JSON is the more recent hard record of a specific choice; the prose gives you the reason.
• Before re-litigating a design choice. If you're about to propose "let's use X instead of Y," grep claude-decisions.json first. If a prior session already rejected X and wrote it down, don't burn the token budget re-deriving that.
• When picking up mid-implementation work. Decisions frame constraints the progress file may not restate.

File contract

claude-decisions.json is a JSON array. Every entry is {ts, decision}: