Codex CLI
Codex CLI memory across sessions
Codex reads AGENTS.md files before it starts work. hippo init adds a short block there
telling Codex to run hippo context --auto at the start of every task, so lessons from earlier
sessions, and from your other agents, come back when they match the task.
Set it up
$ npm install -g hippo-memory
$ hippo init
# optional: capture Codex sessions too
$ hippo hook install codex
Capturing Codex sessions is opt-in. hippo hook install codex wraps the Codex launcher,
hippo hook uninstall codex removes the wrapper, and hippo init prints the command when it
detects Codex. hippo doctor checks the install.
What hippo adds to AGENTS.md
## Project Memory (Hippo)
At the start of every task, run:
```bash
hippo context --auto --budget 1500
```
Read the output before writing any code.
On errors or unexpected behaviour, record it right then, while you work,
never as a closing step:
```bash
hippo remember "<description of what went wrong>" --error
```
It closes with a note that session-end capture runs by itself once the Codex wrapper is installed, and a
hippo capture --stdin command for a manual summary when it is not. The block sits between
<!-- hippo:start --> and <!-- hippo:end --> markers, so the rest of your
AGENTS.md stays yours.
Codex memories and hippo
Codex has a Memories feature of its own: it can turn useful context from eligible prior chats into local memory
files under ~/.codex/memories/. OpenAI's docs say to keep required team guidance in
AGENTS.md or checked-in documentation, and to treat memories as a helpful recall layer, not as the only
source for rules that must always apply
(OpenAI docs (opens in new tab),
checked 2026-09-28).
Hippo is a recall layer too, with two differences. You can mark a lesson wrong with hippo outcome --bad
or replace one with hippo supersede. And the store sits in your project, with markdown mirrors you can
commit, shared with Claude Code, Cursor and any MCP client.
How do I give Codex memory across sessions?
hippo init adds its instructions to your AGENTS.md, which Codex reads before it starts work. Capturing Codex sessions is opt-in: hippo hook install codex wraps the Codex launcher, and hippo hook uninstall codex removes the wrapper.
Which agents does hippo work with?
hippo init detects Claude Code, Codex, Cursor, OpenClaw, OpenCode and Pi, and wires itself into each one's instruction file, hooks or plugin. It only patches instruction files that already exist. Any MCP client can use the MCP server, and other tools can call the CLI or the HTTP API that hippo serve starts.
What happens when a memory turns out to be wrong?
Mark it, and it drops out of the top results. hippo outcome --bad weakens the memories from the last recall, hippo supersede <id> "<new fact>" replaces one with a newer version, and hippo reject <id> --reason "<why>" stops that value from returning at all. On the synthetic E1 test, where every mark is correct, plain BM25 plus the outcome mark cut how often a marked-bad memory stayed in the top five from 71.9% to 0.0%. Real marks are noisier, because --bad marks the whole recall batch.