How to Build a Structured Memory System for Claude Code and Eliminate Re‑Explanation

Claude Code can act like a forgetful assistant: after a discussion about an architecture decision, reopening the project forces you to repeat the same information, and experience from one project cannot be transferred to another. The root cause is that all configuration lives in a single, growing CLAUDE.md file.

Original Project Layout

WeChatPublic/ 
├── 2026/                # articles by month
├── wechat-md-style.css
├── CLAUDE.md            # only one file
└── STATUS.md

The problems are obvious:

Everything is crammed into CLAUDE.md (>200 lines).

No persistent project memory; each session requires a full explanation.

Guidelines are easily forgotten, leading to repeated mistakes.

Switching to a new project offers no reuse.

Reorganized Structure

The new layout introduces a .claude folder that separates core configuration, rules, memory, skills, templates, and agent‑team definitions.

WeChatPublic/ 
├── CLAUDE.md                # core project config
└── .claude/ 
    ├── 00-INDEX.md         # overall index
    ├── rules/              # 4 rule files
    │   ├── 00-README.md
    │   ├── 01-writing.md   # writing style
    │   ├── 02-design.md     # design system
    │   ├── 03-publishing.md# publishing strategy
    │   └── 04-images.md    # image guidelines
    ├── memory/             # 4 memory files
    │   ├── 00-README.md
    │   ├── decisions.md    # important decisions
    │   ├── history.md      # project history
    │   ├── lessons.md      # lessons learned
    │   └── problems.md    # open issues
    ├── skills/             # reusable skill files
    │   ├── article-planner.md
    │   └── article-reviewer.md
    ├── templates/          # template files
    │   ├── article.md
    │   └── decision-record.md
    └── agent-teams/        # Claude agent configuration
        └── wechat-publisher-team.yaml

The project now consists of 18 files, turning a chaotic dump into a systematic knowledge base.

CLAUDE.md – Project Identity

# WeChat Public Account – AI Technical Articles
> AI, Claude Code, MCP, Skills technical article management

## Project Overview
A technical newsletter for developers and AI‑tool enthusiasts, focusing on practical AI tool tutorials.

## Key Information
| Property | Value |
|----------|-------|
| **Publish Time** | Mon‑Fri 20:28 |
| **Article Length** | 2000‑3000 words |
| **Audience** | Developers, AI‑tool fans |
| **Themes** | MCP, Skills, Rules, RAG, OpenClaw |
| **Cover Style** | Warm tones + off‑white background + hand‑drawn |

## Common Commands
# Quick start
mkdir -p "2026/XMonth/2026-XX-XX-Title/imgs/prompts"
cp .claude/templates/article.md "Title.md"

# Generate cover
/baoyu-cover-image article.md --palette warm --rendering hand-drawn

# Publish via Agent Team
# See .claude/agent-teams/wechat-publisher-team.yaml

Key Points

Start with a one‑sentence project description.

Present essential information in a table for quick reference.

Provide ready‑to‑use commands.

Rules Splitting Example (Writing Guidelines)

# Public Account Article Writing Guidelines

## Writing Style
### Must Follow
- ❌ Avoid AI‑sounding phrases like "值得注意的是", "总而言之", "首先".
- Write conversationally, as if chatting with a friend.
- Emphasize real‑world cases, limit theory.
- Keep each article 2000‑3000 words.

### Prohibited Content
- ❌ Over‑theoretical, no practical examples.
- ❌ Obvious AI‑tone.
- ❌ Exceed 3000 words.

## Article Structure Template
> One‑sentence hook (blockquote) to spark interest

## 1. Introduction
Introduce a scenario or problem to create resonance.

## 2. Core Content
Explain step‑by‑step, include code examples.

### 🎯 Sub‑section Title
Use emojis for readability.

## N. Conclusion
Summarize key takeaways.

Memory Files – Capturing Project Knowledge

decisions.md records important decisions, reasons, and impact:

# Important Decision Record
## 2026-03-25 – Project Structure Optimization
**Decision**: Adopt unified structure `CLAUDE.md + rules/memory/skills`
**Reason**:
- Inconsistent structures across projects increased switch cost.
- Lack of project memory caused loss of historical decisions.
- Experience could not be reused.
**Impact**:
- Unified management for all projects.
- Claude Code retains context.
- Cross‑project experience becomes reusable.

history.md logs chronological events, e.g.:

# Project History
## 2026-03-25
### Project structure optimization completed
- Created 18 configuration files
- Integrated into PM system
- Updated memory (decisions, history, lessons)
### Agent Team system established
- Added wechat-publisher-team.yaml
- Enabled automated publishing workflow

lessons.md captures best practices and pitfalls, such as writing style, length control, and image guidelines.

Effect Comparison

Before

Every new task requires a full re‑explanation:

Me: Write an article about MCP.
Claude: Sure, what style?
Me: Conversational, no AI tone.
Claude: Length?
Me: 2000‑3000 words.
Claude: What about images?
Me: Warm‑tone hand‑drawn cover...

After

Me: Write an article about MCP.
Claude: Got it, planning now...

Claude reads the rules/ files directly, automatically applying writing style, image preferences, and publishing schedule without repeated prompts.

Cross‑Project Reuse

The same 18‑file structure was applied to four additional projects (Flashlight, work projects, personal website), adding 14, 7, and 9 files respectively, demonstrating the scalability of the approach.

Implementation Steps

Step 1 – Create Directory Structure

mkdir -p .claude/{rules,memory,skills,templates}

Step 2 – Write CLAUDE.md

Either let Claude generate it automatically with /init or write it manually (project name, overview, tech stack, quick commands).

Step 3 – Split Rules into rules/

Prompt Claude: "Split the guidelines in CLAUDE.md into the .claude/rules/ directory" or create the files manually (e.g., .claude/rules/01-writing.md, .claude/rules/02-design.md, …).

Step 4 – Create Memory Files

Recommended: let Claude record decisions, history, lessons during daily work. Manual alternative: create .claude/memory/decisions.md, history.md, lessons.md, problems.md yourself.

Step 5 – Start Using Claude Code

# Launch Claude Code in the project
claude
# Claude automatically reads all configuration files and works without re‑explaining context.

Advanced Tips

Tip 1 – Path‑Specific Rules

---
paths:
  - "src/api/**/*.ts"
---
# API development rule
- All API endpoints must include input validation

Rules load only for matching files, saving context.

Tip 2 – Symlink Shared Rules

# Share a TypeScript rule across projects
ln -s ~/shared-typescript-rules.md .claude/rules/typescript.md

Update once, all projects benefit.

Tip 3 – Periodic Memory Cleanup

Regularly archive old entries in decisions.md (e.g., move previous month’s decisions to an archive folder) to keep the file manageable.

Conclusion

The guide provides both theory (why a structured memory system matters) and practice (how to build it in under ten minutes). After the transformation, Claude Code remembers all past decisions, writing conventions, and project history, dramatically reducing repetitive explanations and enabling consistent, scalable AI‑assisted development across multiple projects.