Skip to content

README.md

Latest commit

 

History

History
399 lines (283 loc) · 11.4 KB

README.md

File metadata and controls

399 lines (283 loc) · 11.4 KB

Codex Plugin for mem9

Persistent memory for Codex.

After setup, it does two things automatically:

  • recalls relevant memories before each user prompt
  • saves a recent user / assistant window when Codex stops

Automatic recall uses recallMinPromptLength, which defaults to 5, after stripping already-injected memory context from the current prompt.

The plugin exposes:

  • $mem9:setup
  • $mem9:cleanup
  • $mem9:recall
  • $mem9:store

$mem9:setup is the main entrypoint. It manages shared profiles in the mem9 home, applies either global or project scope, and repairs the managed Codex hooks in the Codex home.

Requirements

  • Codex CLI 0.122.0 or newer
  • A Codex App build with plugin and hook support
  • Node.js 22 or newer
  • Network access to the mem9 server API

Install and First-Time Setup

  1. Add the marketplace:
codex plugin marketplace add mem9-ai/mem9

  1. In Codex, run /plugins, search for mem9, open the mem9-ai marketplace entry, and choose Install plugin.

  2. Restart Codex or open a fresh Codex session with the same CODEX_HOME. For normal installs, that is $HOME/.codex.

  3. Run:

    $mem9:setup

  4. If one repository needs a different profile, timeout, or recall prompt-length threshold, see Profiles and Project Scope.

  5. When you want an on-demand recall or an explicit store, run:

    $mem9:recall
$mem9:store

You do not need to enable hooks manually first. $mem9:setup inspects the saved profiles, enables the Codex hooks feature, and installs the managed hooks. Codex 0.129.0+ uses hooks = true; Codex 0.122.0 through 0.128.x uses codex_hooks = true.

Where Files Are Stored

The Codex plugin uses two home directories:

Variable Default when unset What lives there
CODEX_HOME ~/.codex on macOS/Linux Codex user state, hooks.json, config.toml, and mem9-managed Codex runtime files under $CODEX_HOME/mem9/
MEM9_HOME ~/.mem9 on macOS/Linux Shared mem9 credential profiles in $MEM9_HOME/.credentials.json

Most macOS/Linux users can leave both variables unset. With the defaults, Codex integration files live under ~/.codex/, and mem9 credentials live in ~/.mem9/.credentials.json. In shell commands, ~ means the same home directory as $HOME.

The defaults are equivalent to starting Codex from a shell with:

export CODEX_HOME="$HOME/.codex"
export MEM9_HOME="$HOME/.mem9"
codex

On Windows PowerShell, the same defaults resolve under your user profile:

$env:CODEX_HOME = "$env:USERPROFILE\.codex"
$env:MEM9_HOME = "$env:USERPROFILE\.mem9"
codex

Use the same CODEX_HOME and MEM9_HOME in trusted-shell commands that save or update profile keys. $mem9:setup keeps API key entry out of the Codex TUI and writes the key to $MEM9_HOME/.credentials.json.

Profiles and Project Scope

Use $mem9:setup for profile setup. It creates or selects mem9 profiles, saves profile keys, and applies the selected profile globally or for the current repository.

Set the default profile

  1. Run $mem9:setup.
  2. Choose create-new to create a mem9 API key, or choose use-existing to reuse a saved profile.
  3. Choose user scope.

This selects the default profile Codex uses across repositories.

Use a different profile in one repository

  1. Open Codex from that repository.
  2. Run $mem9:setup.
  3. Choose create-new or use-existing for the repository profile.
  4. Choose project scope.

Project scope can override:

  • profileId
  • defaultTimeoutMs
  • searchTimeoutMs
  • recallMinPromptLength

Return a repository to the default profile

  1. Open Codex from that repository.
  2. Run $mem9:setup.
  3. Choose clear project scope.

The repository will use the user-scope default profile again.

Use the same CODEX_HOME and MEM9_HOME when starting Codex and when saving profile keys from a trusted shell. With the defaults above, Codex reads integration files from ~/.codex and mem9 reads shared profiles from ~/.mem9.

What setup writes

Manual edits are mainly for recovery or automation. The recommended path is still $mem9:setup.

Saved profiles are written to $MEM9_HOME/.credentials.json:

The keys under profiles are profile IDs. For example, "profileId": "work" selects the profiles.work entry.

{
  "schemaVersion": 1,
  "profiles": {
    "default": {
      "label": "Personal",
      "baseUrl": "https://api.mem9.ai",
      "apiKey": "..."
    },
    "work": {
      "label": "Work",
      "baseUrl": "https://api.mem9.ai",
      "apiKey": "..."
    }
  }
}

The user-scope default is written to $CODEX_HOME/mem9/config.json.

A project override is written to <project>/.codex/mem9/config.json. It only needs the fields that differ from the user-scope default:

{
  "schemaVersion": 1,
  "profileId": "work",
  "searchTimeoutMs": 15000,
  "recallMinPromptLength": 5
}

Remote update-check settings stay in user scope. Project scope only controls the active profile and request tuning for that repository.

Daily Commands

$mem9:setup

Single entrypoint for mem9 setup in Codex.

What it does:

  • inspects the current runtime, profiles, and scope config
  • lets you create a new mem9 API key or reuse an existing global profile
  • applies either user scope or project scope
  • repairs the Codex hooks feature flag, $CODEX_HOME/hooks.json, and the managed hook shims
  • keeps API key entry out of the Codex TUI

Project scope keeps profile, timeout, and recall prompt-length overrides. User scope also owns updateCheck.enabled and updateCheck.intervalHours.

$mem9:cleanup

Cleanup for the mem9-managed Codex files.

What it does:

  • inspect emits machine-readable JSON with sanitized paths and the current removable targets
  • run removes mem9-managed entries from $CODEX_HOME/hooks.json
  • run removes $CODEX_HOME/mem9/hooks/
  • run removes $CODEX_HOME/mem9/install.json
  • run removes $CODEX_HOME/mem9/config.json
  • run removes $CODEX_HOME/mem9/state.json
  • run --include-project also removes <project>/.codex/mem9/config.json

What it does not do:

  • it keeps $MEM9_HOME/.credentials.json
  • it keeps $CODEX_HOME/config.toml
  • it keeps $CODEX_HOME/mem9/logs/codex-hooks.jsonl

$mem9:recall

Manual memory lookup for the current request.

What it does:

  • uses the current effective profile
  • respects project override config when present
  • searches /v1alpha2/mem9s/memories with the current API key
  • uses searchTimeoutMs

$mem9:store

Manual memory store for one user-approved fact, preference, or instruction.

What it does:

  • uses the current effective profile
  • respects project override config when present
  • stores one content entry with synchronous confirmation
  • uses defaultTimeoutMs

Upgrade

Upgrade the Git marketplace entry, then restart Codex:

codex plugin marketplace upgrade mem9-ai

This updates the installed mem9 plugin for normal releases. Migration releases surface a SessionStart notice that asks for $mem9:setup once.

Uninstall / Reset

Follow this order:

  1. Enter Codex and run $mem9:cleanup.

  2. In Codex, open /plugins, search for mem9, and uninstall the plugin.

  3. After step 2 succeeds, exit Codex and run:

    codex plugin marketplace remove mem9-ai

This order keeps mem9-managed hooks and plugin state in sync while you remove the integration. This uninstall flow keeps $MEM9_HOME/.credentials.json. If you want a full removal, delete $MEM9_HOME/.credentials.json after the uninstall steps finish.

Local Development / Testing

This repository also ships a repo-local marketplace manifest at:

<repo>/.agents/plugins/marketplace.json

For local testing:

  1. Clone this repository.

  2. Open Codex with the repository root as the working directory. Codex discovers the repo-local marketplace from <repo>/.agents/plugins/marketplace.json.

  3. In Codex, run /plugins, search for mem9, open the repo-local marketplace entry for this checkout, and choose Install plugin.

  4. Run $mem9:setup.

  5. Restart Codex after plugin or marketplace changes.

  6. Reinstall mem9 from the repo-local marketplace when Codex still shows the older package after restart.

  7. Verify the plugin package from the repo root:

    pnpm --dir codex-plugin test
pnpm --dir codex-plugin typecheck

For script-level help during development:

node ./skills/setup/scripts/setup.mjs --help
node ./skills/setup/scripts/setup.mjs profile save-key --help
node ./skills/cleanup/scripts/cleanup.mjs --help
node ./skills/cleanup/scripts/cleanup.mjs run --help

Debugging

Set this before starting Codex:

export MEM9_DEBUG=1

By default the Codex plugin writes JSONL logs here:

$CODEX_HOME/mem9/logs/codex-hooks.jsonl

You can override the file path with MEM9_DEBUG_LOG_FILE.

Common issues:

  • If $mem9:setup returns no matches after installing from /plugins, restart Codex or open a fresh Codex session. Codex loads plugin skills when the session starts.
  • If inspect reports missing_install_metadata before setup finishes, continue with $mem9:setup. scope apply writes $CODEX_HOME/mem9/install.json.
  • If SessionStart says mem9 is not configured, run $mem9:setup.
  • If a repository needs a different profile, timeout, recall prompt-length threshold, or a cleared local override, rerun $mem9:setup in that repository and apply or clear project scope.
  • If you want to remove the managed Codex files before reinstalling or resetting mem9, run $mem9:cleanup.
  • If the selected profile is missing, run $mem9:setup to create or repair global profiles.
  • If the selected profile is missing an API key, run $mem9:setup and choose create-new, or add the profile manually in $MEM9_HOME/.credentials.json and rerun $mem9:setup, then choose use-existing.
  • If setup repairs malformed JSON files, it keeps sibling .bak copies before rewriting them.
  • If you installed an older prerelease that still points hooks at $CODEX_HOME/mem9/runtime/, run $mem9:setup once after upgrading.

Reference: Files, Config, Environment

File Layout

Runtime defaults:

CODEX_HOME=~/.codex
MEM9_HOME=~/.mem9

Global Codex integration:

$CODEX_HOME/hooks.json
$CODEX_HOME/config.toml

Global mem9 runtime and config:

$CODEX_HOME/mem9/hooks/
$CODEX_HOME/mem9/install.json
$CODEX_HOME/mem9/config.json
$CODEX_HOME/mem9/state.json
$CODEX_HOME/mem9/logs/codex-hooks.jsonl

Project override written by scope apply --scope project:

<project>/.codex/mem9/config.json

Shared credentials:

$MEM9_HOME/.credentials.json

Config Files

Credentials file:

{
  "schemaVersion": 1,
  "profiles": {
    "default": {
      "label": "Personal",
      "baseUrl": "https://api.mem9.ai",
      "apiKey": "..."
    }
  }
}

Global default config:

{
  "schemaVersion": 1,
  "profileId": "default",
  "defaultTimeoutMs": 8000,
  "searchTimeoutMs": 15000,
  "recallMinPromptLength": 5,
  "updateCheck": {
    "enabled": true,
    "intervalHours": 24
  }
}

Project override example:

{
  "schemaVersion": 1,
  "profileId": "work",
  "recallMinPromptLength": 5
}

Remote update-check settings stay in the global config. Set recallMinPromptLength to 0 to recall on every non-empty stripped user prompt.

Environment Overrides

Runtime and setup can use environment variables:

  • MEM9_API_URL
  • MEM9_API_KEY
  • CODEX_HOME
  • MEM9_HOME