Persistent memory for Codex with MCP

# ~/.codex/config.toml
[mcp_servers.oceandb]
url = "https://app.oceandb.ai/api/mcp"

What Codex should remember#

Codex can inspect a repository each time it starts, but not every important constraint lives in the files. Teams make decisions in reviews, incidents, experiments, and conversations. Personal preferences may apply across many repositories. Those are good candidates for an external memory layer.

OceanDB gives Codex three complementary operations: remember for structured capture, recall for hybrid semantic and lexical retrieval, and restricted SQL for exact questions that need the full data model.

The result is not a replacement for repository context. It is the missing history around that context.

Keep AGENTS.md and memory separate#

Use AGENTS.md for instructions that every agent working in the checkout must follow: commands, conventions, architecture, boundaries, and verification requirements. Keep those instructions versioned with the code.

Use OceanDB for context that grows through work:

• a decision and the alternatives considered;
• a stakeholder preference that spans several repositories;
• an operational constraint learned during an incident;
• a failed approach worth avoiding next time;
• a handoff that Claude Code or Cursor may continue.

This split prevents a global Codex configuration from becoming a dumping ground while still allowing a fresh task to recover the reasoning that code alone cannot show.

Give Codex a standing memory instruction#

After onboarding_status confirms the connection, install the master prompt in the appropriate Codex instruction scope. It asks Codex to search memory before requesting repeated context and to save only facts that remain useful after the current task ends.

A useful first test is:

Remember that API compatibility takes priority over internal cleanup until version 2 ships.

Open another Codex task and ask which constraint governs cleanup work. A successful answer should be grounded in an OceanDB recall, not in the previous task transcript.

Cross-repository and cross-agent continuity#

The user-level MCP definition makes the tool available to Codex regardless of the current checkout. OceanDB’s projects and tags then provide the subject boundary inside the store, while personal and shared workspaces provide the visibility boundary.

The same distinction enables cross-agent handoffs. Codex can save the result of an investigation; Claude Code can recall it during implementation; Cursor can retrieve the same constraint during an editor task.

Memory without agent-level deletion#

Coding agents routinely receive broad local permissions, so the memory service should enforce its own boundary. OceanDB’s MCP path runs under a database role that can select, insert, and update permitted content but cannot delete, truncate, or alter the schema.

Humans review raw entries, maintained pages, and proposed contradictions in the dashboard. The underlying store can also leave as Markdown or SQL. Codex gets a useful language over memory without becoming its irreversible administrator.