Design input: separating computed quality_score from human rating

[filhocf]

Context. In our fork we've been mapping how quality_score flows through quality/. Today it's a single overloaded field: the AI scorer, implicit scorer, manual rating, and the decay association-boost all write to it, and ~10 consumers read it with no way to tell the origin. When a human rates a memory, the current 0.6*user + 0.4*existing blend mixes the human opinion and the machine guess into one number — each can dilute or erase the other.

Proposal (design only, not a PR yet). Keep two origin fields in metadata (additive, no schema change): computed_quality (machine, keeps its quality_provider/quality_components) and user_rating (human, already exists). Materialize the effective value into the existing quality_score on write, so the ~7 raw metadata.get('quality_score') consumers need zero changes. Composition: human rating wins when present, else computed, else 0.5. A single 👎 de-ranks in search but does not trigger forgetting; repeated 👎 (from rating_history) do.

Four questions where your input shapes the design (they touch retention/forgetting, which you own):

1. Rating→quality normalization. user_rating is −1/0/+1. Current (rating+1)/2 maps 👎 to exactly 0.0, which under "human wins" floors the memory. Prefer a floor above 0 for 👎, or a dedicated curve?
2. Negative-rating forgetting threshold. A single 👎 de-ranks but must not delete; how many accumulated 👎 (over what window) should feed forgetting.py?
3. Materialize vs read-time projection. We lean toward materializing effective quality into quality_score at write time because ~7 consumers read the raw field (two operate on plain dicts, no Memory object). Acceptable, or is there a reader you'd rather keep authoritative?
4. Sync codec. Making user_rating sync across hosts needs it as a new positional field in the CSV codec (metadata_codec.py), gated by a codec version bump. OK to coordinate a version for this?

@doobidoo, happy to turn this into a small PR once the four points are settled. Full design write-up available if useful.

🇧🇷 Tradução PT-BR (para referência)

Contexto. No nosso fork mapeamos como o quality_score flui pelo quality/. Hoje é um campo único sobrecarregado: o scorer de IA, o scorer implícito, o rating manual e o association-boost do decay escrevem todos nele, e ~10 consumidores leem sem saber a origem. Quando um humano avalia uma memória, o blend atual 0.6*user + 0.4*existing mistura a opinião humana e o palpite da máquina num só número — cada um pode diluir ou apagar o outro.

Proposta (só design, ainda não é PR). Manter dois campos de origem no metadata (aditivos, sem mudança de schema): computed_quality (máquina, mantém quality_provider/quality_components) e user_rating (humano, já existe). Materializar o valor efetivo no quality_score existente na escrita, para que os ~7 consumidores que leem o campo cru não mudem nada. Composição: rating humano vence quando presente, senão o computado, senão 0.5. Um único 👎 rebaixa na busca mas não dispara forgetting; vários 👎 (do rating_history) sim.

Quatro perguntas onde tua opinião molda o design (tocam retenção/forgetting, que é teu domínio):

1. Normalização rating→qualidade. user_rating é −1/0/+1. O (rating+1)/2 atual mapeia 👎 para exatamente 0.0, o que sob "humano vence" joga a memória no chão. Preferes um piso acima de 0 para 👎, ou uma curva dedicada?
2. Threshold de forgetting por rating negativo. Um 👎 rebaixa mas não deve apagar; quantos 👎 acumulados (em que janela) devem alimentar o forgetting.py?
3. Materializar vs projeção na leitura. Inclinamo-nos a materializar a qualidade efetiva no quality_score na escrita, porque ~7 consumidores leem o campo cru (dois operam em dicts puros, sem objeto Memory). Aceitável, ou há um leitor que preferes manter como autoritativo?
4. Codec de sync. Fazer o user_rating sincronizar entre hosts exige ele como novo campo posicional no codec CSV (metadata_codec.py), com bump de versão do codec. OK coordenar uma versão para isso?

[doobidoo]

Answering both this and #1290 here, since they are the same arc -- I will drop a pointer on that one.

The split is right, and the reason it matters is narrower than "two origins are cleaner": today the rating endpoint blends the human opinion into the same field that retention reads, and the retention path is not built to receive an opinion. web/api/quality.py:135 writes 0.6 * user_score + 0.4 * old_score into metadata['quality_score'], and Memory.quality_score (models/memory.py:238-240) is just a property over that key, so forgetting.py:165 reads the blended number directly. A single thumbs-down today lands at 0.4 * old, which for a default 0.5 memory is 0.2, which falls in the low band at forgetting.py:176: threshold_days = 30 + (0.2/0.5) * (90-30) = 54 days, and :187 makes it eligible for deletion at twice that. Under your "human wins" composition it would be 0.0, i.e. the 30-day floor and deletion at 60 days of no access. So the answer to question 1 depends entirely on question 2, and both depend on something you did not ask:

Retention should read computed_quality, not the effective value. That is the cleaner cut than any curve. Search ranking is where a human opinion belongs -- it is reversible, and a wrong down-vote costs one bad ranking. Forgetting is not reversible in the same way, and a down-vote is a statement about usefulness to one person at one moment, not about whether the content is worth keeping. Split the consumers and both of your first two questions get much less sharp.

With that in place:

1. Normalization. For the search-facing effective value, map -1/0/+1 to 0.25/0.5/0.9 rather than 0.0/0.5/1.0. A thumbs-down should de-rank hard without pinning to an absolute floor, and a single thumbs-up should not claim more certainty than the scorer's top band. If you keep a single field feeding both consumers, then a floor above 0 is mandatory, not a preference.
2. Negative-rating forgetting threshold. With retention on computed_quality, ratings do not feed forgetting.py at all in the first version. If you want a signal there later, the shape I would accept is: two or more thumbs-down from distinct raters, no thumbs-up, and no access in the medium retention window -- i.e. it demotes a memory from medium to low retention rather than deleting it. I would rather ship the split first and measure how ratings actually accumulate before wiring a deletion path to them.
3. Materialize vs read-time. Materialize, as you propose. Seven raw readers, two of them on plain dicts, is a strong argument, and Memory.quality_score is already a projection over metadata, so materializing keeps one definition of "effective" rather than two. Condition: computed_quality must never be lost when the effective value is written -- the re-scoring path has to be able to recompute the machine number without a human rating erasing its input.
4. Sync codec. I do not think you need the codec change, and I would rather you did not take it. compress_metadata_for_sync() only folds the fields in its quality_fields list into _q (quality/metadata_codec.py:298-310); user_rating is not among them, so it already crosses to Cloudflare as a plain metadata key today, and computed_quality would do the same. Adding either to the CSV buys a few bytes on an int and costs a coordinated version, which is the wrong trade -- especially because _q currently carries no version marker at all, so an appended positional field is not something an older reader can detect. If we ever do version that codec, it should be for a reason bigger than one rating field, and the first change should be the marker itself.

The real sync constraint is next door and it is worth designing around now: storage/hybrid.py:713-718 skips the Cloudflare metadata sync entirely for any memory whose metadata JSON exceeds 9.5KB, with a warning and no retry. rating_history is a growing list of dicts and is not compressed by the codec, so a heavily-rated memory can cross that line and then silently stop syncing its quality data. Cap it (last N entries, N small) in the same PR.

Scope for a first PR, if you want to take it: the two origin fields plus the effective-value write, forgetting.py reading computed_quality, the rating_history cap, and tests on real sqlite-vec storage via temp_db_path showing that a thumbs-down changes ranking and does not change the retention band -- red on main, green on the branch, both runs in the PR body. No codec change. Leave the multi-rater and deletion-signal questions out of it.

Question 2 stays open in the sense that I am not committing to a deletion rule for ratings at all yet -- that is deliberate.