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 <skill-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
<!-- User-confirmed rules. Never decay. -->

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

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

Create ~/agent-memory/corrections.log:

# Corrections Log (last 50)

<!-- 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

Signal	Confidence	Action
"No, do X instead"	High	Log correction
"I told you before"	High	Bump priority, flag repeated
"Always/Never do X"	Confirmed	Promote to preference
Same correction 3x	Auto	Ask to confirm as rule
"For this project…"	Scoped	Write to projects/{name}.md

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

Rule	Trigger
Promote to HOT	Pattern applied 3x in 7 days
Demote to WARM	Unused 30 days
Archive to COLD	Unused 90 days
Delete	Never (unless user says "forget X")

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

Say this	Agent does
"What do you know about X?"	Search all tiers, report findings
"Show my patterns"	Display hot.md contents
"Memory stats"	Show tier sizes, health, recent activity
"Forget X"	Remove from all tiers (confirm first)
"Export memory"	ZIP all memory files
"记住这个" / "Remember this"	Log to corrections or promote to preference

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

Problem	Cause	Solution
Memory not loading	Directory doesn't exist	Run bootstrap script or mkdir -p ~/agent-memory
hot.md too large	Over 100 lines, slow loading	Run compaction: merge similar entries, archive unused
Corrections not promoting	Haven't hit 3x threshold	Repeat correction or say "Always do X" to force
Agent forgot a preference	Entry decayed to COLD	Retrieve from archive/ and re-add to hot.md
Multi-agent conflicts	Two agents learned opposite rules	Check agents/*.md for conflicts, set explicit override
"Memory stats" shows 0	Fresh install, no corrections yet	Normal — memory builds over time from interactions
Permission denied on ~/agent-memory	OS file permissions	chmod -R 755 ~/agent-memory (Linux/Mac)

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