Agent Memory Architecture

# Agent Memory Architecture

Complete memory system for AI agents using only files. No APIs. No databases. No external dependencies. Just smart file structures and disciplined practices that give your agent perfect recall.

---

## 1. Memory Architecture Overview

```
workspace/
├── MEMORY.md              ← Long-term curated memory (the brain)
├── ACTIVE-CONTEXT.md      ← Hot working memory (what matters NOW)
├── AGENTS.md              ← Operating manual (how you work)
├── memory/
│   ├── 2026-01-15.md      ← Daily notes (raw event log)
│   ├── 2026-01-16.md
│   ├── heartbeat-state.json  ← Heartbeat tracking state
│   ├── topics/
│   │   ├── project-alpha.md  ← Topic-specific deep context
│   │   ├── client-acme.md
│   │   └── tech-stack.md
│   └── archive/
│       ├── 2025-Q4.md       ← Quarterly archive summaries
│       └── 2025-Q3.md
```

### The 5 Memory Layers

| Layer | File | Purpose | Read Frequency | Write Frequency |
|-------|------|---------|----------------|-----------------|
| **1. Hot** | ACTIVE-CONTEXT.md | Current priorities, blockers, in-flight work | Every session | Multiple times/day |
| **2. Warm** | MEMORY.md | Curated long-term knowledge, decisions, people | Every main session | Weekly curation |
| **3. Daily** | memory/YYYY-MM-DD.md | Raw event log, conversations, actions taken | Today + yesterday | Throughout the day |
| **4. Topic** | memory/topics/*.md | Deep context on specific subjects | When topic comes up | As knowledge grows |
| **5. Cold** | memory/archive/*.md | Historical summaries, rarely accessed | On explicit search | Quarterly rollup |

### Core Principle: Write It Down

**Memory is limited. Files are permanent.**

- "Mental notes" don't survive session restarts. Files do.
- If someone says "remember this" → write to a file
- If you learn a lesson → update the relevant file
- If you make a mistake → document it so future-you doesn't repeat it
- **Text > Brain** 📝

---

## 2. Layer 1: Hot Memory (ACTIVE-CONTEXT.md)

Your workin...

# Agent Memory Architecture 🧠

Complete zero-dependency memory system for AI agents. No APIs, no databases, no external tools — just smart file structures that give your agent perfect recall.

## What This Skill Does

- **5-Layer Memory Architecture** — hot, warm, daily, topic, and archive layers
- **Session Startup Protocol** — what to read and when, optimized for token cost
- **Write-Ahead Protocol** — never lose critical info mid-session
- **Memory Hygiene Schedule** — daily, weekly, monthly, quarterly maintenance
- **Context Window Management** — progressive loading, overflow handling, handoff protocol
- **Heartbeat Integration** — automated memory maintenance during agent wake-ups
- **Security Rules** — what to store, what never to store, privacy in shared contexts
- **Migration Guides** — from no system, from MEMORY.md-only, from external tools

## Install

```bash
clawhub install afrexai-agent-memory-system
```

## Quick Start

```
/memory-status   → Check your memory system health
/memory-review   → Run weekly review and curation
/remember [fact] → Instantly save something important
/handoff         → Prepare for clean session transition
```

## Why Zero Dependencies?

Every other memory skill requires APIs, databases, or cloud services. This one works with plain markdown files. Benefits:

- **$0 cost** — no API calls, no subscriptions
- **Works offline** — no internet required
- **No vendor lock-in** — your files, your control
- **Any framework** — OpenClaw, Cursor, Claude Code, anything
- **Instant setup** — create a few .md files and go

## ⚡ Level Up

Want production-ready agent architectures? Our **$47 Context Packs** include complete agent configurations for your industry:

👉 [Browse Context Packs](https://afrexai-cto.github.io/context-packs/)

## 🔗 More Free Skills by AfrexAI

- [afrexai-agent-engineering](https://clawhub.com/skills/afrexai-agent-engineering) — Complete agent design system
- [afrexai-productivity-system](https://clawhub.com/skills...