Skip to content
Palimem Docsspec v1.7.0

Use Palimem with Codex

Connect Palimem to the OpenAI Codex CLI using either the ai-memory connect codex helper or the native codex mcp add command. Codex stores MCP config in ~/.codex/config.toml (global) or .codex/config.toml (project-scoped, trusted projects only).

Prerequisites

Section titled “Prerequisites”
  • OpenAI Codex CLI with MCP support
  • Node.js 18+
  • Repository cloned and Node dependencies installed:
    Terminal window
    cd app && npm install
Section titled “Recommended install”

From your repository root:

Terminal window
node app/scripts/ai-memory.js connect codex \
  --project-root "$(pwd)" \
  --data-dir .ai-memory/data

This writes to ~/.codex/config.toml (global). Use --project-config .codex/config.toml for project-scoped config.

Config block

Section titled “Config block”

The committed sample at examples/codex/.codex/config.toml.sample:

[mcp_servers.memory-service]
enabled = true
command = "node"
args = ["/absolute/path/to/repo/app/scripts/memory-service-mcp.js"]


[mcp_servers.memory-service.env]
MEMORY_SERVICE_DATA_DIR = "/absolute/path/to/repo/.ai-memory/data"

Use absolute paths in args and MEMORY_SERVICE_DATA_DIR. Project config overrides global for trusted workspaces.

Verification

Section titled “Verification”
Terminal window
codex mcp list
codex mcp get memory-service

In a Codex session, run /mcp to confirm eleven tools are available:

memory_remember, memory_search, memory_get, memory_forget, memory_status, memory_consolidate, memory_review, memory_profile, memory_reflect, memory_query_temporal, memory_audit_export

Smoke test:

Terminal window
bash examples/codex/demo/codex-smoke.sh

Agent prompt

Section titled “Agent prompt”

Paste this into your Codex session to configure Palimem:

Set up Palimem as governed local memory for this Codex session.


- Project: Palimem (spec v1.7.0)
- Run: codex mcp add memory-service --env MEMORY_SERVICE_DATA_DIR="$(pwd)/.ai-memory/data" -- node app/scripts/memory-service-mcp.js
- Verify: run /mcp inside Codex — expect 11 tools including memory_query_temporal and memory_audit_export


Use local data directory .ai-memory/data. Do not enable cloud services.


Note: Codex does not use lifecycle hooks. Use memory tools directly, or run ai-memory consolidate from cron.

CLI options

Section titled “CLI options”
Flag Purpose
--config PATH Override global config.toml (default: ~/.codex/config.toml)
--project-config PATH Write project .codex/config.toml
--project-root PATH Repo root for resolving script paths (default: $PWD)
--data-dir PATH MEMORY_SERVICE_DATA_DIR resolved to absolute
--replace Overwrite existing memory-service entry
--dry-run Print merged TOML without writing

Difference from Claude Code

Section titled “Difference from Claude Code”

Codex does not use Claude Code lifecycle hooks. Memory capture is explicit through MCP tools. Use operator CLIs for consolidation and review:

Terminal window
# Run consolidation from cron or a session script
node app/scripts/ai-memory.js consolidate \
  --data-dir .ai-memory/data


# Export review report
node app/scripts/ai-memory.js review export \
  --data-dir .ai-memory/data \
  --output .ai-memory/review.md

Troubleshooting

Section titled “Troubleshooting”

ENOENT on memory-service-mcp.js

Install Node dependencies first:

Terminal window
cd app && npm install

Existing entry refused

Re-run with --replace:

Terminal window
node app/scripts/ai-memory.js connect codex \
  --project-root "$(pwd)" --data-dir .ai-memory/data --replace

Tools show 9 instead of 11

Update to spec v1.7.0 — memory_query_temporal and memory_audit_export were added in v1.6.0.

/mcp shows no servers

Verify the config.toml was written to the correct path. For global: cat ~/.codex/config.toml. For project: cat .codex/config.toml.

Seed memory (optional)

Section titled “Seed memory (optional)”
Terminal window
python3 app/import_markdown.py \
  --data-dir .ai-memory/data \
  examples/markdown/USER.md.sample \
  examples/markdown/MEMORY.md.sample

Next steps

Section titled “Next steps”