Agent 记忆设计从零开始：构建真正持续学习的 AI 助手

Every AI conversation starts from zero. No memory of last week’s decisions, no accumulated context about your project, no knowledge of what you’ve already tried. Stateless by design.

This is the problem agent memory systems solve. Here’s how to build one — starting from a version you can set up in five minutes, scaling to a full architecture as the need grows.

Why AI Has No Memory

It’s not an oversight. Stateless design is intentional: it makes systems predictable, auditable, and easier to reason about. Each request is independent.

The cost is that every session starts cold. The AI doesn’t know your codebase conventions, your project history, your preferences, or what you decided last Tuesday.

The workaround: inject context into the session. The question is how to structure that context so it’s maintainable, accurate, and doesn’t bloat every prompt with irrelevant information.

Minimal Viable Version (5 Minutes)

Two files:

project/
├── CLAUDE.md        # project context
└── notes/
    └── daily.md     # running log

CLAUDE.md contains what the agent needs to know to work on this project: tech stack, conventions, architecture decisions, constraints. Not a comprehensive spec — just what it would take a competent developer 30 minutes to figure out by reading the code, condensed into a readable file.

daily.md is a running log of what’s happened: decisions made, problems solved, things tried. Append-only. Dated entries.

That’s it. Load both into context at the start of each session. You now have an agent that knows your project and remembers recent history.

Most projects never need more than this. Build the rest only when you have a specific problem the minimal version doesn’t solve.

Why Layer the Memory

The minimal version has a scaling problem: everything goes in one or two files, and eventually they get large, stale, and contradictory.

The core insight behind layered memory: information has different stability levels.

• Your identity and principles: change rarely, if ever
• Your capabilities and tools: change with major infrastructure updates
• Your operating procedures: change when you find better approaches
• Your domain knowledge: changes as projects evolve
• Your daily activity: changes every day

Mixing these stability levels in the same file means you’re rewriting stable information every time you update volatile information, and vice versa. The layers separate them.

Five-Layer Architecture

memory/
├── character/    # who the agent is
├── abilities/    # what it can do
├── skills/       # how it does things
├── knowledge/    # what it knows
└── logs/  # what's happening

Layer 0: Character

Identity, core principles, communication style, decision-making defaults.

This is the agent’s personality, not its task list. It changes almost never. If you’re building a coordinator agent, this is where you define how it handles ambiguity, what it prioritizes when there’s a conflict, how it communicates.

Example content: “When requirements conflict, ask for clarification rather than guessing. Prefer reversible decisions. Write in direct, specific language.”

Layer 1: Abilities

Capability declarations and the heartbeat mechanism.

The heartbeat file (heartbeat.yaml) is where the agent knows its own state:

can_do:
  - manage project requirements
  - write to memory files
  - execute bash commands

cannot_do:
  - access external services directly
  - modify files outside the project directory

This layer also tracks what tools and integrations the agent has access to. It changes when infrastructure changes.

Layer 2: Skills

Operating procedures — SOPs for recurring tasks.

Write a skill the second time you do something. The first time, you’re figuring it out. The second time, you know enough to write the procedure. After that, the agent follows the procedure instead of rediscovering it.

Each skill file is one procedure: deploy a site, update the changelog, triage incoming requests. Short, step-by-step, immediately actionable.

Layer 3: Knowledge

Structured domain knowledge. One topic per file. Target: under 100 lines.

This is where you put things that are true for months at a time — architecture decisions, API documentation, system design rationale, known constraints. Not what’s happening (that’s Layer 4) — what’s true.

The under-100-lines rule forces specificity. If a file keeps growing, it’s probably covering multiple topics that should be split.

Layer 4: Information

Daily logs, event-driven notes, session summaries.

This is the highest-velocity layer. Daily logs go here. So do notes from specific events: a debugging session, a design discussion, a deployment incident.

File naming: date-based (2026-03-15_daily.md) or event-based (2026-03-15_discuss_auth-design.md). The date makes retrieval easy; the event suffix makes it human-readable.

CLAUDE.md as the Index

With a five-layer structure, CLAUDE.md isn’t the content anymore — it’s the index.

It tells the agent how the memory system is organized, what each layer contains, and how to navigate it. The actual content lives in the layer files.

This keeps CLAUDE.md short and stable. It doesn’t need to change when you add a new skill or update a knowledge file. The index points to the content; the content lives where it belongs.

Phased Build Order

Don’t build all five layers at once. Build the layer you need, when you need it.

Week 1: Minimal viable (Layers 0 and 4 only)

• CLAUDE.md with project context
• Layer 0: write down the agent’s core principles
• Layer 4: start a daily log

You have an agent with identity and memory. That’s enough to start.

Week 2: Add operating procedures (Layer 2)

• When you do something for the second time, write the skill
• Start with the most frequent task

Week 3: Formalize knowledge (Layer 3)

• When you explain the same thing to the agent twice, that’s a knowledge file
• Architecture decisions, system constraints, recurring context

Ongoing: Maintain Layer 1

• Update abilities when tools change
• Review heartbeat when the agent gets something wrong about its own capabilities

The Decision Criterion

When you’re unsure whether something belongs in memory: If all conversations were cleared tomorrow, would the agent still need this information to do its job?

If yes, it belongs in memory. If no, it can stay in the conversation.

This criterion also helps with placement. Information the agent needs every day goes in the layers that load every session (0, 1, 2). Information specific to a project phase goes in Layer 3. Recent events go in Layer 4.

What This Buys You

An agent with layered memory doesn’t forget your conventions. It doesn’t ask you to re-explain your architecture. It doesn’t repeat mistakes that are already documented. It gets more useful the longer you work with it, because the memory accumulates.

The investment is writing things down — which you should probably be doing anyway. The return is an AI collaborator that actually knows your project.

Start with the minimal version. Add layers when you hit the ceiling. The architecture scales with the work.