Mem Rfm

mem-rfm

mem-rfm is long-term memory for coding agents that ranks what it remembers by whether it actually *helped*. The whole thing is one SQLite file and a pure-Python scoring engine; an MCP server and three hooks make it drop-in for Claude Code.

The name comes from marketing's **RFM** analysis, which scores customers on recency, frequency and **m**onetary value. Marketers keep the third axis because the first two come free from any transaction log but measure only engagement: someone who orders constantly and returns everything looks like a good customer until you price the returns. Memories have exactly that blind spot, and mem-rfm answers it the same way.

Recency and frequency come from **ACT-R**, the cognitive model of human memory. Its base-level activation is `ln(Σ tᵢ^−d)`, a sum over every past use decaying with age, which makes the two one quantity rather than two knobs to tune. And in place of monetary value, mem-rfm puts **measured outcomes**: a signed per-memory record of whether acting on the memory helped or hurt, fed straight back into the ranking.

Retrieved-often is cheap to fake, and this project's live program caught helped-when-used being faked too: an agent copies a suggested command, the copy succeeds, and the ledger inflates. So a positive outcome now counts only in sessions where the condition the memory names actually fired. Helped-when-*needed* is the signal. **[The full model →](docs/theory.md)**

How it works

A memory is a row: some text, the condition it applies to, and the ledger it has earned.

content:         setuptools 82 no longer ships pkg_resources, so `import xarray`
                 fails in this venv. Workaround: add a pkg_resources shim to
                 PYTHONPATH.
condition_class: pkg_resources        <- the error that means this applies
value_score:     0.40  (4 outcomes)   <- earned, not assigned at write time

Retrieval multiplies similarity by that earned prior; every retrieval records an access, and