Codex Memory Guard: Preserve Critical State Across Compaction

Where this fits

You're deep in a Codex session, refactoring a module and recording decisions in chat. The context window tightens, compaction triggers, and suddenly the key constraint you confirmed an hour ago is gone. The task boundary blurs, and you're re-explaining context. This skill steps in to make confirmed critical state durable, reviewable, and recoverable across compaction—so you don't lose the thread when the conversation condenses.

Why agents benefit

• Write-through critical memory: The agent persists confirmed decisions, constraints, and blockers to Markdown files immediately, not just in the ephemeral chat buffer.
• PreCompact and compact-resume hooks: The agent can execute a HANDOFF checkpoint before compaction and restore context after, minimizing loss.
• Task-boundary state machine: The agent compares new input against the current goal, estimating duration and suggesting topic switches before committing to work.
• Four-layer Markdown memory: A structured hierarchy (project, session, task, decision) that makes state easy to locate and audit.
• Recovery checkpoint + raw transcript fallback: Even if compaction happens, the agent has a compact checkpoint and a full transcript reference to reconstruct context.

Practical scenarios

Long-running refactor with interruptions

You're mid-way through a multi-file refactor. The agent detects you're about to switch topics and writes the current task state—files changed, next steps, and a verified lesson—to a HANDOFF file. When you return, it resumes from that checkpoint without re-asking for the same details.

Pre-compaction checkpoint

You notice the context is getting heavy. You run the PreCompact hook manually. The agent compresses the session into a structured summary, saves it, and then triggers compaction. After compaction, the agent reads the summary and continues as if nothing was lost.

Initializing memory for a new project

You point the agent at a fresh repo. It runs the initialization script, creating the four-layer Markdown memory structure and a hooks.json with the compaction hooks wired up. From then on, every critical decision is automatically persisted.

Add it to your agent workflow

Install the skill with:

npx skills add wl1650918245/codex-memory-guard --skill codex-memory-guard

Then, in a Codex session, ask it to "initialize memory system" for your project root. The agent will scaffold the memory files and hooks. As you work, it will automatically checkpoint at task boundaries and before compaction. For a manual checkpoint, say "write HANDOFF now" and it will persist the current state.

Compare before adopting

Before committing, compare this skill with alternatives that offer memory persistence or compaction handling. Look at:

• Quality signals: Does the skill handle edge cases like partial failures or concurrent edits? Are the scripts idempotent?
• Maintenance freshness: Check the commit history and issue responses. A skill that isn't updated for current Codex versions may break.
• Alternatives: Other approaches like AGENTS.md conventions or custom hooks may cover your needs with less overhead.
• Workflow fit: Does the four-layer structure match how you organize projects? If you work solo on small tasks, this might be overkill.

Why it is worth tracking

With 22 stars and an active author, codex-memory-guard is a niche but practical solution to a common pain point—compaction losing critical context. Its focus on write-through memory and explicit hooks is aligned with how serious agent developers handle state. Keep an eye on it if you build long-running Codex workflows; it's worth evaluating when you hit your first compaction-induced loss. For more skills like this, check out OpenAgentSkill's listing to see community feedback and similar tools.