Stale context in an AI coding agent is any instruction, decision or project fact that the agent loads at the start of a session after it has stopped being true. Common examples are an old deploy command, a test runner you replaced, or a database you dropped. The agent has no way to tell an old line from a current one. It reads both with the same confidence and acts on whichever one it finds.
This post covers how stale context gets in and why rules files are the usual source. It also covers what we think the fix looks like: keep the history of each decision, but show the agent only the current one.
How stale context breaks AI coding agent sessions
Stale context rarely causes a loud failure. It shows up as a session that goes slightly wrong and costs you twenty minutes before you notice.
Here's a deploy example. In January your CLAUDE.md said "deploy with make deploy, which pushes to Heroku." In March the team moved to Fly.io and wrote a new script, but nobody touched that line. Now you ask the agent to ship a hotfix. It reads the file, finds make deploy, and runs it. If the old target still exists, it might even succeed against an app nobody uses anymore. You find out when the fix isn't live.
Testing goes wrong the same way. Say you moved from Jest to Vitest, but AGENTS.md still says "run npx jest --watch before committing." Codex follows the file and gets a config error. It then "fixes" the error by reinstalling Jest. You end up with two test runners in package.json and a diff you didn't ask for.
Small preferences cause problems too. If you switched to pnpm months ago but one file still mentions npm install, every tool that reads that file will make a package-lock.json you then have to delete. The agent did exactly what it was told. The problem was what it was told.
Why hand-kept CLAUDE.md and AGENTS.md files drift
Every major coding tool now reads a plain Markdown file at start-up, and each tool reads a different one. Here's what the vendors document:
Claude Code (Anthropic docs): CLAUDE.md in the project and a user-level ~/.claude/CLAUDE.md, both loaded when a session starts.
Codex (OpenAI Codex docs): a global ~/.codex/AGENTS.md plus AGENTS.md files from the repo root down to your working folder. Codex joins them together and stops at a combined cap of 32 KiB by default (project_doc_max_bytes).
Gemini CLI (Google's Gemini CLI docs): ~/.gemini/GEMINI.md plus GEMINI.md files found in the workspace and its parent folders. All of them are joined and sent with every prompt.
Cursor (Cursor docs): project rules under .cursor/rules, and it can also read AGENTS.md in the repo.
So a developer who uses three tools keeps three or four files in sync by hand. Nobody does that for long. A decision gets made in one tool's chat, maybe goes into that tool's file, and the other files stay as they were. We wrote up how one store can write a shared briefing into CLAUDE.md, AGENTS.md and GEMINI.md for each tool, because this drift was the first thing that hurt us.
The other problem is cost. Rules files only ever get longer. People add lines and almost never remove them, because deleting one feels risky. Here's a rough estimate using OpenAI's published rule of thumb of about four characters per English token: a 400-line file averaging 60 characters per line is about 24 KB, or roughly 6,000 tokens. You pay that in every session, before you've typed anything. Most of those lines are history, and some are wrong.
How to spot stale context
You usually don't need tooling to see it. You need to notice your own patterns.
You correct the agent on the same point twice in one week.
The agent explains a choice by pointing to a rule you don't remember writing.
Two tools give different answers about the same project. One says Redis, the other says SQLite.
The agent "fixes" something by bringing back a dependency or script you removed on purpose.
When one of these happens, ask the agent to quote the exact instruction it followed. Then search for that line. In Gemini CLI, /memory show prints the whole combined context the model sees, which is the quickest way to find a line that contradicts another.
How to keep agent context current
The obvious fix is to edit the old line. It works, but it loses the reason the decision changed. That reason is often exactly what the agent needs the next time someone suggests bringing Redis back. A better approach is to keep the history and decide carefully what the agent gets served.
Version decisions instead of overwriting them
Treat a decision as a record with a history, the way you'd treat a row with a valid-from date. "We use Redis for the job queue" becomes "we used Redis for the job queue until we dropped the queue; we now use SQLite." The session-start briefing shows only the current state. The older version can still be found by search when someone asks why. The history stays, and the agent doesn't follow the old version.
Consolidate and re-rank on a schedule
Captured notes pile up fast, and raw notes contradict each other. A scheduled pass, nightly in our case, should merge duplicates and fold newer decisions over older ones. It should also re-rank by evidence: how often a memory was actually used, and whether you marked it as helpful. A memory that keeps misleading the agent should drop in the ranking until it falls out of the briefing.
Check that it's working
Ranking you can't measure is a guess. Write a handful of questions whose answers you know, like "what's our deploy target?" or "which package manager?" Then check that recall returns the current answer and not the old one. Rerun those questions after every change to how memory is stored or ranked.
The checklist:
Put each decision in one place, not in three tool-specific files.
When a decision changes, add the new version with a short reason. Don't silently overwrite the old one.
Serve only current decisions at session start, and keep that briefing small and capped.
Consolidate on a schedule so duplicates and contradictions merge.
Rank by use and feedback, so memories that mislead sink.
Test recall against questions from your own history after every change.
Read the store yourself now and then. Pin what's important and delete what's wrong.
Where OpenAB fits
At Open Agentic Brain & Memory (OpenAB), we built the memory we wanted: one store for every coding tool, kept current automatically, and owned completely by the developer. Hooks capture decisions, fixes and preferences from Claude Code, Codex, Cursor, Antigravity and Kilo Code (beta). Memories are tagged by project, which OpenAB finds by walking up to the nearest .git. Everything is stored in a local SQLite database. You can follow one decision from a Claude Code session to Cursor on another laptop to see the full path.
Stale context is handled in the steps above. Each night, brain dream rewrites a project's wiki page as the project changes, so in our own Redis example the briefing says SQLite and records why Redis went away. Recall ranks by relevance first, then by proof: how often a memory was used and whether you said it helped. You can run brain eval to quiz recall on your own history, and on LongMemEval-S we score 96.2% on the "updated facts" questions. You can read, edit, pin or delete every memory in the local control panel, and deletes can be undone.
The briefing also costs very little. It's capped at 2,000 tokens and ready in 84 ms (p50). Loading context for a 10,000-memory store takes 1,325 tokens, against 1,131,367 tokens to dump every memory. On LoCoMo it keeps 97% of the whole-conversation score while reading 18% of the tokens. Those figures, and how we measured them, are on our benchmarks and token cost page. Fewer tokens per session means you hit your Claude, Cursor or Codex limits later.
There's no account and no server of ours involved. Sync between machines is a single age-encrypted file stored as a Release asset in your own private GitHub repo, and the key lives only in your OS Keychain. If you lose that key, nobody can recover your memory, including us.
Before installing anything, try this: search your CLAUDE.md and AGENTS.md for every tool name your project no longer uses. Most repos have at least one.
OpenAB is free and Apache-2.0 licensed, built by Rohith, Chandan and Sushmita. The Open Agentic Brain & Memory home page has install steps for macOS and Linux.
Install Open Agentic Brain & Memory (OpenAB)
FAQ
What is stale context in an AI coding agent?
Stale context is any instruction, decision or fact your agent loads that used to be true and no longer is. It usually lives in a rules file or a memory store. The agent can't tell old from new on its own, so it follows an outdated line with the same confidence as a current one.
How do I know if my agent is using outdated instructions?
Watch for repeated corrections. If you tell an agent the same thing twice in a week, something it reads is out of date. Ask the agent to quote the instruction it followed, then search your rules files for that line. In Gemini CLI, /memory show prints the full combined context.
Should I delete old lines from CLAUDE.md or AGENTS.md?
Yes. Rules files have no history the agent can use, so an old line reads as a live order. Put the reason in a commit message or decision record, then delete the line. Review these files whenever you change deploys, test runners or package managers, and skim them at least monthly.
How does a memory layer know when a decision has been replaced?
It has to see the newer decision and fold it over the old one. In OpenAB, the nightly brain dream pass rewrites the project's wiki page as decisions change, and memories you mark unhelpful rank lower. You can also edit or pin the current version yourself in the control panel.
Will older context be lost if it stops appearing in the start-up briefing?
No. The briefing is a ranked selection capped at 2,000 tokens, not the whole store. Older memories stay in the local SQLite database, and you can still find them with brain_recall or in the control panel. Deletes in OpenAB can also be undone, so removing a memory doesn't have to be final.
Can one memory layer replace separate CLAUDE.md, AGENTS.md and GEMINI.md files?
It can fill them in for you. OpenAB writes its briefing into each file between BRAIN:START and BRAIN:END markers and leaves the rest of the file alone, so your hand-written rules stay. In practice, shared decisions move into memory, and the files keep only stable, tool-specific notes.
Top comments (0)