A couple of months ago I wrote a note into my coding agent’s memory about a Terraform quirk that had just cost me twenty minutes. A week later, in a different project, I hit the exact same problem — and the agent had no idea we’d already been here. The note existed. It just lived somewhere the agent wasn’t looking.

That’s a smaller version of a problem I kept running into, in three different shapes.

The problem with vanilla memory

Most coding agents ship with some notion of persistent memory, and it’s usually not enough, for three specific reasons:

Project memory is scoped by working directory, and the naming hides it. A memory directory keyed to your current path only loads when the path matches. It isn’t global, no matter what it’s called, and that’s the kind of thing you only discover once you’ve written a note that quietly never surfaces again.

One global config file is the only place that’s actually global. Stuffing every learning into it bloats every session’s context — a note about Terraform state now taxes a session that’s just reading logs.

There’s no path from “I learned this” to “my team benefits.” Personal memory, team conventions, and shareable automation are three different shapes. Without an explicit pipeline between them, learnings stay personal forever, one engineer at a time relearning the same lesson.

The 5-layer model

The fix is a small hierarchy, narrow to wide, with an explicit rule for promoting a pattern upward as it proves itself:

Layer	Where	Path (Claude Code convention)	Scope	What lives here
1	Project memory	~/.claude/projects/<cwd>/memory/	Per-project, keyed to the working directory	Experiments, in-flight work, project-specific facts
2	Cross-project memory	~/.claude/memory/	Every session you run	Topical files — one per subject that comes up across projects
3	User-level config	~/.claude/CLAUDE.md	Every session, unconditionally	Orchestration rules only — no topical detail
4	Team-level config	<repo>/CLAUDE.md	Teammates, checked into the repo	Repo conventions, shared context
5	Skill plugin	<shared-plugin-repo>/plugins/<name>/	Anyone, via a package manager	Auto-triggers on relevant tasks

Rule of thumb: a pattern that bites you in two or more projects gets promoted to layer 2. A pattern general enough that your teammates would want it gets promoted to layer 4 or 5. Layer 3 — the one config file that loads unconditionally, every session, forever — is reserved for orchestration rules only. Nothing topical belongs there; every topical fact you put in it, you pay for in every unrelated session for the rest of time.

Layer 2, in practice

Two months in, my cross-project memory was six files and an index: alerting and dashboard quirks, Kubernetes cluster contexts, a PR-review template plus a note on keeping PR comments brief, an auth quirk for one CI system, and a rule that production changes go through the CI pipeline, never a manual session into the box itself. Nothing exotic — just a directory referenced from the one config file that’s genuinely global, so the agent knows to check it. (The layer-2 idea itself I owe to a post by youngleaders.tech — worth reading if this shape resonates.)

The promotion loop

A hierarchy with no promotion discipline just becomes five separate graveyards instead of one. So there’s a loop, driven by a hook — a small script the harness runs automatically at a fixed point in every session, in this case every time I type a prompt:

1. Save with intent. When I write a memory that might generalize beyond the project it came from, I flag it as a graduation candidate right in its own metadata.
2. The hook surfaces candidates. Every four days, it injects a review prompt listing every flagged memory that’s been sitting for a week or more.
3. Decide and act. Promote it to the right layer, clear the flag, or delete it. The loop is tight on purpose — no accumulating backlog of “maybe someday.”
4. A separate nudge catches session learnings before they evaporate — triggered by a few hours of growth, by approaching a context limit, or right after a push, prompting a capture before the session ends and the insight goes with it.

Measured over enough sessions to trust the numbers: the consolidation nudge converts to an actual written memory about 70% of the time (n=40). The promotion review converts to a real action — promote, clear, or delete — about 66% of the time (n=6, small enough to treat as a first data point rather than a settled number). Both matter more than their precision suggests: the alternative to “measure it and iterate” is a memory system that either never grows or never gets curated.

Why the discipline is worth it

For me, day to day, the four-day cycle forces a decision on every candidate — promote or discard — so nothing lingers half-useful forever. For a team, the top layer is the actual bridge from personal habit to shared default: a pattern that started as one engineer’s private note can end up as a skill that auto-triggers for everyone. A few patterns have already made that jump for us: how to fill out a PR description template, keeping PR comments and review feedback genuinely brief instead of padded, checking a PR’s or ticket’s actual current state directly instead of asking a person first, and validating a Kubernetes custom resource against its real source code instead of trusting docs that have drifted. Distributed the same way any other shared package would be — nobody has to remember the convention; the tooling pulls in the right context on its own, the same way it does for the person who wrote it.

Try it yourself

Three steps, in order:

1. Create a cross-project memory directory with an index file. Start with one or two topical files — the things that bite you in more than one project.
2. Reference it from your global config, so the agent knows to check it every session.
3. Tag promotion candidates as you write them. Even without an automated hook, a flag on a memory that feels like it might generalize is a future signal you’ll thank yourself for.

Then upgrade incrementally: automate the promotion review, and once you have a cross-cutting pattern that’s proven itself, package it as something a teammate can install rather than something they have to be told about.

Two months after building this, the same architecture — one small pattern of writing something down, maintaining it, and recalling it when it matters — turned out to generalize a lot further than I expected: to task state across sessions, and eventually to letting the agent review its own pull requests. That’s the next post.