An AI agent forgets everything when its session ends. Persistent memory is anything that survives between sessions. This page compares the four main approaches: context stuffing, vector retrieval, structured databases, and plain files.
Working memory is the context window. It exists only while the session is active. Persistent memory is knowledge that survives between sessions. The agent writes it to storage during one session and reads it back at the start of the next.
The four approaches are context stuffing, vector retrieval, structured databases, and plain files. Most teams use one or two. None of them is universally best.
Context stuffing puts persistent knowledge directly into the system prompt. Every session loads the same block of text. Examples: CLAUDE.md, AGENTS.md, .cursorrules, and custom system-prompt injections.
The problem is scale. Every line rides every prompt. No selective loading. Once the file exceeds a few hundred lines, important rules get buried. Most implementations are read-only for the agent.
Vector retrieval stores knowledge as embeddings and retrieves by similarity search. Tools like mem0, Zep, and LangMem use this pattern. At query time, the system finds the closest vectors and injects them into the prompt.
The weaknesses: opaque (you cannot open a file and read the memory), approximate (relevant facts can be missed), hard to correct (no find-and-replace), and requires infrastructure (embeddings model, vector database, ingestion pipeline).
Structured databases store agent state in SQL tables, graph databases, or key-value stores. The agent queries through generated SQL, a custom API, or a graph traversal.
Requires a schema up front. The agent needs a query layer. Overkill for working notes and learnings. Inspection requires a database client.
Plain-file memory stores knowledge as markdown, JSON, or YAML files in a folder. The agent reads and writes files by path. The folder lives on disk, in git, or behind an MCP server. This is the approach gcontext uses.
Scale ceiling is megabytes. No fuzzy recall. Requires naming discipline. These limits matter only when the corpus grows to thousands of documents.
| Context stuffing | Vector retrieval | Structured DB | Plain files | |
|---|---|---|---|---|
| Setup cost | None | Moderate | High | Low |
| Write path | Human only | SDK call | Query | File write |
| Inspectability | Full | Opaque | Query required | Full |
| Correction workflow | Edit file | Re-embed | Migration | Edit file |
| Cross-tool reach | One tool | One app | One app | Any MCP client |
| Scale ceiling | Kilobytes | Gigabytes | Terabytes | Megabytes |
| Cost model | Per-token | Hosting + API | Hosting | Disk only |
Context stuffing and plain files share the "edit file" correction workflow and full inspectability. The difference is selective loading: context stuffing loads everything, plain files let the agent load only what it needs.
Most agent memory is small and high-value. A project has 20 decisions, 30 API conventions, 10 deployment notes, and a handful of learnings. This fits in a few dozen files totaling a few hundred kilobytes. Files handle this well.
Start with files. Add vector retrieval only when the corpus outgrows what file search can handle. Most teams never reach that crossover. The recommendation is not "files forever." It is "files first."
gcontext packages approach 4 as an open-source MCP server. It serves a folder of plain text files and exposes read_file, write_file, list_dir, grep, and script execution tools. Any MCP client can connect and use the same state folder.
The agent now has persistent, readable, diffable memory. Every file it writes survives the session. Push the folder to git and it survives the machine.
RAG retrieves from a corpus the agent does not own or edit. The documents are external: knowledge bases, help centers, codebases. Agent memory is state the agent writes and reads as part of its work. The agent creates it, updates it, and relies on it in future sessions. RAG is read-only retrieval. Agent memory is read-write state.
Not usually. Most agent memory is small: project decisions, API quirks, deployment logs, team conventions. File-based storage handles this well. Add vector search when your corpus grows to thousands of documents and you need fuzzy recall by meaning rather than by path.
By reading persistent storage at the start of each session. The storage can be files on disk, rows in a database, or embeddings in a vector store. The agent needs tools to read and write that storage. Without persistent storage, the agent starts fresh every time.
Install gcontext. Give your agent readable, writable, diffable memory.