---

XMemo for Codex combines a reusable memory workflow with a hosted Model Context Protocol connection. Codex continues to execute, inspect, and validate work from the repository; XMemo carries the durable context that should survive the current task.

At a glance

Plugin	xmemo-codex-plugin
Version	0.1.0
Bundle	Codex Skill + hosted MCP configuration
MCP endpoint	https://xmemo.dev/mcp
Authentication	Bearer token from XMEMO_KEY
Attribution	codex + optional stable local instance ID
Local memory storage	None in this repository
License	MIT

What it adds

• Focused recall — restore relevant project context before implementation.
• Durable decisions — preserve conclusions and tradeoffs without saving noisy chain-of-thought.
• Working continuity — maintain active task, blocker, next action, and restart state.
• Cross-agent context — reuse user-approved XMemo memory across connected AI tools.
• Attribution — identify Codex-authored memory separately from authentication.
• Reviewable packaging — public manifest, skill, MCP config, legal documents, test prompts, and deterministic validation.

Quick start

The supported setup path configures the same hosted MCP endpoint used by this plugin package:

npm install --global @xmemo/client
xmemo login
xmemo mcp add codex
xmemo mcp add codex --write
xmemo smoke --client codex

The first mcp add is a dry run. The second writes the Codex MCP entry while preserving unrelated configuration. Restart Codex after setup, then ask:

Use XMemo to recall focused context for this repository.

For manual configuration, environment-variable setup, and diagnostics, see install.md.

Architecture

The plugin has two complementary parts:

Component	Responsibility
skills/xmemo-codex/SKILL.md	Teaches Codex when to recall, record decisions, update state, and prepare a handoff
.mcp.json	Declares the authenticated hosted XMemo connection

The package contains no XMemo service implementation, production credentials, private memories, deployment scripts, or internal runbooks.

Data path

1. Codex activates the bundled skill for a memory-aware engineering workflow.
2. The MCP client connects to https://xmemo.dev/mcp over HTTPS.
3. XMEMO_KEY is resolved from the local environment and sent as the bearer credential.
4. XMemo returns or stores only the context selected by the active tool call.
5. Agent headers preserve Codex attribution independently from authentication.

Memory workflow

At task start

1. Recall focused context for the repository, subsystem, and current task.
2. Restore a restart snapshot when continuing unfinished work.
3. Treat live repository state as canonical when memory and code disagree.

During engineering work

1. Capture pending decisions before a material architecture tradeoff.
2. Resolve decisions after implementation or explicit confirmation.
3. Save durable conclusions, not verbose intermediate reasoning.
4. Keep recall scoped to the user's request.

At handoff

1. Save what changed and what was verified.
2. Record the blocker, next action, and concrete follow-ups.
3. Create a restart snapshot when work is incomplete.

Capabilities and boundaries

Capability	Included	Boundary
Hosted XMemo MCP connection	Yes	Requires a user credential
Codex memory workflow Skill	Yes	Activates only for relevant tasks
Recall and search	Yes	Limited to memory visible to the authenticated account
Durable writes and state	Yes	Performed only through explicit workflow/tool use
Cross-agent attribution	Yes	Attribution headers are not authentication
Custom UI	No	No screenshots are submitted as UI metadata
Local memory database	No	Memory remains in the selected XMemo service
Private service code	No	The repository is intentionally reviewable
Official directory approval	No	Pending a successful official review

Authentication and attribution

The bundled server definition resolves authentication and attribution separately:

{
  "XMemo": {
    "url": "https://xmemo.dev/mcp",
    "bearer_token_env_var": "XMEMO_KEY",
    "http_headers": {
      "X-Memory-OS-Agent-ID": "codex"
    },
    "env_http_headers": {
      "X-Memory-OS-Agent-Instance-ID": "XMEMO_AGENT_INSTANCE_ID"
    }
  }
}

Value	Secret	Purpose
XMEMO_KEY	Yes	Authenticates the XMemo account
X-Memory-OS-Agent-ID: codex	No	Identifies the agent family
XMEMO_AGENT_INSTANCE_ID	No	Distinguishes one local Codex installation

Never commit a token into .mcp.json, config.toml, a project file, a screenshot, or a review log.

Package contents

.agents/plugins/marketplace.json   Local marketplace metadata
.codex-plugin/plugin.json          Plugin manifest and install-surface metadata
.github/workflows/validate.yml     Deterministic package validation
.mcp.json                          Hosted XMemo server definition
assets/                            Official logo and README diagrams
examples/review-prompts.md         Synthetic evaluation prompts
scripts/validate-package.py        Zero-dependency package validator
scripts/xmemo-codex-doctor.ps1     Local connection diagnostics
skills/xmemo-codex/SKILL.md        Codex memory workflow
install.md                         Setup and smoke-test guide
privacy.md                         Data-flow and user-control summary
.github/SECURITY.md                Credential and review boundaries
submission-note.md                 Reviewer-facing package summary

The manifest follows the current Codex plugin structure: only plugin.json lives under .codex-plugin/; skills, MCP configuration, marketplace metadata, assets, and supporting documents stay at the plugin root.

Validation

Run the deterministic package validator:

python scripts/validate-package.py

It verifies:

• manifest identity, SemVer, metadata, and relative paths;
• supported direct-map .mcp.json structure;
• endpoint, credential source, and attribution headers;
• marketplace and plugin name alignment;
• Skill frontmatter;
• official image signatures and parseable SVGs;
• README asset/document contracts;
• common committed-secret patterns.

Then check the hosted connection:

pwsh -File scripts/xmemo-codex-doctor.ps1
xmemo smoke --client codex

For MCP-level inspection, use the official inspector:

npx @modelcontextprotocol/inspector@latest

Synthetic evaluation prompts are maintained in examples/review-prompts.md.

Security and privacy

• Credentials stay in the local user environment or an approved secret store.
• The repository contains environment variable names, never token values.
• Agent and instance headers provide attribution only.
• Recall should stay scoped to the active repository and user request.
• Demos and review evidence must use synthetic memory.
• Custom UI is not included, so the manifest intentionally omits screenshots.

Read the full project documents:

• Privacy
• Security
• Submission note

Canonical service policies:

• Privacy policy
• Terms of service
• Support

Review status

This repository is prepared for local validation and future official plugin review. Public release claims must remain evidence-based:

• plugin manifest: present;
• skill bundle: present;
• hosted MCP configuration: present;
• production-safe logo: present;
• package validator and CI: present;
• synthetic test prompts: present;
• official directory approval: not claimed.

See the current official guidance for plugin packaging and plugin submission.

Agent-readable metadata

Field	Value
Package	xmemo-codex-plugin
Runtime	Codex
Role	Skill + hosted MCP
Service	https://xmemo.dev
MCP	https://xmemo.dev/mcp
Credential environment variable	XMEMO_KEY
Agent ID	codex
Agent discovery	https://xmemo.dev/.well-known/agent-discovery.json
Repository	https://github.com/yonro/xmemo-codex-plugin
Review state	Candidate; no official approval claim

License

MIT © 2026 Yonro.