feat(codex): stop writing Codebase Memory guidance to global AGENTS.md

[astandrik]

Note

The original proposed solution below is historical. On August 24, 2026, the repository owner superseded the zero-guidance end state in this PR #1739 comment: Codex should retain a tiny global activation pointer while the installed skill owns the detailed behavior. PR #1739 follows that current direction; the original text is preserved below for decision history.

What problem does this solve?

The Codex installer currently writes Codebase Memory guidance to $CODEX_HOME/AGENTS.md and installs the Codebase Memory skill in the same run.

The behavior is visible in current main:

• The Codex install path builds $CODEX_HOME/AGENTS.md, passes it to install_generic_agent_config, and then installs the skill.
• The shared global guidance is maintained separately from the embedded skill and its activation description.
• The smoke test requires the Codex AGENTS.md file, and the README documents both AGENTS.md and the skill.

This was an intentional multi-agent compatibility choice. Commit 159378ad introduced Codex detection, marker-managed instruction files, and the original global block. Issue #976 and PR #977 later kept .codex/AGENTS.md as lightweight guidance while adding the skill.

Current Codex documentation describes different loading behavior for these two surfaces:

• Global AGENTS.md guidance is read at the start of every run and inherited across repositories.
• A skill starts with its name and description, and Codex loads the full SKILL.md only when the skill is selected.

As a result, Codex receives overlapping Codebase Memory instructions from two separately maintained sources. The global block consumes context even when the task does not call for structural code discovery. It can also drift from the skill's activation, fallback, pagination, coverage, and mutation rules.

A read-only reproduction on v0.10.2 shows that the installer still plans the global write:

$ codebase-memory-mcp --version
codebase-memory-mcp 0.10.2

$ codebase-memory-mcp install --plan |
    jq -r '.instruction_files_planned[] | select(endswith("/.codex/AGENTS.md"))'
/path/to/home/.codex/AGENTS.md

Proposed solution

For Codex, use the installed skill as the workflow instruction surface and stop writing Codebase Memory guidance to the global AGENTS.md.

One implementation path:

1. Pass NULL as the Codex instruction path when calling install_generic_agent_config.
2. Keep the Codex MCP entry, skill, agent profiles, and lifecycle hooks unchanged.
3. During install, remove only the exact codebase-memory-mcp:start/end managed block from an existing $CODEX_HOME/AGENTS.md. Preserve all content outside that block.
4. Keep uninstall able to remove the managed block from older installations.
5. Update install --plan, the smoke test, and the README so they no longer require a Codex global instruction write. If a legacy cleanup is planned, report it as a cleanup rather than a new instruction file.

Suggested regression coverage:

• A fresh Codex install does not create $CODEX_HOME/AGENTS.md.
• An existing user AGENTS.md without the managed markers stays byte-identical.
• An existing user AGENTS.md with the managed block loses only that block.
• install --plan and --dry-run do not mutate either case.
• Repeated installs do not restore the block.
• MCP, skill, profiles, and hooks retain their current behavior.

Alternatives considered

Keeping a short pointer in the global file still loads Codebase Memory guidance for every task and leaves two instruction surfaces to maintain. Copying the skill guidance into AGENTS.md has the same problem and defeats progressive disclosure.

Stopping new writes without a migration would leave the old managed block active for existing users, so the installer should clean up only the block it owns.

Confirmations

• I searched existing issues and this is not a duplicate. Issue feat: install codebase-memory skill for Codex #976 and PR feat(codex): install codebase-memory skill #977 are related, but they made the opposite tradeoff and deliberately retained the global block.

[Frikki]

This should be a top priority.