Codex agent memory that belongs to you

As of 2026-11-21, PLUR 0.23.1 (@plur-ai/cli and @plur-ai/mcp, both requiring Node.js 22 or newer).

Codex already carries context between sessions. It reads your AGENTS.md files every run, and its optional Memories feature turns earlier chats into local memory files. PLUR adds a memory layer you control memory by memory: corrections, preferences and conventions are saved as plain YAML in ~/.plur/ on your disk, found again by local search, and injected into new sessions through Codex hooks. You can read each memory, correct it, or retire it with one command, and the same store works in Claude Code and Cursor.

Install

You need Node.js 22 or newer.

Prefer to let your agent do it? Tell it: "Go to plur.ai and install memory." It follows plur.ai/install.txt: checks for Node.js 22, runs the npm install and plur init --codex, verifies with plur doctor, and tells you what only you can do (restart, trust the hooks).

1. Install the CLI and the MCP server, then set up Codex:

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest
plur init --codex
plur doctor --codex

plur init --codex registers the PLUR MCP server with codex mcp add in ~/.codex/config.toml, writes lifecycle hooks to ~/.codex/hooks.json, and adds a PLUR section to AGENTS.md. If you set CODEX_HOME, that directory is used instead of ~/.codex. plur doctor --codex starts the MCP server the way Codex would and checks that its version matches the CLI.

2. Restart Codex.

3. Trust the hooks. Don't skip this. Open Codex, run /hooks, and trust the PLUR entries. Codex does not run a hook you have not trusted, and it does not warn you, so until you trust them memory never loads. plur doctor reports this too.

4. Say yes to memory in this folder. The first time PLUR runs in a folder you have not decided about, it asks once whether to use memory there. Answer in the chat, or run:

plur folders set "$PWD" --on

5. Check it in a real session. Ask Codex to save a test memory, start a new session, and ask for it back. This matters most in the desktop app: plur doctor --codex checks your config and the MCP server, not hook trust or the environment of a separately launched app.

On Windows: native Windows and WSL2 have separate home folders and separate Codex registrations. Run the setup in each one you use.

Upgrading: run the same three commands again (npm install -g …, plur init --codex, plur doctor --codex) and restart Codex. Init updates older PLUR entries in place and keeps your environment settings, timeouts and comments.

What it remembers, and how to read, correct and delete a memory

PLUR stores engrams: short statements such as a correction, a preference or a convention, each with a scope and a strength that grows with use and fades when unused. It is agent memory, not a code index.

A worked example. In a Codex session you say:

"Commit messages here follow Conventional Commits, and the body explains why, not what."

Codex saves it with plur_learn. It lands in ~/.plur/engrams.yaml with an id such as ENG-2026-11-17-001. In a new session next week, in any repository, you ask Codex to commit and the hooks bring the convention back.

Read it:

plur list                              # every engram
plur recall "commit message style"     # search, the way the agent does
plur dashboard                         # local, read-only page in your browser

Or open ~/.plur/engrams.yaml in any editor. It is plain YAML.

Correct it. This repository uses a different style:

plur forget ENG-2026-11-17-001 --reason "replaced by a per-project rule"
plur learn "In this repo, commit subjects start with the ticket id, e.g. API-142: fix retry"

To push a memory down without retiring it, rate it: plur feedback ENG-2026-11-17-001 negative.

Delete it. plur forget <id> retires the memory: it is no longer recalled or injected. The entry stays in engrams.yaml, marked status: retired, so you can see what was retired. You can also remove an entry from the file by hand.

To switch memory off for one folder: plur folders set ~/scratch --off.

How it compares with Codex's built-in memory

Codex's built-in options are useful, and OpenAI's own advice applies here too: keep rules that must always apply in AGENTS.md. PLUR does not replace AGENTS.md or Codex Memories. You can run both.

AGENTS.md Codex Memories PLUR
Who writes it You Codex, in the background, from earlier chats The agent, through PLUR's tools, or you from the CLI
Default Read on every run Off; turn on in settings or [features] memories = true On once installed and the folder is allowed
Where it lives ~/.codex/AGENTS.md plus files from the repo root down Under your Codex home (memories/ or memories_v2/), per machine ~/.plur/engrams.yaml, one store for all projects, separated by scope
What loads The concatenated files, up to 32 KiB by default Existing memories, when the chat allows it Memories selected by relevance and injected by hooks
When new memory appears When you edit the file After a chat has been idle a while; skips short or active chats When the agent calls plur_learn, during the session
Read and edit Markdown Inspectable files; OpenAI advises against hand-editing as the main control Plain YAML meant for reading; plur list, plur dashboard
Remove one item Edit the file Delete all Codex memories for that machine in settings plur forget <id> for one memory
Other tools Claude Code, Cursor and others read AGENTS.md Codex only Claude Code, Cursor, OpenCode, OpenClaw, Hermes, Antigravity, any MCP client
Other machines Through git Per machine plur sync to a private git remote you choose

FAQ

Codex has Memories now. Why add PLUR? Codex Memories are generated in the background from your earlier chats, stored per machine, and read by Codex only. Use PLUR when you want to see and manage each memory yourself, retire one without wiping the rest, and have the same memory in Claude Code and Cursor.

I installed PLUR but Codex doesn't seem to remember anything. Check the hooks first: run /hooks in Codex and trust the PLUR entries. Codex skips untrusted hooks without a warning. Then run plur doctor --codex, and check the folder is allowed with plur folders list.

Does PLUR change my AGENTS.md? It adds a PLUR section so Codex knows when to save and look up memories. Your own instructions stay as they are.

Does it work in the Codex desktop app and on Windows? The MCP server and hooks are registered in your Codex user config, which the CLI uses. For the desktop app, confirm saving and recalling a test memory in an actual session. On Windows, set up native Windows and WSL2 separately; they have separate home folders.

Will Claude Code and Cursor see what I taught Codex? Yes, once PLUR is set up there too (plur init for Claude Code, plur init --cursor for Cursor). They all read and write the same ~/.plur/ store.

Do my memories leave my machine? Not by default. The store is local YAML and search runs locally; plur doctor downloads the search model once. Syncing is opt-in: plur sync pushes to a git remote you name, which should be private. For what to check before trusting any memory tool, see Choosing an Agent Memory Tool: Test Your Exit Plan First.

Related: What Memory Layer Works with Cursor or Codex? · Your Agent Said It Saved a Memory. Did the Next Session Receive It? · How to Delete Specific Things an AI Remembers About You

Get started

npm install -g @plur-ai/cli@latest @plur-ai/mcp@latest && plur init --codex

Then trust the PLUR hooks with /hooks in Codex. Open source, Apache-2.0: github.com/plur-ai/plur