Skip to content

Codex Plugin

Nuzo includes a thin Codex plugin wrapper in packages/codex-plugin.

The plugin does not implement memory behavior directly. It points Codex at the Nuzo MCP server, while the memory lifecycle remains in packages/core.

Codex is one host package, not the whole product boundary. Claude Code and future MCP-compatible agent CLIs should use the same MCP server and core behavior.

See docs/architecture/agent-host-compatibility.md before changing plugin packaging.

Official Codex Shape

The Codex plugin contract starts with:

  • a plugin folder;
  • a required .codex-plugin/plugin.json manifest;
  • optional bundled capabilities such as skills, apps, and MCP servers;
  • installation through the Codex plugin directory or a configured marketplace source.

For Nuzo, the plugin should only package the MCP server. It should not store memory, rank recall results, validate privacy policy, or implement import/export behavior directly.

Codex identifies the plugin by the manifest name, so Nuzo keeps the stable identifier nuzo and the human display name Nuzo.

Package Layout

Development source:

packages/codex-plugin/
├── .codex-plugin/
│   └── plugin.json
├── .mcp.json
├── README.md
└── package.json

Generated release artifact:

build/plugins/codex/nuzo/
├── .codex-plugin/
│   └── plugin.json
├── .mcp.json
└── LICENSE

Generate and validate it with:

npm run package:plugins

The generated artifact is ignored by Git. Release automation should recreate it from a clean checkout.

Runtime Resolution

The source plugin uses the monorepo build for development:

packages/mcp-server/dist/index.js

The generated release plugin does not rely on that sibling directory. It pins the published MCP package to the same version as the plugin:

{
  "mcpServers": {
    "nuzo": {
      "command": "npx",
      "args": ["--yes", "@nuzo/mcp-server@0.1.0"]
    }
  }
}

0.1.0 is illustrative. Packaging uses the actual shared package version and rejects version drift.

The first launch may need npm registry access. Nuzo does not use latest and does not require a global install.

The MCP server uses the default local memory store:

~/.nuzo/memory/memories.sqlite

To override the store for local testing, run the MCP server with:

NUZO_MEMORY_STORE=/absolute/path/to/memories.sqlite node packages/mcp-server/dist/index.js

Development Install Flow

This flow validates the monorepo source package. It is separate from the generated release artifact.

  1. Build the monorepo:
npm run build
  1. Validate the plugin manifest and MCP config:
npm run check -w @nuzo/codex-plugin
  1. For release-layout testing, generate the artifact:
npm run package:plugins
  1. Point a local marketplace entry at build/plugins/codex/nuzo. The marketplace entry should use source.path relative to the marketplace root.

Example entry:

{
  "name": "nuzo",
  "source": {
    "source": "local",
    "path": "./plugins/nuzo"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Developer Tools"
}

  1. Restart Codex.

  2. Open the plugin directory:

codex
/plugins
  1. Install or enable Nuzo, then start a new thread before relying on the plugin.

The generated config becomes runnable only after its matching @nuzo/mcp-server version exists in npm. Until the first package publication, this validates layout and host metadata rather than a public end-user install.

Direct MCP Fallback

For debugging the MCP server without plugin packaging, configure Codex directly against the built server:

codex mcp add nuzo -- node /absolute/path/to/nuzo/packages/mcp-server/dist/index.js

Use this only to isolate MCP behavior. Plugin validation should still go through the package in packages/codex-plugin.

Exposed Tools

  • memory.remember
  • memory.recall
  • memory.recall_hook
  • memory.list
  • memory.update
  • memory.history
  • memory.forget
  • memory.forget_many
  • memory.export
  • memory.import
  • memory.doctor

Validation

Validate the plugin manifest with:

npm run check -w @nuzo/codex-plugin

The validator checks:

  • .codex-plugin/plugin.json exists;
  • required manifest fields are present;
  • the plugin identifier is stable kebab-case;
  • the license is Apache-2.0;
  • mcpServers points to an existing relative .mcp.json file;
  • source .mcp.json defines the development MCP server path.

Release validation additionally checks:

  • the MCP server runs through npx;
  • @nuzo/mcp-server is pinned to the plugin version;
  • no sibling monorepo path remains in the artifact.

The repository check also validates the plugin metadata:

npm run check

Generate and validate both host artifacts with:

npm run package:plugins

Current Limits

  • Public installation waits for publication of the matching MCP package.
  • Runtime memory remains local and should not be committed to Git.
  • Automatic recall or capture hooks must follow docs/operations/lifecycle-hooks.md before implementation.
  • Capture suggestions must follow docs/spec/capture-suggestions.md and call memory.remember only after confirmation.

Source References

  • Codex manual, Build plugins: plugin manifests, marketplace metadata, local plugin testing, and workspace sharing.
  • Codex manual, Plugins: plugin directory, install flow, enabled state, and new-thread pickup after install.
  • Codex manual, Model Context Protocol: direct MCP setup and plugin-provided MCP server configuration.