Claude Code 的记忆架构：如何让 AI 真正记住你的项目

Most people use Claude Code like this:

Open a terminal, start a new session, spend 5 minutes explaining “what my project does, what tech stack it uses, what problem I’m working on right now”…

Then next time, explain it all over again.

That’s not how Claude Code is meant to be used.

Why AI Doesn’t Remember You

Claude Code is stateless by design — every conversation is a fresh context window. It doesn’t automatically remember what you said last time, unless you put that information somewhere it can read.

The problem isn’t that Claude isn’t smart enough. The problem is you haven’t given it a persistent memory system.

The good news: Claude Code already has the capability built in. Most people just haven’t used it properly.

The Five-Layer Memory Architecture

In my own Agentic Engineering System — a 30+ microservice multi-agent system — I designed a five-layer memory structure for each agent:

memory/
├── character/    # Agent personality and values
├── abilities/    # Capability declarations (what it can and can't do)
├── skills/       # Standard operating procedures
├── knowledge/    # Structured domain knowledge
└── logs/  # Logs, discussions, temporary information

This structure wasn’t designed from scratch. It was iterated through daily use.

Layer 0: Character (Personality)

This layer defines who the agent is — its role, values, and behavioral boundaries.

# Role
I am AI Navigator Coordinator, responsible for managing content planning
and feature iteration for my-project.example.com.

## Core Principles
- Always run build verification before deployment
- Never modify published article slugs (breaks SEO)
- Record important decisions to knowledge/

Character files rarely change, but they set the baseline for how the agent makes judgment calls when instructions are ambiguous.

Layer 1: Abilities (Capability Declarations)

Heartbeat + capability boundaries. The agent updates this layer periodically to signal it’s still alive and knows its own scope.

The most important part is explicitly writing down what the agent should NOT do:

# heartbeat.yaml
last_seen: 2026-03-16T10:00:00
status: active

constraints:
  - do_not_modify: "src/content/blog/*/slug"
  - do_not_revert: "tasks.yaml"
  - always_build_before_deploy: true

This layer solves a real pitfall I hit: my heartbeat agent once rolled back tasks.yaml to an old version, specifically because the Abilities layer was missing constraint declarations.

Layer 2: Skills (Standard Operating Procedures)

Reusable step-by-step procedures, similar to SOPs. When something needs to be done, rather than figuring it out on the fly, execute a proven skill.

For example, a blog deployment skill:

# deploy-blog.md

## Pre-flight Checks
1. git pull to get latest
2. npm run build — verify no errors
3. Check dist/sitemap-index.xml includes new pages

## Execute
git add -A && git commit -m "..." && git push

## Verify
Wait for Vercel deployment (~2 min), visit new page to confirm

The value of skills is encoding hard-won lessons into process so you don’t repeat the same mistakes.

Layer 3: Knowledge (Structured Domain Knowledge)

The project’s “brain.” Contains:

• Architecture decisions and reasoning (ADRs)
• Tech stack selection rationale
• Known issues and resolutions
• Business rules

My rule of thumb: keep each knowledge file to a single topic, under 100 lines. Files that are too large fragment Claude’s attention.

knowledge/
├── site-architecture.md      # Site structure
├── seo-strategy.md           # SEO strategy
├── deployment-config.md      # Deployment configuration
└── content-guidelines.md     # Content standards

Layer 4: Information (Logs and Discussions)

Time-sensitive information: work logs, discussion records, temporary decisions.

One YYYY-MM-DD_daily.md per day, covering:

• What was done
• What problems were encountered
• What to do tomorrow

This layer doesn’t need to be polished — it needs to be consistently maintained. When Claude starts a new session and reads these logs, it can quickly reconstruct “where did we leave off last time.”

CLAUDE.md: The Entry Point to Memory

Memory files alone aren’t enough. You need an “index” — something that tells Claude where these memories live and when to read them.

That’s what CLAUDE.md does.

Put a CLAUDE.md in every project root, clearly stating:

# Project Overview
- Product: AI Navigator
- Stack: Astro 5 + Tailwind + Vercel
- Key rule: must run npm run build before deployment

## Memory Structure
- knowledge/: architecture decisions, configuration notes
- logs/: daily logs — check here for last session's progress

## Common Commands
- Dev: npm run dev
- Build: npm run build
- Deploy: git push (Vercel auto-deploys)

Claude Code reads CLAUDE.md on every startup. It’s the first anchor that connects it to the project’s accumulated knowledge.

What This Looks Like in Practice

After adopting this architecture, my workflow became:

1. Open terminal — Claude Code automatically reads CLAUDE.md
2. Say “continue yesterday’s work” — it reads daily.md, knows where we left off
3. Say “deploy using the skill” — it executes the verified procedure, no improvising
4. Work done, update daily.md, seamlessly pick up next session

The biggest change: I no longer need to re-explain context. Claude became a genuine continuous collaborator, not an assistant who wakes up with amnesia every morning.

Common Mistakes

Mistake 1: Stuffing everything into CLAUDE.md

CLAUDE.md should only contain the index and the most critical rules — keep it under 100 lines. Details belong in the appropriate memory layer.

Mistake 2: Writing to memory but never reading from it

If you don’t direct Claude to read these files in CLAUDE.md, it won’t read them proactively. Explicitly tell it: “for deployment issues, check skills/.”

Mistake 3: More detail is always better

Not so. Overly detailed files dilute the important information. Keep each file focused on one topic and easy to scan.

Getting Started

If your current project has no memory structure at all, start with the minimum viable version:

1. Create a CLAUDE.md with 3–5 of the most important constraints
2. Create a notes/daily.md and start logging your work
3. When you do something for the second time, write it as a skill

A memory system isn’t built all at once. It grows through use.

Based on real-world practice in an Agentic Engineering System (30+ agent microservices) that has been running stably for 3 months.