docs(claude-memory): point stateless purge at the official project-purge command - #1947
Conversation
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
|
Claude finished @kyle-sexton's task in 49s —— View job Security review complete
Scope reviewed: Findings: noneThis PR is a pure documentation/prose change. It adds pointers to the official No injection surfaces, auth/access-control changes, secret handling, or dangerous CI patterns |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 43a037723b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
Claude finished @kyle-sexton's task in 2m 35s —— View job Code review complete
Scope reviewed: the 5 files in Per this repo's 🔴 Important — deletion-scope summary understates what
|
|
Claude has reviewed this PR 5 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
43a0377 to
573ff10
Compare
|
Claude finished @kyle-sexton's task in 4m 25s —— View job Code review complete
Scope reviewed: all 10 files changed vs Note on prior review comments: the code-review and Codex bot comments on this PR (21:28–21:33) reviewed an earlier commit ( Fresh-docs verification: per this repo's
🟡 Nit — stale "re-fetch both/two source pages" pointer, now more wrong than beforeThis PR adds a 4th source page (
This was already stale before this PR (3 sources, not 2), but since this PR is the one that touched the Sources line and pushed it to 4, it's a good place to fix both counts (or reword to "the source pages," dropping the number so it can't drift again). Everything else
|
|
Claude finished @kyle-sexton's task in 1m 11s —— View job Security review complete
Scope reviewed: all 10 files changed in this PR ( Findings: noneThis is a documentation-and-test PR with one small shell-script change; no logic, authorization, injection, secrets-handling, or GitHub Actions surface is touched:
No injection surfaces, auth/access-control changes, secret handling, permission-widening, or dangerous CI patterns are introduced by this diff. |
…size gate `strip_unloaded()` treated a line-1 `---` as frontmatter and skipped to a closing `---` that need not exist, so a leading thematic break or frontmatter clipped mid-file discarded the whole file and reported 0 lines / 0 bytes. M1 is a [FAIL]-severity size check and 0 passes it, so the gate could not fire. An unclosed `<!--` swallowed the file the same way. MEMORY.md carries frontmatter by design — Claude Code stamps a `modified` field into any memory file that has it — so this is a live shape, not a corner case. An opening delimiter is now held rather than dropped and flushed at EOF when it never closes, which counts the whole file exactly as a reader following criteria.md would. One mechanism covers both block kinds. Two further strip defects, same function: the fence rules ran before the comment rule, so a fence inside a comment toggled fence state and leaked the commented-out body back into the count; and a line sharing space with a comment's open or close was dropped whole, losing real content. criteria.md M1 now states the four readings the strip applies and marks them as this plugin's reading, not doc-derived. The memory doc states the fenced-code carve-out under "How CLAUDE.md files load" and says nothing either way for MEMORY.md, so the previous "per the documented comment behavior" was an inference presented as a citation. Byte counts are LF-normalized; that assumption is now recorded rather than silent. official-guidance.md's `Last researched` date scopes the 2026-08-04 re-verify to the memory page, the only source this PR re-checked. Version stays 0.5.5 / criteria 1.5.1: 0.5.5 is unmerged and its changelog entry is this PR's own, so amending it is not a version event. #1947 keeps 0.5.6. Tests: 29/29 pass, including regressions for each defect above. ShellCheck exit 0. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 4m 35s —— View job Code review complete
Scope reviewed: the 5 files this PR changes relative to I re-verified the previously-flagged deletion-scope omission (Codex + earlier review passes): confirmed fixed — all four categories from the live Diffing the newest commit ( 🔴 Important — broken sentence in the Transcripts scope-table row
This is missing a word after "project's" — an incomplete sentence, most likely dropped while splitting the old single "Transcripts / history / sessions / snapshots" row into four (visible in the 🟡 Nit — reference file still makes the blanket claim the split was meant to correctThis PR's own
Everything else
|
|
Claude finished @kyle-sexton's task in 1m 32s —— View job Security review complete
Scope reviewed: the 5 files changed by this PR's two commits (
Findings: noneThis is a pure documentation/prose PR — no executable surface changes:
No injection surfaces, auth/access-control changes, secret handling, permission-widening, or dangerous CI patterns are introduced by this diff. |
1169bef to
51806cd
Compare
|
Claude finished @kyle-sexton's task in 2m 2s —— View job Code review complete
Scope reviewed: the 5 files this PR changes relative to This PR was rebased since the last review pass, so old commit SHAs ( 🔴 Important — broken sentence survives the rebase
This is the same incomplete sentence flagged in the previous review pass (missing a word after "project's" — most likely "transcripts too", matching the 🟡 Nit — reference file's blanket claim still contradicts the PR's own table split
This blanket claim is exactly what this PR's own Resolved since last pass
Everything else
|
|
Claude finished @kyle-sexton's task in 48s —— View job Security review complete
Scope reviewed: the 5 files this PR changes relative to its stated base
Findings: noneThis is a pure documentation PR — no executable surface is touched:
This confirms the same conclusion reached by the prior security-review passes on this PR (at commits No injection surfaces, auth/access-control changes, secret handling, permission-widening, or dangerous CI patterns are introduced by this diff. |
|
Claude finished @kyle-sexton's task in 2m 10s —— View job Code review complete
Scope reviewed: the 5 files this PR changes relative to The latest commit ( 🔴 Important — broken sentence still present after 3 review passes and 2 rebases
Still missing a word after "project's" (most likely "transcripts too" — matching the reference file's quote "Transcripts and auto memory under Resolved since last pass
Everything else
|
|
Claude finished @kyle-sexton's task in 1m 11s —— View job Security review complete
Scope reviewed: the 5 files this PR changes relative to its stated base
Findings: noneThis is a pure documentation PR — no executable surface is touched:
This is consistent with every prior security-review pass on this PR (at commits No injection surfaces, auth/access-control changes, secret handling, permission-widening, or dangerous CI patterns are introduced by this diff. |
|
Claude finished @kyle-sexton's task in 3m 10s —— View job Security review complete
Scope reviewed: all 5 files this PR changes relative to its base (confirmed the diff matches the PR's reported stats exactly — 146 additions / 25 deletions):
Findings: noneThis remains a pure documentation PR — no executable surface is touched, and nothing has changed in that respect since the prior security-review passes on this PR:
This is consistent with every prior security-review pass on this PR (at commits No injection surfaces, auth/access-control changes, secret handling, permission-widening, or dangerous CI patterns are introduced by this diff. (Note: the correctness issues flagged in prior code-review passes — e.g. the incomplete sentence at |
…emory doc (#1933) ## Summary Row-127 doc-alignment pass: every shipped `claude-memory` assertion about the auto-memory / project-memory page was verified against the live doc (https://code.claude.com/docs/en/memory, fetched 2026-08-04, 35,136 bytes, sha256 `7440c455…`). Most claims are current; this PR corrects the ones that drifted. - `skills/audit/reference/official-guidance.md` - `@import` recursion depth: 5 hops → 4 hops (live: "maximum depth of four hops"). - `autoMemoryDirectory`: replaced the stale "user or local settings only; not accepted from project settings" claim with the live behavior — read from any settings scope (user, project, local, policy, `--settings`), with project/local values honored only after the workspace trust dialog. - Quote attribution: "Project memory" section no longer exists; now cites "Set up a project CLAUDE.md". - Added the backing quote for the MEMORY.md limit check measuring stripped content. - `skills/audit/reference/criteria.md` (1.5.0 → 1.5.1): M1 now measures the content that loads — YAML frontmatter and block-level HTML comments are stripped before the index loads and don't count toward the 200-line/25KB limits. - `skills/audit/scripts/memory-dir-stats.sh`: `--memory-lines` measures post-strip loaded content instead of raw `wc -l`, and a new `--memory-bytes` mode covers the 25KB limb; covered by `memory-dir-stats.test.sh`. - `skills/audit/SKILL.md`: scope table now states the 25KB limb of the MEMORY.md load limit alongside the 200-line one, and the pre-computed context reports both post-strip figures so M1 never disagrees with its own injected stats. - Version: claude-memory 0.5.4 → 0.5.5, with CHANGELOG entry. Serialization note: this PR was rebased onto current `main` after the row-60 work landed. Row 60 shipped as #1932 at claude-memory 0.5.4 / criteria 1.5.0 (commit `f668526f7`), which is the `main` this branch now sits on, so this PR takes the next free literals — 0.5.5 / criteria 1.5.1. #1947 (row 74, `stateless` skill) is the only other open claude-memory PR and already claims 0.5.6; it is now rebased on top of this branch and does not touch `skills/audit/reference/criteria.md`. ## Post-rebase CI fix (`8664a65647`) The rebased head failed the `hygiene` check. Root cause: the post-strip test fixture wrote its literal markdown code fence inside a single-quoted `printf` format, and ShellCheck reads backticks in single quotes as an unexpanded command substitution (SC2016). The repo's gate invokes ShellCheck with an empty severity setting — ShellCheck's default `style` level — so the info-level finding failed CI rather than being advisory. Fixed by writing the fixture with double quotes and escaped backticks, which produces byte-identical output (verified by md5) and keeps the file's existing `printf` convention rather than introducing a second fixture-writing mechanism. No `# shellcheck disable` was added. Verified locally on the final head: - `shellcheck --rcfile=.shellcheckrc` over both scripts — exit 0, no findings. - `bash memory-dir-stats.test.sh` — **all 23 checks passed**, including the post-strip line and byte assertions. Both earlier review passes noted they could not execute this suite in the CI sandbox and asked for a local run; this is that run. ## Strip correctness fix (`e597abcd95`) — the M1 gate could not fire An independent verifier pass found that the post-strip measurement shipped earlier in this PR had a hole that inverted the check it was meant to sharpen. `strip_unloaded()` treated a line-1 `---` as opening YAML frontmatter and skipped every line until a closing `---`. When no closing `---` exists, the whole file was discarded: ``` "---\ntype: index\n# Title\nreal\n" -> lines=0 bytes=0 "---\n# Title\nreal one\nreal two\n" -> lines=0 bytes=0 ``` M1 is a `[FAIL]`-severity size gate and **0 always passes it**, so any index with frontmatter clipped mid-file — or a leading `---` used as a thematic break — silently disarmed the gate. The memory doc notes Claude Code stamps a `modified` frontmatter field into any memory file that already has frontmatter, so MEMORY.md is frontmatter-bearing by design; this is a live shape. An unclosed `<!--` swallowed the file the same way. Fixed by holding an opening delimiter's lines and flushing them at EOF when it never closes, so an unterminated block is counted as the content it is — matching what a reader following `criteria.md` counts. One mechanism covers both block kinds. Two further defects in the same function, found while fixing the first: - The fence rules ran before the comment rule, so a fence **inside** a comment toggled fence state and leaked the commented-out body back into the count. - A line sharing space with a comment's open or close was dropped whole, losing real content. **Provenance correction.** The fenced-code carve-out was justified in the script header as "per the documented comment behavior". Re-fetching the live page shows that sentence sits under **How CLAUDE.md files load**, while the MEMORY.md limit paragraph under **How it works** says only that frontmatter and block-level HTML comments are stripped — the doc is silent on the carve-out for MEMORY.md. The behavior is kept (a comment inside a fence is code, not block-level markdown), but `criteria.md` M1 now records it, together with the unterminated-block rule, the partial-line rule, and the `--memory-bytes` LF-normalization assumption, under a `**Provenance**:` note marking them as this plugin's reading rather than doc-derived. Also: `official-guidance.md`'s `Last researched` line now scopes the 2026-08-04 re-verify to the memory page, the only source this PR re-checked, instead of implying the whole source list was refreshed. **Version stays 0.5.5 / criteria 1.5.1.** 0.5.5 is unmerged and its CHANGELOG entry is this PR's own, so amending it is not a version event; #1947 keeps 0.5.6 and no re-stack is needed. Verified on `e597abcd95`: ShellCheck exit 0, **29/29 tests pass** (a regression test per defect), markdownlint clean, all 32 CI checks green and `MERGEABLE` / `CLEAN`. No linked issue ## Related - Source of truth: https://code.claude.com/docs/en/memory ("How Claude remembers your project") - Doc-alignment campaign roster row 127 (claude-memory vs the memory page); supporting facts cross-checked against the live settings, env-vars, and claude-directory pages the reference files cite. - Serialization predecessor: #1932 (roster row 60, claude-memory 0.5.4 / criteria 1.5.0), now on `main`. - Stacked successor: #1947 (roster row 74, claude-memory 0.5.6), based on this branch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- linkage revalidated under v0.10.2 --> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
…rge command `claude project purge` wipes a project's transcripts and auto memory under projects/, its per-session tasks/, debug/, and file-history/ entries, its matching history.jsonl lines, and its ~/.claude.json entry; the stateless skill deliberately stops at auto memory, so a user who asks to wipe what Claude saved about a repo needs the broader route named. Pointer, not a copy of its flags: the reference file quotes the doc's deletion list verbatim and the other call sites cite it. Doc-alignment row 74. Version 0.5.6 sits above #1933's 0.5.5; this branch is stacked on #1933 and merges after it. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
… the scope table The prior commit named `claude project purge` at four call sites and restated its deletion scope at each, so the plugin carried four hand-maintained copies of an upstream list. Keep the verbatim quote in reference/official-guidance.md and turn every other mention into a pointer. Split the merged `Transcripts / history / sessions / snapshots` scope row, whose single verdict was true only of transcripts: `history.jsonl` is "not covered by automatic cleanup", `sessions/` "isn't part of the age-based sweep" and is absent from the deletion list, and `shell-snapshots/`/`backups/` are swept but left alone by the command because they are not project-scoped. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
…s merged sweep claim The changelog counted the old merged row's wrong subjects against an intermediate state of this branch rather than against the PR base. At the base the row asserted only `cleanupPeriodDays`, which is true of transcripts and shell snapshots and false for `history.jsonl` and `sessions/` — two wrong, not three. The purge half it also described was added by this branch's own first commit, so it was never part of the before-state. reference/official-guidance.md still stated the sweep for all four entities as one fact, which is the same defect the entry claims to fix — and SKILL.md now designates that file as the single source for purge scope, so the pointer chain led from a corrected table to an uncorrected reference. Split it and add the two backing quotes. Also: `CLAUDE.local.md` has no user-scope equivalent, so it no longer shares a `repo + user` location cell with CLAUDE.md and `.claude/rules/`; and the `CLAUDE_CODE_SKIP_PROMPT_HISTORY` note no longer refers to a "future skill" that this branch's edit had removed. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The stateless skill designates reference/official-guidance.md as the single source for `claude project purge`'s scope, but only the positive deletion list was quoted there, leaving the negative half the skill ships unsourced. The claude-directory doc states both halves, so the leaves-alone sentence and the confirmation-prompt sentence are now quoted and attributed beside the deletion list, making SKILL.md's "does and does not delete" claim true and purge.md's operator instruction answerable. Also replaces three quotes attributed to the settings doc whose wording was not on that page — the substance was right in all three cases, the quotation fidelity was not. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
f957eec to
d068889
Compare
|
Claude finished @kyle-sexton's task in 53s —— View job Security review complete
Scope reviewed: all 5 files this PR changes vs
Findings: noneThis remains a pure documentation PR — no executable surface is touched, and nothing has changed in that respect since the prior security-review passes on this PR:
This is consistent with every prior security-review pass on this PR (at commits No injection surfaces, auth/access-control changes, secret handling, permission-widening, or dangerous CI patterns are introduced by this diff. (Note: correctness/prose issues from prior code-review passes are outside this security lane's scope and are not re-reported here.) |
…lock would swallow (#1962) Follow-up to #1933 (work-items row 127, campaign ledger #1941). #1933 shipped the M1 index-size measurement fixes for `memory-dir-stats.sh`; this closes the last under-count residual that surfaced during its gate review, after the PR had already merged. No linked issue — the residual was found by #1933's own gate review rather than filed as an issue, and the campaign ledger it belongs to stays open past this PR. ## The bug `memory-dir-stats.sh` admitted `#` lines to its frontmatter grammar. A `MEMORY.md` that opens with a `---` thematic break, carries heading lines, and reaches any later `---` therefore had the whole span stripped as frontmatter: ``` --- # heading one # heading two --- body ``` Raw 5 lines / 41 bytes, reported **1 line / 5 bytes**. M1 is a `[FAIL]`-severity size gate, and a low count always passes it, so the shape disarmed the gate outright rather than merely mismeasuring it. This is the same failure species #1933 exists to eliminate — silent under-count on the gate — reached through the frontmatter grammar instead of the comment strip. A `#` line is a comment to YAML but a **heading** to markdown, and headings are loaded content. The grammar now accepts only blank lines and `key:` mapping entries. ## Evidence Measured against `origin/main`'s script and this branch's, same fixtures: | fixture | 0.5.6 | 0.5.7 | |---|---|---| | 5-line heading pseudo-block | 1 line / 5 bytes | 5 / 41 (raw) | | 20 headings + later `---` (23 lines) | 1 line / 5 bytes | 23 / 123 (raw) | | genuine `key:`-only frontmatter | 1 / 5 | 1 / 5 (still strips) | | genuine frontmatter with a `# note` | 1 / 5 | 6 / 44 (raw) | The bound is capped at `fmcap` (20) lines, so the worst case was ~22 content lines — 11% of the 200-line budget — never a full disarm of the line limb, but enough to make a five-line index report one. ## The cost, stated plainly A real YAML comment inside frontmatter now ends the block, and ending it strips **nothing at all**: the opening `---`, every entry held so far, and the rest of the block through its close all count. That is an over-count, the direction M1's readings already guess toward — it can make the gate fire early, never fail to fire. It takes a hand-edited index to reach, since Claude Code only stamps a `modified` scalar into frontmatter a file already has. Comments join an existing class rather than opening a new one: frontmatter this grammar cannot parse already ended the block before this change, and a block sequence under `tags:` still does. `criteria.md` M1 reading 1 records both halves. ## Verification - Full suite **60/60, exit 0** — run in this worktree off current `main`. - Fresh-context verifier, rationale withheld, **PASS on all six criteria** (suite; heading fixture reports raw; `key:`-only frontmatter still strips; comment/fence behavior unregressed; no `#` alternation left in the executed awk; version + changelog hygiene). It derived every expectation from the awk before looking at output, and added its own mutation check — running `origin/main`'s pre-fix script side by side to confirm the fix is load-bearing and the numbers above reproduce. ## Versions `claude-memory` 0.5.6 → **0.5.7** (0.5.5 → 0.5.6 landed via #1947); `criteria.md` 1.5.1 → **1.5.2**; CHANGELOG entry under `[0.5.7]`. ## Related - #1933 — predecessor, merged. Shipped the M1 measurement fixes (frontmatter bounding, greedy-comment fix, comment re-scan) this builds on; the residual fixed here was found during its gate review. Not closed by this PR. - #1941 — campaign ledger tracking work-items row 127 and its siblings. Stays open past this PR. - #1947 — carried `claude-memory` 0.5.5 → 0.5.6, the version this PR bumps from. Reference only. --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1 participant
Summary
Roster row 74. The
statelessskill governs auto memory only, and said so without naming the official route for the broader ask ("wipe everything Claude saved about this repo"). Claude Code now ships that route:claude project purge(v2.1.124+). This PR names it wherever the skill states its own scope boundary — the SKILL.md scope statement and table,context/purge.md's pre-gate presentation and follow-through, andreference/official-guidance.md's out-of-scope section — and retires the reference file's now-false "there is no built-in purge command" claim.Pointer, not a copy: the deletion plan and flags stay in https://code.claude.com/docs/en/claude-directory.
No executable step changes. The bash fences driving Steps 2–4 (manifest capture, backup, delete) and the confirmation gate are byte-identical to the base branch; the additions are narrative bullets outside any executable block, and nothing causes the skill to invoke
claude project purgeitself.Review finding fixed — full deletion scope
Codex flagged (P2,
official-guidance.md:127) that the summarized deletion scope omitted a category. Re-fetching the live page on 2026-08-04 confirmed it: the command deletes four categories, and the PR's original prose listed three, dropping per-sessiontasks/,debug/, andfile-history/entries — checkpoint/restore and debug history. That matters because this text is read to a user deciding whether to run a destructive wipe; the omission would have led them to believe checkpoint history survives.Sweeping the diff found the same omission in five places, not the one flagged. All are corrected:
reference/official-guidance.mdout-of-scope sectionSKILL.mdscope statementcontext/purge.mdStep 2 (pre-gate text)context/purge.mdStep 5CHANGELOG.md0.5.6 entryTwo authoritative enumerations now remain (the reference file's verbatim quote and Step 2's pre-gate text), down from five independently-maintained paraphrases.
Stacking and version
Rebased onto
mainafter #1933 merged, so the diff contains only this PR's five files.0.5.6sits directly above #1933's0.5.5in bothplugin.jsonand the CHANGELOG, with no gap.Fresh-context verification completed 2026-08-05 after the rebase: the five-file diff was reviewed against the live official
claude-directorypage;claude project purgeversion, deletion scope, exclusions, confirmation behavior, session cleanup, and history persistence all match.markdownlint(14 files), JSON parsing, changelog/version parity, andgit diff --checkpass locally; the repository-wide skill gate exceeded the local 60-second observation window, so protected CI remains authoritative for that lane.No linked issue
Related
claude project purge, v2.1.124+)🤖 Generated with Claude Code