memory-refiner

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:

1. Current project .codex/
2. Repo-local AGENTS.md or similar repo-local instruction files
3. 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.