Memory Retention Policies

Technical documentation for ekkOS memory retention: session, standard, and Forever Memory™

Overview

Each memory item in ekkOS has a retention_policy that determines how long it persists and whether it's subject to decay algorithms.

The retention policy controls:

How long the memory item persists
Whether decay algorithms apply
When the item can be pruned or archived

Retention Policies

Policy	Description	Decay
`session`	Ephemeral. Cleared automatically at the end of a session.	Immediate
`standard`	Long-lived but subject to decay if unused, low-quality, or irrelevant.	Gradual
`forever`	Never decayed, never pruned. Always preserved.	Never

What Uses Forever Memory™ Today

The following content types are automatically assigned retention_policy='forever':

Multimodal items -- Images, audio files, and other media uploads
Forged patterns -- Patterns created via the crystallize/forge mechanism
User preferences -- Settings and configuration that define how you work
Core semantic knowledge -- Important facts and insights explicitly marked as important
Any memory explicitly upgraded -- Items manually promoted to Forever Memory™

Decay Exception

Items with retention_policy='forever' skip the decay algorithm entirely.

The decay calculation explicitly checks for Forever Memory™:

if (retention_policy === 'forever') {
  return 1.0;  // never decays
}

This means Forever Memory™ items:

Never have their decay score calculated
Are excluded from retention maintenance jobs
Cannot be pruned or archived automatically

Layer-Specific Retention

Different memory layers use different retention policies by default:

Working Memory (Layer 1)

session

Ephemeral. Cleared after 24 hours or when session ends.

Episodic Memory (Layer 2)

standard

Long-term but subject to decay. Retained for 30+ days, then gradually fades if unused.

Pattern Memory (Layer 4)

forever

All patterns are Forever Memory™. They represent proven solutions you want to keep.

Multimodal Uploads

forever

Images, audio, and other media files are stored as Forever Memory™.

API Reference

When creating or updating memory items, you can specify the retention policy:

Create Memory with Retention Policy

POST /api/v1/memory
{
  "content": "Important insight",
  "title": "Something to remember",
  "retention_policy": "forever"  // or "standard" or "session"
}

Upgrade Memory to Forever

POST /api/v1/memory/:id/retention
{
  "retention_policy": "forever"
}

Create Forever Memory Directly

POST /api/v1/memory/forever
{
  "userId": "uuid",
  "content": "important insight or knowledge",
  "title": "Something I want to keep forever",
  "metadata": { "scope": "private" }
}

Best Practices

1. Use Forever Memory™ for Important Content

Files, patterns, and key insights should use Forever Memory™. These are items you never want to lose.

2. Standard Memory for General Knowledge

Use standard retention for general knowledge that can fade if unused. The decay algorithm will preserve what matters.

3. Session Memory for Temporary Context

Use session retention for temporary context that only matters during active work sessions.

Learn More

Explore Forever Memory™ features or read about the memory layers.

Forever Memory™ Feature Documentation Home