Agent Memory Architecture

Files (3)

• README.md
• SKILL.md
• _meta.json

SKILL.md (first lines)

# 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 working scratchpad. What's happening RIGHT NOW.

### Template

```markdown
# ACTIVE-CONTEXT.md — What's Hot

Last updated: 2026-01-15 14:30 GMT

## 🔥 Current Priority
[ONE sentence: what is the most important thing right now?]

## In Progress
- [ ] Task A — status, next step
- [ ] Task B — status, blocker

## Waiting On
- Waiting for [person] to [action] — asked [date]
- Waiting for [system] to [complete] — ETA [time]

## Key Decisions Made Today
- Decided to [X] because [Y] — reversible: yes/no

## Context for Next Session
[What does future-you need to know to pick up where you left off?]
```

### Rules
- **Max 50 lines** — if it's longer, you're hoarding. Move completed items to daily notes.
- **Update before ending session** — your gift to future-you
- **One priority** — if everything is priority, nothing is
- **Delete completed items** — this is NOT an archive

---

## 3. Layer 2: Long-Term Memory (MEMORY.md)

Your curated brain. Distilled knowledge, not raw logs.

### Structure Template

```markdown
# MEMORY.md — Long-Term Memory

## About [Human]
- Name, preferences, timezone, communication style
- What motivates them, what frustrates them
- Key relationships, roles, goals

## About Me [Agent]
- Name, personality, capabilities
- Operating preferences learned over time

## Active Projects
### Project Name
- Status, key decisions, blockers
- Links to relevant topic files

## Key People
- [Name] — role, relationship, communication notes

## Lessons Learned
- [Date] — [What happened] → [What I learned]

## Preferences & Patterns
- [Human prefers X over Y]
- [This approach works better than that one]

## Important Dates

From LeoYeAI/openclaw-master-skills, MIT.

More from LeoYeAI/openclaw-master-skills