Memory decay and lifecycle

A memory system that only accumulates gets worse over time. Sigil forgets in four distinct ways, and only one of them ever deletes anything.

1 · Lifecycle stages

Every fact is in one of three stages.

Stage	Meaning	Ranked against?
fresh	Just captured. Not yet trusted.	No
stable	The canonical pool.	Yes
editing	Recently retrieved; receptive to AUDM updates and contradictions.	Yes

fresh → stable

Requires one hour and either importance=vital or at least one access.

That gate is the quiet workhorse of the whole design. A low-importance fact that nobody ever touched stays fresh forever — never entering the canonical pool, never competing for a retrieval slot, effectively forgotten.

No LLM call decided that. No delete happened. The fact is still there if you go looking. It just never earned its way into ranking.

stable → editing

Happens inline, on a search hit. Retrieval marks a fact as recently-touched and opens a short window in which AUDM updates land more freely — because a fact you just used is the one most likely to be corrected next.

editing → stable

Closes after 30 minutes of no further access.

sigil status    # distribution across stages

2 · Per-kind TTL

Pod kinds declare their own decay.

Kind	TTL
claude_session	90 days
project	never
person	never
playbook	never
vital	never
directive	never

Session facts expire because session context is genuinely ephemeral — what you were debugging on a Tuesday in March shouldn’t rank against a query next year.

The escape hatch is built in: when a session ends, its summary attaches to both the session pod and the project pod. The session copy expires; the project copy is durable. Conclusions outlive the session that produced them.

3 · Activation decay

ACT-R base-level activation falls off as -0.5 × ln(t) in days. A fact you haven’t touched in six months has materially lower activation than one you used yesterday.

This never removes anything. It’s a ranking pressure — an old fact still wins if it’s clearly the better match, because activation is bounded to a (1 + 0.10 × activation) multiplier. See Ranking.

The floor sits at one full day. Below that the decay term would flip sign and become a bonus — and since retrieval itself bumps last_accessed_at, every returned fact would sit at the floor and the term would stop discriminating entirely.

4 · Hebbian edge half-life

Co-retrieval edges between entities decay with a 30-day half-life (hebbian.entity.halfLifeDays). Below minEffective (default 0.5) an edge is ignored in ranking.

An association you formed six months ago and never used again shouldn’t still be steering your results. The half-life is what makes the co-retrieval graph track how you think now rather than how you thought once.

What isn’t decay: supersession

When a fact contradicts an existing one, the old one is superseded — it stops being retrieved but is not removed, and the link to its replacement survives.

That’s correction, not forgetting. See Deduplication.

sigil maintain

The batch pass that runs the transitions which aren’t inline.

sigil maintain

• Promote eligible fresh facts to stable
• Close editing windows older than 30 minutes
• Consolidate graph edges

Nothing breaks without it — the inline transitions still happen, and search still works. What degrades is the cleanliness of the ranking pool: facts stay stuck in editing, promotions lag. Monthly is plenty.

Run it after a heavy ingest

A large ingest produces a lot of fresh facts at once. Running sigil maintain an hour later promotes the ones that qualify, so they enter ranking sooner.

Deliberate forgetting

sigil facts --limit=50
sigil forget 9fK2a1b0

The only operation that actually deletes a fact. Use it for things that are simply wrong.

For a fact that’s right but shouldn’t reach a particular agent or machine, scope it instead:

sigil visibility 9fK2a1b0 agent
sigil visibility 9fK2a1b0 device

For a whole context you’re done with:

sigil pod archive <uid>              # deactivate, keep the facts
sigil namespace delete <ns> --confirm # destructive

The design position

Sigil deliberately does not delete on a timer. Storage is cheap; a wrongly-deleted fact is not recoverable and a user has no way to know it happened.

So the strategy is: let unhelpful facts fail to be promoted, let activation push stale ones down, let TTL expire only genuinely ephemeral session context, and make explicit deletion an explicit command.

The one thing that is automatic and irreversible is claude_session TTL — and that’s why its summaries are copied to the project pod first.