Consolidate plugins & skills into main repo + build Codex plugin #699

Context

Codex CLI now supports plugins (docs) — installable bundles that can package skills, MCP servers, and app integrations.

Our advantage:

• Codex users are already our biggest traffic source (79 clicks/week on docs:/integrations/codex)
• "codex memory" is a top search query (pos 4.0, 30 clicks/week)
• We already have a working MCP server — plugin is just better packaging

Current State (repo sprawl)

We have 3 separate repos that are really just different ways to distribute the same thing:

1. basic-memory-skills — 10 skills teaching agents how to use BM effectively
2. basic-memory-plugins — Claude Code plugin (skills + commands + hooks)
3. Need: Codex plugin — same skills, different packaging format

All three are core BM functionality, not separate products. They should live in the main repo.

Proposed Unified Structure

basic-memory/
├── src/                        # Python MCP server + CLI (existing)
├── docs/                       # Docs (existing)
├── skills/                     # ← Merge basic-memory-skills here
│   ├── memory-tasks/
│   ├── memory-schema/
│   ├── memory-reflect/
│   ├── memory-notes/
│   ├── memory-defrag/
│   └── ... (10 total)
└── plugins/                    # ← Merge basic-memory-plugins here
    ├── claude-code/            # Claude Code plugin
    │   ├── .claude-plugin/
    │   ├── skills/             # Can reference ../skills/
    │   └── commands/
    └── codex/                  # New Codex plugin
        ├── .codex-plugin/
        ├── skills/             # Can reference ../skills/
        └── .mcp.json

Why Consolidate

Single source of truth:

• Skills are core functionality, not a separate product
• Plugins are distribution mechanisms for those skills
• Easier to keep in sync with BM version bumps

Avoid duplication:

• Many skills are identical across Claude Code/Codex plugins
• Can reference or copy from central /skills/ directory
• Single README, single release process

Discoverability:

• New users find everything in one place
• Clear hierarchy: BM server → skills → plugins

Codex Plugin Specifics

What it includes:

1. MCP server config (.mcp.json) — auto-configures uvx basic-memory
2. Skills (reuse from /skills/):
   • memory-search — "Search my knowledge graph for X"
   • memory-write — "Save this to my knowledge graph"
   • memory-context — "Load context about X from my graph"
   • memory-tasks — "Create/update tasks that survive compaction"
   • memory-projects — "Switch to project Y"
3. Assets — icon, logo, screenshots
4. Manifest (.codex-plugin/plugin.json) — metadata, install surface copy

Distribution:

1. Initial: Local marketplace (users install via GitHub URL)
2. Later: Submit to official OpenAI Plugin Directory (when available)

Competitive position:

Mem0, Letta, Zep — all API-based, no Codex plugins yet
We'd be first with a real knowledge graph plugin for Codex

Migration Plan

• Move /skills/ from basic-memory-skills → basic-memory/skills/
• Move contents from basic-memory-plugins → basic-memory/plugins/claude-code/
• Create basic-memory/plugins/codex/ for Codex plugin
• Build Codex plugin (manifest + .mcp.json + skills + assets)
• Test both plugins (Claude Code + Codex) from consolidated repo
• Update marketplace URLs to point to subdirectories
• Archive basic-memory-skills and basic-memory-plugins repos (README redirects)
• Document plugin installation in docs.basicmemory.com
• Announce in Discord + social
• Submit Codex plugin to OpenAI directory (when available)

Example Plugins to Study

• claude-review-loop — review automation plugin
• Codex official docs

Open Questions

• Should plugins reference ../skills/ via symlinks or copy files during build?
• Do we need cloud API integration in plugins or just local MCP?
• What starter prompts should we suggest in defaultPrompt for Codex?
• Can we auto-configure project routing (multi-project support)?

Related Repos

• https://github.com/basicmachines-co/basic-memory-skills (10 skills, last updated Mar 26)
• https://github.com/basicmachines-co/basic-memory-plugins (Claude Code plugin, last updated Feb 15)
• https://github.com/basicmachines-co/openclaw-basic-memory (separate, different ownership model)