self-improving-for-codex

Self-improving for Codex

Overview

Use this skill to give Codex a durable, Codex-native self-improving loop without depending on OpenClaw-only primitives such as SOUL or HEARTBEAT.md.

This skill assumes one stable rule-entry file and one stable memory directory:

• Global rule entry: ~/.codex/AGENTS.md
• Global memory directory: prefer ~/.codex/memories/

Workflow

1. Audit the current state

Inspect these locations first:

• global AGENTS.md
• the candidate memory directory
• any existing PROFILE.md, ACTIVE.md, LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md
• any existing automation related to nightly review or memory maintenance

If the environment already contains a partial setup, preserve it and extend it instead of replacing it blindly.

2. Establish the memory layout

Create or normalize these files in the global memory directory:

• PROFILE.md
• ACTIVE.md
• LEARNINGS.md
• ERRORS.md
• FEATURE_REQUESTS.md

Read references/memory-files.md when creating or repairing these files.

Use this separation consistently:

• PROFILE.md: long-term stable user profile and communication preferences
• ACTIVE.md: compact high-priority rules worth reading at the start of future tasks
• LEARNINGS.md: reusable learnings and corrections not yet promoted to top-level rules
• ERRORS.md: reusable debugging and environment failure knowledge
• FEATURE_REQUESTS.md: missing capabilities worth tracking across sessions

3. Wire the loop through AGENTS.md

Use AGENTS.md as the single Codex-native entry point.

Its job is to tell Codex:

• which memory files to read before starting work
• when to log new entries
• how to classify entries by file
• when to promote content from raw logs into ACTIVE.md
• that AGENTS.md itself must not be edited automatically unless the user explicitly asks

Read references/agents-snippet.md before proposing or updating the AGENTS.md text.

Unless the user explicitly asks for direct edits, propose the exact AGENTS.md snippet in chat and let the user apply it manually.

4. Add an optional nightly review loop

When the user wants recurring maintenance, create a nightly automation that:

• reviews the current memory files
• primarily refines LEARNINGS.md, ERRORS.md, and FEATURE_REQUESTS.md
• proposes or applies safe updates to the memory files
• never edits AGENTS.md automatically

Read references/nightly-review.md before designing the automation.

5. Validate the loop

Before finishing, confirm the setup actually forms a loop:

1. AGENTS.md points Codex to PROFILE.md and ACTIVE.md
2. the five memory files exist and have sane content
3. promotion rules are explicit
4. if automation was requested, the automation prompt clearly explains the refinement-only role and promotion rules

Promotion Rules

Apply these promotion rules consistently:

• Promote to ACTIVE.md only when the content is stable, cross-task useful, and likely to improve future execution or communication
• Keep PROFILE.md limited to durable user identity, style, and preference facts
• Keep temporary context out of PROFILE.md
• Keep one-off noise out of all memory files
• If a candidate item is ambiguous, keep it in a raw log or leave it as a proposal instead of promoting it

Safety Rules

• Do not assume Codex automatically reads arbitrary memory files; route the loop through AGENTS.md
• Do not describe OpenClaw-only mechanisms as if they exist natively in Codex
• Do not edit AGENTS.md automatically unless the user explicitly asks
• Prefer updating ACTIVE.md over bloating AGENTS.md
• Prefer compact, maintainable rules over long narrative summaries

Deliverables

When using this skill, aim to produce some or all of these:

• a memory directory with the five core files
• a proposed AGENTS.md snippet
• an optional nightly automation prompt
• a short explanation of what was created, what was not changed, and how the loop works