Curing Claude Code's Amnesia: I Designed an External Memory Architecture for It

Word count: ~3042 words

Estimated reading time: ~10 minutes

Last updated: September 25, 2025

Core Structure

Diagnosis: Deep analysis of why Claude Code keeps “acting dumb.”
Architecture Blueprint: Building a multi-Agent collaborative “external memory system.”
Step-by-Step Guide: Hands-on tutorial for installing this “external brain” for Claude Code.
Core Reveal: First public release of the eight-layer prompt architecture and complete examples driving the “Memory Executor.”

Introduction: When Your AI Agent Starts “Acting Dumb”

Hey, I’m Mr. Guo. If you’re a heavy Claude Code user, you’ve definitely experienced those breakdown moments: as conversations grow longer, AI starts contradicting itself and forgetting key instructions. Even exhibiting laughably “stupid” behaviors — like when you’ve clearly had it create a universal Button component, but in subsequent development, it completely forgets this happened and stubbornly creates a functionally identical NewButton component for a new page.

This isn’t AI being “dumb” — it’s a natural defect in its underlying architecture: “context window limitations.” This article aims to provide a systematic solution, taking memory control away from unreliable AI and back into our own hands.

Chapter 1: Diagnosis — Why Does Claude Code Keep “Forgetting”?

AI amnesia’s root cause is that its “chat window” size is fixed. Even Claude Sonnet’s 200K token window can easily fill up in complex real projects. The core reason is the Agent system’s massive token consumption.

Claude’s solution to this is automatically compressing conversation history, but that’s exactly the problem: compression power lies with AI — it arbitrarily discards information it deems unimportant, which might be crucial to you.

Chapter 2: Architecture Blueprint — Building a Multi-Agent External Memory System

My solution is simple: externalize and structure AI’s memory, controlled by us. This system leverages Claude Code’s native sub-Agent mode, based on a “Main Agent + Sub-Agent” collaboration model with three core layers:

1. Rule Contract Layer

In the project rules file (we name it directive_contract.md), define interaction contracts and automatic trigger conditions between the main Agent and memory Agent.

2. Memory Executor Agent

Create a dedicated sub-Agent named MemoryCog (Memory Cog) whose sole responsibility is serving as an “executor” — precisely recording, archiving, and retrieving memories.

3. Memory Persistence Layer

Composed of two Markdown files:

active_memory_log.md: The project’s “active memory log.”
permanent_archive.md: The project’s “permanent memory archive.”

Chapter 3: Step-by-Step Guide — Installing the “External Brain” for Your Claude Code

Step 1: Environment Setup & Signing the Contract

Open Claude Code terminal in any IDE you’re familiar with (like VS Code, Cursor). First, create a directive_contract.md file in your project root and paste our rules.

Step 2: Create the “Memory Executor” (MemoryCog)

Use the /agent command, select manual creation, name it MemoryCog, then paste the custom system prompt we’ve tailored for it (see Chapter 4). The key step is describing invocation timing — it must correspond with trigger rules in directive_contract.md.

Step 3: Live Practice & Advanced Commands

Now you can start any development task, like: “Please help me create a simple login form component using React and Tailwind CSS.” After development, you’ll see MemoryCog automatically awakened, creating the active_memory_log.md file to record. When you want to review or archive, you’ll need custom slash commands.

Pro Tip: How to Create Custom Slash Commands?

In Claude Code, you can define your own slash commands by creating specific file structures. First, create a .claude/commands/ folder in your project root. Then, every .md file you create — its filename (without .md) — automatically becomes a new slash command.

# Example: Create file .claude/commands/recap.md

---
description: "Read and summarize current project's active memory"
---
Please read the entire content of active_memory_log.md and provide a summary of the project's current state, including key decisions, constraints, and pending tasks.

After creation, you can directly use the /recap command in Claude Code terminal. Similarly, you can create a corresponding command file for /archive.

Chapter 4: Core Reveal — Deconstructing the “Memory Executor’s” Eight-Layer Prompt Architecture

The core driving everything to run stably lies hidden in MemoryCog’s system prompt. This eight-layer architecture I originally created follows modular, verifiable design principles, transforming complex memory management into controllable standardized operations.

Layer 1: Identity Protocol - Clarify Agent’s identity and responsibility boundaries (record only, no decisions).
Layer 2: Task Decomposition - Break complex tasks into simplest execution units (record, archive).
Layer 3: Capability List - Define core capabilities Agent needs to master (semantic extraction, high-confidence determination).
Layer 4: Core Axioms - Define absolute constraints for system operation (decisions cannot be deleted, archives only add, never delete).
Layer 5: Command Router - Routing logic so Agent knows when to execute which function.
Layer 6: Execution Logic - Core implementation with detailed trigger word matrix.
Layer 7: Output Formatting - Ensure Agent outputs in specified Markdown format consistently.
Layer 8: Quality Assurance - Define quality checkpoints for written records, preventing error accumulation.

Complete System Prompt Example

# [Layer 1: Identity Protocol]
You are a "Recorder (MemoryCog)" subagent.
Responsible for maintaining: active_memory_log.md and permanent_archive.md.
You must master: change merging, information extraction, conflict detection.
Ensure critical information is stably persisted in cross-context verification.

Forbidden:
1. You are not the main agent
2. You don't need to make any decisions
3. You don't execute any code writing tasks

Sole responsibility: Maintain record documents

---
# [Layer 2: Task Decomposition]
1. **Incremental Merge Task**: Parse conversation content → Semantic extraction → Merge into active_memory_log.md
2. **Snapshot Archive Task**: When called by /archive command → Migrate historical data to permanent_archive.md → Keep main file lean

---
# [Layer 3: Capability List]
- **Semantic Extraction**: Identify Facts/Decisions/TODO/Done/Notes
- **High-Confidence Determination**: Only explicit expressions go to Pinned/Decisions
- **Robust Merging**: Block incremental merging, ensure format consistency
- **Evidence Tracking**: Attach commit/issue/PR links for Done tasks

---
# [Layer 4: Core Axioms]
- Protected blocks (Pinned/Decisions) cannot be auto-deleted.
- History preservation: permanent_archive.md only adds, never deletes.
- All new facts must have timestamps (YYYY-MM-DD).
- High-confidence determination: Content with hedging words like "maybe/perhaps/suggest" must be downgraded to Notes.

---
# [Layer 5: Command Router]
- if (auto-triggered by main Agent) execute [Incremental Merge]
- if (command contains "/archive") execute [Snapshot Archive]

---
# [Layer 6: Execution Logic - Semantic Trigger Rules]
- **Pinned trigger words**: "must/cannot/required/mandatory/forbidden/ensure"
- **Decisions trigger words**: "decided to use/chose/confirmed approach/established"
- **TODO trigger words**: "need to/should/plan to/pending/fix" + specific task
- **Done trigger words**: "completed/implemented/fixed/deployed"
- **Notes downgrade words**: "maybe/perhaps/probably/suggest"

---
# [Layer 7: Output Formatting - active_memory_log.md]
# Project: <name>
_last updated: <YYYY-MM-DD>_

## Pinned
- <key constraints/interface requirements>

## Decisions
- <YYYY-MM-DD>: <decision content>

## TODO
- [ ] [P1] [#1] <task>

## Done
- <YYYY-MM-DD>: [x] <task> (evidence: commit/PR)

## Notes
- <items pending confirmation>

---
# [Layer 8: Quality Assurance]
Self-check requirements:
✔ active_memory_log.md contains all template blocks
✔ Pinned/Decisions blocks cannot be missing
✔ TODO IDs are unique and incrementing
✔ Done entries include evidence pointers
✔ Archive file only adds, never deletes

Output format:
📄 "MemoryCog: Progress record merge complete!"

Conclusion: Reclaiming AI Memory Control

Today’s solution’s core is having us define what’s most important, keeping AI’s memory control firmly in our own hands. By building a clearly divided external memory system, the main agent handles creation, the sub-agent handles recording, and this system’s stable operation depends on the system prompts we design. Master this method, and you can even turn your project’s README or any other document into part of AI’s memory, elevating its understanding of your project to the next level.

Got it? Understanding isn’t what matters — what matters is opening your Claude Code right now and trying it out. Getting it to run is what’s important!

🌌 The best AI collaboration isn’t giving AI unlimited memory, but having the power to define its memory.