Three-layer memory architecture for long-term AI learning with Claude
SaferSkills independently audited claude-layered-memory-architecture (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Solving AI memory limitations through hierarchy, not accumulation.
A three-layer memory system that eliminated 60% RAG retrieval failures in 10+ months of AI-assisted learning.
After 10 months using Claude for Python learning with Socratic method:
Root cause: Accumulated 79,000 lines of documentation in RAG. The knowledge was causing the problem, not solving it.
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Project MD (Bootstrap / "BIOS") │
│ └→ Declarative config that auto-triggers Skill loading │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: SKILL.md (Permanent Knowledge / "Hard Drive") │
│ └→ 900 lines distilled from 79,000 original documentation │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: RAG (Rotational Working Memory / "RAM") │
│ └→ Only current exercise, cleared between sessions │
└─────────────────────────────────────────────────────────────┘| Innovation | Description |
|---|---|
| MD as declarative MCP | Project description auto-triggers Skill in Claude.ai |
| Intentionally rotational RAG | Cleared per exercise, not accumulated |
| Human-as-Firewall | Manual curation before cloud upload |
| Three-tier sync | Local → Claude Code → Claude Desktop |
| Metric | Before (RAG-Only) | After (Layered) |
|---|---|---|
| RAG retrieval failures | 60% | 0% |
| Compaction frequency | Every 4-5 prompts | Rarely |
| Session continuity | Poor | Excellent |
| Context control | None | Full |
┌──────────┐ ┌──────────┐ ┌──────────┐
│Exercise N│ --> │Exercise │ --> │Exercise │ --> ...
│ in RAG │ │ N+1 │ │ N+2 │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
v v v
┌─────────────────────────────────────────────┐
│ SKILL.md (Permanent) │
│ Concepts consolidated here over time │
└─────────────────────────────────────────────┘
RAG size: CONSTANT (~5-10% capacity)
SKILL size: GROWS SLOWLY (only key concepts)
Retrieval failures: 0%📄 [Full Documentation (English)](docs/layered-memory-architecture.md)
📄 [Documentación Completa (Español)](docs/arquitectura-memoria-capas-es.md)
The full documents include:
This architecture was validated by Claude Opus 4.5 running inside the system described:
"I am the proof that this architecture works. This document was created inside a Claude.ai Project that uses the exact three-layer system. The Project MD triggered my Skill automatically, I have access to 900 lines of permanent knowledge, and the RAG contains only the current session. The system works."
>
— Claude Opus 4.5, December 21, 2025
See full documentation for detailed implementation.
| Tool | Purpose |
|---|---|
convert_pdfs_to_md.py | Converts PDFs to searchable Markdown |
sanitize_filenames.py | Removes problematic characters for Claude Desktop |
Result: 133 PDFs converted, 277 files sanitized in 5 rounds.
✅ Ideal for:
❌ Not recommended for:
JuanMa Cruz Herrera Spanish data science student, 51 years old 10+ months learning Python with Claude using Socratic method
MIT - Use freely for educational purposes.
Questions? Improvements? Alternative approaches?
Particularly interested in:
Created: December 21, 2025 Platform: Claude.ai Projects + Claude Code + Claude Desktop
"The solution to AI memory isn't more memory—it's better memory architecture."
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.