Durable, user-owned project memory for Codex.
Recall the context behind the code, preserve engineering decisions, and hand work across sessions without embedding memory or secrets in the repository.
Quick start · Architecture · Memory workflow · Package · Security · Validation
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.
Important
This repository is a public plugin review candidate. It does not claim approval or availability in the official Codex or universal plugin directory.
| 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 |
- 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.
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 codexThe 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.
Tip
To run without a global installation, use
npx --yes --package @xmemo/client xmemo <command>.
For manual configuration, environment-variable setup, and diagnostics, see install.md.
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.
- Codex activates the bundled skill for a memory-aware engineering workflow.
- The MCP client connects to
https://xmemo.dev/mcpover HTTPS. XMEMO_KEYis resolved from the local environment and sent as the bearer credential.- XMemo returns or stores only the context selected by the active tool call.
- Agent headers preserve Codex attribution independently from authentication.
- Recall focused context for the repository, subsystem, and current task.
- Restore a restart snapshot when continuing unfinished work.
- Treat live repository state as canonical when memory and code disagree.
- Capture pending decisions before a material architecture tradeoff.
- Resolve decisions after implementation or explicit confirmation.
- Save durable conclusions, not verbose intermediate reasoning.
- Keep recall scoped to the user's request.
- Save what changed and what was verified.
- Record the blocker, next action, and concrete follow-ups.
- Create a restart snapshot when work is incomplete.
| 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 |
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.
.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.
Run the deterministic package validator:
python scripts/validate-package.pyIt verifies:
- manifest identity, SemVer, metadata, and relative paths;
- supported direct-map
.mcp.jsonstructure; - 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 codexFor MCP-level inspection, use the official inspector:
npx @modelcontextprotocol/inspector@latestSynthetic evaluation prompts are maintained in examples/review-prompts.md.
- 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:
Canonical service policies:
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.
| 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 |
MIT © 2026 Yonro.