Claude Code memory without polluting global config

Claude Code's persistent memory feature lets the agent remember facts about you and your work across sessions. Used right, it's a productivity multiplier. Used wrong, your memory becomes a junk drawer that drags down every session.

This post is the practical hygiene playbook.

What memory is in Claude Code

Memory is durable context — facts the agent retains across sessions. Different from:

• CLAUDE.md: explicit, file-based, version-controlled. You write it.
• Conversation history: ephemeral within a session.
• Memory: agent-managed, persisted, recalled automatically when relevant.

The agent saves to memory when something seems durably useful. The user can also explicitly say "remember that I prefer X."

What's worth remembering

Three categories of useful memory:

Category 1: user profile facts

Things about you that don't change session-to-session:

• "User is a Swift / TypeScript developer."
• "User runs macOS, primarily M-series hardware."
• "User prefers concise responses; doesn't need long explanations."
• "User is comfortable with vim and tmux."

These are true regardless of which project. Save in global memory.

Category 2: durable preferences

Workflow-level preferences that apply broadly:

• "User prefers to commit frequently rather than in big batches."
• "User likes function tests written before the function (TDD)."
• "User uses feature flags rather than long-running branches."

These shape how the agent operates across projects.

Category 3: project-specific durable rules

Things specific to a project that don't change:

• "In mq-dir, every Codable type hand-rolls init(from:) for migration."
• "In our SaaS, all API routes go through the auth middleware in lib/auth.ts."

These belong in project-scoped memory or, equivalently, in the project's CLAUDE.md.

What's NOT worth remembering

The biggest source of memory pollution is letting the agent save things that should be ephemeral:

Session progress

"Yesterday we refactored auth; today we're working on docs."

This is session log, not durable knowledge. Don't persist.

Current bug states

"There's a flaky test in tests/auth/login.test.ts."

If you fix the bug, the memory becomes stale. Don't persist; investigate fresh each session.

Specific code locations that change

"The validation code is in src/lib/validate.ts."

Files move and get refactored. The memory rots. Either include in CLAUDE.md (where it can be updated) or skip.

Conversational chatter

"User said 'thanks' on 2026-04-22."

The agent occasionally tries to save things like this. They're noise. Prune aggressively.

Decisions that haven't settled

"Considering switching from React to Solid."

Until the decision lands, it's just ambient possibility. Don't memorialize.

The hygiene rules

Three rules that keep memory clean:

Rule 1: Memory is for facts, not events

Facts: "User is a Swift developer." Events: "User asked about Swift on April 22."

Memory should hold facts. If it has events, you've corrupted it.

Rule 2: If it'll be wrong in 3 months, don't persist

"User is currently debugging auth" → wrong in 3 days. Don't save. "User uses Repository pattern in mq-dir codebase" → still right in 3 months. Save.

Rule 3: Quarterly review

Once a quarter, look at your memory:

• Anything irrelevant? Remove.
• Anything stale? Update or remove.
• Anything durable that's missing? Add.

Memory rots if not maintained.

What good memory looks like

Example memory entries (all useful, all durable):

- User is a Swift / TypeScript developer building macOS apps.
- User prefers concise responses (under 200 words for most questions).
- User uses Cursor for editing, Claude Code for delegated work.
- User commits frequently with DCO sign-off (git commit -s).
- User keeps a flat prompt library at ~/dev/_shared/prompts/.
- User's mq-dir project uses SwiftUI/AppKit, mqdirCore as a separate target.
- User's mq-dir requires every Codable change to have a migration test.
- User maintains zero telemetry posture across mq-dir; don't suggest analytics.

Eight entries, all durably true. Each adds context without being session-specific.

What bad memory looks like

- User asked about auth on 2026-04-22.
- User said the test is flaky in login.test.ts.
- User is considering hiring a designer.
- User mentioned they slept poorly last week.
- User likes pizza.
- User's git rebase failed yesterday.

Six entries, all noise. None will be useful in future sessions; some will actively mislead.

Pruning workflow

Quarterly memory review:

Step 1: list current memory

Open the memory file (location varies by Claude Code version; check docs).

Step 2: classify each entry

For each entry, mark:

• Keep: durable fact, still true.
• Update: durable but slightly outdated (refine).
• Remove: ephemeral, stale, or noise.

Step 3: prune

Delete the "remove" entries. Update the "update" entries.

Step 4: add what's missing

What facts about your work would you want the agent to know but currently don't? Add as memory entries.

15-30 minutes per quarter. Memory stays useful indefinitely.

Project-specific memory vs global

A common question: where does each piece of context belong?

The pattern: global = personal preferences. Project = codebase facts. Session = current task. Memory should align with global; project facts should be in CLAUDE.md.

When memory and CLAUDE.md disagree

If memory says "use TypeScript strict" and a project's CLAUDE.md doesn't enforce it, the agent might apply your preference (memory) to a project that doesn't follow it.

Mitigation: project CLAUDE.md should be authoritative for project-specific behavior. Memory should be personal preference that gives way to project rules.

In practice: the agent usually handles this correctly — project context wins over personal preferences.

What never to memorize

Three categories never put in memory:

Secrets

API keys, passwords, internal URLs. Memory is persisted to disk; it's a security surface. Don't store anything that needs to be confidential.

Client-confidential information

If you're consulting and have client-specific context, don't put it in memory. It'll bleed into other client work.

Personal sensitive information

Health, finances, family. The agent doesn't need them; they shouldn't be in a tool's persistent storage.

File-manager setup for memory hygiene

mq-dir setup for the quarterly review:

• Pane 1: the memory file (~/.claude/memory.json or wherever).
• Pane 2: project CLAUDE.md files (browse).
• Pane 3: notes — your classification of each memory entry.
• Pane 4: cmux pane to test changes (start a fresh session and see if the agent's behavior matches your intent).

Routine quarterly housekeeping. Memory stays useful.

Common abuse patterns

Three patterns to watch for:

"Just save it for context"

Every fact gets memorized "in case it's useful later." Memory bloats with noise.

Counter: memorize only if it'll matter in 3 months.

Trusting auto-saved memory

Claude Code auto-saves things it thinks are durable. The judgment isn't perfect. Review periodically; the agent's "this is a fact about you" can be wrong.

Not pruning

Memory accumulates. Sessions slow down (more context). Old facts contradict new behavior. Prune.

Mistaking memory for documentation

Memory is the agent's working knowledge. Documentation is for humans. They overlap but aren't the same. CLAUDE.md is the documentation; memory is a complement.

Verdict

Claude Code memory is useful when curated, harmful when ignored. The hygiene:

1. Persist facts, not events.
2. Skip anything that'll be wrong in 3 months.
3. Quarterly review (15-30 minutes).
4. Project-specific stuff goes in CLAUDE.md, not memory.
5. Never persist secrets / confidential info.

Used right, memory adds 5-10% to AI productivity by removing repeated explanations. Used wrong, it adds noise that costs more than it saves.

The default Claude Code behavior is reasonable but auto-saves can be over-eager. Quarterly review keeps things clean.

mq-dir helps in the review (panes for memory file, CLAUDE.md, notes, test session). Free, MIT, pairs with the workflow.