Use Oracle Agent Memory with Codex

Coding agents often begin a task without the decisions, repository conventions, architecture notes, and troubleshooting lessons discovered in earlier sessions. Reconstructing that context from source files and chat history costs time, money, and can lead to inconsistent changes.

The Oracle AI Agent Memory plugin for Codex (now ChatGPT Work) gives Codex persistent project memory. Codex can search prior knowledge before substantial work, add concise durable facts for a later session, and, when explicitly enabled, capture user prompts and final assistant replies in the current memory thread.

This guide packages the existing Codex plugin as a downloadable local marketplace and walks through both roles required to use it:

Warning: The included MCP server is a learning and reference deployment. It uses a shared-secret JWT and its default configuration serves plain HTTP on the local computer. Review and adapt authentication, transport security, credential storage, token lifecycle, authorization, and observability before using it beyond a trusted environment.

Download the plugin

Download the Codex plugin project, codex_plugin.zip. The archive is built from the repository’s examples/codex_plugin directory and contains the plugin manifest, Memory skill, MCP configuration, hooks, and reference server.

Extract it on the computer where you will run Codex. Read the plugin manifest, .mcp.json, and hooks/hooks.json before installing it. For general plugin concepts and installation behavior, see the ChatGPT plugin documentation.

unzip codex_plugin.zip
cd codex_plugin

Understand the components

The downloaded project has three plugin components and one administrator-run service:

The plugin defaults to http://127.0.0.1:8000/mcp. That works when the administrator and Codex run on the same computer. For an administrator-managed service, change the url in .mcp.json to the approved MCP endpoint before distributing or installing the plugin.

Install the Python requirements

The hooks and the MCP server run in different Python environments. Install their requirements where they execute.

Environment Required libraries
Python used to launch Codex requests. The plugin hook invokes that environment’s python executable.
Python used to run the reference MCP server oracleagentmemory, fastmcp, PyJWT, and python-dotenv, plus Oracle AI Database connectivity and configured embedding and LLM providers.

For example, install the hook dependency in the environment from which you start Codex:

python -m pip install requests

Install the reference server dependencies in the environment that will start the server:

python -m pip install oracleagentmemory fastmcp PyJWT python-dotenv

For SDK and database setup, see Setup Guide and Run Oracle AI Database locally.

Administrator: configure the Memory MCP server

The server reads its connection, model, and signing configuration from misc/.env. Copy the supplied template and populate it with values for your environment:

cp misc/.env.sample misc/.env
DB_USER="<database-user>"
DB_PASSWORD="<database-password>"
DB_CONNECT_STRING="<database-connect-string>"
EMBEDDER_MODEL_ID="<embedding-model-id>"
EMBEDDER_API_BASE="<embedding-api-base>"
EMBEDDER_API_KEY="<embedding-api-key>"
LLM_MODEL_ID="<llm-model-id>"
LLM_API_BASE="<llm-api-base>"
LLM_API_KEY="<llm-api-key>"
JWT_SECRET="<signing-secret>"

Generate the signing secret once, store it securely, and place the value in misc/.env. The same secret is required when issuing user tokens.

export JWT_SECRET="$(openssl rand -hex 32)"

Start the server from the extracted plugin directory:

python misc/remote_mcp_server.py \
  --host 127.0.0.1 --port 8000

Note: If the server is remote, use the host and port appropriate to that deployment, then make its endpoint match the plugin’s .mcp.json configuration.

Administrator: issue a user token

The reference server derives the user_id and agent_id scope from the bearer token rather than accepting those values from Codex. Create a token for the user and agent context that should share memory. Export the same signing secret used by the server, then run:

export JWT_SECRET="<same-signing-secret>"
python misc/create_token.py \
  --user-id "<user-id>" \
  --agent-id "<agent-id>"

Give the printed token to the intended Codex user through an approved secret delivery mechanism. Treat it as a credential for the memory scope encoded in it. The reference token lifetime and signing approach are example behavior, not a production token-management policy.

User: install the plugin in Codex

From the extracted plugin directory, add the local marketplace and install the plugin:

codex plugin marketplace add .
codex plugin add oracle-ai-agent-memory@codex-oam

Start Codex with the token supplied by the administrator:

OAM_MCP_TOKEN="<user-token>" codex

Run /mcp and confirm that the memory server is available with the search and add tools. These tools work without automatic capture.

User: optionally enable automatic session capture

The plugin’s hooks send each submitted user prompt and final assistant reply to the Memory MCP server. After installing and restarting Codex, run /hooks, inspect the Oracle AI Agent Memory UserPromptSubmit and Stop hooks, and explicitly trust them only if you want that behavior. For hook behavior and configuration details, see the ChatGPT hooks documentation.

Leaving the hooks untrusted disables automatic capture but does not prevent Codex from searching or adding memory through the MCP tools.

Conclusion

In this guide we learned how to download and install the Oracle AI Agent Memory Codex plugin, configure its reference MCP server, issue a scoped user token, and optionally capture session messages. Codex can now search durable project context and save reusable knowledge for later coding sessions.

→ Having learned how to use Oracle Agent Memory with Codex, you may also be interested in Use Agent Memory with an MCP Server.