/project-memory
Puts each CLAUDE.md note in the deepest file it applies to, so every session loads less and the notes stay true.
Created by Piyush Baheti · Source: piyush-tkd/skillsdugout/tree/main/plugins/project-memory
Who it is for
Anyone who keeps CLAUDE.md files in a repository, especially a large or multi-service one.
When to use it
- Something is worth recording for future sessions.
- A note in CLAUDE.md has turned out to be wrong.
- The root CLAUDE.md keeps growing.
Example
You ask
Add a note to our CLAUDE.md: the reminder job in services/scheduling-service only sends emails when NOTIFY_ENABLED=true, so running it locally sends nothing. The root CLAUDE.md lists each service; services/scheduling-service/CLAUDE.md already exists.
It writes the note and where it goes
Edit: services/scheduling-service/CLAUDE.md. The note is true only of this service's reminder job, so the service file is the deepest file that covers it.
Leave alone: the root CLAUDE.md. It is a router that lists services with a one-line pointer, and this gotcha is not true of the whole repo.
Gotchas
- The reminder job sends emails only when
NOTIFY_ENABLED=true. It is unset by default, so running the job locally sends nothing and logs no error. SetNOTIFY_ENABLED=trueto exercise the email path.
Output is Markdown (.md), shown formatted. Sample run on 2026-10-03 with an illustrative repository.
Evidence
Our test
No baseline test yet. We will publish one, with and without the skill, when testing is done.
Reported by the community, by app
Compatibility labels come from our tests only. Community reports add detail but cannot mark an app as tested.
Editorial review in progress
We have not finished testing this listing against doing the task without it. The verdict appears here when we have. Our team made this skill; it gets the same test as external work.
How we reviewSetup and customization
- Works with no setup after install.
What it can access
- Reads
- CLAUDE.md files and the folders they cover
- Changes
- Edits or creates CLAUDE.md files when you ask
Install
- Add the Skills Dugout marketplace once.
/plugin marketplace add piyush-tkd/skillsdugout - Install /project-memory.
/plugin install project-memory@skillsdugout - Start a new session and ask for it, for example "add this to CLAUDE.md".
Not tested in Claude apps yet. These steps follow Claude apps's documented skills folder.
- Turn on code execution in Settings, under Capabilities. Skills need it.
- Download the skill zip from this page.
- Open Customize, then Skills, and choose Upload a skill. Pick the zip.
Not tested in Cursor yet. These steps follow Cursor's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add project-memory --app cursor - For one repository only, run it inside the repo and add --project.
- No Node.js? Download the zip from this page and unzip it into ~/.cursor/skills/.
Not tested in Codex yet. These steps follow Codex's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add project-memory --app codex - For one repository only, run it inside the repo and add --project.
- No Node.js? Download the zip from this page and unzip it into ~/.codex/skills/.
Not tested in GitHub Copilot yet. These steps follow GitHub Copilot's documented skills folder.
- Install it with one command. Needs Node.js 18 or later.
npx skillsdugout add project-memory --app copilot - For one repository only, run it inside the repo and add --project.
- In VS Code, turn on the chat.useAgentSkills setting.
- No Node.js? Download the zip from this page and unzip it into ~/.copilot/skills/.
Community reviews
No reviews yet. Be the first to rate it after you try it.
Each review records the app, version, task and outcome; those outcomes feed the Evidence section. One rating per person; creators reply but cannot rate their own work.
No reviews yet. Be the first to rate it after you try it.
Source, license and versions
- Source
- github.com/piyush-tkd/skillsdugout/tree/main/plugins/project-memory
- License
- MIT, as stated in the repository
- 0.1.0 · 2026-10-03 · First release.
Show the full skill instructions
Updating a CLAUDE.md (project memory)
Overview
The CLAUDE.md files in the working directory and every folder above it load at session start. A CLAUDE.md in a subfolder loads only when Claude reads files in that subfolder. So a line at the repo root is paid for by every session, including ones that never touch that area; the same line in a subfolder costs nothing until it is relevant.
One exception: anything pulled in with an @import loads wherever the importing file loads. Moving
detail into a nested file saves nothing if the root still imports it.
Two questions, in order — most notes die at the first:
- Would a reader act differently because of this note?
- Which is the deepest file that covers every case it applies to?
When to use
- A change made a documented claim wrong
- A service or folder gained behaviour its notes do not mention
- A folder has durable, non-obvious rules that someone working there needs and that are not written anywhere
- The convenient file to edit is a router, or the repo root
When NOT to use — write nothing when:
- Opening the file says the same thing; headers and named tests are already read
- It restates structure — a package list, an endpoint table
grepanswers - It is a plan, a status, or intended work; that belongs in a ticket
- It narrates how something got built
A note nobody acts on is not free. It costs tokens and dilutes the rest.
Quick reference
The deepest file covering every case the note applies to, and no more.
| True of… | Goes in |
|---|---|
| every service and subproject | the repo-root CLAUDE.md |
| one service, all of it | that service's CLAUDE.md |
| one package or workflow folder | that folder's CLAUDE.md — create it if the note earns it |
| one file or method | a comment in that file |
| one kind of file wherever it lives (tests, migrations) | a path-scoped rule in .claude/rules/ |
A router lists its children, never its grandchildren — plus one pointer row.
Common mistakes
| Mistake | Instead |
|---|---|
| Writing to the root because it is already open | Deepest governing file, plus a pointer row |
| Notes for a folder you did not read | Read the file headers first |
| Listing endpoints or classes | Name only the ones with a trap in them |
| Importing a nested file from the root | Let it load on demand |
Red flags — stop
- The file you are about to edit is the one already open
- The note is going in a router because that is where you are
- You have not read the target folder's file headers
- Writing because you were told to, not because a reader would act
Reference
Why the depth rule matters
In one monorepo, moving detail down into nested files took the always-loaded chain from 816 lines to 388. The largest single file went from 1,715 lines to 182 plus seven nested files, with nothing lost — each detail now loads only where it applies.
Correcting something already written
Replace the wrong claim with the current, verified one. Version control keeps the history.
Keep a one-line "used to be X, now Y" note next to the claim only when people or code may still be acting on the old belief — a changed default, a removed endpoint, a renamed flag. Otherwise the next reader cannot tell a stable fact from one that just changed, and will trust a stale cache, script or habit.
What a leaf file carries
- A one-line scope blockquote with an upward pointer
- What it is, in plain terms — port and database if a service
- The domain as a pipeline, not a class inventory
- Known gotchas, each naming the exact broken mechanism
- "Used to be true and is not" corrections, where people may still rely on the old claim
- Build and run commands scoped to that module
A verified "there is no X" line is often the most useful thing in a leaf file — "There is no
/auth/register", "There is no delete". It forecloses a plausible wrong assumption rather than only
stating the true one. Write one only when it is checked and someone would otherwise assume X exists.
Plans after they ship
A document that describes the future becomes wrong the day the thing ships — it now claims the work is outstanding. Delete it, archive it, or rewrite it as present-tense documentation, following the repo's policy. Present-tense operational documents — runbooks, cheatsheets, contracts — matter more after shipping. Never leave a dangling link: a link to nothing teaches the next person less than a sentence saying where the document went.
Worked example
A nightly reminder job is added to scheduling-service, living there rather than in the shared
worker service because its data is in the scheduling schema.
| Where | What goes there |
|---|---|
| Root CLAUDE.md | Nothing. One job in one service changes nothing true of the whole repo |
services/scheduling-service/CLAUDE.md |
Why it lives here, since the next person will otherwise move it; and that NotificationClient is optional, so a local stack sends no emails |
ReminderScheduler.java |
Why 07:00 and not hourly. One file, one comment |