Codex CLI persistent memory: how to make Codex remember between sessions

Codex CLI is OpenAI’s terminal coding agent, and as of the releases current in August 2026 it does not remember your last session on its own. Every run starts from the same two inputs: the AGENTS.md instruction files it finds on disk, and whatever you type. So Codex CLI persistent memory is not a setting you switch on. It is a file you keep, plus an instruction telling Codex to read that file first.

Codex already keeps two kinds of state, and neither one is memory. AGENTS.md is a static instruction file loaded at startup, layered from your Codex home directory down to the project root. Codex also stores session transcripts, so codex resume reopens one past thread and nothing else. A memory store is a third thing: a small, curated set of durable facts that every future session reads, whichever project or machine you are on.

What Codex keeps and what it drops

Layer	Where it lives	Survives a new session	Good for
Session transcript	Codex home directory	Only via codex resume, on that one thread	Picking up an interrupted task
AGENTS.md	Codex home directory, project root, nested folders	Yes, Codex loads it every run	Standing rules and conventions
Markdown memory store	A folder of markdown files you own	Yes, if AGENTS.md tells Codex to read it	Decisions, facts, open follow-ups
Memory server over MCP	A server process you run	Yes, while the server runs and stays configured	Structured recall with no files to manage

AGENTS.md tells Codex how to behave. A memory store tells Codex what has already been decided.

The simplest version that works

Start with one markdown file and one rule. Create an empty file at ~/notes/agent-memory.md, outside any single repository so every project can reach it. On Windows that file is %USERPROFILE%\notes\agent-memory.md.

Then add an instruction to your global AGENTS.md, which lives at ~/.codex/AGENTS.md:

## Memory

Before proposing an approach, read ~/notes/agent-memory.md and follow any
decision recorded there. At the end of a task, append one line per new
decision, fact, or open question, with the date.

That is enough to make Codex remember context between sessions, and for a solo project it may be all you ever need.

Be realistic about what an instruction buys you. Codex will usually read the file before it decides something. The write-back is less reliable, because an end-of-task instruction competes with everything else in context and an abruptly ended session never reaches it. Expect to ask for it by hand sometimes.

Where the flat-file version runs out

That two-file setup holds up until the memory file gets long. Four things break, roughly in this order.

The first is size. Codex reads the whole memory file every time it consults it, so once the file passes a few hundred lines you spend real context on facts irrelevant to the task in front of you. The second is retrieval: a flat list gives Codex no way to ask what you decided about authentication without reading everything.

The third is structure. A decision that still binds, a fact with a shelf life, and a follow-up you never closed all look identical in a bullet list. The fourth is concurrent editing. Appending a line is usually safe, but an agent that reads the file, changes a line, and writes the whole file back will silently erase whatever another agent wrote in between.

Memory servers over the Model Context Protocol

Codex CLI can connect to servers that speak the Model Context Protocol, a standard way for agents to call external tools. Several of those servers exist purely to store and retrieve memories. They fix retrieval and structure without you managing files, and one server serves every client that speaks the protocol.

The cost is a process to run and keep running, plus memory you cannot read with cat or edit yourself. For a store you want to open in five years, that matters. Memory servers versus plain markdown files works through the tradeoff.

A memory store Codex can query and write to safely

Jotura is a free local-first markdown notes app for Mac, Windows, Linux, and Android. Local-first means the notes live on your own disk and the app works with no network. It ships with a command-line tool called jotura, and notes stay ordinary .md files in an ordinary folder, so nothing locks the memory store inside an app.

Jotura began as Adam Richardson’s own notes app, built for speed, privacy, and sharing. The agent commands came later, on foundations that already existed.

curl -fsSL jotura.io/install.sh | bash

On Windows, run irm jotura.io/install.ps1 | iex instead. That one command installs the app, the CLI, and the agent skills, Codex included.

Point the CLI at your vault

The CLI needs to know which folder is your vault, the folder your notes live in. It reads --vault, then the JOTURA_VAULT environment variable, then whichever vault the desktop app opened last. With none of those set, every command below exits with code 6 and the message “no vault specified”.

export JOTURA_VAULT=~/notes-vault

Set it explicitly. The instructions below run in every project you open, so without the variable Codex files memories into whatever vault the desktop opened last.

Logging and recalling decisions

Writing a decision looks like this:

jotura memory log --kind decision \
  --title "Postgres over SQLite for the metrics service" \
  --project "Metrics" \
  --body "Three worker processes write concurrently. SQLite write locking was the deciding factor."

Reading back before proposing anything looks like this:

jotura memory recall "database choice" --project "Metrics"
jotura context "add a retention job to the metrics service"

recall ranks results by relevance, freshness, and importance, and context returns a compact pack for the task at hand. Recall is keyword search, so it matches words rather than meaning: a decision filed as “Postgres over SQLite” will not surface for the query “which database”. Title your memories with the words you will search for later.

Each memory is one small markdown note with a YAML frontmatter block at the top holding its kind, date, and project, so you can read, grep, or delete them without the CLI. jotura memory supersede retires a decision and jotura memory resolve closes a follow-up, so the store does not fill with stale claims.

Why the writes are safe

jotura edit --if-hash <hash> refuses to write if the file changed since the agent read it, which is what stops two agents from clobbering each other. Body edits never touch frontmatter. There is more at the CLI reference.

Telling Codex to use it

Codex had no session-start hook as of August 2026, so the trigger lives in AGENTS.md. Jotura installs a real session-start hook for Claude Code with jotura hook install claude, but Codex needs the instruction file. Replace the ## Memory section you added earlier with this one:

## Memory

Run `jotura context "<task>"` at the start of a session. Before proposing an
approach, architecture, or library, run `jotura memory recall "<topic>"` and
never contradict an active decision without flagging it. When a decision is
made or a bug's root cause is found, record it with
`jotura memory log --kind decision|fact|followup`.

Codex asks before running shell commands by default, so expect an approval prompt the first few times it reaches for jotura. Raise the approval level for that project if you want recall to run uninterrupted. memory log writes files, and a read-only sandbox will refuse it.

Keeping AGENTS.md itself in one place

Once the instruction file is doing real work, you want it identical on every machine. Jotura keeps agent configuration in an Agents/ folder in the vault, where Agents/Codex/AGENTS.md maps to ~/.codex/AGENTS.md, and one edit there can cover Claude Code, Gemini, and Copilot too. See syncing AGENTS.md across computers for that workflow.

What belongs in memory, and what does not

Record decisions with the reason behind them, facts with a shelf life, and follow-ups you intend to close. Skip anything the code already states clearly, because a memory note that duplicates the source goes stale and starts lying. Never put credentials or API keys in a memory store: anything in it can end up quoted in a commit message, a pull request description, or a transcript you share later.

Honest limits

Jotura is closed source. There is no iOS app, no plugin system, no graph view, and no publish-to-web. Getting the vault onto a second machine needs your own tool, such as Git or Syncthing, or Jotura Sync at 4 pounds a month or 40 pounds a year. Sync is end-to-end encrypted, the server never sees your note contents, filenames, or keys, and there is no free trial.

None of this is exclusive to Codex. The same store works when you switch agents mid-task, which the guide on when your AI agent forgets everything between sessions covers.

FAQ

Does Codex read the memory store automatically? No. Codex loads AGENTS.md automatically, and AGENTS.md is where you tell it to run the recall command. Without that instruction, nothing happens.

Do I have to use Jotura for this? No. A single markdown file in a git repository wins on what matters most for memory you keep for years. It costs nothing, installs nothing, depends on no vendor, and any tool on earth can edit it. Jotura’s CLI adds ranked retrieval, a decision and follow-up model, and hash-checked writes. If you are one person on one machine, the plain file is genuinely the better answer.