Retention and decay

The workers live in brain-workers and run inside each shard — not as a separate process against a shared database. They use the same single-writer path the write pipeline uses; there is no privileged shadow connection. Maintenance workers default on; destructive GC workers default off.

Salience decay

Every memory carries a salience in [0, 1] — a measure of importance that acts as the ranking tiebreaker when two memories match a cue equally well by similarity. Initial salience is stamped at encode time from an agent hint, a surprise score, the memory kind, and a baseline. From there it evolves:

salience(M) = clip( S₀(M) + access_boost(M) − decay(M),  0, 1 )

The decay worker lowers salience over time; accessing a memory boosts it. The net effect is that frequently-recalled memories stay prominent while never-touched ones fade — without ever being deleted. A recall can filter on salience (min_salience / confidence_min) so an agent that only wants strong, important matches can raise the floor. Decay changes ranking prominence, not existence: a decayed memory is still stored and still retrievable if you ask for it directly.

Consolidation

The consolidation worker reconciles near-duplicates that content dedup didn't catch — paraphrases, the same fact restated across sessions. Byte-identical text is collapsed synchronously at write time by the BLAKE3 fingerprint policy (Write pipeline); semantic near-duplicates are folded together afterward, so the graph doesn't accumulate a dozen rephrasings of one fact. Consolidated memories are their own kind and start slightly above episodic salience — they represent learned patterns.

Tombstone reclamation

Deletion goes through forget, which tombstones rather than erasing (see Supersession and provenance). A tombstoned memory is invisible to reads immediately, but the slot isn't freed right away:

soft forget → tombstoned (invisible to reads)
              ↓ grace period (default 7 days)
           reclaimed (slot version incremented, MemoryId retired)

A reclamation worker wakes periodically, finds memories whose forgot_at + grace has passed, and reclaims their slots in batches — so actual reclamation may trail the grace expiry by a few minutes, which is harmless because the memory is already invisible during grace. Hard forget zeroes the vector and text at tombstone time; the same grace clock then governs when the slot is reused. Reclamation is the only path other than hard forget that physically frees storage.

Other maintenance workers

Alongside decay, consolidation, and reclamation, each shard runs a standing set of correctness workers — HNSW maintenance, tantivy indexing, the supersession sweep, the idempotency-table sweep, WAL retention, snapshotting, and (for the typed graph) entity resolution and entity GC. These are load-bearing, not optional: they're what keep the indexes within seconds of the writes and the graph consistent with the memories. See Architecture.

When to tune

The defaults suit general agent use. Reach for the knobs when:

• Long-lived facts — your domain has facts that shouldn't fade (legal entity names, geographic constants). Lengthen the decay half-life or raise their salience so they stay prominent.
• Short-lived events — your events lose value within days. Shorten the grace window and let reclamation take over sooner.
• Compliance-driven retention — regulations cap how long you may hold user data. Use hard forget for erasure and keep the grace window short; the forget event itself is retained in the audit trail even after the bytes are gone.

Resist per-row decay overrides. The workers perform well precisely because they do bulk passes; per-row parameters would force per-row recomputation on every tick.

Manual forget

When you need to delete on demand — a user asks for erasure, a memory was written wrong, a tenant is offboarded — call forget. Soft forget honours the grace window (restorable until reclamation); hard forget zeroes the bytes immediately inside the write transaction. Both are recorded in the WAL audit trail. See SDK: forget.