Persistent Memory

Persistent Memory

Persistent Memory keeps long-running project context in .agent/ so future Codex sessions can resume with less drift.

Trigger Conditions

Use this skill when:

• .agent/ files are missing, stale, inconsistent, or need initialization.
• Starting, continuing, pausing, or handing off long-running work.
• A plan, decision, task status, verification result, or blocker must persist across turns.

Do Not Trigger

Do not use this skill when:

• The user explicitly forbids writing project memory.
• The task is truly one-shot and no project state changes.
• A different project memory system is mandated by the user and conflicts with .agent/.

Memory Files

Maintain these files:

• .agent/PROJECT_BRIEF.md: stable project goal, constraints, source priority, commands, conventions.
• .agent/PLAN.md: current plan, phases, milestones, verification gates.
• .agent/TASKS.md: task list with status, owner/role, and next action.
• .agent/LOG.md: append-only chronological work log.
• .agent/DECISIONS.md: durable decisions with rationale and alternatives.
• .agent/HANDOFF.md: resume instructions for the next agent/session.
• .agent/REVIEW_CHECKLIST.md: self-review and quality checklist.

When Shen-Hua V2 runtime is enabled, also maintain:

• .agent/state/tasks.jsonl: machine-readable task queue.
• .agent/state/events.jsonl: append-only runtime event log.
• .agent/state/memory-index.json: local memory retrieval index.
• .agent/state/sync-outbox.jsonl: external sync outbox.
• .agent/resume-prompt.md: future-session resume prompt.
• .agent/automation-prompt.md: Codex automation prompt.

Update Rules

1. Read existing memory before changing it.
2. Preserve useful prior context; do not rewrite history into fiction.
3. Use timestamps for log entries.
4. Prefer concise append/update blocks over wholesale rewrites.
5. Mark uncertainty explicitly.
6. Keep .agent/HANDOFF.md current enough that another agent can resume immediately.

Required .agent/ Updates

When invoked, update at least one relevant memory file. For ordinary long-task rounds, update:

• .agent/LOG.md
• .agent/TASKS.md
• .agent/HANDOFF.md

For first-time setup, create all seven files with usable starter content.

Other Skills

Persistent Memory supports all Shen-Hua skills. It does not need to call other skills unless memory repair reveals that planning, verification, review, or handoff is missing.

Use $runtime-operator when the task needs queue operations, memory indexing/search, resume prompt generation, automation prompts, sync export, or the runtime gate.

Subagents

Do not launch subagents for routine memory updates. If multiple subagents are already running, record their assignments and statuses in .agent/TASKS.md and .agent/HANDOFF.md.

Verification Commands

No build/test command is required for memory-only edits. Validate by confirming the files exist and contain no placeholder-only sections.

Output Format

MEMORY UPDATE
Files read:
Files updated:
New facts:
Open uncertainties:
Next resume point:

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fengsihao23-eng
• Source: fengsihao23-eng/shen-hua
• License: MIT

Install and usage instructions live in the source repository linked above.