Memory That Burns Quota

Agent memory has at least three different price shapes, and operators often blend them into one alarming number.

First, always-loaded instructions occupy context every time a session begins. Second, auto memory may load a bounded index and retrieve topic files when relevant. Third, a plugin may run additional model calls to capture, compress, rank, or inject observations. All three can be useful. None should receive an unlimited budget merely because its output is called memory.

The hard part is measuring the overhead honestly. Context present in a prompt is not automatically billed at the same rate on every request. Prompt caching, provider plans, model selection, and plugin architecture change the economics. A transparent policy therefore starts with token exposure, then uses the provider’s own usage surface to understand actual quota or cost.

The operating split matters. Automater Lite’s tray and Library can keep supported records searchable without loading them into every model turn, while the local-first vault defines the redaction boundary for stored and exported history. An archive is not prompt context until an operator or retrieval tool sends material back to a model.

What Claude Code currently loads

Claude Code’s first-party memory documentation distinguishes persistent instructions from auto memory.

CLAUDE.md files contain human-authored project guidance. They are loaded into the session according to scope, so a long root file is recurring context. Anthropic advises keeping each file concise and moving specialized procedures into skills, which load only when relevant.

Auto memory is different. Claude writes notes for itself under ~/.claude/projects/<project>/memory/. The first 200 lines or 25 KB of MEMORY.md are loaded at session start; longer material should live in topic files that Claude reads when needed. Auto memory is on by default, can be toggled with /memory, and is machine-local. The main conversation’s auto memory is not automatically shared with every subagent, although a forked context can inherit content already present in its parent.

These details replace two common myths:

• Claude Code does not document an unbounded /mnt/memory/ store being replayed into every local CLI session.
• A large topic library does not mean the whole library enters every prompt. The bounded index is always loaded; topic files are retrieved on demand.

That is a better architecture than indiscriminate replay, but the index and instruction files still deserve a budget.

Four places memory can consume tokens

1. Always-loaded project instructions

A root CLAUDE.md full of build commands, architecture history, coding conventions, release procedures, and one-off incident notes may feel like a free knowledge base. It is not. Its active portion is context before the task begins.

Keep only durable, broadly applicable rules in the always-loaded layer. Put narrow workflows in skills or linked documents. A useful test is simple: if fewer than one in four sessions needs a paragraph, that paragraph probably should not load in all four.

2. The auto-memory index

The bounded MEMORY.md index is small enough to audit. Open it periodically. Remove stale preferences, duplicate facts, and observations that belong in source control. Link to topic files with clear labels so relevance retrieval has useful signals.

The 200-line or 25 KB cap is a loader limit, not a quality target. Filling it with low-value notes still wastes attention and context.

3. Retrieved topic files

On-demand recall is the useful spend: the session needs deployment history, a topic file contains the relevant decisions, and Claude reads it. The token cost is attached to a task that benefits from it.

Retrieval can still overreach. If a topic file mixes five systems, a question about one service pulls in four irrelevant histories. Split memory by decision domain, keep titles concrete, and review the retrieval behavior with /context when a session feels unexpectedly heavy.

4. Third-party capture and compression

claude-mem is a real example of a richer memory layer. Its project describes capturing tool activity, using AI to compress observations, and injecting relevant context into later sessions. That can improve continuity, but it introduces work beyond first-party file loading. The exact token and dollar cost depends on the plugin version, selected model, configuration, and how much context it retrieves.

Do not infer a universal multiplier from somebody else’s screenshot. Measure the plugin’s own calls and compare sessions with the feature enabled and disabled on the same task class.

Build a memory budget from exposure, then verify usage

Start with a model that makes no billing claim. Suppose an operator has 4,000 tokens of standing instructions and index content, starts 40 sessions in a week, and performs six deliberate recalls of 2,000 tokens each.

Weekly context exposure	Always-load policy	Retrieval-first policy
Session starts	40	40
Standing memory per start	4,000 tokens	500 tokens
Standing-context exposure	160,000 tokens	20,000 tokens
On-demand retrieval	0	6 × 2,000 = 12,000 tokens
Modeled memory exposure	160,000 tokens	32,000 tokens

The model says the retrieval-first shape exposes 128,000 fewer memory tokens across those starts. It does not say the operator will be charged for exactly 160,000 input tokens at a single rate. Some content may be cached, a subscription may meter usage differently, and the provider may count work in ways a local estimate cannot see.

Use Claude Code’s current controls to close that gap:

• /context shows what is occupying the current context window.
• /usage shows plan usage for subscription accounts.
• The Claude Console exposes spend and token reports for API billing.

Anthropic’s cost documentation explains the distinction between subscription-plan usage and API cost tracking. Keep that distinction in the article, your spreadsheet, and any internal dashboard. “Tokens in context,” “quota consumed,” and “dollars billed” are three different measurements.

Run a controlled memory audit

One dramatic session is a poor benchmark. A useful audit compares the same small task shape under two controlled configurations and repeats it enough times to expose variance.

Choose a repository with no sensitive data and a task that is deterministic but not trivial, such as locating one configuration path and explaining the validation chain. Do not use a one-line greeting: the fixed startup overhead will dominate so completely that the result says little about daily work.

For each run, record:

Field	Why it matters
Claude Code and plugin versions	Memory and usage behavior can change between releases
Model and account type	Context limits, caching, plan metering, and API rates differ
Working directory	Claude Code memory and sessions are project-scoped
Loaded CLAUDE.md files	The active instruction chain may differ by path
Auto memory state	/memory can show whether the feature is enabled
Plugin state and configuration	Capture, compression, and retrieval policies belong to the plugin
/context snapshot	Shows what occupied the context window in that run
Provider usage or Console report	Separates local estimates from the authoritative meter
Task outcome and wall time	A cheaper run that loses required context may be a false economy

Run the baseline with the production instruction set and memory features. Then change one variable: shorten the always-loaded file, disable one plugin, or replace standing content with a focused topic file. Start a fresh session for each trial so earlier conversation history does not contaminate the comparison.

The result should be a range, not a heroic percentage. Report something like “the reduced standing layer removed roughly this many tokens from /context across these five runs, while task quality stayed constant.” Do not convert that into dollars unless the account is API-billed and the Console report supports the conversion.

Finally, inspect false negatives. Did the smaller memory configuration forget a required convention, repeat discovery work, or make a wrong assumption that the baseline avoided? Memory earns budget by preventing those costs. The audit is successful when it identifies the smallest layer that preserves the outcome, not when it drives context to zero.

Classify every candidate memory item after the audit. Keep a fact in the standing layer only when it is durable and broadly useful. Move a narrow but reusable fact into a focused topic file. Leave task history in the searchable archive until a specific question calls for it. Delete duplicates, stale preferences, and information already owned by source control. Record the reason for each retained standing item so the next review can challenge the decision instead of treating accumulated context as permanent. This turns the exercise into a maintainable policy rather than a one-time cleanup.

The archive-first memory protocol

The cheapest full transcript is the one that stays on disk until a task needs it. Local search does not consume model tokens; sending retrieved text back into a model does.

Use this four-part protocol:

1. Keep the standing layer small. Reserve root instructions and the auto-memory index for durable facts that help most sessions.
2. Archive complete records. Preserve transcripts locally with their session, repository, timestamp, and provider metadata.
3. Retrieve by question. Search for a decision or incident, inspect the hit, and inject only the excerpt needed for the current task.
4. Review the meter. Compare a representative week before and after the change rather than extrapolating from a single dramatic session.

Automater Lite follows that archive shape for supported assistants: its Library imports local transcripts for search and resume, while the local token meter gives operators a fleet-level view. The archive itself is not automatically model context. A user chooses what to reopen or pass into a new exchange.

Automater Lite is free on automater.ai; Pro is $29/year.

Archive-first is not memory-off. It is a separation of concerns: retain broadly, retrieve narrowly, and pay inference cost only when recalled context helps the task.

Keep secrets out of every recall layer

Cost discipline and security point in the same direction. A credential in an always-loaded file is repeatedly exposed to model and tool contexts. A secret in an auto-memory topic can resurface later in a session with different permissions. A transcript archive can also contain secrets unless ingestion redacts them.

Do not store raw credentials in CLAUDE.md, auto memory, plugin databases, or pasted recall bundles. Use a secret manager for the value, retain only the secret’s name and operating rule, and apply the local-first vault redaction path before long-term indexing.

When auto memory is worth the overhead

Do not disable useful memory just to make a token chart look clean. Persistent project conventions, recurring environment facts, and hard-won corrections can save more context than they consume. The relevant question is marginal value:

• Did the memory prevent repeated discovery work?
• Was the recalled material relevant to this task?
• Could the same fact live in source control or a focused skill?
• Does the provider usage view confirm the overhead is material?
• Would a smaller index plus topic retrieval preserve the benefit?

Keep memory that earns its place. Move everything else out of the automatic path.

FAQ

Does Claude Code memory consume tokens?

Text loaded from CLAUDE.md, the auto-memory index, or a retrieved topic file becomes context and therefore contributes to token usage. Actual quota or dollar impact varies with caching, account type, model, and request pattern. Use /context for composition and /usage or Console reports for metering.

Does Claude Code load the entire memory directory every session?

No. Current docs say the first 200 lines or 25 KB of MEMORY.md load at session start. Separate topic files are read when relevant. Keep the index concise so it points to focused material rather than becoming the material.

Should I turn off auto memory to save quota?

Measure before disabling it. First prune standing instructions, split topic files, and compare representative sessions. Disable or replace a layer when its recurring overhead exceeds the continuity it provides.

Sources

• Claude Code memory — auto-memory location, loader limits, scope, and instruction guidance
• Claude Code costs — subscription usage, API costs, /usage, and context-cost controls
• claude-mem — third-party capture, compression, and relevant-context injection
• Automater — current Library, token-meter, privacy, and pricing claims