Persistent Memory for AI Coding Agents: Stop Re-Explaining

The re-explaining tax

If you use a coding agent, you know the tax. Every new session starts cold. You re-explain which directory the API lives in, that the team uses pnpm not npm, that the auth module is off-limits, and that the tests run with a specific command. The agent was productive yesterday and remembers none of it today. Persistent memory for AI coding agents is the fix: give the agent a place to keep what it learned about your codebase so you stop paying that tax every morning.

The problem is not that models cannot remember. It is that most coding-agent setups throw the memory away between runs. The context lives in the chat session, and when the session ends or the process restarts, it is gone. Persistent memory for AI coding agents means moving that knowledge somewhere durable, so tomorrow's session starts where today's ended.

What "memory" means for a coding agent, specifically

Not all memory is equal. For a coding agent, four kinds are worth keeping, and they persist differently:

The insight is that most of this is not exotic. Project facts and preferences belong in a file you commit, so every session and every teammate's agent reads the same ground truth. The industry has more or less standardized on this: a plain markdown file at the repo root that the agent loads on startup. Tools like Claude Code, Aider, and Cursor all support some version of it.

The cheapest persistent memory: a file in the repo

Before any database, the highest-leverage move is a project instructions file. A markdown file committed to the repo, loaded automatically, that tells the agent the things you keep repeating:

# Project notes for the coding agent

- Package manager: pnpm (never npm or yarn)
- Run tests: `pnpm test`
- Do NOT touch: src/auth/** (security-reviewed, changes need a human)
- API routes live in src/routes/, one file per route
- Prefer editing existing files over creating new ones

# Project notes for the coding agent

- Package manager: pnpm (never npm or yarn)
- Run tests: `pnpm test`
- Do NOT touch: src/auth/** (security-reviewed, changes need a human)
- API routes live in src/routes/, one file per route
- Prefer editing existing files over creating new ones

This is persistent memory for AI coding agents in its simplest, most durable form. It is committed, so it survives everything: restarts, new machines, new teammates. It is versioned, so it improves over time. And it costs nothing to run. The Aider documentation covers conventions files, and most agents read a similarly-named file at the repo root. Start here before you build anything.

When a file is not enough: task state across restarts

A committed file handles facts and preferences. It does not handle task state: the work-in-progress the agent has in flight. If an agent is halfway through a refactor across twelve files and the process restarts, a file in the repo does not remember which files it already changed. That state needs durable, per-run storage.

This is where the hosting question shows up. An agent running in a container with an ephemeral filesystem loses its working state on every restart, because the container's disk is wiped. To persist task state you need a volume that outlives the process:

# Bad: state written here vanishes when the container restarts
/tmp/agent-progress.json

# Good: state on a mounted volume that survives restarts
/workspace/.agent/progress.json

# Bad: state written here vanishes when the container restarts
/tmp/agent-progress.json

# Good: state on a mounted volume that survives restarts
/workspace/.agent/progress.json

The /workspace volume is the difference between an agent that resumes a refactor after a crash and one that starts over, redoing work and burning tokens twice. If you are packaging your agent, get this right in the container setup, which we cover in how to containerize an AI agent with Docker.

Codebase memory: index, do not re-scan

The third kind of memory is structural: where things are and how they connect. Coding agents build this by reading the code, which is slow and token-expensive to redo every session. Persisting it means keeping an index the agent can reload instead of rebuilding from scratch.

For most repos, the agent re-reading files on demand is fine, and you do not need a heavy retrieval system. For very large codebases, a semantic index (embeddings over the code) lets the agent find relevant files by meaning instead of scanning everything. That is a retrieval problem, and whether it justifies a dedicated store is exactly the question we work through in vector database for AI agent memory. The short version: index only when the codebase is too large to navigate by convention, and try the lightweight option first.

Why persistent memory for AI coding agents is a hosting problem

Notice the pattern across all four kinds of memory: the ones that fail are the ones that depend on the process staying alive. A file in the repo persists because it lives outside the agent. Task state persists only if it is written to durable storage outside the process. The moment your agent's memory depends on the container not restarting, you have a memory that will not last.

So persistent memory for AI coding agents is partly a writing-good-files problem and partly a hosting problem. The agent needs:

• A committed instructions file (you write this).

• A persistent volume for task state (your hosting provides this).

• Optionally, a durable index for large codebases (retrieval, if warranted).

On Sokko, anything your agent saves is kept for you and survives restarts and redeploys, so its memory sticks without any extra engineering on your side. The deploying your first agent walkthrough shows the flow.

Practical setup, start to finish

To stop re-explaining your codebase, in order of leverage:

1. Write the instructions file. Commit a markdown file with your package manager, test command, off-limits paths, and style rules. This alone removes most of the daily re-explaining.

2. Give the agent a persistent volume. Ensure task state is written to durable storage, not the container's ephemeral disk.

3. Point state writes at the volume. /workspace/.agent/ or similar, never /tmp.

4. Index only if you must. For large repos, add semantic retrieval over the code. For most, skip it.

5. Improve the file over time. Every time you catch yourself re-explaining something, add it to the instructions file so you never explain it again.

Do the first two and the re-explaining tax mostly disappears. The remaining steps are for scale.

What to put in the instructions file (and what not to)

The instructions file is the highest-leverage piece, so it is worth getting right. Good things to commit:

• Hard rules. Package manager, test command, build command, forbidden directories. Anything the agent must never get wrong.

• Conventions the code does not make obvious. "Routes go in one file each", "we use tabs", "error messages are lowercase". The things a new hire would ask.

• The review bar. What you expect before the agent calls a change done: tests pass, no new dependencies without a note, existing files preferred over new ones.

Things to keep out of it:

• Secrets. It is committed, so anything in it is public to everyone with repo access. Keys go in injected environment variables, never here.

• Volatile detail. File-by-file descriptions rot the moment the code changes. Point at where things live, not at every line.

• Novel-length context. The file is loaded into the agent's context on every session, so it costs tokens each time. Keep it tight. A page of sharp rules beats ten pages of narrative.

Treat the file as a living document. Every time you correct the agent on something it should have known, add a line so you never correct it on that again.

A quick test: does your setup actually persist?

Before you trust the memory, prove it survives a restart with a two-minute check:

1. Start a task with the agent and let it make a few changes.

2. Restart the agent process (or redeploy the container).

3. Ask it what it was doing.

If it picks up where it left off, your persistence is real. If it starts cold and asks you to re-explain, the state was living somewhere ephemeral, in the session or the container's temporary disk, and it is not actually persistent memory yet. This test catches the most common failure, which is an agent that seems to remember within a session but forgets across restarts.

The payoff

Persistent memory for AI coding agents is not a research problem. It is mostly discipline: put the durable facts in a committed file, put the task state on a volume that survives restarts, and stop keeping anything important in a process that can die. Do that, and the agent that helped you yesterday is still up to speed today, instead of asking you again which package manager you use.