AI agent memory: short-term context and persistent project knowledge.

Two kinds of memory, constantly conflated

An agent has short-term memory — the context window — and possibly long-term memory — an external store. They behave nothing alike, and most confusion in this space comes from using one word for both.

Notice the failure modes are opposite. Short-term memory fails by forgetting. Long-term memory fails by remembering the wrong thing confidently. A memory system that ignores the second failure mode has traded one problem for a subtler one.

Why bigger context windows don't solve it

Every model generation raises the ceiling, and every time it does, someone argues persistence is about to become unnecessary. It isn't, for a reason that has nothing to do with size: the window starts empty. A one-million-token context and a one-thousand-token context are equally empty at the start of tomorrow's session. Capacity is not persistence.

Two further practical points. A large window still gets compacted on long tasks, and compaction is lossy in the direction that hurts — it keeps narrative and drops specifics. And the tokens are not free: filling a huge window with everything that might be relevant is both expensive and, in measurable ways, worse for the model's attention than supplying the few things that are.

The four things people call "memory"

1. Conversation memory. Facts extracted automatically from what you said. Great for preferences ("prefers TypeScript", "deploys on Fridays, unfortunately"). Weak for engineering knowledge, because extraction can't tell a decision from a passing thought.
2. Instruction files. CLAUDE.md, AGENTS.md, custom instructions. Deterministic and always present — which is also the constraint, since they're loaded in full every turn and therefore have to stay short. More on this trade.
3. Retrieval over existing documents. Classic RAG. Answers "what does our documentation say"; can't answer "what did we learn last Tuesday" unless someone wrote it down.
4. Curated project memory. Notes the agent writes deliberately as it works: decisions, root causes, constraints, rejected approaches. Highest precision, and the only one of the four whose content is created by the work itself.

These stack. Most working setups use an instruction file for rules and a project-memory store for everything that accumulates.

What's worth remembering

The good candidates share one property: they were expensive to learn and are invisible in the code.

And the bad candidates: anything already in the code (it will go stale and disagree), transcripts of how you got somewhere (keep the conclusion), speculation that was never confirmed, and anything that changes weekly.

The staleness problem

This is the part most memory products under-serve, so it's worth stating clearly. Project knowledge doesn't just accumulate, it expires. The decision to use a queue-based importer was correct in March and reversed in June. If both notes sit in the store with equal standing, an agent will retrieve either, cite it confidently, and be wrong half the time.

A memory layer that's going to be trusted needs, at minimum: timestamps on everything, a way to mark a note superseded rather than deleting it, revision history so you can see how a claim evolved, and status on each note so "we decided" and "we're considering" don't look identical. Retrieval quality is a necessary condition, not a sufficient one — the harder problem is surfacing the current knowledge rather than merely the similar knowledge.

Making it work in practice

Knownbase is curated project memory reached over MCP. The agent writes when something durable happens and searches before it starts work; notes are project-scoped, tagged, statused, versioned, and linkable to each other.

{
  "mcpServers": {
    "knownbase": { "url": "https://knownbase.dev/mcp" }
  }
}

The habit matters more than the tool. One paragraph in your instruction file — search before starting, save decisions and root causes, keep code in git — is what turns a memory server from a feature into a working practice.

When you don't need any of this

If a project is new, small, single-person and single-tool, an instruction file covers it and a memory layer is overhead. The threshold is usually crossed when you first watch an agent re-solve something you know it already solved, or when your instruction file passes a few hundred lines and keeps growing. Before that, skip it.

Keep reading

• Why AI agents need persistent memory
• Why AI coding agents keep making the same mistakes
• MCP memory servers explained
• How to write an agent handoff the next session can use
• Persistent memory for Claude Code

FAQ

What is AI agent memory?

Any mechanism that lets an agent carry information across a boundary its context window cannot cross — usually the end of a session, but also a compaction pass or a switch to a different tool. It splits into short-term memory (the context window, volatile) and long-term memory (an external store the agent reads and writes deliberately).

Isn't a bigger context window the same thing?

No, and this is the most common confusion in the category. A larger window lets a single session hold more, which is genuinely useful. It does nothing about a session that has ended, because the window starts empty every time. Capacity and persistence are different properties.

What's the difference between agent memory and RAG?

RAG retrieves from a corpus that already exists and that the agent does not write to: your documentation, your wiki, your codebase. Agent memory retrieves from a corpus the agent itself creates while working. The retrieval machinery is often identical; the difference is authorship, and it changes what the store contains — RAG holds what someone wrote down, memory holds what was figured out.

Should memory be automatic or curated?

It depends on what you are storing. Automatic extraction is right for preferences and personal context, where missing something costs more than storing something useless. Curated writes are right for engineering knowledge, where a confidently-returned obsolete decision is worse than an empty result. Precision beats recall when an agent is going to act on what it retrieves.

How do you stop memory going stale?

You cannot fully, so the store has to make staleness visible instead of hiding it. That means timestamps, statuses, revision history, and the ability to mark a decision superseded rather than silently keeping both versions. A memory layer with no notion of time will eventually hand an agent last year's answer with today's confidence.

Can several agents share one memory?

Yes, and that is where most of the value is. If the store lives outside any one tool, a finding written by Claude Code is readable by Codex, by Cursor, and by a teammate's agent. Memory that belongs to a tool is tool memory; memory that belongs to the project is project memory.