memory-tiers

name	memory-tiers
version	0.1.0
description	Tiered memory management for AI agents — LRU cache for context. Hot/warm/cold tiers with automatic promotion, demotion, and access tracking.

Memory Tiers

A tiered memory system for AI agents. Like CPU cache hierarchy, but for your context window.

Architecture

MEMORY.md (Tier 1 — Hot)          ← Always loaded, ~100 lines max
  ↕ promote (accessed) / demote (stale 7+ days)
memory/tier2-recent.md (Warm)     ← On-demand, last 30 days
  ↕ promote / demote (stale 30+ days)
memory/tier3-archive.md (Cold)    ← Search only, deep history
  ↕
memory/YYYY-MM-DD.md (Raw)        ← Immutable daily logs

Scripts

All scripts are in scripts/ relative to this SKILL.md.

Track Memory Access

Scans session transcripts for memory file reads/writes/searches. Run regularly.

node scripts/track.js                    # scan last 24h
node scripts/track.js --since 72         # scan last 72 hours

Output: Updates state/access-log.json with per-file and per-section access data.

Run Maintenance

Promotes/demotes sections between tiers based on access patterns.

node scripts/maintain.js --dry-run       # preview changes
node scripts/maintain.js                 # apply changes
node scripts/maintain.js --demote-days-t1 5   # custom T1 demotion threshold

Rules:

• Tier 1 sections not accessed in 7 days → demote to Tier 2