Retention policies

Every rule is the AND of four age/activity conditions, all optional, plus the same eight dimension filters the Lore Explorer's filter bar offers:

max_read_count counts a DIFFERENT direction from max_seen_count: the first counts how many times a lesson was read back, the second how many times it was written. A lesson written once and read fifty times matches max_seen_count: 1 but not max_read_count: 1. Neither is called "seen" in the dashboard for that reason — the Explorer labels them "Recurrence" and "Consumption", the same two words the lesson detail sheet uses.

One caveat on max_read_count: reads have only been counted since the read_count column shipped, so a long-lived lesson can show a low count it never earned. Pair it with min_age_days only once your store has been counting for a while.

unseen_days is deliberately the NARROWEST of the three "has this been touched" signals a lesson carries, and the Lore Explorer's detail sheet shows all three side by side so they're never confused for one another: "Recurrence" (seen_count — how many times the lesson has been written, unrelated to reading), "Consumption" (read_count / last_read_at — how many times it has been read back, by ANY surface: a bulk memory.list/.search result page, GET /memories/:id, or a human opening the dashboard's own detail sheet all bump it), and "Last agent open" (last_opened_at). unseen_days reads only the last of those — it only moves when an agent deliberately retrieves this ONE lesson over MCP (memory.read) or the CLI (lorekit read/show), never from riding along in a list page or from a person browsing the dashboard. That is what keeps "unseen for 90 days" honest: reloading the Explorer, or a memory.list call that happens to include the lesson, does not reset the clock.

A lesson no agent has ever opened has no last_opened_at to measure from, so the clock starts at its creation date. A lesson written a week ago therefore does not match unseen_days: 90 — it has not yet had 90 days in which to go unread. This matters most right after last_opened_at was introduced, when every pre-existing lesson has no recorded open: without the fallback, unseen_days would match the entire store regardless of threshold.

Preview what a rule would catch before saving it as a policy, with the CLI:

lorekit groom --scope repo::acme/app --unseen-days 90

or the REST API:

curl -X POST https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/memories/groom/preview \
  -H "Authorization: Bearer $LOREKIT_TOKEN" -H "Content-Type: application/json" \
  -d '{"scope": "repo::acme/app", "unseen_days": 90}'

Both answer { "count": <n>, "keys": [{ "scope", "key" }] } — the exact set a run would archive, because a saved run and a preview resolve through the IDENTICAL candidate query. Nothing is changed by a preview.

The Lore Explorer previews the same conditions a different way: its "Age & activity" filter (min_age_days / unseen_days / max_seen_count / max_read_count) combines with its own filter bar (the same eight dimension filters above) to narrow the list to the actual lesson ROWS a policy with those conditions would catch, not just a count — so you can scroll through them before saving anything. Once at least one condition or filter is set, a Create retention policy action hands the current scope, conditions AND filter bar to Settings → Retention Policies, which opens the New policy dialog pre-filled with all of it, using the identical filter control to edit it further.

lorekit policy create --scope repo::acme/app --name "stale repo lore" \
  --unseen-days 90 --mode review

Each condition has its own flag — --min-age-days, --unseen-days, --max-seen-count, --max-read-count — and lorekit policy update pairs each with a --clear-* form for removing one from a saved policy:

# never actually read back, and old
lorekit policy create --scope repo::acme/app --name "unused lore" \
  --min-age-days 90 --max-read-count 0 --mode review

lorekit policy update <id> --clear-max-read-count

mode: review is the default — the policy is saved and shows up in the dashboard's Retention Policies settings for you to run by hand whenever you like (lorekit groom --policy-id <id> --run). mode: auto gets swept nightly, but only once you also pass --enabled — a saved auto policy always starts disabled, so creating one never archives anything unattended by itself:

lorekit policy create --scope repo::acme/app --name "stale repo lore" \
  --unseen-days 90 --mode auto --enabled

lorekit policy list / update <id> / delete <id> round out the set. Deleting a policy deletes the RULE only — it never touches the lessons it matched.

The eight dimension filters (tags, source_agent, trigger, kind, host, origin_repo, origin_branch, origin_pr and their *_mode pairs) are reachable today through the dashboard, POST /policies/PATCH /policies/:id, and the MCP policy.create/policy.update/groom.preview/groom.run tools — lorekit policy/lorekit groom have no CLI flags for them yet.

Some lessons should never be swept, no matter what rule matches them — a load-bearing convention, a hard-won gotcha you want permanent. Mark it protected and every policy (and every manual groom --run) skips it:

lorekit pin repo::acme/app::the-load-bearing-lesson
# …later, if it's no longer special:
lorekit unpin repo::acme/app::the-load-bearing-lesson

lorekit protect <scope::key> [--off] is the longer spelling of the same call. Protection is per-lesson and persists until you explicitly clear it — it survives every policy change, and a disabled policy or one in review mode obviously can't reach it either.

lorekit groom --policy-id <id> --run

prompts for confirmation (or pass --yes non-interactively) and then archives every match — recoverable via lorekit restore or memory.restore, exactly like any other archive. An auto + enabled policy runs on its own every night; nothing else needs to happen for it to take effect once you flip --enabled on.