Memory Lifecycle and Versioning

How memories are created, buffered, reinforced, archived, and versioned.

Memories in MemoryOS are living data. A signal can start as a weak candidate, become a stored memory, gain importance through use, be superseded by a newer claim, or be archived when it should no longer surface.

Lifecycle states

State	Meaning	Returned by normal retrieval?
Weak candidate	Borderline signal waiting for repeated evidence or feedback	No
Active memory	Durable memory available for retrieval	Yes
Hot memory	Frequently accessed memory cached for faster retrieval	Yes
Archived memory	Kept for audit/export, removed from normal search	No
Versioned memory	Memory with append-only history in memory_versions	Current version only

From conversation to memory

add() is asynchronous. After a request passes the quality gate, extraction can produce:

Result	Meaning
memories_created > 0	One or more durable memories were stored
pending_candidates_buffered > 0	Weak signals were buffered instead of stored
nothing_to_extract = true or zero created	No durable memory was found

Weak candidates protect the system from storing uncertain one-off statements as permanent memory.

Reinforcement

A weak candidate can later be promoted when MemoryOS sees stronger evidence, for example:

• the same signal appears again in a later conversation
• retrieval feedback confirms the signal was useful
• a user correction produces a stronger replacement memory

Promotion creates a normal active memory and preserves the lineage from the weak candidate.

Retrieval feedback

After retrieval, your agent can report whether returned memories were useful.

Feedback can:

• increment useful-memory signals
• mark a memory as ignored or not useful
• queue an async correction job when the user corrects the agent
• help operators see extraction quality problems in the dashboard

See Extraction Quality Loop for working SDK examples.

Lifecycle manager

The lifecycle manager runs during off-peak hours and performs these jobs:

1. Decay - reduce importance_score for stale memories when appropriate. The original score stays in original_importance_score.
2. Auto-archive - soft-remove stale low-value memories from search without deleting them from PostgreSQL.
3. Hot promotion - move high-value, frequently used memories into Redis for faster retrieval.
4. Score recompute - recalculate baseline importance when needed.
5. Payload retention - redact old extraction payloads while preserving source hashes for audit.

Auto-archived memories are marked is_archived = true and system_archived = true. They stay in the database and appear in GDPR exports. Hard delete is a separate explicit action.

Version history

Every meaningful change creates an append-only row in memory_versions.

Change type	Trigger
created	First extraction
conflict_update	Superseded or changed by conflict resolution
manual_edit	User or operator edited the memory
importance_decay	Importance dropped meaningfully
importance_boost	Importance increased through access or feedback
archived	Archived or deleted from active search

Version rows are never updated or deleted.

GDPR export

The export endpoint returns active memories, archived memories, and version history. Normal retrieval returns only currently searchable memories.

Related pages

• Extraction Quality Loop
• Memory Provenance
• POST /v1/memories/retrieve