Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

feat(plugin): ship Codex plugin manifest + marketplace (#311)

Rohit Ghumarec21410e28754
diff --git a/.codex-plugin/marketplace.json b/.codex-plugin/marketplace.json
new file mode 100644
index 00000000..65ec86ce
--- /dev/null
+++ b/.codex-plugin/marketplace.json
@@ -0,0 +1,22 @@
+{
+ "name": "agentmemory",
+ "interface": {
+ "displayName": "agentmemory"
+ },
+ "plugins": [
+ {
+ "name": "agentmemory",
+ "source": {
+ "source": "git-subdir",
+ "url": "https://github.com/rohitg00/agentmemory.git",
+ "path": "./plugin",
+ "ref": "main"
+ },
+ "policy": {
+ "installation": "AVAILABLE",
+ "authentication": "ON_INSTALL"
+ },
+ "category": "Memory"
+ }
+ ]
+}
diff --git a/README.md b/README.md
index cc8e79f1..4f330c5d 100644
--- a/README.md
+++ b/README.md
@@ -107,7 +107,7 @@ agentmemory works with any agent that supports hooks, MCP, or REST API. All agen
<td align="center" width="12.5%">
<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
<strong>Codex CLI</strong><br/>
-<sub>MCP server</sub>
+<sub>6 hooks + MCP + skills</sub>
</td>
<td align="center" width="12.5%">
<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
@@ -355,6 +355,25 @@ Implementation details live in `src/cli.ts` (see `runUpgrade` around the `src/cl
Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 4 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 51 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
```
+### Codex CLI (Codex plugin platform)
+
+```bash
+# 1. start the memory server in a separate terminal
+npx @agentmemory/agentmemory
+
+# 2. register the agentmemory marketplace and install the plugin
+codex plugin marketplace add rohitg00/agentmemory
+codex plugin install agentmemory
+```
+
+The Codex plugin ships from the same `plugin/` directory as the Claude Code plugin. It registers:
+
+- `@agentmemory/mcp` as an MCP server (all 51 tools when `AGENTMEMORY_TOOLS=all`)
+- 6 lifecycle hooks: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
+- 4 skills: `/recall`, `/remember`, `/session-history`, `/forget`
+
+Codex's hook engine injects `CLAUDE_PLUGIN_ROOT` into hook subprocesses (per [`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs)), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.
+
<details>
<summary><b>OpenClaw (paste this prompt)</b></summary>
@@ -427,7 +446,8 @@ The agentmemory entry is the **same MCP server block** across every host that us
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Same `mcpServers` block. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (auto-merges). |
| **OpenClaw** | OpenClaw MCP config | Same `mcpServers` block, or use the deeper [memory plugin](integrations/openclaw/). |
-| **Codex CLI** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually. |
+| **Codex CLI (MCP only)** | `.codex/config.toml` | TOML shape: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, or add `[mcp_servers.agentmemory]` manually. |
+| **Codex CLI (full plugin)** | Codex plugin marketplace | `codex plugin marketplace add rohitg00/agentmemory` then `codex plugin install agentmemory`. Registers MCP + 6 lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop) + 4 skills. |
| **OpenCode** | `opencode.json` | Different shape — top-level `mcp` key, command as array: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | Copy [`integrations/pi`](integrations/pi/) and restart pi. |
| **Hermes Agent** | `~/.hermes/config.yaml` | Use the deeper [memory provider plugin](integrations/hermes/) with `memory.provider: agentmemory`. |
diff --git a/plugin/.codex-plugin/plugin.json b/plugin/.codex-plugin/plugin.json
new file mode 100644
index 00000000..0e4e4798
--- /dev/null
+++ b/plugin/.codex-plugin/plugin.json
@@ -0,0 +1,15 @@
+{
+ "name": "agentmemory",
+ "version": "0.9.10",
+ "description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 51 MCP tools, 4 skills, real-time viewer.",
+ "author": {
+ "name": "Rohit Ghumare",
+ "url": "https://github.com/rohitg00"
+ },
+ "license": "Apache-2.0",
+ "homepage": "https://github.com/rohitg00/agentmemory",
+ "repository": "https://github.com/rohitg00/agentmemory",
+ "skills": "./skills/",
+ "mcpServers": "./.mcp.json",
+ "hooks": "./hooks/hooks.codex.json"
+}
diff --git a/plugin/hooks/hooks.codex.json b/plugin/hooks/hooks.codex.json
new file mode 100644
index 00000000..73e43c66
--- /dev/null
+++ b/plugin/hooks/hooks.codex.json
@@ -0,0 +1,67 @@
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs",
+ "statusMessage": "agentmemory: loading session context"
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/prompt-submit.mjs",
+ "statusMessage": "agentmemory: recalling relevant memories"
+ }
+ ]
+ }
+ ],
+ "PreToolUse": [
+ {
+ "matcher": "Edit|Write|Read|Glob|Grep",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/pre-tool-use.mjs"
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use.mjs"
+ }
+ ]
+ }
+ ],
+ "PreCompact": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/pre-compact.mjs"
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/stop.mjs"
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/test/codex-plugin.test.ts b/test/codex-plugin.test.ts
new file mode 100644
index 00000000..bb380876
--- /dev/null
+++ b/test/codex-plugin.test.ts
@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const repoRoot = resolve(__dirname, "..");
+const pluginRoot = join(repoRoot, "plugin");
+
+function readJson<T = unknown>(path: string): T {
+ return JSON.parse(readFileSync(path, "utf-8")) as T;
+}
+
+describe("Codex plugin manifest (developers.openai.com/codex/plugins)", () => {
+ it("ships .codex-plugin/plugin.json with kebab-case name + version + references", () => {
+ const manifestPath = join(pluginRoot, ".codex-plugin/plugin.json");
+ expect(existsSync(manifestPath)).toBe(true);
+ const manifest = readJson<{
+ name: string;
+ version: string;
+ description?: string;
+ skills?: string;
+ mcpServers?: string;
+ hooks?: string;
+ }>(manifestPath);
+ expect(manifest.name).toBe("agentmemory");
+ expect(manifest.name).toMatch(/^[a-z][a-z0-9-]*$/);
+ expect(manifest.version).toMatch(/^\d+\.\d+\.\d+/);
+ expect(manifest.skills).toBeDefined();
+ expect(manifest.mcpServers).toBeDefined();
+ expect(manifest.hooks).toBeDefined();
+ });
+
+ it("manifest version matches main package.json", () => {
+ const pkgVer = readJson<{ version: string }>(join(repoRoot, "package.json")).version;
+ const codexVer = readJson<{ version: string }>(
+ join(pluginRoot, ".codex-plugin/plugin.json"),
+ ).version;
+ expect(codexVer).toBe(pkgVer);
+ });
+
+ it("all referenced manifest paths resolve to existing files / directories", () => {
+ const manifest = readJson<{ skills: string; mcpServers: string; hooks: string }>(
+ join(pluginRoot, ".codex-plugin/plugin.json"),
+ );
+ expect(existsSync(join(pluginRoot, manifest.skills))).toBe(true);
+ expect(existsSync(join(pluginRoot, manifest.mcpServers))).toBe(true);
+ expect(existsSync(join(pluginRoot, manifest.hooks))).toBe(true);
+ });
+
+ it("hooks.codex.json contains only events Codex supports (no Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure)", () => {
+ const hooksPath = join(pluginRoot, "hooks/hooks.codex.json");
+ const hooks = readJson<{ hooks: Record<string, unknown> }>(hooksPath);
+ const events = Object.keys(hooks.hooks);
+ const codexSupported = new Set([
+ "SessionStart",
+ "UserPromptSubmit",
+ "PreToolUse",
+ "PostToolUse",
+ "PermissionRequest",
+ "PreCompact",
+ "PostCompact",
+ "Stop",
+ ]);
+ for (const event of events) {
+ expect(codexSupported.has(event), `unexpected event "${event}" in hooks.codex.json`).toBe(true);
+ }
+ expect(events).toContain("SessionStart");
+ expect(events).toContain("UserPromptSubmit");
+ expect(events).toContain("PreToolUse");
+ expect(events).toContain("PostToolUse");
+ expect(events).toContain("PreCompact");
+ expect(events).toContain("Stop");
+ });
+
+ it("hook command scripts referenced in hooks.codex.json exist on disk", () => {
+ type HookHandler = { type: string; command: string };
+ type HookEntry = { hooks: HookHandler[] };
+ const hooks = readJson<{ hooks: Record<string, HookEntry[]> }>(
+ join(pluginRoot, "hooks/hooks.codex.json"),
+ );
+ const scriptRefs = new Set<string>();
+ for (const entries of Object.values(hooks.hooks)) {
+ for (const entry of entries) {
+ for (const handler of entry.hooks) {
+ const match = handler.command.match(/\$\{CLAUDE_PLUGIN_ROOT\}\/(scripts\/[^\s]+)/);
+ if (match) scriptRefs.add(match[1]);
+ }
+ }
+ }
+ expect(scriptRefs.size).toBeGreaterThan(0);
+ for (const rel of scriptRefs) {
+ expect(existsSync(join(pluginRoot, rel)), `missing hook script: ${rel}`).toBe(true);
+ }
+ });
+});
+
+describe("Codex marketplace.json (.codex-plugin/marketplace.json at repo root)", () => {
+ it("ships a marketplace manifest pointing at the plugin/ subdirectory", () => {
+ const marketplacePath = join(repoRoot, ".codex-plugin/marketplace.json");
+ expect(existsSync(marketplacePath)).toBe(true);
+ const marketplace = readJson<{
+ name: string;
+ plugins: Array<{
+ name: string;
+ source: { source: string; url: string; path: string; ref?: string };
+ }>;
+ }>(marketplacePath);
+ expect(marketplace.name).toBe("agentmemory");
+ expect(marketplace.plugins).toHaveLength(1);
+ const entry = marketplace.plugins[0];
+ expect(entry.name).toBe("agentmemory");
+ expect(entry.source.source).toBe("git-subdir");
+ expect(entry.source.path).toBe("./plugin");
+ expect(entry.source.url).toMatch(/rohitg00\/agentmemory/);
+ });
+});