Claude Code agents running out of memory? Check which memory first

Claude Code agents running out of memory? Check which memory first

Claude Code agents running out of memory have hit RAM, the context window or recall between sessions. The fix depends on which one ran out, from stopping one leftover process to a line in CLAUDE.md.

Aaron Delasy
Aaron Delasyfounder

Claude Code agents running out of memory fail in three ways: Linux kills the process, autocompact thrashes on a full context window, or a new session forgets yesterday's correction. The fix for one does nothing for the other two. Worse, the blunt workaround from one GitHub thread, pkill -9 -f "claude", ends every healthy session along with the broken one. I checked each command and number below against Anthropic's docs and the linked issues on November 18, 2026.

Find out which memory ran out first

Anthropic's troubleshooting guide treats high memory use and a thrashing autocompact as two problems with two sets of fixes, so match the symptom to a row before changing anything.

What you seeWhat ran outFirst move
Out of memory and Killed process for claude in dmesg, or exit code -9RAM on the machineList every Claude process with its parent
The critical memory usage warning in one sessionThat session's heap, past 2.5GBRestart it and run claude --continue
A session pinned at 100% CPU right after an updateNothing yet; the release is the suspectCompare claude --version with open memory issues
Claude Code says autocompact is thrashingThe context window/compact with a focus, or hand the job to a subagent
A new session repeats a mistake you corrected yesterdayRecall between sessionsWrite the decision into CLAUDE.md

One Claude Code session grew from 467MB to 7.5GB in 20 seconds

GitHub issue #22042 reports Claude Code 2.1.27 growing from about 467MB to 7.5GB within 20 seconds of a one-word prompt, until Linux killed it.

The reporter's VM had 8GB of RAM and 4GB of swap. Its dmesg log shows the kernel's OOM killer ending the claude process. By the reporter's account, the growth began when a second session started while the first was still running. A VM with 39GB froze the same way. Rolling back to 2.1.25 held each session at about 470 to 550MB. The issue's advice is blunt: "Maximum 2 concurrent Claude Code sessions per machine, running 2.1.25."

Bar chart of Claude Code memory in GitHub issue 22042: version 2.1.25 steady at about 470 to 550MB, version 2.1.27 at 467MB on launch, about 5.0GB fifteen seconds later and 7.5GB when the OOM killer ended it, against the 8GB of RAM on the reporter's VM and Anthropic's 4GB minimum

GitHub shows the issue locked as resolved on February 19, 2026, yet no maintainer in the thread names a fix version. Memory fixes kept shipping after that. The changelog entry for 2.1.323 fixes "a memory spike at the next prompt after Claude changed a very large file". Version 2.1.327 fixes "the screen staying blank or frozen after a brief out-of-memory error".

Anthropic lists 4 GB+ of RAM as the hardware requirement for Claude Code. Version 2.1.27 went through nearly twice that in 20 seconds.

So before I blame my own workload, I run claude --version and look for open issues with the perf:memory label on that version. If nothing matches, the troubleshooting guide suggests restarting with claude --safe-mode to check whether a plugin, MCP server or hook is behind the high memory use.

For a session that keeps growing, /heapdump writes two files. Anthropic says the -diagnostics.json is safe to attach to a GitHub issue. The .heapsnapshot holds the full conversation and any credentials the process held. I delete it once I'm done (and I never attach it anywhere).

Parallel sessions on one machine share one RAM budget

In a Claude Code agent team, each teammate "runs as a separate Claude instance," so every teammate you add draws on the same machine's RAM.

Sessions you start by hand in separate worktrees add up the same way. A worktree keeps their files apart; the machine stays shared.

Leftover processes count too. In an Aperant issue, Query.close() in the Python claude-agent-sdk hung at 100% CPU and left a Claude Code subprocess alive after every agent session. Memory piled up until the OOM killer ended processes mid-build with exit code -9. The issue closed in January 2026 with a suggestion to try the latest version. On any machine that runs SDK agents, leftovers are the first thing I'd look for.

One machine's RAM shared by a hand-started Claude Code session, a second session in a worktree, two agent team teammates, a leftover SDK subprocess, plugins and MCP servers, and the editor and browser, with the kernel's OOM killer ending a process once RAM and swap run out

To see where the memory went, I list every Claude process with its parent, its age and its resident memory in kibibytes:

bash
ps -eo pid,ppid,etime,rss,args | grep '[c]laude'

Killing every claude process takes the healthy sessions down too

The Aperant workaround, pkill -9 -f "claude", kills every process whose full command line matches claude, including every session that was working fine.

A leftover is easier to target. Its parent PID points at the app that started it. Once that app exits, the parent becomes init or the nearest subreaper, because Linux hands an exiting process's children to them. The etime column gives each process's age. A Claude process hours older than any session I have open stands out, and I stop that one by PID:

bash
# Claude processes whose parent is init
pgrep -P 1 -f claude

# stop one leftover by its PID
kill 12345
Two ways to free memory from Claude Code: pkill -9 -f claude ends four healthy sessions along with one leftover process, while the targeted path lists processes with their parent and age, stops only the leftover by PID, moves transcripts over 50MB to a backup folder and pins a version that works

Transcripts came up in the #22042 thread as well. One commenter found a 3GB JSONL file full of duplicate entries and wrote that once they truncated it, "the issue disappeared." Another deleted every transcript over 50MB. Claude Code keeps each one at ~/.claude/projects/<project>/<session>.jsonl and deletes it after cleanupPeriodDays, 30 days by default. I move big transcripts aside instead, so I can put back a session I still want to resume:

bash
mkdir -p ~/claude-transcripts-backup
find ~/.claude/projects -name "*.jsonl" -size +50M -exec mv {} ~/claude-transcripts-backup/ \;

A lower cleanupPeriodDays in settings keeps the folder from growing back, down to a minimum of 1 day.

Deleting all of ~/.claude, the other fix in that thread, costs more than it saves. The directory reference says removing ~/.claude/projects/ loses resume, continue and rewind for past sessions plus auto memory for every project. Your login lives in ~/.claude/.credentials.json, so it goes too. For one project, claude purge <path> --dry-run prints the deletion plan without deleting anything.

Then I pin a version that works. On a team I'd rather pick the day the CLI changes than learn it from a crash. Per the setup docs, curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89 installs one version, and DISABLE_AUTOUPDATER set to "1" in the settings env stops the background update check. The stable channel is gentler. It serves a version about a week old and skips releases with major regressions. It's what I'd give a team that doesn't read release notes.

Context and recall run out in different ways

Each Claude Code session begins with a fresh context window, so a long session fills its own window while a new one knows only what CLAUDE.md and auto memory hand it.

Context and recall in Claude Code compared: the context window is written by the session, starts empty every session and is cleared with /compact, /clear or a subagent; CLAUDE.md is written by you and loads at every session start; auto memory is written by Claude, loads its first 200 lines or 25KB at session start and turns off with /memory

For a full context window, /compact takes a focus, such as /compact keep only the plan and the diff. /clear starts over between tasks. A subagent does a verbose job in its own context window. When Claude Code reports that autocompact is thrashing, the troubleshooting guide also suggests reading a big file in chunks instead of whole. And between unrelated tasks I'd rather /clear than /compact.

Recall between sessions comes from two sources that load when a session starts. CLAUDE.md is the file you write. Auto memory holds the notes Claude writes for itself, and only its first 200 lines or 25KB load. A correction that lives only in the chat ends with that context window unless auto memory saved it. I put the ones that matter into CLAUDE.md and share that file with the team like code. If auto memory fills up with noise, /memory turns it off. CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 does the same from the environment.

How Aldena sizes the RAM each conversation gets

Aldena runs each conversation in its own sandbox on a provider the team connects, such as Boat, at a default size an owner or admin picks when creating the project.

Aldena is my product, so weigh this section with that in mind. A conversation is a chat plus every chat its agents hand work to. Every agent in it shares the one sandbox, Claude Code included.

Boat sizevCPURAMNote
small24 GB
standard48 GB
large816 GBNot on Boat's free trial
x-large1632 GBNeeds a Boat plan of $100 a month or more

The project's settings keep the default under server, and any change there applies to new conversations. I size for the heaviest thing a conversation runs. Anthropic's floor for Claude Code is 4 GB, which is all of a small sandbox. A conversation that also builds the app and runs its test suite gets standard or larger from me.

An Aldena project on Boat whose default sandbox size changes from standard, 4 vCPU and 8 GB, to large, 8 vCPU and 16 GB, with two conversations started before the change in their own standard sandboxes and a third started after it in its own large sandbox, each holding a Claude Code agent and the agent it delegates to

Boat bills machine time per second to the team's own account while the sandbox runs. Aldena adds nothing on top. The sandbox sleeps 30 minutes after its last command and wakes with the conversation's next turn, so a bigger size costs more only while it runs.

Each project stays on its Claude Code and Codex versions until an owner or admin updates it. A release like 2.1.27 reaches a project only when someone picks it. For recall, agent memory gives each agent a private memory of up to 50 entries and each project a shared one of up to 100, at 500 characters an entry. Both outlive the chat that wrote them. Writing past a cap fails until someone prunes an entry. The cap annoys me a little, and it's also what keeps that memory short enough to read.

Sandboxing coding agents covers what a sandbox keeps apart beyond memory. For one developer running two sessions, I wouldn't pay for any of this. I'd pin a version first, since rolling back to 2.1.25 steadied the sessions in #22042, then check ps for leftovers before anyone types pkill.

ready when you are

spin up your first project.

one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.