playbooks

home / skills / openclaw / skills / memory-tiers

memory-tiers skill

/skills/chrisrobison/memory-tiers

This skill manages memory tiers for AI agents, automatically tracking access and promoting or demoting context across hot, warm, and cold storage.

npx playbooks add skill openclaw/skills --skill memory-tiers

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
3.3 KB
---
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.

```bash
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.

```bash
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
- Tier 2 sections not accessed in 30 days → demote to Tier 3
- Tier 2/3 sections accessed in last 24h → promote to Tier 1

### Manual Promote/Demote
Move a specific section between tiers.

```bash
node scripts/promote.js --list                           # show all sections
node scripts/promote.js --section "LARC" --from 3 --to 1  # promote
node scripts/promote.js --section "TextWeb" --from 1 --to 2 # demote
```

### Health Report
Show current tier sizes, staleness, and recommendations.

```bash
node scripts/report.js                   # pretty-printed
node scripts/report.js --json            # machine-readable
```

## Heartbeat Integration

Add to your heartbeat routine (every few hours):

```markdown
## Memory Maintenance
1. Run `node <skill_dir>/scripts/track.js` to update access tracking
2. Run `node <skill_dir>/scripts/maintain.js --dry-run` to check for needed changes
3. If changes look good, run without --dry-run
4. Run `node <skill_dir>/scripts/report.js` to verify health
```

## State Files

- `state/access-log.json` — Per-file and per-section access timestamps and counts
- `state/maintenance-log.json` — History of maintenance actions taken

## Tier Rules

| Rule | Threshold | Action |
|------|-----------|--------|
| T1 stale | Not accessed 7 days | Demote to T2 |
| T2 stale | Not accessed 30 days | Demote to T3 |
| T2/T3 accessed | Accessed in last 24h | Promote to T1 |
| T1 over limit | >100 lines | Demote lowest-access sections |
| Daily log | Never modified after day ends | Source of truth |

## File Conventions

Tier files should have these headers:

```markdown
# MEMORY.md — Working Memory (Tier 1)
<!-- last_maintained: YYYY-MM-DD -->
<!-- tier: 1 — hot context -->
```

Sections use `##` or `###` headers. The maintenance scripts parse these to identify movable units.

The `## Index → Deeper Tiers` section in MEMORY.md should always be last — it provides pointers to content in lower tiers.

Overview

This skill implements tiered memory management for AI agents using an LRU-style cache across Hot, Warm, and Cold tiers. It automatically promotes frequently accessed sections and demotes stale content, keeping a small working memory loaded while archiving deep history. The system includes tracking, maintenance, and reporting scripts to automate lifecycle actions and health checks.

How this skill works

The skill scans session transcripts to log per-file and per-section accesses, storing data in an access log. Maintenance scripts evaluate access patterns and apply promotion/demotion rules: hot (Tier 1) stays small and always loaded; warm (Tier 2) is on-demand recent context; cold (Tier 3) is searchable archive. Daily immutable logs remain the source of truth and maintenance produces human-readable reports and machine JSON outputs.

When to use it

  • Keep a compact working context while preserving long-term history for agents that form long-running sessions.
  • Reduce prompt size and token costs by loading only Tier 1 into the context window.
  • Automate lifecycle of notes, facts, or memory snippets that change in relevance over time.
  • Support agents that need quick access to recent events but occasional deep-history search.
  • Maintain an auditable archive of raw daily logs while exposing curated snippets to the agent.

Best practices

  • Limit Tier 1 to ~100 lines and use clear section headers (## or ###) for atomic movable units.
  • Run tracking regularly (every few hours) and run maintenance with --dry-run first to preview changes.
  • Keep an immutable daily log file per date as the canonical record; never edit daily logs after the day ends.
  • Use the Index → Deeper Tiers section at the end of Tier 1 to point to archived content rather than duplicating it.
  • Tune demotion thresholds only after reviewing access logs and maintenance reports; avoid aggressive demotion that loses short-term context.

Example use cases

  • A conversational agent that keeps recent project facts in Tier 1 and archives older meeting notes to Tier 3 for occasional search.
  • Customer support assistant that promotes frequently referenced troubleshooting steps to hot memory and demotes infrequent ones to warm or cold.
  • Research assistant that keeps active literature summaries in Tier 1 while moving older paper notes to Tier 3 searchable archives.
  • Compliance logging: store immutable daily transcripts in raw files while surfacing important compliance items into the working memory for agent checks.

FAQ

How are promotion and demotion thresholds configured?

Default rules are 7 days for T1→T2 and 30 days for T2→T3; these can be adjusted when running maintenance scripts via command flags.

What if Tier 1 grows beyond the limit?

The maintenance routine demotes the lowest-access sections until Tier 1 fits the ~100-line target; run --dry-run to inspect proposed demotions first.

Are daily logs modifiable?

No. Daily logs are treated as immutable source-of-truth files and should not be edited after the day ends.