Claude Code Memory Feature Tested: 26 of 45 Entries Were Never Read — Should You Turn It Off?

For AI to work effectively in a codebase, it needs to understand what the codebase looks like, where things live, and how to get things done. Over the past few years, countless developers have experimented with systems, plugins, and "memory" mechanisms to automatically encode "how things should be done" into an agent's brain. Theo (t3.gg) threw cold water on that entire approach in a recent video, backing it up with a sobering real-world test on his own machines.

This article draws on Theo's test results alongside a conversation between Pi creator Mario and Flask creator Armin to trace a growing consensus in the AI coding world: code doesn't need a separate memory system.

The Core Argument: Code Is Truth, Memory Is Unnecessary Maintenance Overhead

Mario's opening line in the conversation is sharp enough to stand on its own: "For programming, I don't need a memory system. Code is truth — it's the ground truth, and it's always evolving. I don't need another place that needs to be maintained. I already have a codebase to maintain."

Theo agrees completely. He points out that even code comments go stale: a comment explains why the code was written a certain way, but the code changes while the comment doesn't — and now that comment has gone from "useless" to "actively harmful." It leads both humans and agents in the wrong direction.

The more fragmented the information, the worse the split-brain problem becomes. Change something in one place, forget to sync it elsewhere, and the whole system breaks down. In the AI era this problem is even more widespread — people casually drop markdown planning files into repos, and months later those files are badly out of date, continuously poisoning the model's context.

bash Is All You Need

Another key insight from the conversation: bash is all you need. Mario and Armin, coming from different directions, both found that today's models are natively trained to be good at using bash. Give them tools and bash, and they can reliably find what they need.

Theo points to Cursor as compelling evidence. The Cursor team was once the company that pushed AST, embeddings, and code graphs to their limits — they built their reputation on dynamically feeding models "exactly the right context." Back then, Cursor's CEO Michael loved to talk about how context windows would keep growing until they could hold an entire codebase.

But Claude Code proved a different path works: you don't need fancy dynamic context graphs. Give the model tools and bash, and it will find what it needs on its own. Once models started being trained to work this way, those complex context management systems lost their purpose. Even Cursor itself has largely abandoned the code traversal system that originally made them famous.

Theo's conclusion is direct: "If you're still building fancy context management systems instead of just giving the agent tools to find things, you're already behind the curve."

AST (Abstract Syntax Tree) is a tree-shaped representation of code that captures syntactic relationships in a language. Embeddings map code snippets to high-dimensional vectors, enabling retrieval by semantic similarity. Code graphs explicitly model relationships like function calls and module dependencies as graph structures. Together, these three technologies formed the technical foundation of "traditional RAG-style" code understanding — systems that pre-parse the entire codebase and dynamically retrieve the most relevant snippets to stuff into context before the model generates a response. Cursor's early competitive advantage was precisely how refined this pipeline was. The rise of Claude Code shows that once a model is sufficiently trained to be an agent that "uses tools to find things," the pre-processing index and retrieval layer becomes extra engineering overhead rather than a real moat. bash commands like grep, find, and git log are essentially a flashlight for the model — letting it explore the codebase when it needs to, rather than relying on a pre-mapped route.

The Damning Test: 45 Memory Entries, 26 Never Read

The most valuable part of the video is Theo running a live test on his own machines. While developing t3 code across multiple machines with Claude Code and Codex, he noticed agents frequently writing to memory and decided to investigate what was actually being stored.

The results were painful:

• On one machine, the only memory entry was a feature spec from 9 days ago for something he never intended to ship;
• The main clone had 45 memory entries, including things like "onboarding redesign" and "sidebar redesign preference variant C" — long-outdated temporary states;
• Many entries were point-in-time status records (whether a certain PR was merged, whether a certain leak was fixed, whether an outdated GitHub CLI version had been updated) — the moment time moves on, these become actively misleading;
• A lot of content duplicated AGENTS.md — rules that should be read by every agent were being redundantly stuffed into memory instead.

The most damning data came from usage frequency: across more than 355 sessions on that machine, only 19 had opened any memory file, while 80 sessions had written to or edited memory — a 3:1 write-to-read ratio. And of the 45 memory entries, 26 had never been read even once.

Theo made the call on the spot: disable Claude Code memory across his entire cluster, archive and tag everything, then delete it all. "I knew it was going to be bad, but I didn't think it was going to be this bad."

The Alternative: Build Knowledge Into Architecture, Not Into Memory

So what's the right approach after turning memory off? Theo lays out a layered framework, drawing on a value-ordering model from Lauren (potato) — a former React ecosystem engineer, now at Cursor — which says every time you correct an agent, you should ask yourself how to completely eliminate that mistake.

Layer one: eliminate entire classes of errors through architecture. This is something Theo has been doing since before the AI era, and it's why he built t3 stack and why he loves tRPC and Convex — end-to-end type safety between frontend and backend makes whole categories of bugs disappear. He shared a real example: t3 code's data transfer layer had ballooned to tens of megabytes for loading a single thread. After optimizing it down under 10K, regressions kept creeping back. So he added a complex check to CI that replays real threads, measures actual WebSocket data transmission, and sets a ceiling 30% above the optimized baseline. Any change that crosses the line fails the PR outright. "Now when the agent's changes cause a regression, it fixes it before telling me it's done."

Layer two: lint rules or tests. If the architectural layer can't eliminate the problem, catch it in CI so the agent finds the issue before bothering you.

Layer three: skills and rules. Theo emphasizes that skills should be a safety net and fallback — not something you pile onto reflexively. They're better suited to process-related concerns (like exposing a server remotely) than to the code itself.

The Right Way to Write AGENTS.md: Convey Direction, Not Corrections

Theo showed off his "least generic" AGENTS.md, built around one core idea: don't just tell the agent what it's not allowed to do — help it understand how you want it to think.

His AGENTS.md starts by explaining "what this is" and "how it works," then uses a section called "what makes t3 code special" to communicate direction:

• Open-source first — reminds the model not to suggest closing off any part of the codebase (the model has genuinely made such suggestions);
• Remote ready — emphasizes that the remote experience matters, so the model doesn't call something done after it only works locally;
• Glossary — gives agent and human a shared vocabulary;
• Taste — encodes collaborator Julius's preferences (complexity converging at adapter boundaries, no unnecessary any types, comments that describe purpose rather than line-by-line annotation) to continuously calibrate direction.

Theo holds up a quote from Uncle Bob as a guiding principle: "Imposing human discipline on agents might be wrong, but imposing human values on agents is not."

AGENTS.md (sometimes called CLAUDE.md or Cursor Rules) is a plain-text file stored at the root of a repository. At the start of every new session, it's automatically injected at the very front of the model's context window — effectively "the first thing you say every time you wake the agent up." Its priority sits above generic system prompts but below real-time instructions the user gives during a session. Because every session starts with an empty context, AGENTS.md is currently the most reliable vehicle for cross-session "persistent knowledge" — unlike automatic memory with its random writes and near-zero read rates, it's content the developer deliberately curates that gets read every single time. Theo's emphasis on "conveying direction" in how you write it is fundamentally about exploiting this mechanism's stability: rather than using it as a patch ("don't use console.log"), use it to establish a shared worldview so the model can make decisions that fit the project's character even without explicit instructions.

Closing: Make the Agent Know You Well Enough to Surprise You

Theo's final point: you and your agent should work together well enough that you're "frequently surprised by how well it understands you." Every time you open a new thread, the agent's brain is wiped clean — but that doesn't mean you need automatic memory to "preserve" anything. If anything, automatic memory makes it worse. What you actually need is to load everything that matters to you into its brain the moment it wakes up.

For developers currently using Claude Code, Theo's advice is clear: turn memory off. Invest that energy in architecture design, CI guardrails, and a carefully written AGENTS.md. The return on investment beats automatic memory by a wide margin.