Claude‑Mem Coding Skill

What This Skill Does

This skill teaches Claude how to:

• Mine claude-mem (via MCP) for high‑signal past work.

• Maintain a concise, high‑impact CLAUDE.md (~1,500 tokens).

• Maintain a curated MEMORY.md of lessons learned and directions, so future work is faster and less error‑prone.

It is an entry point, not a full manual. Detailed workflows and examples live in separate reference files that Claude can open on demand.

When to Use This Skill

Claude should activate this skill when:

• A feature, refactor, or significant bugfix is completed.

• An infra/deployment change introduces new operational lessons.

• Starting work on an area with substantial history in claude-mem.

• Performing a daily “memory maintenance” pass on an active repo.

Inputs and Outputs

Inputs

Claude relies on:

• Files (in repo root):

• CLAUDE.md – main project instructions.

• MEMORY.md – curated lessons and directions.

• claude-mem MCP tools (already installed & connected):

• search – index‑level observation search.

• timeline – temporal context around observations.

• get_observations – full structured details.

Outputs

This skill produces:

• Patch‑style edits to:

• MEMORY.md – new or updated lessons, patterns, and playbooks.

• CLAUDE.md – refreshed rules while staying under ~1,500 tokens.

• No raw claude-mem transcripts are copied; only compressed, actionable guidance.

How Claude Should Behave

1. Mine claude-mem → Update MEMORY.md

High‑level behavior (details in claude-mem-usage.md ):

• Use progressive disclosure against claude-mem:

• search for recent decision , bugfix , refactor , discovery , change observations.

• timeline around promising IDs to see context.

• get_observations for a small set of high‑value IDs.

• From those, update MEMORY.md with:

• Architectural decisions and their impact.

• Implementation patterns and anti‑patterns.

• Debugging playbooks and DevOps lessons.

Constraints

• Prefer short bullets over long prose.

• Record why decisions were made and how to act next time.

• Never store secrets or credentials in MEMORY.md .

For a full template and examples, Claude should open:

• memory-structure-reference.md

• claude-mem-usage.md

2. Distill MEMORY.md → Refresh CLAUDE.md (≈1,500 tokens)

High‑level behavior:

Read the existing CLAUDE.md and approximate its size; keep the body around 1–1.5k tokens for optimal behavior.

Pull only current, high‑impact content from MEMORY.md :

• Still‑valid architectural directions.

• Frequently reused patterns and gotchas.

• Operational guardrails that materially affect daily work.

Rewrite historical notes as timeless rules, e.g.:

• “When adding retries to DB writes, always use the shared retry helper instead of manual loops.”

Use links instead of inlining:

• .clauderules/code-style.md for style.

• .clauderules/testing.md for testing.

• MEMORY.md sections for deeper background.

Token Discipline

• If CLAUDE.md is too long:

• Merge overlapping bullets.

• Drop generic advice that doesn’t change behavior.

• Replace detailed explanations with references to supporting docs.

Diff‑First

• Propose minimal patches, not full rewrites:

• Update only sections that need change (e.g., “Architectural Directions”, “Patterns & Gotchas”).

• Preserve stable layout and headings.

• Always leave final acceptance to human review in Git/CI.

For concrete layouts and example diffs, Claude should open:

• claude-md-layout-reference.md

• example-diffs.md

Safety and Priority Rules

Claude must:

Always:

• Query claude-mem before re‑solving problems already encountered in this project.

• Update MEMORY.md after meaningful work with concise, actionable lessons.

• Keep CLAUDE.md focused on rules that change how work is done, not on general LLM tips.

Never:

• Overwrite CLAUDE.md or MEMORY.md entirely; always propose small diffs.

• Paste raw claude-mem observations verbatim into either file.

• Store secrets, API keys, or sensitive infra details in these files.

Conflict resolution priority:

• Explicit instructions in CLAUDE.md .

• Latest curated guidance in MEMORY.md .

• Raw claude-mem observations and session summaries.

• Ad‑hoc reasoning in the current session.

Quick “How to Call Me”

Users can invoke this skill with prompts like:

“Use the claude-mem coding skill to:

• mine claude-mem for recent work,

• update MEMORY.md with lessons, and

• refresh CLAUDE.md under the ~1,500‑token budget.”

Claude should then:

• Run the claude-mem search → timeline → get_observations flow.

• Draft a patch for MEMORY.md with new lessons.

• Draft a patch for CLAUDE.md derived from MEMORY.md .

• Present both patches clearly for human review and commit.

External References

To keep this SKILL.md lean and within best‑practice size, Claude should open these files when more detail is needed:

• claude-mem-usage.md – detailed claude-mem MCP workflows, filters, and example queries.

• memory-structure-reference.md – full MEMORY.md templates and longer examples.

• claude-md-layout-reference.md – canonical CLAUDE.md section layouts and size guidance.

• example-diffs.md – sample before/after patches for CLAUDE.md and MEMORY.md.