| name | memory-refiner |
| description | Use this skill when the user asks to refine Codex memory, improve Codex instructions or config, analyze session or history patterns, optimize context efficiency, or update global or project-local Codex guidance based on repeated interaction patterns. |
| metadata | {"short-description":"Refine Codex memory and config from history and active instruction layers"} |
Memory Refiner
Overview
Use this skill to audit how Codex is configured and instructed, then suggest targeted improvements. This skill is Codex-specific: analyze Codex files and usage patterns, not Claude files.
When To Use
Use this skill when the user asks to:
- refine or optimize Codex memory, instructions, rules, or config
- analyze repeated session patterns or recurring corrections
- reduce context bloat or reorganize guidance for lazy loading
- separate global guidance from project-local overrides
Workflow
1. Collect Evidence
- Use the current conversation as the highest-signal short-term evidence.
- Treat interruption or abort notices in the current conversation (for example
Conversation interrupted or turn_aborted) as workflow signals, even if they do not appear in history.jsonl.
- Run
python3 scripts/scan_history.py --format markdown to summarize ~/.codex/history.jsonl.
- Look for repeated preferences, repeated corrections, interruption or abort signals, approval friction, context bloat, stale guidance, and recurring task patterns.
2. Audit Active Memory Surfaces
- Run
python3 scripts/list_memory_surfaces.py --cwd "$PWD" --format markdown.
- Read only the files that are relevant to the request.
- Include the current project's local
.codex/ when present.
- Include repo-local instruction files such as
AGENTS.md when present.
3. Apply Scope Precedence
Use this precedence when evaluating what should win for the current repo:
- Current project
.codex/
- Repo-local
AGENTS.md or similar repo-local instruction files
- Global
~/.codex
Flag shadowing, duplication, and conflicts across these scopes.
4. Synthesize Recommendations
- Separate findings by scope: global, project-local, and repo-local.
- Keep universal guidance project, language, framework, and technology agnostic unless repeated evidence strongly justifies specificity.
- Treat explicit user statements as higher priority than inferred preferences.
- Do not turn one-off incidents into permanent memory.
5. Suggest Before Applying
For each recommendation, provide:
- target file
- scope
- priority
- change type:
add, modify, move, delete, or split
- exact proposed change or diff-ready text
- a short rationale tied to evidence
Do not apply changes until the user approves the specific items.
6. Apply Approved Changes
- Apply only the approved subset.
- Re-check for conflicts after editing.
- Re-run surface discovery if the scope layout changed.
In Scope
~/.codex/AGENTS.md~/.codex/instructions/**/*.md~/.codex/rules/*.rules~/.codex/config.toml~/.codex/skills/*/SKILL.md~/.codex/skills/*/agents/openai.yaml- current project
.codex/**/*.{md,toml,rules,yaml,yml}
- current project
AGENTS.md
Out Of Scope By Default
- Claude config or Claude skills
- unrelated repositories'
.codex/ directories
- auth, sqlite, logs, tmp, sessions, caches, and shell history
- raw history dumps when a compact summary is enough
Output Style
- Be compact and evidence-based.
- Separate facts, assumptions, and recommendations.
- Prefer moving specialized guidance out of global or root files into lazy-loaded files when appropriate.
