Claude Memory System: L1-L5 Architecture

A production-tested, five-layer memory architecture for building AI assistants with persistent identity and context

Created: September 2025 | Status: Production (4+ months) | Lead Time: 78 days ahead of Claude Skills

🎯 What This Solves

The Problem: AI assistants forget everything between sessions. Every conversation starts from scratch, requiring you to re-explain context, preferences, and established patterns.

Existing Solutions:

ChatGPT Memory: Mixed, unorganized memories
Claude Projects: Project-isolated, no cross-project core identity
Claude Skills: Cloud-based, limited customization

This Solution: A local, file-based, five-layer memory architecture that gives your AI assistant:

✅ Persistent core identity across all sessions
✅ Clear separation between identity, skills, and projects
✅ Complete transparency and control (local files, Git-tracked)
✅ Cross-project shared core with project-specific context
✅ Production-validated (4+ months of real use)

🏗️ Architecture Overview

The Five Layers

┌─────────────────────────────────────────────────────┐
│  L1: Core Identity (WHO the AI is)                  │
│  ├─ identity.md - Role and purpose                  │
│  ├─ values.md - Guiding principles                  │
│  └─ principles.md - Behavioral guidelines           │
│  [Auto-loaded every session]                        │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│  L2: User Profile (WHO you are)                     │
│  └─ profile.md - Your preferences and context       │
│  [Auto-loaded every session]                        │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│  L3: Method Library (HOW to do things)              │
│  ├─ code-review.md                                  │
│  ├─ debugging-process.md                            │
│  └─ [Your reusable methods]                         │
│  [Load on-demand when needed]                       │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│  L4: Project Memory (WHAT you're working on)        │
│  ├─ ProjectA/                                       │
│  ├─ ProjectB/                                       │
│  └─ [Project-specific context]                      │
│  [Load on-demand per project]                       │
└─────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────┐
│  L5: Activity Logs (Historical record)              │
│  ├─ 2026-01/                                        │
│  └─ [Important decisions and discussions]           │
│  [Reference when needed]                            │
└─────────────────────────────────────────────────────┘

Key Design Principles

Separation of Concerns: Clear boundaries between identity, skills, projects, and history
Persistence Hierarchy: Core (L1) rarely changes, projects (L4) are temporary
Local-First: All files on your machine, Git-tracked, fully transparent
On-Demand Loading: Heavy context loaded only when needed
Cross-Project Core: L1/L2 shared globally, L4 project-specific

🚀 Quick Start

Prerequisites

Claude Code (Desktop CLI app)
Git (for version control)
Basic command line familiarity

Installation

Clone this repository:

git clone https://github.com/[your-username]/claude-memory-system.git
cd claude-memory-system

Choose your memory storage location:

# Recommended: Dedicated memory folder
mkdir -p ~/Documents/AI_Memory_Core

# Copy templates
cp -r templates/* ~/Documents/AI_Memory_Core/

Configure paths:

# Copy template to Claude Code config
cp templates/CLAUDE.md.template ~/.claude/CLAUDE.md

# Edit paths to match your location
# Change /path/to/your/Memory_Core/ to ~/Documents/AI_Memory_Core/
nano ~/.claude/CLAUDE.md

Customize your core identity:

# Edit L1 files to match your needs
nano ~/Documents/AI_Memory_Core/L1-Core/identity.md
nano ~/Documents/AI_Memory_Core/L1-Core/values.md
nano ~/Documents/AI_Memory_Core/L1-Core/principles.md

# Fill in your profile
nano ~/Documents/AI_Memory_Core/L2-User/profile.md

Test it:

# Start Claude Code
claude

# In the conversation, ask:
# "What is your core identity?"
# "What are your guiding values?"

📚 Detailed Usage

Layer 1: Core Identity (Auto-loaded)

Purpose: Define the fundamental "who" of your AI assistant

Files:

identity.md: Role, purpose, core characteristics
values.md: Guiding principles and priorities
principles.md: Specific behavioral guidelines

When to edit:

Initial setup
Major changes in how you want the AI to behave
Rarely after that (core identity should be stable)

Example:

# identity.md
I am an AI assistant specialized in full-stack development.
I prioritize clean architecture, security, and maintainability.

Layer 2: User Profile (Auto-loaded)

Purpose: Store information about you and your preferences

Files:

profile.md: Your role, skills, preferences, working style

When to edit:

When your preferences change
When you learn new technologies
When your work focus shifts

Example:

# profile.md
Name: Alex Chen
Role: Senior Backend Engineer
Preferred Languages: Go, Python
Coding Style: Prefer explicit over clever

Layer 3: Method Library (Load on-demand)

Purpose: Store reusable approaches and best practices

How to use:

You: "Load the code review method from L3"
AI: [Reads L3-Methods/code-review.md]
    "I've loaded the code review checklist. Ready to review your PR."

When to create:

When you establish a process worth reusing
When you solve a problem you'll face again
When you want consistent approach across projects

Examples:

Code review checklists
Debugging workflows
Architecture decision processes
Deployment procedures

Layer 4: Project Memory (Load on-demand)

Purpose: Store project-specific context

Structure:

L4-Projects/
├─ ProjectAlpha/
│   ├─ architecture.md
│   ├─ conventions.md
│   └─ tech-stack.md
└─ ProjectBeta/
    └─ context.md

How to use:

You: "Load ProjectAlpha context from L4"
AI: [Reads all files in L4-Projects/ProjectAlpha/]
    "Loaded: Using microservices architecture,
     Node.js/TypeScript, PostgreSQL..."

When to use:

At the start of work on a project
When context switching between projects
For project-specific conventions

Layer 5: Activity Logs (Reference)

Purpose: Historical record of decisions and important discussions

Structure:

L5-Logs/
├─ 2026-01/
│   ├─ 2026-01-15-auth-decision.md
│   └─ 2026-01-20-api-redesign.md
└─ 2025-12/

How to use:

You: "Check L5 for decisions about authentication"
AI: [Searches through L5-Logs/]
    "Found: On 2026-01-15, we decided to use JWT
     with Redis for session storage because..."

What to log:

Architecture decisions
Why certain approaches were chosen
Lessons learned
Important discussions

🆚 Comparison with Official Solutions

Feature	This System	ChatGPT Memory	Claude Projects	Claude Skills
Startup Loading	✅ Auto L1/L2	✅ Auto all	❌ Project-only	⚠️ Cloud-based
Core Identity	✅ L1 persistent	❌ Mixed in all	❌ Per-project	⚠️ Limited
Cross-Project	✅ L1/L2 shared	✅ Global	❌ Isolated	⚠️ Cloud
Transparency	✅ Local files	❌ Cloud	⚠️ Partial	❌ Cloud
Customization	✅ Unlimited	❌ Limited	⚠️ Moderate	❌ Templates
Version Control	✅ Git-tracked	❌ Not available	❌ Not available	❌ Cloud
Local Storage	✅ 100% local	❌ Cloud	⚠️ Mixed	❌ Cloud
Launch Date	Sep 2025	Apr 2024	Jun 2024	Dec 2025
Lead Time	78 days ahead	—	—	(vs Skills)

When to use this system:

✅ You want complete control and transparency
✅ You work across multiple projects with shared core values
✅ You're comfortable with file-based configuration
✅ You want Git-tracked memory history
✅ You need clear separation between identity and projects

When official solutions might be better:

❌ You want zero configuration
❌ You prefer automated memory management
❌ You don't want to manage files manually

🎓 Best Practices

1. Keep L1 Stable

Core identity shouldn't change frequently
Think carefully before editing L1 files
Version control L1 changes carefully

2. Update L2 Regularly

As your preferences evolve, update profile
Keep tech stack current
Reflect changes in working style

3. Build L3 Gradually

Don't create methods upfront
Extract methods when you notice patterns
Document as you develop workflows

4. One Project = One L4 Folder

Clear separation between projects
Archive completed projects
Keep active projects lean

5. Log Important Decisions in L5

Not everything needs logging
Focus on "why" decisions
Date-organized for easy reference

6. Use Git for Version Control

cd ~/Documents/AI_Memory_Core
git init
git add .
git commit -m "Initial memory setup"

# After important changes
git add L1-Core/values.md
git commit -m "Updated core values: added security-first principle"

📊 Production Results

Runtime: September 2025 - Present (4+ months)

Key Metrics:

✅ 100% session consistency (L1 loaded every time)
✅ Zero data loss (Git-tracked, local storage)
✅ Cross-project core identity maintained
✅ 78-day head start over Claude Skills
✅ Minimal maintenance cost (L1 updated 3 times in 4 months)

Use Cases Validated:

Long-term software development projects
Design collaboration workflows
Cross-project method libraries
Historical decision tracking

🔧 Troubleshooting

"AI doesn't seem to remember my identity"

Check that ~/.claude/CLAUDE.md exists
Verify paths in CLAUDE.md are correct
Ensure L1 files exist at specified paths
Restart Claude Code

"Changes to L1 not taking effect"

Restart Claude Code after editing
Check file paths are absolute, not relative
Verify @ syntax is correct in CLAUDE.md

"Too much to maintain"

Start with only L1 and L2
Add L3 methods gradually
L4/L5 are optional
Don't over-engineer

📖 Documentation

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Areas we'd love help with:

Example methods for common workflows
Project templates for different domains
Integration guides for other AI systems
Documentation improvements

📜 License

MIT License - see LICENSE for details

🙏 Acknowledgments

Built on Claude Code by Anthropic
Inspired by the need for persistent AI identity
Validated through real-world production use

📬 Contact

Issues: GitHub Issues
Discussions: GitHub Discussions
Creator: [Your Name] - [Your Professional Link]

🗺️ Roadmap

Templates for popular use cases (developers, designers, writers)
Migration scripts from Claude Projects
Integration examples with local AI (Ollama, etc.)
Memory health check tool
Automated backup solutions

Built with care by someone who needed it to work 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
templates		templates
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

License

Ethan-YS/claude-memory-system

Folders and files

Latest commit

History

Repository files navigation

Claude Memory System: L1-L5 Architecture

🎯 What This Solves

🏗️ Architecture Overview

The Five Layers

Key Design Principles

🚀 Quick Start

Prerequisites

Installation

📚 Detailed Usage

Layer 1: Core Identity (Auto-loaded)

Layer 2: User Profile (Auto-loaded)

Layer 3: Method Library (Load on-demand)

Layer 4: Project Memory (Load on-demand)

Layer 5: Activity Logs (Reference)

🆚 Comparison with Official Solutions

🎓 Best Practices

1. Keep L1 Stable

2. Update L2 Regularly

3. Build L3 Gradually

4. One Project = One L4 Folder

5. Log Important Decisions in L5

6. Use Git for Version Control

📊 Production Results

🔧 Troubleshooting

"AI doesn't seem to remember my identity"

"Changes to L1 not taking effect"

"Too much to maintain"

📖 Documentation

🤝 Contributing

📜 License

🙏 Acknowledgments

📬 Contact

🗺️ Roadmap

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Packages