agent-memory

# Agent Memory — promotion is earned, not asserted > **Portability:** stdlib only. No database, no embeddings, no network, no LLM calls. ## The problem A project's `CLAUDE.md` is a memory system with one tier and no eviction: every durable fact and every passing preference land in the same always-loaded file, until the important lines are diluted by the incidental ones. Facts learned mid-session vanish at teardown unless someone writes them down. **The fix is not more storage — it is a promotion ladder.** A claim earns its way toward always-loaded context by recurring; a human confirms the last step. ## The four tiers Tiers are distinguished by **injection policy**, not storage format. | Tier | Holds | Injected | Committed | |---|---|---|---| | **L0** | raw session transcripts | never | no (already on disk) | | **L1** | candidate atoms | on relevance, at prompt time | no (gitignored) | | **L2** | this project's context | every session start | yes, after adopt | | **L3** | stable cross-project persona | always | yes, after adopt | ## The gates Nothing moves up because it sounded important. It moves up because it recurred. - **L0 → L1** — an explicit marker fires (a directive, a correction, a stated preference, a named lesson, a reproducible failure). Rule-based, high precision, deliberately low recall. - **L1 → L2** — ≥ 3 distinct sessions spanning ≥ 2 distinct calendar days. A claim stated outright needs 2 sessions; the distinct-day rule still applies. A ver...