Skip to content

memory-explainer.md

Latest commit

 

History

History
101 lines (60 loc) · 6.07 KB

memory-explainer.md

File metadata and controls

101 lines (60 loc) · 6.07 KB

What "Memory" Means in a Coding Agent

Layer 3 of the four-layer harness. The part that maintains itself. Read this when you've used your harness for a few weeks and want to understand what's accumulating in the background.

The Short Version

Most modern coding agents have some form of persistent memory — facts they learn about you, your projects, and your preferences that survive across sessions. The mechanism varies (Claude has structured auto-memory; Gemini and Codex have evolving conventions; generic agents may have none at all), but the conceptual idea is the same: things you correct your agent on, or facts you ask it to remember, get persisted somewhere it'll re-read next session.

You don't manage Layer 3 the way you manage Layers 1, 2, and 4. Memory accumulates as a side effect of how you use your agent.

What Goes Into Memory (Typically)

Different agents store different things, but the common categories:

  • Your role and context. What kind of work you do, your stack, your common projects.
  • Operational preferences. "Use pnpm, not npm." "I prefer named exports." "Don't write git push without asking."
  • Project state. The current phase of a project, who's involved, what's blocked.
  • Past corrections. When you tell the agent "don't do X" and it persists that.
  • External references. "Bugs for this project are tracked in Linear project FOO." "Slack channel for this team is #X."

What does NOT go into memory (or shouldn't):

  • Secrets, credentials, tokens.
  • PII, customer data.
  • Anything you wouldn't want to send to the agent's hosting provider.

If you ever ask your agent to remember something sensitive, assume it lives in plain text somewhere on disk or in the agent's cloud storage. The memory layer is convenience, not security.

How Memory Differs From Rules (Layer 2)

This is the most useful distinction to internalize:

Rules (Layer 2) Memory (Layer 3)
You write them. The agent writes them (with your prompting).
They apply to all projects. They apply contextually — agent decides when to surface a memory.
They're explicit policy. They're observed facts.
You edit them in a text editor. You influence them by talking to the agent.
They live in a config directory. They live in the agent's storage layer (may or may not be a file you can read directly).

Rule of thumb: if it's a correction you'd apply across many projects, it's a rule. If it's a fact about the current state of this work, it's memory.

What To Do When Memory Drifts

Sometimes the agent remembers something stale: a project state that's changed, a preference you've since revised, a relationship that's out of date. You'll notice when the agent confidently asserts something that's wrong.

When that happens:

  1. Correct the memory explicitly. "Forget what I said earlier about X. The current state is Y." Most agents will update.
  2. Verify by asking. "What do you currently remember about X?" If the answer is still wrong, the memory didn't update; check your agent's docs for how to clear or edit memory.
  3. For Claude Code specifically: memory lives in ~/.claude/projects/<project-slug>/memory/. You can read those files directly and edit them with a text editor.

What To Do When Memory Doesn't Exist

If you're using a generic agent that has no memory layer, you have two options:

  1. Use Layer 4 (project context file) as your memory substitute. Add a section like "Current state of this work" and update it as you go. It's manual, but it works.
  2. Use Layer 2 (rules) for stable preferences that would otherwise live in memory. Less ideal because rules are global; preferences that should be project-scoped don't fit well — but it's a workaround.

The four-layer model still applies; you just collapse Layers 3 and 4 into Layer 4 if your agent doesn't have native memory.

A Pattern Worth Knowing — Memory Indexes

In the claude-harness-starter advanced setup, an MEMORY.md file is used as an index that points at detailed memory topic files. This pattern scales:

  • 1-3 sessions of memory: agent's default handling is fine.
  • 5-20 topic memories: an index file helps you (and the agent) find specific topics fast.
  • 20+ topic memories: an index is required, plus pruning.

You won't need this in your first few months. It's worth knowing as a graduation signal — when you start wanting structure in your memory layer, you're in advanced territory.

When Memory Is the Wrong Layer

Sometimes you'll be tempted to ask the agent to remember something that should be in a rule or a project file instead. Examples:

  • "Remember: always use tabs not spaces" → this is a rule. Put it in ~/.<agent>/rules/coding-style.md. Memory might forget; the rule file won't.
  • "Remember: this project uses Postgres 15" → this is project context. Put it in your project's CLAUDE.md / GEMINI.md / AGENTS.md. Memory is contextual; the project file is authoritative.

Rule of thumb (the other one): if you can imagine a future moment when the agent should have known this without you reminding it, the fact belongs in a file, not in memory.

What This Means For You

You don't need to manage memory carefully in your first few months. Use your agent. Correct it. Ask it to remember things when it makes sense. Periodically (once a month-ish) ask the agent "what do you remember about my work?" and skim the answer for accuracy.

When the answer starts containing stale or wrong things, that's the signal to engage with memory more deliberately. Until then, leave it alone — it's the layer that maintains itself.