Agent Memory Architect

Persistent, self-organizing memory for AI agents. Learn from corrections, remember preferences, share knowledge across agents, and get smarter over time.

Quick Start

Automated Setup

Run the bootstrap script to initialize everything:

python \x3Cskill-dir>/scripts/bootstrap.py

This creates the full directory structure, hot.md, corrections.log, and index.md — ready to go.

Manual Setup

If you prefer manual setup:

mkdir -p ~/agent-memory/{projects,domains,agents,archive}

Then create ~/agent-memory/hot.md:

# HOT Memory — Always Loaded

## Preferences
\x3C!-- User-confirmed rules. Never decay. -->

## Patterns
\x3C!-- Observed 3+ times. Decay after 30 days unused. -->

## Recent
\x3C!-- New corrections. Promote after 3x confirmation. -->

Create ~/agent-memory/corrections.log:

# Corrections Log (last 50)

\x3C!-- Format:
[DATE] WHAT → WHY
  Type: preference|technical|workflow|communication
  Count: N/3
  Status: pending|confirmed|archived
-->

Done. Memory is active. Everything below is automatic.

Architecture

Three-tier storage inspired by CPU cache hierarchies:

🔥 HOT  — hot.md (≤100 lines, always loaded)
    Confirmed preferences + high-frequency patterns. Never decays.

🌡️ WARM — projects/, domains/, agents/ (≤200 lines each, loaded on context)
    Per-project and per-domain knowledge. Decays after 90 days unused.

❄️ COLD — archive/ (unlimited, loaded on explicit query)
    Historical reference. Never auto-deleted.

See references/architecture.md for full design details including file formats, lifecycle rules, namespace inheritance, and compaction pipelines.

How It Works

Detection — What Triggers Learning

Ignore — What Does NOT Trigger Learning

• Silence (never infer from no response)
• One-time instructions ("do X now")
• Hypotheticals ("what if…")
• Third-party preferences ("John likes…")
• Context-specific ("in this file…")

Auto-Promotion / Demotion

Self-Reflection

After completing significant work, evaluate:

1. Did it meet expectations? — Compare outcome vs intent
2. What could be better? — Identify improvements
3. Is this a pattern? — If yes, log to corrections

Log format:

CONTEXT: [task type]
REFLECTION: [what I noticed]
LESSON: [what to do differently]

Applying Memory

When using a learned pattern, always cite the source:

Using bullet format (from hot.md:12, confirmed 2026-01)

Conflict Resolution

1. Most specific wins: project > domain > global
2. Most recent wins (same level)
3. If ambiguous → ask user

User Commands

Memory Stats

On "memory stats", report:

📊 Agent Memory

🔥 HOT: hot.md — X entries (≤100 line limit)
🌡️ WARM: projects/ (N files), domains/ (N files)
❄️ COLD: archive/ (N files)

Recent 7 days: X corrections, Y promotions, Z demotions

Multi-Agent Setup

For teams with multiple agents, see references/multi-agent.md. Each agent gets its own HOT memory while sharing WARM knowledge:

~/agent-memory/
├── hot.md              # Main agent HOT (always loaded)
├── agents/
│   ├── coder.md        # Coder agent HOT
│   ├── writer.md       # Writer agent HOT
│   └── daily.md        # Daily agent HOT
├── domains/            # Shared domain knowledge
├── projects/           # Per-project patterns
└── archive/            # Decayed patterns

Security

See references/security.md for complete boundaries.

Never store: passwords, API keys, financial data, health info, biometrics. Store with caution: work context (decay after project ends), schedules (general patterns only).

Compaction

When hot.md exceeds 100 lines:

1. Merge similar corrections into single rules
2. Archive unused patterns
3. Summarize verbose entries
4. Never lose confirmed preferences

Troubleshooting

Scope

This skill ONLY:

• Learns from explicit user corrections and self-reflection
• Stores preferences in local files (~/agent-memory/)
• Reads its own memory files

This skill NEVER:

• Accesses external services
• Infers preferences from silence
• Stores sensitive data
• Modifies its own SKILL.md