best-project-memory
Use when restoring project context at the start of repo work, maintaining durable project memory across sessions, recording decisions, updating task state, preparing handoffs, or saving progress into repo-native memory files. Especially useful when users ask to continue previous
Install
npx skills add https://github.com/dengyie/awesome-skills/tree/main/best-project-memory
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dengyie-awesome-skills@llmmart
git clone https://github.com/dengyie/awesome-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole dengyie/awesome-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Best Project Memory
Mission
Maintain a lightweight, repo-native continuity layer that another Codex session can reload quickly.
Prefer filesystem truth over chat memory. Keep the memory compact, current, and handoff-ready.
Core Storage
Use .codex-memory/ in the current repository root.
Always maintain these core files:
.codex-memory/project-state.md.codex-memory/session-log.md.codex-memory/decisions.md.codex-memory/todo.md
Use these optional directories when the work justifies them:
.codex-memory/phases/.codex-memory/handoffs/.codex-memory/workstreams/.codex-memory/snapshots/
Read references/state-schema.md before creating or restructuring the files.
Read references/surface-contract.md before changing the memory surface or deciding which objects are script-owned.
Required Workflow
Restore context before project work.
- Ensure
.codex-memory/exists. - Read the four core files when they exist.
- If phase or handoff docs exist and are obviously relevant, read only the needed ones.
- Give a short loaded-context recap covering objective, phase, active TODOs, latest decisions, and blockers.
- For concrete project delivery work, establish the milestone execution contract before implementation starts.
- Ensure
Establish a milestone execution contract for production work.
- Use a milestone as the current-session scope container. It must deliver at least one of: user capability, release gate closure, core architecture boundary, or blocking defect fix.
- Classify discovered work before editing:
P0: delivery blockers, severe bugs, security issues, build failures.P1: required current-milestone functionality, tests, or refactors.P2/P3: optimizations, enhancements, and long-term maintenance. Route these to backlog only.Manual-required: external accounts, certificates, signing, notarization, real devices, production secrets, or third-party permissions.
- Output and then obey this Step 0 contract:
Milestone:
Goal:
P0/P1 scope:
Out-of-scope P2/P3:
Manual-required:
Phase limit:
Phase split:
Acceptance criteria:
Stop conditions:
- Freeze scope after the contract. Expand only for a true P0/P1 blocker.
- Default to at most 3 phases; use at most 5 only for genuinely complex milestones.
- Make each phase a deliverable closure around feature, architecture, defect fix, test gate, build chain, permission path, or release gate. Do not create phases for single files, fields, scripts, evidence snippets, or standalone paperwork.
- Stop after the milestone's P0/P1 work passes necessary verification. Do not automatically open the next milestone.
Keep the state panel current.
- Treat
project-state.mdas the single current snapshot. - Overwrite only the live summary content there.
- Keep it concise and operational.
- Push workstream-level detail down into
workstreams/*.mdinstead of bloating the global state.
- Treat
Append session history.
- Add a new entry to
session-log.mdafter meaningful progress, at session close, or when the user asks to save progress. - Do not rewrite old session entries unless correcting obvious factual mistakes.
- Add a new entry to
Record important decisions.
- Add ADR-lite entries to
decisions.mdfor meaningful choices, tradeoffs, or policy changes. - Include rationale and impact, not just the conclusion.
- Add ADR-lite entries to
Maintain actionable TODO state.
- Keep
todo.mdfocused on active work. - Mark completed items done instead of deleting them.
- Move stale or obsolete items only when their status is clear.
- Do not promote backlog items into new phases unless they block the current milestone's P0/P1 acceptance criteria.
- Record
Manual-requiredgaps with impact and validation entrypoint, but do not create development phases for them unless they materially shorten current-milestone verification.
- Keep
Summarize completed phases and milestone stops.
- After each phase, record completed content, validation, review score/status, key decisions, new backlog, manual-required gaps, and remaining phase budget.
- When stop conditions are met, write a milestone delivery summary or a manual-attention report. Do not continue into polish, extra evidence, or unrelated TODO cleanup after the stop condition is satisfied.
Create handoff artifacts when the work spans sessions or people.
- Use
handoffs/for compact continuation packs. - Use
phases/for milestone summaries. - Use
workstreams/for bounded parallel tracks inside larger projects. - Use
snapshots/for machine-oriented evidence captures. - Read
references/handoff-patterns.mdbefore writing a new handoff file.
- Use
Update Policy
Read references/update-policy.md before deciding where new information belongs.
Read references/update-triggers.md when deciding what kind of event should create a state update, promotion, or compaction step.
Use this routing rule:
- Current snapshot:
project-state.md - Time-ordered work record:
session-log.md - Durable choice with rationale:
decisions.md - Action queue:
todo.md - Milestone recap:
phases/*.md - Session transfer pack:
handoffs/*.md - Parallel task state:
workstreams/*.md - Evidence snapshot:
snapshots/*
Do not dump everything into session-log.md.
Deterministic Helpers
Use the helper scripts when they reduce repeated hand editing:
scripts/init_memory.py: initialize.codex-memory/with the standard files and optional phase/handoff directoriesscripts/append_session.py: append a structured session entry tosession-log.mdscripts/handoff_pack.py: generate a compact handoff file from the current memory snapshotscripts/compact_session.py: compact oldersession-log.mdhistory into a shorter summary and optional phase recap
Resolve script paths relative to this skill directory. For a user-scope install, they are usually under $HOME/.agents/skills/best-project-memory/scripts/.
Reference Routing
references/state-schema.md: read before creating or normalizing memory filesreferences/surface-contract.md: read before changing structure, ownership, or script write boundariesreferences/update-policy.md: read before deciding what to updatereferences/update-triggers.md: read when mapping work events to memory actionsreferences/quality-rules.md: read when checking whether the memory has drifted into low-quality patternsreferences/integration-patterns.md: read when another skill should consume or update this memory modelreferences/examples.md: read when you want concrete memory-entry examplesreferences/handoff-patterns.md: read before writing handoff or phase summaries
Load only the references needed for the current task.
Completion Standard
A project-memory pass is complete only when:
- the repo memory folder exists or has been intentionally confirmed unnecessary
- concrete project work has a visible milestone contract or an explicit reason it is unnecessary
- current objective, phase, blockers, and next step are easy to find
- durable decisions are captured with rationale
- TODOs reflect the real state of work
- another Codex session could resume without rereading the whole conversation
Files (awesome-skills)
-
agents
-
openai.yaml 302 B
Loading…
-
-
references
-
examples.md 2.7 KB
Loading… -
handoff-patterns.md 1.4 KB
Loading… -
integration-patterns.md 2.1 KB
Loading… -
quality-rules.md 2.9 KB
Loading… -
snapshot-schema.md 866 B
Loading… -
state-schema.md 3.2 KB
Loading… -
surface-contract.md 2.5 KB
Loading… -
update-policy.md 2.6 KB
Loading… -
update-triggers.md 2 KB
Loading… -
workstream-template.md 474 B
Loading…
-
-
scripts
-
append_session.py 1.7 KB
Loading… -
compact_session.py 8.9 KB
Loading… -
generate_handoff.py 5.7 KB
Loading… -
handoff_pack.py 2.3 KB
Loading… -
init_memory.py 3.4 KB
Loading… -
memory_lint.py 7.7 KB
Loading… -
promote_decision.py 2.6 KB
Loading… -
snapshot_state.py 4.2 KB
Loading… -
stale_todo_check.py 3.5 KB
Loading… -
sync_workstream.py 2.9 KB
Loading…
-
-
tests
-
test_skill_package.py 36.3 KB
Loading…
-
-
SKILL.md 7.6 KB
--- name: best-project-memory description: Use when restoring project context at the start of repo work, maintaining durable project memory across sessions, recording decisions, updating task state, preparing handoffs, or saving progress into repo-native memory files. Especially useful when users ask to continue previous work, save progress, summarize current state, capture decisions, or make another agent session resume cleanly. --- # Best Project Memory ## Mission Maintain a lightweight, repo-native continuity layer that another Codex session can reload quickly. Prefer filesystem truth over chat memory. Keep the memory compact, current, and handoff-ready. ## Core Storage Use `.codex-memory/` in the current repository root. Always maintain these core files: - `.codex-memory/project-state.md` - `.codex-memory/session-log.md` - `.codex-memory/decisions.md` - `.codex-memory/todo.md` Use these optional directories when the work justifies them: - `.codex-memory/phases/` - `.codex-memory/handoffs/` - `.codex-memory/workstreams/` - `.codex-memory/snapshots/` Read `references/state-schema.md` before creating or restructuring the files. Read `references/surface-contract.md` before changing the memory surface or deciding which objects are script-owned. ## Required Workflow 1. Restore context before project work. - Ensure `.codex-memory/` exists. - Read the four core files when they exist. - If phase or handoff docs exist and are obviously relevant, read only the needed ones. - Give a short loaded-context recap covering objective, phase, active TODOs, latest decisions, and blockers. - For concrete project delivery work, establish the milestone execution contract before implementation starts. 2. Establish a milestone execution contract for production work. - Use a milestone as the current-session scope container. It must deliver at least one of: user capability, release gate closure, core architecture boundary, or blocking defect fix. - Classify discovered work before editing: - `P0`: delivery blockers, severe bugs, security issues, build failures. - `P1`: required current-milestone functionality, tests, or refactors. - `P2/P3`: optimizations, enhancements, and long-term maintenance. Route these to backlog only. - `Manual-required`: external accounts, certificates, signing, notarization, real devices, production secrets, or third-party permissions. - Output and then obey this Step 0 contract: ```text Milestone: Goal: P0/P1 scope: Out-of-scope P2/P3: Manual-required: Phase limit: Phase split: Acceptance criteria: Stop conditions: ``` - Freeze scope after the contract. Expand only for a true P0/P1 blocker. - Default to at most 3 phases; use at most 5 only for genuinely complex milestones. - Make each phase a deliverable closure around feature, architecture, defect fix, test gate, build chain, permission path, or release gate. Do not create phases for single files, fields, scripts, evidence snippets, or standalone paperwork. - Stop after the milestone's P0/P1 work passes necessary verification. Do not automatically open the next milestone. 3. Keep the state panel current. - Treat `project-state.md` as the single current snapshot. - Overwrite only the live summary content there. - Keep it concise and operational. - Push workstream-level detail down into `workstreams/*.md` instead of bloating the global state. 4. Append session history. - Add a new entry to `session-log.md` after meaningful progress, at session close, or when the user asks to save progress. - Do not rewrite old session entries unless correcting obvious factual mistakes. 5. Record important decisions. - Add ADR-lite entries to `decisions.md` for meaningful choices, tradeoffs, or policy changes. - Include rationale and impact, not just the conclusion. 6. Maintain actionable TODO state. - Keep `todo.md` focused on active work. - Mark completed items done instead of deleting them. - Move stale or obsolete items only when their status is clear. - Do not promote backlog items into new phases unless they block the current milestone's P0/P1 acceptance criteria. - Record `Manual-required` gaps with impact and validation entrypoint, but do not create development phases for them unless they materially shorten current-milestone verification. 7. Summarize completed phases and milestone stops. - After each phase, record completed content, validation, review score/status, key decisions, new backlog, manual-required gaps, and remaining phase budget. - When stop conditions are met, write a milestone delivery summary or a manual-attention report. Do not continue into polish, extra evidence, or unrelated TODO cleanup after the stop condition is satisfied. 8. Create handoff artifacts when the work spans sessions or people. - Use `handoffs/` for compact continuation packs. - Use `phases/` for milestone summaries. - Use `workstreams/` for bounded parallel tracks inside larger projects. - Use `snapshots/` for machine-oriented evidence captures. - Read `references/handoff-patterns.md` before writing a new handoff file. ## Update Policy Read `references/update-policy.md` before deciding where new information belongs. Read `references/update-triggers.md` when deciding what kind of event should create a state update, promotion, or compaction step. Use this routing rule: - Current snapshot: `project-state.md` - Time-ordered work record: `session-log.md` - Durable choice with rationale: `decisions.md` - Action queue: `todo.md` - Milestone recap: `phases/*.md` - Session transfer pack: `handoffs/*.md` - Parallel task state: `workstreams/*.md` - Evidence snapshot: `snapshots/*` Do not dump everything into `session-log.md`. ## Deterministic Helpers Use the helper scripts when they reduce repeated hand editing: - `scripts/init_memory.py`: initialize `.codex-memory/` with the standard files and optional phase/handoff directories - `scripts/append_session.py`: append a structured session entry to `session-log.md` - `scripts/handoff_pack.py`: generate a compact handoff file from the current memory snapshot - `scripts/compact_session.py`: compact older `session-log.md` history into a shorter summary and optional phase recap Resolve script paths relative to this skill directory. For a user-scope install, they are usually under `$HOME/.agents/skills/best-project-memory/scripts/`. ## Reference Routing - `references/state-schema.md`: read before creating or normalizing memory files - `references/surface-contract.md`: read before changing structure, ownership, or script write boundaries - `references/update-policy.md`: read before deciding what to update - `references/update-triggers.md`: read when mapping work events to memory actions - `references/quality-rules.md`: read when checking whether the memory has drifted into low-quality patterns - `references/integration-patterns.md`: read when another skill should consume or update this memory model - `references/examples.md`: read when you want concrete memory-entry examples - `references/handoff-patterns.md`: read before writing handoff or phase summaries Load only the references needed for the current task. ## Completion Standard A project-memory pass is complete only when: - the repo memory folder exists or has been intentionally confirmed unnecessary - concrete project work has a visible milestone contract or an explicit reason it is unnecessary - current objective, phase, blockers, and next step are easy to find - durable decisions are captured with rationale - TODOs reflect the real state of work - another Codex session could resume without rereading the whole conversation
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.