three-layer-memory

Three-Layer Memory Architecture

Overview

A tiered memory system that gives Claude agents persistent knowledge across sessions by storing different types of information in the right place. Layer 1 (Memory MCP) holds cross-application global memory shared between Claude Desktop and Claude Code. Layer 2 (auto-memory) holds per-repository project context that travels with the codebase. Layer 3 (external markdown editor) serves as a research library for long-form artifacts the agent can reference but does not own.

Core principle: Different types of knowledge belong in different memory tiers. Putting everything in one place creates noise; splitting it correctly means the agent always has the right context without being overwhelmed.

Dependency: Layer 1 requires the Memory MCP server. Layer 3 requires Joplin, Obsidian, or any markdown-based knowledge tool accessible via file path or MCP.

When to Use

• When starting a new project and configuring how the agent should remember things
• When you notice the agent forgetting decisions, preferences, or context between sessions
• When you work across multiple tools (Claude Desktop + Claude Code) and need shared state
• When you have research artifacts (design docs, API references, vendor comparisons) that the agent should consult

When NOT to Use

• Single-session throwaway tasks where persistence has no value
• Projects where you are the only consumer of the context (just use your own notes)
• As a replacement for proper documentation -- memory tiers supplement docs, they do not replace them

Common Mistakes

Mistake	Why it's wrong
Storing everything in CLAUDE.md	CLAUDE.md is for instructions, not knowledge. It tells the agent how to behave, not what it knows. Dumping facts there makes it bloated and slow to parse.
Putting project-specific decisions in global Memory MCP	Global memory pollutes other projects. A database schema decision for Project A is noise when working on Project B. Use Layer 2 per-repo auto-memory instead.
Skipping CLAUDE.md routing instructions	Without explicit instructions telling the agent which tier to use, it will default to whatever is easiest -- usually forgetting entirely. The routing config is what makes the system work.
Using Layer 3 for things that change frequently	The external research library is for stable reference material. If the content changes every sprint, it belongs in Layer 2 auto-memory where it is versioned with the repo.
Treating memory as write-only	Memory that is never pruned becomes stale and misleading. Review and clean each layer periodically. Old decisions that have been reversed are worse than no memory at all.