ReMe/plugins/codex/README.md

ReMe Plugin for Codex

Connect Codex to ReMe — file-native long-term memory for AI agents. The plugin gives Codex recall (read long-term memory) and records every session automatically via a Stop hook.

What you get

• MCP tools from the reme server: search, traverse, daily_list, frontmatter_read, read, auto_memory_cc, and more.
• Stop hook (hooks/auto_memory.py) — when a session ends it calls ReMe's server-side auto_memory_cc tool in a detached background process. Recording is fully automatic and asynchronous.
• Skill reme-memory — recall long-term memory before answering (semantic search, topological traverse, state daily_list/frontmatter_read, then read with citations), plus a server status check.

Deployment Model

The plugin connects to a shared HTTP MCP server you start once — it does not spawn ReMe. One server means one set of background watchers / dream cron across all your Codex sessions.

Prerequisites

1. Install ReMe (Python 3.11+):

   pip install "reme-ai[core]"
   

2. Configure model credentials in a .env (see example.env):

   EMBEDDING_API_KEY=sk-xxx
   EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
   LLM_API_KEY=sk-xxx
   LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
   

3. Start the ReMe MCP server (one time, leave it running):

   reme start service.backend=mcp service.transport=streamable-http
   

   It serves http://127.0.0.1:2333/mcp. To use a different port, start with service.port=<port> and update the url in .mcp.json to match.

Install the Plugin

Copy the plugins/codex/ directory to your Codex plugins location and install:

# Clone or copy the plugin directory
cp -r plugins/codex/ ~/.codex/plugins/reme/

# Configure MCP connection
# The .mcp.json is already bundled with the plugin

Restart Codex, then verify the reme server and its tools are connected. The reme-memory skill can then recall memory and report server health.

Plugin Structure

plugins/codex/
├── .codex-plugin/
│   └── plugin.json          # Codex plugin manifest
├── hooks/
│   ├── hooks.json           # Stop hook configuration
│   └── auto_memory.py       # Session recording hook
├── skills/
│   └── reme-memory/
│       └── SKILL.md         # Memory recall skill
├── .mcp.json                # MCP server connection
└── README.md                # This file

Notes

• The plugin's MCP server URL lives in plugins/codex/reme/.mcp.json. Keep it in sync with how you start ReMe (host/port). Override with REME_HOST / REME_PORT env vars.
• The Stop hook needs python3 on PATH. It logs to plugins/codex/hooks/auto_memory_hook.log.
• The MCP tool-name prefix may include the server segment depending on your Codex version; the skill uses the wildcard pattern so it works either way.
• Recording is best-effort: if the server is down, the hook logs and gives up silently without blocking the session.

Troubleshooting

Tools not showing up

1. Verify ReMe is running: curl -s http://127.0.0.1:2333/health_check
2. Check the MCP server URL in .mcp.json matches your ReMe port
3. Restart Codex after installing the plugin

Stop hook not recording

1. Check the log: cat plugins/codex/hooks/auto_memory_hook.log
2. Verify python3 is on PATH
3. Ensure the ReMe server is running when you end a session

Connection refused

The MCP server may not be running. Start it with:

reme start service.backend=mcp service.transport=streamable-http

Then retry.