From 8b9eb12065ef567213bd3b78f2a4617610a83aa0 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 19 Apr 2026 14:48:04 -0500 Subject: rename: memorize → codify MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "memorize" implied passive storage (same mental model as auto-memory). "codify" captures the actual operation: editorial selection, specific phrasing, deliberate commit to a lasting artifact. Changes: - memorize/ → codify/ - SKILL.md: name: codify; title updated; all references changed - Default CLAUDE.md section: ## Memorized Insights → ## Codified Insights - Makefile SKILLS updated - Old ~/.claude/skills/memorize symlink removed; codify symlink created --- memorize/SKILL.md | 192 ------------------------------------------------------ 1 file changed, 192 deletions(-) delete mode 100644 memorize/SKILL.md (limited to 'memorize/SKILL.md') diff --git a/memorize/SKILL.md b/memorize/SKILL.md deleted file mode 100644 index f77540f..0000000 --- a/memorize/SKILL.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -name: memorize -description: Curate concrete, actionable insights into the project's `CLAUDE.md` so they survive across sessions and compound over time. Harvests recent-session learnings (patterns that worked, anti-patterns that bit, API gotchas, verification checks), filters against quality gates (atomic, evidence-backed, non-redundant, verifiable, safe), and writes into a dedicated `## Memorized Insights` section rather than scattering entries. Use after a productive session, a bug fix that revealed a non-obvious pattern, or an explicit review where you want learnings preserved. Supports `--dry-run` to preview, `--max=N` to cap output, `--target=` to write elsewhere, `--section=` to override the destination section. Flags insights that look cross-project and suggests promotion to `~/code/rulesets/claude-rules/` instead. Do NOT use for session wrap-up / progress summaries (not insights), for private personal context (auto-memory handles that, not a tracked file), or for rules that belong in a formal rules file (those go under `.claude/rules/`). Synthesis of Agentic Context Engineering (ACE, arXiv:2510.04618) — grow-and-refine without context collapse. ---- - -# Memorize - -Turn transient session insights into durable, actionable entries in the project's `CLAUDE.md`. The goal: each run of this skill should make the next session measurably better, without diluting what's already there. - -## When to Use - -- End of a productive session where you want concrete patterns preserved -- After a bug fix that revealed a non-obvious constraint or gotcha -- After a review where a pattern was identified as worth repeating (or avoiding) -- When you notice yourself re-deriving the same insight — it belongs written down - -## When NOT to Use - -- For a session wrap-up summary (that's narrative, not an insight) -- For personal/private context (auto-memory at `~/.claude/projects//memory/` captures that — see below) -- For formal project rules — those belong in `.claude/rules/*.md` -- When you have no specific, evidence-backed insight yet — skip rather than fabricate - -## Relationship to Other Memory Systems - -Three distinct systems, zero overlap: - -| System | Location | Scope | Purpose | -|---|---|---|---| -| **auto-memory** | `~/.claude/projects//memory/` | Private, per-working-directory | Session-bridging context about the user and project (feedback, user traits, project state). Written continuously by the agent. | -| **`/memorize` (this skill)** | Project `CLAUDE.md` | Public, tracked, per-project | Explicit, curated rules and patterns. Written deliberately by the user invocation. | -| **Formal rules** | `.claude/rules/*.md`, `~/code/rulesets/claude-rules/` | Public, tracked, per-project or global | Stable policy (style, conventions, verification). Authored once, rarely updated. | - -Use the right system for the right content. - -## Workflow - -Four phases. Each can be skipped if it has no content; none should be silently merged. - -### Phase 1 — Harvest - -Identify candidate insights from recent work. Look at: - -- The session transcript (or files referenced by `--source`) -- Recent commits and their messages -- Any `.architecture/evaluation-*.md` from `arch-evaluate` -- Reflection or critique outputs if they exist -- Anti-patterns you caught yourself falling into - -**Extract only:** - -- **Patterns that worked** — preferably with a minimum precondition and a worked example or reference -- **Anti-patterns that bit** — with the observable symptom and the reason -- **API / tool gotchas** — auth quirks, rate limits, idempotency, error codes -- **Verification items** — concrete checks that would catch regressions next time -- **Specific thresholds** — "pagination above 50 items" not "pagination when needed" - -**Exclude:** - -- Progress narrative ("today we shipped X") -- Personal preferences ("I like functional style") -- Vague aphorisms ("write good code") -- Unverified claims (if you can't cite code, docs, or repeated observation, skip) - -### Phase 2 — Filter (Grow-and-Refine) - -For each candidate insight, apply these gates. Fail any → drop the entry. - -- **Actionable.** A reader could apply this immediately. "Write good code" fails; "For dataset lookups under ~100 items, Object outperforms Map in V8" passes. -- **Specific.** Names a threshold, a file, a flow, a version, or a named tool. Generic insights are noise. -- **Evidence-backed.** Derived from code you just read, docs you just verified, or a pattern observed more than once. Speculation doesn't count. -- **Atomic.** One idea per bullet. If the insight has two distinct parts, it's two bullets. -- **Non-redundant.** Check existing `CLAUDE.md` content. If something similar exists, prefer merging or skipping over duplicating. If the new one is genuinely more specific and evidence-backed than the existing one, append it and mark the older one with `(candidate for consolidation)` — don't auto-delete prior user content. -- **Safe.** No secrets, tokens, private URLs, or PII. Nothing that would leak in a public commit. -- **Stable.** Prefer patterns that'll remain valid. If version-specific, say so. - -### Phase 3 — Write - -Write approved insights to a dedicated section of `CLAUDE.md`. Default section name: **`## Memorized Insights`**. Override with `--section=`. - -**Discipline:** - -- **One section only.** Don't scatter entries across CLAUDE.md. All memorized content in one place means future `/memorize` runs and human readers find it fast. -- **Create the section if absent.** Place it near the end of CLAUDE.md, before any footer links. -- **Preserve chronology within the section.** Newer entries appended; don't shuffle. -- **Include provenance.** Each entry gets a date and, where useful, a one-word source hint (`pattern:`, `gotcha:`, `threshold:`, `anti-pattern:`, `verify:`). - -**Entry format:** - -```markdown -- **.** (`` — YYYY-MM-DD) -``` - -Examples: - -```markdown -- **Pagination threshold.** Fetch endpoints returning >50 items must paginate; clients assume everything ≤50 is complete. (`threshold` — 2026-04-19) -- **Map vs Object for small lookups.** In V8, Object outperforms Map for <~100 keys; Map wins at 10k+. Use Object for hot config lookups. (`pattern` — 2026-04-19) -- **Never log `load-file-name` from batch-compile context.** Both `load-file-name` and `buffer-file-name` are nil during top-level evaluation; `file-name-directory nil` raises `stringp, nil`. (`gotcha` — 2026-04-19) -``` - -### Phase 4 — Validate - -After writing, check: - -- [ ] Every entry passed all Phase 2 gates -- [ ] Each entry is atomic (one idea) -- [ ] No near-duplicates were created -- [ ] The `## Memorized Insights` section is coherent — entries flow, categories aren't interleaved randomly - -If the validation surfaces a problem, fix before exiting. - -## Cross-Project Promotion - -Some insights apply to *all* the user's projects, not just this one. Examples: - -- "Always emit JSON with a stable key order for git diffs" -- "For TypeScript libraries, expose types via `package.json#exports`" - -When an insight reads as general rather than project-specific, the skill emits a **promotion hint** at the end of the run: - -``` -Promotion candidates: -- "JSON stable key order" — reads as general. Consider adding to: - ~/code/rulesets/claude-rules/style.md - (would apply to every project via global install) - -Keep as project-specific, promote, or drop? [k/p/d] -``` - -Promotion happens manually — the skill doesn't edit the rulesets repo automatically. The hint is a nudge to think about scope. - -## Arguments - -- **`--dry-run`** — show the proposed entries and where they'd be written; do not modify any files. -- **`--max=N`** — cap output to the top N insights by specificity + evidence. -- **`--target=`** — write to a different file. Defaults to `./CLAUDE.md`. Use e.g. `docs/learnings.md` if the project prefers a separate file. -- **`--section=`** — override the default `## Memorized Insights` section name. -- **`--source=`** — scope what gets harvested. Values: `last` (most recent message), `selection` (a user-highlighted region if supported), `chat:` (a specific past conversation), `commits:` (e.g., `commits:HEAD~10..`). Defaults to a reasonable window of recent session context. - -## Output - -On a real run (not `--dry-run`): - -1. Short summary — "added N entries to ``: X patterns, Y gotchas, Z thresholds." -2. Any promotion candidates flagged for global-rules consideration. -3. Confirmation of the file path modified. - -On `--dry-run`: - -1. Preview of each proposed entry with the section it would land in. -2. Flagged promotions. -3. Explicit confirmation nothing was written. - -## Anti-Patterns - -- **Summarizing the session instead of extracting insights.** "Today we refactored X" is narrative. "X's public API requires parameters in Y order due to Z" is an insight. -- **Writing entries without evidence.** If you can't point to code, docs, or multiple observations, the entry is speculation. -- **Overwriting prior content.** Mark conflicts for consolidation; don't auto-delete what the user wrote. -- **Scattering entries.** One section. Grep-able. Coherent. -- **Batch-writing 20 entries in one session.** If the session generated 20 real insights, many of them aren't. Filter harder. 3-5 genuine entries per run is typical. -- **Adding to `CLAUDE.md` when auto-memory is the right system.** Private user-context goes in auto-memory; public project rules go here; static policy goes in `.claude/rules/`. -- **Promoting too eagerly.** "This applies to all projects" is a strong claim. If you can't name three unrelated projects where the rule would fire, it's project-specific. - -## Review Checklist - -Before accepting the additions: - -- [ ] Each entry has a source hint and a date -- [ ] Each entry passes the atomic / specific / evidence-backed / non-redundant / safe / stable gates -- [ ] The `## Memorized Insights` section exists exactly once in the target -- [ ] Promotion candidates (if any) have been flagged, not silently promoted -- [ ] `--dry-run` was used at least once if the target file is under active template management (e.g. bundled CLAUDE.md from rulesets install) - -## Maintenance - -`CLAUDE.md` accumulates over time. Periodically: - -- **Consolidate.** Entries marked `(candidate for consolidation)` deserve a look. Often the older entry is superseded; sometimes it's a special case of the newer one. -- **Retire.** Entries about deprecated tools or obsolete versions should be removed explicitly (with a commit message noting the retirement). -- **Promote.** Re-scan for entries that have started firing across multiple projects — those belong in `~/code/rulesets/claude-rules/`. -- **Trim.** If the section grows past ~40 entries, either the project is complex enough to warrant splitting `CLAUDE.md` into multiple files, or the entries haven't been curated aggressively enough. - -## Theoretical Background - -The grow-and-refine / evidence-backed approach draws on Agentic Context Engineering (Zhang et al., *Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models*, arXiv:2510.04618). Key ideas borrowed: - -- **Generation → Reflection → Curation** as distinct phases, not a single compression step -- **Grow-and-refine** — accumulate granular knowledge rather than over-compressing to vague summaries -- **Avoiding context collapse** — resist the temptation to rewrite old entries into smoother prose; specificity is the value - -This skill implements the Curation phase. Reflection and Generation happen in the main conversation. -- cgit v1.2.3