mmag

Mixed Memory-Augmented Generation (MMAG) for AI agents. Five cognitive memory layers — conversational, long-term user, episodic, sensory, and short-term working — coordinated into a unified LLM contex

SKILL.md

GitHub

MMAG — Mixed Memory-Augmented Generation

Give your agent a real memory.

Most agents forget everything the moment a session ends. MMAG fixes that by organizing memory into five layers that mirror how human cognition works — so your agent can recall past conversations, adapt to user preferences, track upcoming events, and stay aware of its environment.


🧠 For the Agent: When and How to Use This Skill

Always call context.sh at the start of every session and inject the output as your system prompt. This is the primary integration point.

~/.openclaw/skills/mmag/context.sh

Trigger Rules — What to Store and When

Situation Action
User shares a preference, habit, or personal fact store.sh long-term "<fact>" --label <topic>
User mentions a future event, meeting, or deadline store.sh episodic "<event with date>"
User provides location, time, or environmental info store.sh sensory "<context>"
A notable exchange happens during the session store.sh conversational "<summary>"
You receive the current task or goal store.sh working "<goal>"
Session ends prune.sh — archives working memory into episodic
Context window is getting full snapshot.sh — compress all layers to disk

Decision Flow

Session start
  → run context.sh → inject output into system prompt
  → store.sh working "Current task: <goal>"

During session
  → on personal fact → store.sh long-term
  → on scheduled event → store.sh episodic
  → on location/time → store.sh sensory
  → on key exchange → store.sh conversational

Session end
  → run prune.sh

Weekly / before compression
  → run snapshot.sh

Priority Order (for conflict resolution)

When memory signals conflict, apply in this order:

  1. Long-term user traits — shape personalization and tone
  2. Episodic events — override defaults when time-sensitive
  3. Sensory context — adjust register and urgency
  4. Conversational history — maintain coherence across turns
  5. Working memory — governs the current task focus

📖 For Humans: Understanding the Five Layers

Layer What it stores Human analogy
💬 Conversational Dialogue threads and session history What was said 5 minutes ago
🧍 Long-Term User Preferences, traits, and background How a friend remembers you over years
📅 Episodic Timestamped events and reminders A personal diary or calendar
🌦️ Sensory Location, weather, time of day Situational awareness
🗒️ Working Current session scratchpad Mental notepad while solving a problem

🚀 Setup

Initialize (once)

~/.openclaw/skills/mmag/init.sh

Creates:

memory/
├── conversational/     # dialogue logs, one file per session
├── long-term/          # user profile and preference files
├── episodic/           # daily event logs  (YYYY-MM-DD.md)
├── sensory/            # environmental context snapshots
└── working/            # ephemeral session scratchpad
    └── snapshots/      # compressed backups

🛠️ Command Reference

Script Usage Output
init.sh init.sh Creates the 5-layer memory/ directory
store.sh store.sh <layer> "<text>" [--label <name>] Appends a timestamped entry
retrieve.sh retrieve.sh <layer|all> [query] Prints matching lines (auto-decrypts .md.enc)
context.sh context.sh [--max-chars N] Outputs a complete, prioritized system-prompt block
prune.sh prune.sh Archives working → episodic, clears scratchpad
snapshot.sh snapshot.sh Saves working/snapshots/<timestamp>.tar.gz
stats.sh stats.sh Prints per-layer file count, size, last entry
keygen.sh keygen.sh Generates a 256-bit key → ~/.openclaw/skills/mmag/.key
encrypt.sh encrypt.sh [--layer <layer>] [--file <path>] Encrypts .md → .md.enc, removes originals
decrypt.sh decrypt.sh [--layer <layer>] [--file <path>] [--stdout] Decrypts to disk or pipes to stdout

Valid layers: conversational · long-term · episodic · sensory · working


🔐 Privacy & Encryption

Long-term memory contains biographical data. MMAG ships with built-in AES-256-CBC encryption via openssl.

First-time setup — generate a key

~/.openclaw/skills/mmag/keygen.sh
# saves to ~/.openclaw/skills/mmag/.key  (chmod 600)

⚠️ Back up your key file. Without it, encrypted memories cannot be recovered.

Encrypt the long-term layer

~/.openclaw/skills/mmag/encrypt.sh --layer long-term

Encrypts all .md files → .md.enc and securely removes the originals.

Decrypt when needed

# Restore to disk
~/.openclaw/skills/mmag/decrypt.sh --layer long-term

# Or decrypt a single file
~/.openclaw/skills/mmag/decrypt.sh --file memory/long-term/preferences.md.enc

Transparent access

context.sh and retrieve.sh automatically decrypt .md.enc files in-memory — no plaintext is written to disk. Key is resolved in this order:

  1. MMAG_KEY environment variable
  2. ~/.openclaw/skills/mmag/.key file
  3. Interactive passphrase prompt
# Use env var (e.g. in automated contexts)
export MMAG_KEY=$(cat ~/.openclaw/skills/mmag/.key)
~/.openclaw/skills/mmag/context.sh

Other best practices

  • Audit with retrieve.sh long-term to review what's stored.
  • Erase on demand — delete any file in memory/long-term/ to remove specific traits.
  • Minimize — only store what genuinely improves interactions.

🔭 Extensibility

The store.sh / retrieve.sh / context.sh interface is intentionally generic. New layers require only a new directory and one added block in context.sh. Planned extensions:

  • Multimodal sensory — connect visual or audio signals
  • Dynamic profile embeddings — learned preference vectors instead of static files
  • Event-triggered retrieval — proactively surface episodic items before deadlines
  • Encrypted cloud backup — optional remote sync of the long-term layer

Based on the Mixed Memory-Augmented Generation (MMAG) research pattern. Paper: arxiv.org/abs/2512.01710