Skip to content

memory-lifecycle.md

Latest commit

 

History

History
110 lines (76 loc) · 3.86 KB

memory-lifecycle.md

File metadata and controls

110 lines (76 loc) · 3.86 KB
Raw
title Memory Lifecycle

Memory Lifecycle

Uteke uses a soft-delete lifecycle model for memory management. No automated process hard-deletes a memory. Memories transition through a reviewable soft-delete state before eventual pruning.

How It Works

remember() → ACTIVE → soft_deprecate() → DEPRECATED (hidden, restorable) → prune() → HARD DELETE
State Visible in recall? Restorable? TTL
ACTIVE ✅ Yes N/A —
DEPRECATED ❌ Hidden from recall/search ✅ promote() 30 days (configurable)
PRUNED ❌ Gone ❌ No —

What triggers deprecation?

  1. Auto-lifecycle cycle (server background thread, every 7 days by default)
  2. Manual uteke lifecycle cycle command
  3. Explicit delete() / forget(): redirected to soft-delete when soft_delete_only = true (default)
  4. Dream consolidation: duplicate memories are deprecated, not deleted

What triggers hard delete (prune)?

Only two controlled paths can hard-delete:

  1. prune(): Expired deprecated memories (past deprecated_ttl_days). Runs automatically during lifecycle cycle when auto_prune_enabled = true.
  2. forget(): Only when soft_delete_only = false (not the default).

Configuration

See Configuration → Memory Lifecycle for the full config reference.

Default settings: 1% max deprecation per cycle, 90-day minimum age, 30-day TTL:

[lifecycle]
soft_delete_only = true
auto_aging_enabled = true
auto_aging_interval_hours = 168
min_age_days = 90
max_access_count = 3
max_deprecate_percent = 1.0
deprecated_ttl_days = 30
auto_prune_enabled = true
dream_dedup_soft_delete = true

CLI Usage

# Check lifecycle status
uteke lifecycle status

# Run a lifecycle cycle manually
uteke lifecycle cycle

# Restore a deprecated memory
uteke lifecycle promote <memory-id>

See CLI Reference → lifecycle for details.

HTTP API

Method Endpoint Description
GET /lifecycle/status Active vs deprecated counts
GET /lifecycle/deprecated List deprecated memories with TTL metadata (#1007)
POST /lifecycle/cycle Run lifecycle cycle
POST /lifecycle/promote Promote deprecated → active

See HTTP API Reference → Lifecycle for request/response schemas.

Best Practices

Production deployments

  • Keep soft_delete_only = true (default). This is your safety net: no data loss from bugs, misconfigured agents, or accidental deletes.
  • Tune max_deprecate_percent based on your memory volume. For large stores (10K+ memories), 1% per cycle is 100 memories/week. Adjust if that feels too aggressive or too conservative.
  • Monitor deprecated count via /lifecycle/status or uteke lifecycle status. A growing deprecated count without corresponding pruning may indicate a TTL misconfiguration.

Development / testing

  • Set deprecated_ttl_days = 1 for faster iteration during development.
  • Set soft_delete_only = false only in disposable test databases where you want true hard-delete semantics.

Disabling auto-lifecycle entirely

[lifecycle]
auto_aging_enabled = false

Memories will still be soft-deleted on explicit delete()/forget(), but no automatic aging or pruning will occur. You can still run uteke lifecycle cycle manually.

Migration from pre-v0.13.0

Existing databases are automatically migrated:

  • A deprecate_reason column is added to the memories table (nullable, uses column_exists() migration pattern, no schema version bump).
  • All existing memories remain ACTIVE, no behavior change on upgrade.
  • The auto-lifecycle background thread starts with default settings on first server boot.

No manual migration steps required.