# Record Project Memory > Use when a task has converged (end of resolve-issue, process-code-review, or the final orchestrator report) and a durable, reusable lesson was learned. Distils only the lessons that clear a strict promotion bar and appends them — after a dedup/supersede/prune curation pass — to the per-project compound memory file, never recording trivia, secrets, or PII. - Skill: `pekral/record-project-memory` (Agent Skill) - Install (CLI): `npx skillmds@latest add pekral/record-project-memory` - Raw SKILL.md: https://api.skillmd.com/api/skills/pekral/record-project-memory/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - License: MIT - Author: pekral (https://skillmd.com/u/pekral) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/pekral/record-project-memory --- ## Constraints - Apply `@rules/compound-engineering/general.mdc` *Compound Memory (per project)* — this skill is the write side of that rule; it owns the promotion bar, the curation pass, and the file convention defined there. - Apply `@rules/git/general.mdc` - **Write-only to the memory file.** This skill modifies exactly one file: `docs/memory/PROJECT_MEMORY.md` in the project being worked on. It never edits production code, tests, configuration, `CLAUDE.md`, or `.cursor/rules/project.mdc`. - **Never record secrets, credentials, tokens, or PII** — apply the same prohibition the security rules apply to logs and tracker comments. When a lesson can only be stated with a secret, generalize it until the secret is gone or drop the entry. - **Per-project only.** The memory file lives in the target project, never in this shared rules package. Never write a project lesson into `rules/**` as a global rule. - Output must be in English (the memory file is a code artifact, like `CLAUDE.md`). ## Use when - A `@skills/resolve-issue` or `@skills/process-code-review` run has converged (review loop at 0 Critical / 0 Moderate) and is about to publish its final report. - An orchestrating run reaches its final report after the convergence gate. - The user explicitly asks to record a lesson into project memory. Do **not** run this skill mid-task, before convergence, or for a task that produced no durable lesson. ## Inputs - `CONVERGED_CONTEXT` — required. The converged task context: what was implemented/fixed, the review findings that recurred, the wrong turns taken, and the design decisions made. The orchestrator passes this from the shared brief; a skill passes its own run context. - `SOURCE_REF` — required. The PR / issue link to record in each entry's `Source:` field. - `AGENT_ROLE` — optional. The role writing this entry: `orchestration`, `analysis`, `implementation`, `review`, or `shared`. When omitted, defaults to `shared`. Written as the `Role:` field of every entry produced in this invocation. Pass the caller's own role — do not guess. ## Required approach ### 1. Locate (or plan) the memory file - Target `docs/memory/PROJECT_MEMORY.md` in the project being worked on. - If it does not exist, plan to create it with a one-line index header (`# Project memory — `). Creating it is allowed; this is the file's first write. - If the project demonstrably has no `docs/` tree and refuses to grow one, fall back to the project's existing learnings / decision-log file per `@rules/compound-engineering/general.mdc`. Never fall back to `CLAUDE.md` or `.cursor/rules/project.mdc` themselves. ### 2. Extract candidate lessons from the converged context List every candidate lesson the task surfaced: a recurring review finding, a non-obvious bug cause, a rejected approach, an architectural decision, or the canonical "this kind of change belongs in an existing part of the system, not a new abstraction" insight. ### 3. Apply the promotion bar (all three gates must pass) Keep a candidate only when it clears **all** of: 1. **Recurs beyond this task** — it generalizes to future work, not a one-off detail of this issue. 2. **Cost real effort to discover** — non-obvious, surprising, or learned after a wrong turn. 3. **Not already captured** — not already obvious from the code, the tests, the git history, or an existing rule. Drop every candidate that fails any gate. If **no** candidate clears the bar, record nothing and report `no entry: nothing cleared the promotion bar` — a trivial task writes nothing. ### 4. Format each surviving lesson One entry per lesson, in the greppable format from the rule: ``` ### — - Trigger: - Rule: - Example: - Source: Added: - Role: ``` `` is kebab-case and unique within the file. `Added:` is today's date. `Role:` is the value of the `AGENT_ROLE` input (defaults to `shared` when not provided). Strip any secret / credential / token / PII before writing. ### 5. Curation pass (before appending) Read the existing file and curate so it stays small and non-redundant: - **Dedup** — if an equivalent entry exists (same or very similar slug / lesson), do not add a duplicate; strengthen the existing entry only when the new occurrence adds a sharper trigger or example. - **Supersede** — when a new lesson replaces or contradicts an older entry, update (or mark superseded) the old one instead of keeping both. - **Prune** — remove entries whose referenced code was removed or whose lesson was promoted into a real `rules/**` file. - **Soft cap** — when the file grows large, consolidate related entries rather than letting it sprawl. - **Role dedup** — when deduplicating, consider entries with the same slug across different `Role:` values: if both `implementation` and `shared` carry the same lesson, keep the `shared` one and remove the role-specific one. Never widen a role-specific entry to `shared` unless the lesson genuinely applies across all roles. ### 6. Write and report - Apply the curated changes to the memory file (append new entries, edit/remove superseded or pruned ones). - Report in conversation: the slugs added, edited, pruned, and the count that failed the promotion bar — so the convergence handoff records what memory changed. ## Done when - Every candidate lesson was run through the three-gate promotion bar. - Surviving lessons were written to `docs/memory/PROJECT_MEMORY.md` in the entry format, after the curation pass deduped/superseded/pruned. - No secrets, credentials, tokens, or PII were written. - Only the memory file was modified — no production code, tests, `CLAUDE.md`, or `.cursor/rules/project.mdc`. - The report lists the slugs added/edited/pruned, or states `no entry: nothing cleared the promotion bar`. ## Output Humanization - Use [blader/humanizer](https://github.com/blader/humanizer) for all skill outputs to keep the text natural and human-friendly.