Memoir Memoir
GitHub
All blogs
Essay

Your coding agent has amnesia, and you've been the unpaid memory layer

Memory is becoming the codebase for AI agents. Here is what version control for it looks like.

6 min read

The $100 branch switch

It's Tuesday morning. You're on a refactor branch: migrate-to-deck-gl. You spend two hours pair-programming with your agent to port map components. You implement new geospatial patterns: "No more Leaflet. Use Deck.gl GeoJsonLayer. Switch CRS from 4326 to 3857."

By noon, the agent is flying. It understands the new world.

Then, an urgent bug hits production. You git checkout main. You ask the agent to fix a quick popup in the legacy Leaflet map.

The agent suggests a Deck.gl WebGL layer.

You now have two choices, both of which cost you:

  • The Argument. You spend 10 minutes (and thousands of tokens) arguing with the agent: "No, we are on the legacy branch. Use Leaflet."
  • The Token Rent. You keep a 5,000-line CLAUDE.md to explain both versions. Even with prompt caching, you are paying a "storage tax" every time you hit enter. If you step away for ten minutes, the cache expires, and you pay full price to re-load the entire lecture.

In the AI era, branch switching has become a token burner. You are paying token rent to re-teach your agent what it already learned, simply because it doesn't understand your git state.

The "global variable" anti-pattern

Most developers work in branches to isolate work. But AI memory is usually global and flat.

  • The CLAUDE.md trap. Using CLAUDE.md as a permanent memory store is an anti-pattern. It's a giant global variable that grows until it chokes your context window.
  • The MEMORY.md cache tax. Claude Code's MEMORY.md is even more expensive. Because it's a flat file injected at the top of your prompt, every time the agent "learns" a new fact and updates the file, it invalidates your entire prefix cache.
  • The vector DB mess. "Auto-memory" uses vector search to find "relevant" text based on vibes. It pulls experimental patterns into your stable production hotfix because they "sound" similar, regardless of what branch you are on.

Memory race conditions

If you run parallel agents or share an agent across a team, it's like multiple threads writing to the same global variable without a mutex. One agent "commits" a new pattern, instantly corrupting the context for everyone else.

We are shipping memory "data corruption" as a feature.

Memory is the new codebase

The real value of a coding agent isn't just the LLM; it's the custom code stored in its memory: your repo's architecture, your team's standards, and your current branch's state.

The memory has become the codebase.

Memoir brings version control discipline to AI memory. It integrates directly into Claude Code as a set of automatic skills and hooks.

1 · Branch-aware memory

Memoir doesn't just sit next to your code; it follows it.

  • Automatic branch sync. Memoir tracks your git state. When you switch your Claude Code session to a new branch, Memoir automatically switches its internal memory branch to match. The agent's recalled facts are instantly scoped to your current branch.
  • The merge reminder. When you switch away from a feature branch that has new memories, Memoir keeps track. It provides a simple UI to review and merge these lessons into main once your code is ready. A lesson learned during a refactor isn't lost — but it doesn't leak prematurely either.
  • memoir blame. See exactly who taught the agent a specific rule.

2 · Hierarchical paths (no more "vibe search")

Memoir replaces fuzzy vector search with semantic key lookups. Instead of the agent reading a 4,000-line CLAUDE.md, Memoir's recall skill fetches the exact path needed:

  • gis.layers.rendering-engine
  • gis.crs.default-projection

This targeted retrieval keeps the prompt prefix stable and kills the token rent problem.

Tuesday afternoon, replayed

With Memoir installed as a Claude Code plugin, the migration looks like this:

Branch-aware memory in action As you check out branches, Memoir automatically swaps the agent's memory to match — keeping main's stable state isolated from refactor state. BRANCH · main [Leaflet + 4326] stable production state git checkout migrate-to-deck-gl BRANCH · migrate-to-deck-gl [Deck.gl + 3857] agent learns refactor patterns git checkout main BRANCH · main [Leaflet + 4326] memoir restores stable state
Memoir scopes the agent's memory to the current git branch — no arguing, no contamination, no token waste.

On branch migrate-to-deck-gl — the agent automatically calls remember after a decision: 

> memoir:remember "Use Deck.gl GeoJsonLayer" -p gis.mapping.config

Switching to main for a hotfix:

$ git checkout main

Memoir detects the branch change: 

Switched memory context to main. Note: migrate-to-deck-gl has 3 new memories.

When you ask the agent to fix the legacy Leaflet bug, it only sees the stable rules for main. It writes the correct fix. No arguments. No contamination. No token waste.

Try it now

Memoir is Apache 2.0 and free forever. It's built for Claude Code first — head to the install guide on the homepage to get set up in a minute.

Get started with Memoir

If memory is the new codebase, we are still writing in raw text files. Memoir is git init.