Project Memory Skill

A tiny agent skill for durable project memory.

Agents read recent memory before substantial work and write short session memory afterward under:

docs/memory/YYYY-MM-DD/descriptive-slug-memory-YYYY-MM-DD.md

The point is simple: help future Codex, Claude, and other coding-agent sessions recover what happened, what was learned, decisions, gotchas, constraints, verification, open decisions, and useful next context without rereading the whole repo from scratch.

Why This Exists

Agent context resets are expensive. A small Markdown memory habit compounds into better collaboration:

• fewer repeated discoveries
• clearer project continuity
• better continuity between agents and humans
• less guessing after long-running or multi-day work

This is not a diary, transcript, or full knowledge-management system. It is a small continuity convention for durable lessons, decisions, and context.

Install

Copy SKILL.md into your agent skills folder or into any skill-distribution mechanism your agent supports.

For Codex-style local skills, a typical destination is:

~/.codex/skills/project-memory/SKILL.md

You can also copy the convention into a repo-level AGENTS.md, CLAUDE.md, or contributor guide if that is how your project gives agents instructions.

For agents that do not support formal skills, paste this into your project instructions:

Before substantial work, check for recent project memory:

find docs/memory -type f -name '*.md' | sort | tail -10

Read the most recent relevant memory files before acting.
After meaningful work, write a concise new memory file at:

docs/memory/YYYY-MM-DD/descriptive-slug-memory-YYYY-MM-DD.md

Capture what happened, what was learned, decisions, files changed,
verification, gotchas, constraints, open decisions, and useful next context. Do
not store secrets, credentials, PHI, private tokens, raw sensitive logs, or
verbose transcripts. Include handoff or resume instructions only when work is
incomplete, interrupted, or explicitly handed off.

Convention

Before substantial work:

find docs/memory -type f -name '*.md' | sort | tail -10

Read the most recent relevant files, then continue with the task.

After meaningful work, create a new file:

docs/memory/2026-05-18/runtime-contract-memory-2026-05-18.md

Keep it concise. Capture the durable parts of the session: what happened, what was learned, why decisions were made, and what still needs judgment.

Do not write memory for tiny edits, quick answers, or routine work with no durable decisions, constraints, verification, or next actions.

What Goes In Memory

• session summary
• what was learned
• decisions made
• open decisions
• files created or changed
• source-of-truth docs
• commands and verification
• gotchas and constraints
• open questions
• recommended next work, when useful
• handoff or resume notes, only when work is incomplete

What Does Not Go In Memory

• secrets, tokens, keys, or private credentials
• PHI or unnecessary sensitive details
• raw logs with private data
• verbose transcripts
• routine command spam

Repo Contents

SKILL.md                         # The drop-in skill
templates/memory-template.md     # Copyable memory template
examples/                        # Example memory files for common repo types
docs/launch-checklist.md         # Publishing checklist
agents/openai.yaml               # Optional Codex UI metadata

Adapting By Project Type

For SaaS/product repos, capture scope decisions, schema/API changes, auth or billing constraints, migrations, and verification commands.

For design or marketing sites, capture brand decisions, approved assets, client-sensitive placeholders, screenshot verification, and visual gotchas.

For agent/workspace repos, capture operational state, live paths, background jobs, lessons learned, exact resume commands when work is incomplete, and safety constraints.

License

MIT