Memoir Memoir
GitHub
All blogs
Essay

Your second memory file: Claude Code's notebook meets Memoir's repo

Claude Code's auto-memory is the agent's private notebook. Memoir is the project's branchable, queryable archive. Here's how to use both — and why parallel work breaks the first one.

5 min read

Two systems, two jobs

Claude Code ships with a memory system already running. Memoir is a separate Claude Code plugin you install alongside it. They solve different problems.

  • Claude Code's auto-memory (built in). A flat file at ~/.claude/projects/<slug>/memory/, indexed by MEMORY.md and injected at the top of every session. The agent writes to it whenever it learns something durable — your role, preferences, corrections, project context — organized by type (user, feedback, project, reference).
  • Memoir (Claude Code plugin, opt-in). A git-like memory store at ~/.memoir/<slug>/, accessed through the memoir:recall and memoir:remember skills. Memories live on branches that follow your git branches, organized by semantic taxonomy paths (context.*, knowledge.*, preferences.*). A Stop hook auto-captures at the end of each turn.

Auto-memory is the agent's private notebook — what it remembers about you. Memoir is the project's shared archive — what the repo remembers about itself, on a specific branch, in a form any tool can read.

Auto-memory belongs to the agent. Memoir belongs to the repo.

Where the notebook breaks

Even as a solo developer, you feel the leak the moment you switch tasks: yesterday's refactor lessons sit in MEMORY.md when you check out main for today's hotfix. Run two or three agents in parallel and a flat file handles concurrent contexts the way a global variable handles concurrent threads: badly. Since auto-memory shipped, the same complaints keep surfacing — in three flavors.

Reliability and decay

  • Instruction drift. The agent recites a "lesson learned" from last week, then fails to apply it. The fact is in the file; the behavior doesn't follow.
  • Context rot. Memory files accumulate stale debugging notes and "yesterday" timestamps that lose meaning as weeks pass. Nothing expires.
  • Worktree mismatch. Memory is keyed by folder path, so parallel worktrees each get their own MEMORY.md — with no shared trunk and no merge story. Concurrent writes are last-write-wins.

Security and privacy

  • Secret leaks. Nothing stops the agent from auto-saving an API key from a .env file or chat log into a plaintext memory file.
  • Cross-project pollution. Global memory triggers have surfaced references from unrelated projects mid-session — reportedly during client demos.
  • Memory poisoning. Researchers have demonstrated attacks where a hostile document forces the agent to write incorrect or insecure memories that persist across sessions.

Workflow and performance

  • Context bloat. Auto-injecting memory at the top of every session is, in practice, context stuffing — background noise that can degrade reasoning on hard tasks.
  • False confidence. The presence of memory creates an illusion of reliability. Users skip verification because the agent "already knows" — until it doesn't.

These aren't separate bugs to patch. They're symptoms of the same shape: a single, mutable, plaintext heap with no scope, no expiry, and no audit trail.

Branched memory, by example

Memoir's model maps onto how you already think about parallel work. Each git branch gets a memory branch. Lessons learn on the branch where they were taught. Merging is explicit.

Three parallel agents, three memoir branches, one trunk Three Claude Code sessions run in parallel against three git worktrees. Each session has its own memoir branch, scoped to the git branch it's on. Lessons merge back to main when the work does. TRUNK · main memoir/refactor-deck-gl agent A · port map components learns: Deck.gl, CRS 3857 memoir/hotfix-popup agent B · fix legacy popup sees only: Leaflet, CRS 4326 memoir/spike-tile-cache agent C · prototype cache learns: throwaway, won't merge memoir-sync-branch
Each parallel agent learns on its own branch. Useful lessons merge back to main; throwaway spikes stay isolated.

You spin up three worktrees for three concurrent tasks:

$ git worktree add ../app-refactor    refactor-deck-gl
$ git worktree add ../app-hotfix      hotfix-popup
$ git worktree add ../app-spike       spike-tile-cache

Open Claude Code in each. Memoir's SessionStart hook reads the git branch and switches its memory branch automatically. Agent A learns Deck.gl patterns on memoir/refactor-deck-gl; Agent B sees a clean Leaflet world on memoir/hotfix-popup and writes the right fix; Agent C tinkers on memoir/spike-tile-cache without poisoning anyone else. When the refactor lands, the lessons land with it: 

$ /memoir:memoir-sync-branch refactor-deck-gl

The spike branch never merges — its memories stay where they were learned, invisible to everyone else.

When to reach for which

They aren't competitors — a healthy setup uses both.

  • Auto-memory for facts about you: role, tooling preferences, corrections. Single-context and personal — let Claude Code maintain it.
  • Memoir for facts about the project on a specific branch: architectural choices, workaround rationales, refactor patterns. Anything you'd want another agent to query without re-reading your transcript.
  • Always Memoir when more than one agent is touching the repo at once. A flat notebook can't isolate three simultaneous contexts. A branched store can.

Try it now

Memoir is Apache 2.0 and ships as a Claude Code plugin. Install takes a minute — head to the quickstart on the homepage.

Get started with Memoir

Auto-memory is fine when you're alone in the editor. The moment you aren't, you need branches.