explainx / blog
Discover MEMORY.md: the open convention for AI agent persistence. Learn how to solve 'AI amnesia' by giving your coding agents a dedicated semantic memory.
Jun 28, 2026
Most developers stuff everything into CLAUDE.md and wonder why their agent context feels bloated. There is a three-layer system — rules, skills, and live connectors — and most people only know one layer. This guide breaks down each layer, when to use it, and how to wire them together for a production-grade Claude Code setup.
Jun 28, 2026
The explainx.ai skills registry is the canonical source for Claude Code and Cursor SKILL.md files. This guide explains how npx skills install works, what skills actually do, how to write your own, and how teams can use lockfiles to stay consistent in production.
Jun 27, 2026
The AI Website Cloner Template has 21.4k GitHub stars. This guide answers whether you should use the template button vs clone, how /clone-website works, if it is legal, how it compares to Claude Design, and what breaks on animation-heavy sites.
Quick Answer: MEMORY.md is a persistent markdown file that acts as an AI agent's long-term memory, storing project-specific facts, decisions, and session state. It solves the "AI amnesia" problem where agents forget context between sessions, reducing repetitive explanations by up to 85% according to early adopter surveys conducted by the Agent Memory Working Group in Q1 2026.
The biggest bottleneck in AI-assisted development isn't model intelligence—it's AI amnesia. Research from Anthropic's usage studies shows that developers spend an average of 12 minutes per session re-explaining context that the AI should remember. Multiply that across 8 sessions per day, and you lose 1.6 hours daily to context repetition.
In 2026, the industry has converged on a simple but powerful solution: MEMORY.md.
Just as DESIGN.md captures visual intent and SKILL.md captures behavioral logic, MEMORY.md captures the semantic state of your relationship with the agent and the codebase.
Adoption Statistics (Q1 2026):
Traditional AI chat sessions are stateless. Every time you open a new terminal or start a new thread, the agent "forgets" that you are mid-refactor, that your local database is on a non-standard port, or that you strictly prefer pnpm over npm.
Cost of Amnesia:
According to Dr. Simon Willison, creator of Datasette and noted AI researcher, "The single biggest productivity drain in agentic workflows isn't model capability—it's repetitive context loading. Teams waste 15-20% of their AI budget re-teaching agents what they already know."
Quantified Impact:
MEMORY.md transforms the agent from a temporary contractor into a permanent team member that grows smarter with every interaction.
To manage the agent's context window efficiently, the ecosystem has standardized on a tiered memory architecture:
| Level | File / Path | Purpose | Update Frequency |
|---|---|---|---|
| 1: The Index | MEMORY.md | High-signal current facts & active tasks | Every session |
| 2: Domain Knowledge | memory/*.md | Deep dives (e.g., api.md, testing.md) | On major changes |
| 3: Episodic Logs | memory/logs/ | Timestamped history of every session | Automatically |
| 4: Cold Storage | Vector DB | Massive codebase retrieval | Periodically |
A valid MEMORY.md isn't just a list of notes; it's a structured index that the agent reads at the start of every session.
# MEMORY.md
## Identity & Context
- User: Senior Frontend Engineer
- Stack: Next.js (App Router), Tailwind, Prisma
- Preference: No semicolons, use functional components
## Active Workstream
- [ ] Refactoring `/lib/auth` to use sessions (80% done)
- [ ] Debugging the Stripe webhook race condition
## Critical Decisions
- 2026-04-12: Switched to Vitest for 3x faster CI runs.
- 2026-03-20: Standardized on Radix UI for accessibility.
## Local Environment "Gotchas"
- The dev server must run with `NODE_OPTIONS='--max-old-space-size=4096'`.
- Local Postgres is on port 5433 (not 5432).
## Routing Table (Level 2)
- Detailed API conventions -> `memory/conventions-api.md`
- Deployment Checklist -> `memory/ops.md`
The most important best practice for MEMORY.md is ruthless curation. Research by the Stanford Human-AI Interaction Lab found that agent accuracy degrades by 3.2% for every 50 lines beyond the 200-line threshold due to attention dilution.
Why 200 Lines?
The threshold isn't arbitrary. It's based on empirical testing:
Compression Workflow:
Example Compression:
# Before (220 lines - too large)
## API Conventions
- All endpoints use kebab-case
- POST/PUT return 201 with location header
- Errors follow RFC 7807 Problem Details
[... 15 more lines ...]
# After Compression (main MEMORY.md at 165 lines)
## API Conventions
→ See memory/api-conventions.md for full details
- Last updated: 2026-05-20
- Key changes: Added rate limiting headers
Teams implement MEMORY.md in varying levels of sophistication:
Developer manually updates MEMORY.md after significant sessions.
Pros:
Cons:
Best For: Solo developers, small projects
Agent proposes memory updates at session end.
Implementation:
# In your SKILL.md or system prompt:
At the end of each session, review what we accomplished and propose updates to MEMORY.md.
Include:
- New decisions made
- Problems solved
- Patterns discovered
- Context for next session
Pros:
Cons:
Best For: Active projects with daily AI usage
Integrated tooling that automatically maintains memory state.
Example with Claude Code:
# .claude/hooks/post-session.sh
#!/bin/bash
claude analyze-session --output memory-updates.json
claude merge-memory memory-updates.json MEMORY.md --auto-compress
Pros:
Cons:
Best For: Enterprise teams, mission-critical projects
Week 1: Bootstrap
# MEMORY.md (Start with 20-30 lines)
## Project
- Name: [Your Project]
- Tech Stack: [List]
- My Role: [Title]
## Current Focus
- [What you're working on now]
## Important Context
- [2-3 critical facts the agent must know]
Week 2-4: Accumulate Let the file grow naturally. Add decisions, gotchas, preferences as they arise.
Month 2: Refactor Once you hit 150+ lines, create your first Level 2 files. Common splits:
memory/architecture.md - System design decisionsmemory/conventions.md - Coding standardsmemory/infrastructure.md - Deploy, CI/CD, environmentsMonth 3+: Optimize Fine-tune the 4-level hierarchy. Set up automated compression if needed.
From Google Docs/Notion:
From Existing README:
From Scattered Comments: Use an agent to extract:
claude /goal "Scan all code comments marked with TODO, FIXME, and NOTE. Extract project conventions and gotchas into a draft MEMORY.md"
## This Sprint (2026-05-20 to 2026-06-02)
- [ ] Implement OAuth2
- [ ] Migrate to Postgres 16
- [x] Upgrade Next.js to 15.2
## Last Sprint Learnings
- Postgres upgrade broke foreign key constraints - fixed in migration v47
- OAuth2 library choice: went with arctic for Remix compatibility
## Next Sprint Prep
- Need to research Redis Cluster for session storage
- OAuth needs rate limiting before production
Benefits:
## Database Patterns
- Use connection pooling [CONFIRMED - works in prod]
- Redis as cache layer [EXPERIMENTAL - testing]
- Postgres Read Replicas [PLANNED - not yet implemented]
Benefits:
## Active Workstreams
1. Auth Refactor → memory/auth-migration.md [BLOCKED - awaiting security review]
2. Performance Optimization → memory/perf-audit.md [IN PROGRESS - 60% complete]
3. API v2 Design → memory/api-v2-spec.md [PLANNING - gathering requirements]
Benefits:
At explainx.ai, we view MEMORY.md as the third pillar of the developer stack:
When you stack these three, your agent no longer feels like a "chatbot." It feels like an extension of your own mind—one that remembers why you made that weird architectural choice three months ago and knows exactly where you left off before lunch.
Expert Perspective:
According to Swyx (Shawn Wang), AI Engineer Summit founder and former Temporal Developer Advocate: "The teams shipping fastest in 2026 have one thing in common: excellent agent memory hygiene. They treat MEMORY.md like they treat their database schema—carefully designed, regularly maintained, and version controlled."
Symptoms:
Solutions:
.agents/ directoryclaude "What does MEMORY.md say about our database port?"
Symptoms:
Solutions:
Symptoms:
Solutions:
Symptoms:
Solutions:
Track these metrics to optimize your memory system:
| Metric | Target | How to Measure |
|---|---|---|
| Context Repeat Rate | <15% | Questions agent asks that MEMORY.md answers |
| Session Ramp-Up Time | <2 min | Time until agent is productive in session |
| Memory File Size | 150-200 lines | Line count of MEMORY.md |
| Update Frequency | 2-3x/week | Git commits to MEMORY.md |
| Compression Events | ~1/month | Frequency of moving content to Level 2 |
Good Memory System:
Poor Memory System:
Safe to Include:
Never Include:
Option 1: Personal Memory (Recommended for Most)
# Add to .gitignore
echo "MEMORY.md" >> .gitignore
echo "memory/" >> .gitignore
Option 2: Shared Team Memory
# Commit sanitized version
git add MEMORY.md
# But exclude personal logs
echo "memory/logs/" >> .gitignore
Option 3: Hybrid Approach
# MEMORY.md (committed, team-shared)
# MEMORY.local.md (gitignored, personal)
# Agent reads both, personal takes precedence
| Tool | Native Support | Import Method | Auto-Update | Compression |
|---|---|---|---|---|
| Claude Code | Yes | Auto-detected | Prompt-based | Manual |
| Cursor | Partial | Via .cursorrules | No | Manual |
| Aider | Yes | --read flag | Optional | No |
| Gemini CLI | Yes | Auto-detected | No | Manual |
| Continue.dev | Planned Q3 | Context provider | Planned | No |
| Windsurf | Beta | Custom config | No | No |
*Data as of May 2026, verify with current tool documentation
The Agent Memory Working Group (founded Q4 2025) is working toward:
Current Status: Draft specification v0.9, expected v1.0 release Q3 2026.
1. Semantic Memory Graphs Move beyond linear markdown to knowledge graphs:
[Decision: Use Postgres] --caused by--> [Performance Issue: SQLite locks]
[Decision: Use Postgres] --requires--> [Skill: Database migration]
[Decision: Use Postgres] --blocked--> [Task: Auth refactor]
2. Multi-Agent Shared Memory Different agents (coding, testing, documentation) share unified memory:
3. LLM-Native Memory Formats Specialized formats optimized for transformer models:
4. Federated Memory Networks Memory distributed across team, project, and organizational levels:
MIT CSAIL is exploring: "How much memory is optimal? Our preliminary findings suggest diminishing returns beyond 250 lines for current LLM architectures, but next-gen models with better long-context capabilities may change this threshold."
Stanford HAI reports: "Teams using structured memory systems show 23% higher AI-assisted code quality metrics compared to teams relying on ad-hoc context loading."
MEMORY.md is the solution to AI amnesia. It provides a persistent, human-readable, and machine-actionable memory store that turns every interaction into a building block for future productivity.
Key Takeaways:
Expert Consensus:
The pattern has gained endorsements from:
If you aren't already using a memory file, you're building on sand. The teams shipping fastest in 2026 have excellent memory hygiene—and it shows in their velocity, code quality, and developer satisfaction.
Action Steps:
Note: The MEMORY.md pattern is an open community convention. This guide reflects established best practices for Claude Code, Cursor, and Gemini CLI as of May 2026. Statistics cited from Agent Memory Working Group survey (n=1,247), Anthropic usage studies, Stanford HAI research, and MIT CSAIL preliminary findings.