Agent Memory Skill

Agent Memory Management

Memory system with automatic decay, tiered search, and creative recall. Works with any directory of markdown files.

Quick Start

1. Scan existing files

python3 memory-engine.py scan 

Reports: file count, YAML coverage, size, recommendations.

2. Bootstrap YAML frontmatter

python3 memory-engine.py init  [--dry-run]

Adds relevance, last_accessed, tier to files missing frontmatter. Infers type from directory path. Infers dates from YAML fields, git log, or file mtime.

3. Run decay

python3 memory-engine.py decay  [--dry-run]

Updates all cards: recalculates relevance scores and reassigns tiers. Schedule daily via cron for automatic forgetting.

4. Touch on read

python3 memory-engine.py touch 

Promotes card one tier up (graduated recall). Multiple reads = stronger memory.

5. Creative recall

python3 memory-engine.py creative  

Random sample from cold/archive tiers. Read these cards and look for unexpected connections.

6. Health check

python3 memory-engine.py stats 

Shows tier distribution, context budget, stale card count.

Core Concepts

Three-Layer Architecture

| Layer | What | Size Target | Loaded | |-------|------|-------------|--------| | Hot context | State file (volatile focus, blockers) |

Creates `.memory-config.json`:
```json
{
  "tiers": {"active": 7, "warm": 21, "cold": 60},
  "decay_rate": 0.015,
  "relevance_floor": 0.1,
  "skip_patterns": ["_index.md"],
  "type_inference": {"crm/": "crm", "leads/": "lead"},
  "use_git_dates": true
}

Adjust tier thresholds and decay rate to match your domain's natural rhythm. Fast-moving domains (sales): tighter thresholds (active=3, warm=10, cold=30). Slow domains (research): wider thresholds (active=14, warm=45, cold=120).

Anti-Patterns

| Don't | Do Instead | |-------|------------| | Load all contacts into state file | Keep them in vault cards, search on demand | | Create "knowledge graph" that duplicates vault | Vault IS the graph. Use index files for navigation | | Store same fact in 3 files | One card per entity, reference via links | | Delete old daily files to "save space" | Keep all dailies, let tier decay handle visibility | | Auto-load all daily files at session start | Load only today + yesterday; search older on demand | | Search all 500 cards for every question | Check index first, filter by tier, then search | | Touch every card during bulk operations | Only touch on meaningful read/update | | Build elaborate review systems | Let decay handle it — if you don't use it, it fades |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: smixs
• Source: smixs/agent-memory-skill
• License: MIT

Install and usage instructions live in the source repository linked above.