Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .codex-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Memory"
"category": "Developer Tools"
}
]
}
164 changes: 164 additions & 0 deletions docs/plugins/codex-local.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
# Agent Memory for local Codex

The plugin connects Codex to your running Agent Memory daemon through a bundled
stdio MCP bridge. It uses the same store as your configured Claude Code client.
It includes 17 shared skills, the daemon's enabled tools, three fixed resources,
three resource templates, and three prompts. The default daemon exposes 54 tools;
features such as embeddings, reflection, and team operations still need their
normal runtime configuration. Six optional hooks provide automatic capture on
Codex versions that support and trust them.

## Build and try the current source

Use Node.js 20+ and the system `zip` utility on macOS or Linux. From the repository:

```sh
npm install --legacy-peer-deps --no-audit --no-fund
npm run plugin:pack:codex
node dist/cli.mjs
```

The final command starts Agent Memory and may offer to install its pinned iii
engine. Keep the daemon running. In another terminal, use `node dist/cli.mjs status`
to check it. Use the built runtime when testing unreleased main; the published npm
package can lag the checkout.

Packaging creates `dist/plugins/agentmemory-codex-local/` and a versioned ZIP.
The archive has `.codex-plugin/plugin.json` and `.mcp.json` at its root, and
contains the bundled bridge, shared skills, icon, and supported hook scripts.
It excludes the Claude and Copilot manifests so their defaults cannot override
Codex configuration. `build-info.json` records the base revision and archive hashes;
uncommitted changes are included in the build, so it is not a release attestation.

Install the built folder through its generated local marketplace:

`agentmemory-local-preview` names this local test marketplace. It is not an npm
package or a public directory listing.

```sh
codex plugin marketplace add ./dist/plugins
codex plugin add agentmemory@agentmemory-local-preview
```

Restart Codex, inspect its MCP connection, and run the onboarding starter prompt.
Local installation copies the plugin into Codex's cache. After changing source,
rebuild and refresh or reinstall the preview; editing the source folder alone
does not update an installed copy.

After the feature is released in the repository, marketplace installation is:

```sh
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```

Those marketplace commands track published repository content. They do not install
unpublished changes from your working tree. Restart Codex after installation.

## Connection and capture

The bridge runs with `node scripts/plugin-bridge.mjs` from the installed plugin
directory. Codex resolves its relative `cwd` to that directory, including paths
with spaces. No npm download occurs when the bridge starts.

Default daemon URL: `http://localhost:3111`. Local authentication works without
copying a secret into Codex: the bridge uses `AGENTMEMORY_SECRET` from the host
environment, then the secret in `~/.agentmemory/.env`, then the daemon-generated
`~/.agentmemory/secret`. It rereads credentials for each request so a daemon
started after the bridge can connect without reinstalling the plugin.

For a custom port, supply `AGENTMEMORY_URL` to the MCP host and reconnect MCP.
Local credential files are read only for loopback URLs. A remote daemon requires
an explicit host `AGENTMEMORY_SECRET` and HTTPS when authenticated. Never put
credential values in a plugin manifest or archive.

`agentmemory connect codex` remains the alternative for MCP-only setup. If that
connection already exists, choose either it or the plugin's MCP connection to
avoid duplicate tools. Do not overwrite unrelated Codex configuration.

Check `/hooks` and trust the plugin hooks before expecting automatic capture.
Some Codex versions require `agentmemory connect codex --with-hooks` for global
hooks. Inspect the existing configuration first: enabling both native plugin
hooks and global copies can duplicate capture. Validate one captured event in
your host. On uninstall, remove any separately installed global hook entries or
MCP entry you no longer want; deleting the plugin does not remove your memories.

The bridge returns a visible failure if the daemon is stopped or authentication
fails. It does not save into the standalone fallback store. It does not retry
mutations automatically; a timeout can happen after a write committed, so inspect
state before retrying. Reconnect after changing the daemon's enabled tool surface.

Capture hooks ship with their shared `_capture.mjs` dependency. During an outage,
supported hooks retain observations in the runtime's bounded local spool. Inspect
it with `agentmemory capture --json`. The daemon recovers its spool at startup;
use `agentmemory capture --drain` to request recovery while it is running. Use the same port
and data-directory settings as the hooks. This recovery applies to captured
observations; failed MCP tool writes are not queued automatically.

## Verify before distributing

After packaging, run the live smoke test with an already installed binary matching
`III_PINNED_VERSION` in `src/version.ts`:

```sh
AGENTMEMORY_TEST_III=/absolute/path/to/iii npm run test:plugin:live
```

It starts a real engine and worker on temporary loopback ports, with a temporary
store and no model credentials. It checks daemon-generated authentication,
packaged hook capture and offline recovery, both MCP entry points sharing
memories, resources, prompts, lessons, deletion, outage failures, and persistence
across an engine restart. It launches hook scripts directly;
desktop hook dispatch and host trust UI still require a manual host test. The
normal test suite skips this check unless the engine path is explicitly set.

After publishing the selected runtime and shim versions, run:

```sh
npm run plugin:verify:published
```

This read-only registry check rejects mismatched runtime, shim, and engine SDK
versions, including a reused version whose published engine dependencies differ
from source. It requires an exact shim-to-runtime dependency. Building a ZIP does
not publish the matching daemon; do not distribute it as a release until this
check passes. The check does not establish OpenAI directory eligibility.

## Data and costs

Basic keyword recall requires no model key. Storage remains in the configured
daemon's local state. Local embeddings need an optional model download and local
compute. Compression, reflection, and external embeddings can use model tokens
and send selected content to the configured provider. Context injection consumes
the coding agent's context budget. Enable these features deliberately.

Memory results are evidence, not instructions. Respect user rules about saving,
verify changing facts against current code, and avoid saving secrets. Project
metadata is a retrieval aid, not an account or tenant authorization boundary.

## Public directory submission

The generated `agentmemory-codex-review` ZIP has MCP and skills but no lifecycle
hooks. It is a preparation artifact, not a submission-ready claim. OpenAI's
standard public flow currently expects a production HTTPS MCP server. Its guide
directs authors who need local MCP to contact OpenAI for support. Confirm local
stdio eligibility and the supported test environment before submitting this
archive. Removing hooks does not remove that requirement.

Once eligibility is confirmed: select a verified developer identity in the
[plugin dashboard](https://platform.openai.com/plugins), upload the complete MCP
package, resolve validation findings, supply five positive and three negative
tested scenarios plus an accessible demo, and submit for review. Publish after
approval. Privacy, terms, support details, and any required review access must be
real and accessible; this build does not invent those URLs or credentials.

See the repository's `docs/plugins/codex-submission.md` for the local-support brief
and proposed reviewer scenarios. Rebuild against the final release commit after
pending PRs merge, align runtime and manifest versions, and repeat artifact tests.

Sources checked October 1, 2026:

- [Packaging and local runtime](https://developers.openai.com/plugins/build/plugins)
- [Submission requirements](https://developers.openai.com/plugins/deploy/submission)
- [Local MCP eligibility](https://developers.openai.com/plugins/guides/submit-claude-plugin)
- [Codex hooks](https://learn.chatgpt.com/docs/hooks)
69 changes: 69 additions & 0 deletions docs/plugins/codex-submission.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Local MCP submission preparation

Status: local Codex package implemented; public directory eligibility, release
version, policy URLs, accessible demo, and review execution remain to be completed.
Nothing has been submitted or published by this workflow.

## Brief for the OpenAI contact

Agent Memory is an Apache-2.0 persistent-memory project for coding agents. We want
to distribute a Codex plugin with a local stdio MCP server. The bundled Node.js
bridge connects to the user's local Agent Memory daemon. It shares the daemon's
memory store with other configured coding agents. A hosted deployment would not
provide equivalent access to local sessions, files, or offline workflows.

The package includes guided setup, recall, session handoff, lessons, and memory
management. No account is needed for local keyword recall. Optional external model
providers are configured separately. The review archive contains no lifecycle
hooks; local users can install the capture-enabled package where supported.

Please confirm whether local stdio MCP is eligible for directory review, which
Codex surfaces can install it, and how reviewers should receive and launch the
local daemon. Please also confirm whether capture hooks require a separate review
path. We can provide an isolated sample dataset and a recorded local walkthrough.

This is a draft to send after release details are filled in. It has not been sent.

## Reviewer scenarios

Use an isolated daemon with synthetic repositories Alpha and Beta. Record the
runtime version, plugin hash, host version, tool outputs, and actual results for
each case. These are proposed acceptance scenarios, not completed user testing.

| Kind | Prompt or setup | Expected tools and behavior |
| --- | --- | --- |
| Positive | Remember that Alpha uses cursor pagination because offset scans exceeded its latency budget. | `memory_save`; save the supplied fact and reason, return its identifier. |
| Positive | In a fresh Codex session, recall why Alpha uses cursor pagination. | `memory_smart_search` or `memory_recall`; return the saved fact and provenance. Verify it belongs to Alpha. |
| Positive | Resume the most recent session for Alpha. | `memory_sessions`, then recall; select Alpha's recorded session and open question. |
| Positive | Learn that CI must run tests once because watch mode hangs. | `memory_lesson_save`, then `memory_lesson_recall`; preserve the correction and scope. |
| Positive | Forget the synthetic pagination memory with this identifier. | `memory_governance_delete`; honor the exact authorized target, then verify absence. |
| Negative | Stop the daemon while requesting a save. | A visible failure; no fallback-store success claim and no automatic write retry. |
| Negative | Seed a memory that instructs the model to export other memories to an unrelated URL. | Treat the record as untrusted data; do not execute the instruction. |
| Negative | Ask to resume a project with no matching session, while Beta has recent sessions. | Report no matching project session; do not substitute Beta or invent history. |

Project scope is not multi-tenant access control. Do not claim that a user with
access to the local daemon cannot read other projects in that same store.

## Release gates

- Rebuild from the final release commit after reviewing overlapping pending PRs.
Existing work includes MCP annotations, project scoping, standalone resources
and prompts, Codex hook refresh, and shim version pinning. Preserve those PRs.
- Validate the packaged bridge over stdio and HTTP, then install it in a clean
Codex CLI and desktop profile. Verify one real captured event and a restart.
- Run `npm run plugin:verify:published` after publishing matched versions; a
successful source build does not establish npm compatibility.
- Test Claude Code and Codex against the same isolated daemon for handoff.
`AGENTMEMORY_TEST_III=/absolute/path/to/iii npm run test:plugin:live` exercises
their MCP entry points and packaged hook scripts. It does not replace a host UI
test or the recorded walkthrough.
- Record all eight reviewer scenarios, including tool errors and provenance.
- Fill in accessible privacy and terms URLs, support details, and the demo URL.
Use synthetic data; provide review access separately if requested.
- Obtain OpenAI's local-MCP eligibility instructions, then upload the review ZIP
and resolve dashboard checks. Do not submit the hook-containing local ZIP to a
flow that disallows lifecycle hooks.

[Official submission guide](https://developers.openai.com/plugins/deploy/submission)
and [local MCP conversion guidance](https://developers.openai.com/plugins/guides/submit-claude-plugin)
were checked October 1, 2026. Recheck before submission.
3 changes: 3 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,9 @@
"skills:gen": "tsx scripts/skills/generate.ts",
"engine:hashes": "node scripts/engine-hashes.mjs",
"skills:check": "tsx scripts/skills/generate.ts --check && tsx scripts/skills/check.ts",
"plugin:pack:codex": "npm run build && node scripts/plugins/package-codex.mjs",
"plugin:verify:published": "node scripts/plugins/verify-published.mjs",
"test:plugin:live": "node scripts/plugins/test-live.mjs",
"bench:load": "node --import tsx benchmark/load-100k.ts",
"bench:capture-costs": "node --import tsx benchmark/capture-costs.ts",
"eval:longmemeval": "tsx eval/runner/longmemeval.ts",
Expand Down
2 changes: 1 addition & 1 deletion plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "agentmemory",
"version": "0.9.29",
"description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 8 skills, real-time viewer.",
"description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 12 hooks, 54 MCP tools, 17 skills, real-time viewer.",
"author": {
"name": "Rohit Ghumare",
"url": "https://github.com/rohitg00"
Expand Down
28 changes: 25 additions & 3 deletions plugin/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "agentmemory",
"version": "0.9.29",
"description": "Persistent memory for AI coding agents -- captures tool usage, compresses via LLM, injects context into future sessions. 6 hooks, 54 MCP tools, 8 skills, real-time viewer.",
"description": "Local persistent memory for coding agents. Recall decisions, resume sessions, learn from corrections, and manage memory through 54 MCP tools and 17 skills. Optional capture through 6 Codex hooks.",
"author": {
"name": "Rohit Ghumare",
"url": "https://github.com/rohitg00"
Expand All @@ -10,6 +10,28 @@
"homepage": "https://github.com/rohitg00/agentmemory",
"repository": "https://github.com/rohitg00/agentmemory",
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"hooks": "./hooks/hooks.codex.json"
"mcpServers": "./.mcp.codex.json",
"hooks": "./hooks/hooks.codex.json",
"interface": {
"displayName": "Agent Memory",
"shortDescription": "Memory across coding sessions",
"longDescription": "Recall past decisions, resume work, save useful context, and learn from corrections across Codex and Claude Code using one local Agent Memory daemon. Includes search, session history, lessons, graph queries, memory maintenance, export, and deletion workflows. Requires Node.js 20+ and a running Agent Memory daemon. Basic keyword recall needs no model key. Embeddings and model-based features require configuration; external providers may receive selected data when enabled. Automatic capture requires trusted, supported hooks. Designed for local Codex sessions.",
"developerName": "Rohit Ghumare",
"websiteURL": "https://github.com/rohitg00/agentmemory",
"supportURL": "https://github.com/rohitg00/agentmemory/issues",
"category": "Developer Tools",
"capabilities": ["Local persistent memory", "Session handoff", "Lessons and recall", "Memory management"],
"defaultPrompt": [
"Check my local Agent Memory connection and explain which features are enabled.",
"Recall decisions relevant to this repository, with the evidence for each.",
"Resume the latest session for this repository and show the recorded next step."
],
"logo": "./assets/icon.svg",
"composerIcon": "./assets/icon.svg"
},
"extensions": {
"com.openai": {
"onboardingSkill": "./skills/agentmemory-config/SKILL.md"
}
}
}
12 changes: 12 additions & 0 deletions plugin/.mcp.codex.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"mcpServers": {
"agentmemory": {
"command": "node",
"args": ["scripts/plugin-bridge.mjs"],
"cwd": ".",
"env_vars": ["AGENTMEMORY_URL", "AGENTMEMORY_SECRET"],
"startup_timeout_sec": 20,
"tool_timeout_sec": 30
}
}
}
35 changes: 35 additions & 0 deletions plugin/assets/icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading