Why your AI agent forgets your project (and what to do about it)

Short version: Your agent doesn’t forget the project because the model is bad — it forgets because its memory is the context window, and nothing else. The window resets between sessions, compaction cuts it mid-session, and the default setup has no separate layer where project state could live. The fix is adding that layer — anything from a rules file to MCP memory; which one depends on what exactly you’re losing.

Three reasons agents forget

When an agent “forgot everything”, the concrete cause is usually one of three — and each has its own repair.

1. The window resets between sessions. The model stores nothing between runs. Every new session is a blank page plus whatever the client put into context: system prompt, project rules, maybe a few files. Yesterday’s conversation about why you chose Postgres is not on that list. The symptom: you re-explain the project at the start of every session.

2. Compaction cuts the middle of long sessions. When the history hits the window limit, the client replaces it with an automatic summary. The plot survives; the details don’t: exact wording of decisions, numbers, rejected options. The symptom: mid-session the agent proposes the thing you talked it out of an hour ago. The mechanism in detail: context compaction.

3. There’s no state layer. This is the root cause of the first two. In a typical “model + client” setup, project state has nowhere to live: the code is in the repo, but “what we decided and why”, “which bug is open”, “what’s next” isn’t written in the code. Until that layer exists, forgetting comes back no matter how big the window is.

Diagnosis: which case is yours

Spend a week marking the moments when the agent loses something. A pattern usually shows up fast:

• It loses everything between sessions, but remembers fine within one → cause 1; you need a durable session start.
• It loses agreements inside long sessions → cause 2; you need shorter sessions plus recording facts as they happen.
• It loses decisions and their reasoning (“why did we do it this way”), even after you’ve repeated them → cause 3: decisions live nowhere but chats.
• It loses work statuses (“what’s in progress, what’s done”) → cause 3 again: task state doesn’t exist outside your head.

For most people working with an agent daily, the diagnosis is a combination of 1+3.

The spectrum of solutions

The options line up by strength and by cost of adoption.

A rules file (CLAUDE.md, AGENTS.md, .cursor/rules). A static document the client loads into every session. Great at carrying standards: “deploys go through the script only”, “tests are mandatory”. Bad at state: a rules file doesn’t update itself, and “what we decided yesterday” doesn’t land there until you write it in. Cost of adoption — an evening.

RAG over documents. Indexing the repo, the wiki, past documents; the agent searches them semantically. Good at answering “what do we have written about X”. Bad at “what did we decide about X” — decisions live in chats, not documents, and RAG doesn’t see them. Plus the infrastructure: embeddings, an index, reindexing.

MCP memory (our variant is MaxGraph). A separate server where the agent maintains a knowledge graph itself: project entities, owner decisions, open bugs and tasks, events. At session start the agent reads a digest, during work it records facts, at the end it closes the session with outcomes. State lives outside the window, so it survives both session switches and compaction. It’s also cheaper in tokens: a digest-backed start costs ~4,200 tokens versus ~8,900 for reading the project from scratch.

When to choose what

• Solo project, short tasks, the agent is a “patch and forget” tool — a rules file is enough. The state is in your head, and that’s fine.
• Daily agent work, one project, and the morning re-explanation is grating — MCP memory. This is exactly the case a start digest plus live decision recording closes. Setup: 10 minutes for Claude Code or for Cursor.
• A large document base, questions are mostly “where is it written” — RAG, possibly on top of memory.
• Several projects and people, decisions get lost between them — memory with per-project separation; RAG over documents as a complement, not a replacement.

A common path: start with a rules file, hit “it doesn’t remember yesterday” within a month, add memory. That’s a normal progression — the layers complement each other rather than compete.

FAQ

Doesn’t a huge context window (1M tokens) solve this? No. The window resets between sessions regardless of size. And within a session, a long context hurts accuracy: the model gets worse at finding details in the middle of the transcript. Window size treats the symptom, not the cause.

What about just writing detailed prompts at the start of each session? It works, at the cost of your time and completeness. By our measurements a manual briefing is competitive on tokens, but a human writes it every time, and a 1,500-character brief doesn’t hold dozens of decisions plus task statuses.

Isn’t memory just another notes file? No — the difference is who writes it. A notes file is maintained by you. Memory is maintained by the agent itself, following a protocol: it records a decision the moment it’s made, updates a task status when closing it, reads the digest at session start. Your role is not to write, but to check.

Does my data go to the cloud? Depends on the implementation. MaxGraph is a local server; data lives in data/ on your machine, with one-click JSON export. Internet is needed once — for license activation after the trial.

What’s next

• An overview of all memory approaches: the agent memory guide.
• How compaction works and what it loses: about compaction.
• MCP memory versus hosted services: MaxGraph vs Mem0 and Zep.
• Terminology: the agent memory glossary.