Memory Lifecycle

Remem memories have a lifecycle. They can expire, decay, be promoted, be archived, or be deleted. Five distinct background tasks — plus the connection-discovery worker — run on independent schedules inside the remem-server process (Tokio tasks, no separate worker process required).

TTL expiration

Short-term memories with a ttl (seconds) set expire automatically when the TTL elapses. The expire_short_term task identifies expired memories and either archives them or promotes them to long_term, depending on access count — see Promotion below. Default schedule: every 5 minutes (expire_short_term_secs = 300).

{
  "memory_type": "short_term",
  "ttl": 3600,
  "content": "..."
}

Importance decay

Long-term memories lose about 0.5% of their importance per day, applied by the apply_importance_decay task (default schedule: daily, apply_importance_decay_secs = 86400). This prevents stale memories from polluting search results — a memory created long ago and never reinforced will decay toward zero importance and rank lower in search.

Flashbulb memories (see below) are exempt from importance decay for as long as their flashbulb protection is active.

Active forgetting (health)

Every memory has a health score (0–100, default 100 at creation). The active_forgetting task (default schedule: daily, active_forgetting_secs = 86400) decays health based on time since the memory was last recalled:

• Short-term memories: −8/day
• Long-term memories: −2/day

A memory is hard-deleted once its health reaches 0. Fetching a memory — GET /api/v1/memories/{id} or the MCP get_memory tool — boosts its health by +10, capped at 100. Frequently-recalled memories therefore effectively never decay away, while memories nobody looks at eventually get cleaned up automatically.

Flashbulb memories are exempt from active forgetting for as long as their flashbulb protection is active.

Emotional memory & flashbulb protection

store_memory accepts two optional fields that drive real lifecycle behavior:

• emotional_valence (float, -1.0 to 1.0)
• arousal (float, 0.0 to 1.0)

A memory created with arousal >= 0.8 becomes a flashbulb memory:

• It is force-promoted to long_term immediately.
• Its importance is floored at 0.9.
• It is exempt from importance decay and active forgetting for 30 days, tracked via a flashbulb_until timestamp on the memory.

This promotion only happens at creation time. Raising arousal past 0.8 later via update_memory does not retroactively apply flashbulb protection to an existing memory.

Promotion

Promotion moves a memory from short_term to long_term. There are three ways this happens:

1. Manual — call the promote_to_longterm MCP tool, or POST /api/v1/memories/{id}/promote. This works on any short-term memory at any time.
2. Automatic, at creation only, for flashbulb memories — a memory created with arousal >= 0.8 is force-promoted to long_term immediately, as described above.
3. Automatic, at TTL expiration, based on access count — when a short-term memory’s ttl elapses, the expire_short_term task checks its access_count: at or above the threshold (3), it’s promoted to long_term instead of archived. Below the threshold, it’s archived as usual. This only fires at the moment of expiration, not continuously.

curl -X POST "http://localhost:4545/api/v1/memories/{id}/promote" \
  -H "Authorization: Bearer your-key"

Archiving (soft delete)

Archiving removes a memory from search/list/stats results while retaining it in storage:

curl -X DELETE "http://localhost:4545/api/v1/memories/{id}?hard=false" \
  -H "Authorization: Bearer your-key"

hard=false is the default, so DELETE /api/v1/memories/{id} with no query string also soft-archives. The response is 200 with {"success": true, "message": "memory deleted"}.

Business — Coming soon

Restoring archived memories through a web-based admin UI is a Business Edition feature (the Backoffice). In Community Edition, restore an archived memory by updating it directly through the REST API or MCP update_memory tool.

Hard delete

Hard delete removes the memory from all indexes and storage permanently:

curl -X DELETE "http://localhost:4545/api/v1/memories/{id}?hard=true" \
  -H "Authorization: Bearer your-key"

Background task schedule

There is no single unified lifecycle interval — each task runs on its own schedule, configured under [tasks] in remem-server.toml:

Task	Default interval	Config key
expire_short_term	5 minutes	expire_short_term_secs = 300
apply_importance_decay	daily	apply_importance_decay_secs = 86400
active_forgetting	daily	active_forgetting_secs = 86400
consolidate_similar	weekly	consolidate_similar_secs = 604800
cleanup_archived	monthly	cleanup_archived_secs = 2592000
discover_connections	hourly	discover_connections_secs = 3600

All tasks run as Tokio tasks inside the remem-server process — no external scheduler or separate worker process is required. Each task can be inspected and controlled via the REST API:

curl http://localhost:4545/api/v1/tasks -H "Authorization: Bearer your-key"
curl -X POST http://localhost:4545/api/v1/tasks/apply_importance_decay/run \
  -H "Authorization: Bearer your-key"

GET /api/v1/tasks returns the status of all registered tasks plus discovery-queue metrics. POST /api/v1/tasks/{name}/run triggers a task immediately (202 Accepted, runs in background; 409 if already running). GET /api/v1/tasks/{name}/history returns its recent run log, and POST /api/v1/tasks/{name}/pause / .../resume pause or resume its scheduled runs.