> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoryo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Lifecycle and Versioning

> How memories decay, archive, promote to hot cache, and keep version history.

Memories in MemoryOS are living data. They can become more relevant through usage, less relevant through inactivity, get superseded by newer facts, or be soft-archived when they're no longer worth surfacing.

## States

| State           | Meaning                                                 |
| --------------- | ------------------------------------------------------- |
| Active          | Searchable, appears in retrieval                        |
| Hot             | Frequently accessed, cached in Redis for fast retrieval |
| Archived        | Kept in PostgreSQL, removed from normal search          |
| System archived | Auto-archived by the lifecycle manager                  |
| Versioned       | Change history recorded in `memory_versions`            |

## Lifecycle manager

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

1. **Decay** — reduce `importance_score` for memories not accessed recently. The original extraction 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.

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          |
| `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 full version history. Normal retrieval returns only currently searchable memories.

## Related pages

* [MemoryEngine](/concepts/memory-engine)
* [POST /v1/memories/retrieve](/api-reference/retrieve)