claude-code-memory

Overview

Use this skill when the task involves memory design or memory hygiene for Claude Code or a similar coding agent.

This skill organizes memory into three layers:

1. Instruction memory
2. Session memory
3. Durable memory

The intent is to keep each layer narrow, useful, and easy to trust.

Before you start

• Identify the host tool's instruction file. For Claude Code this is usually CLAUDE.md or CLAUDE.local.md. Other common examples are AGENTS.md and .github/copilot-instructions.md.
• Identify or create a repo-local durable memory directory. The default layout in this skill uses .agent-memory/.
• Identify or create the session summary file at .agent-memory/session/summary.md.

Layer 1: Instruction memory

Treat the host instruction file as the rule layer. In Claude Code, this is the CLAUDE.md layer.

Put information here only if it is:

• stable
• normative
• broadly applicable across future work
• costly for the agent to rediscover incorrectly

Good candidates:

• test commands
• review expectations
• approval boundaries
• release process rules
• communication style preferences that consistently apply

Do not place transient task state here.

Layer 2: Session memory

Maintain .agent-memory/session/summary.md as the short-lived working notebook for the current thread.

It should answer:

• What is actively being worked on now
• What did the user ask for
• Which files and functions matter
• Which commands have already been run
• Which errors happened and how they were resolved
• What remains next

This layer should be updated during long tasks and before compaction or handoff.

Use this structure:

# Session Title

# Current State

# Task Specification

# Files and Functions

# Workflow

# Errors and Corrections

# Key Results

# Worklog

Keep it concise but concrete. Prefer file paths, exact commands, and specific failure modes over generic summaries.

Layer 3: Durable memory

Use .agent-memory/ for long-lived memories that should survive across conversations.

Store durable memories in topic files and keep .agent-memory/MEMORY.md as an index.

Use the following durable memory types:

user-profile

Information about the user's role, goals, background, and level of familiarity.

Examples:

• backend-heavy engineer who wants frontend explanations grounded in systems concepts
• founder who prefers quick trade-off summaries

working-style

Guidance about how to collaborate with this user or team.

Examples:

• run tests before proposing a commit
• avoid long recap paragraphs
• prefer one bundled refactor PR in this codebase

project-context

Important project facts that are not derivable from the repo.

Examples:

• freeze window dates
• stakeholder constraints
• migration rationale
• incident aftermath that still shapes decisions

external-reference

Pointers to systems outside the repo.

Examples:

• which dashboard matters for this codepath
• which Linear board tracks this class of bugs
• which Slack channel owns deployment coordination

Durable memory format

Each durable memory should live in its own file with frontmatter:

---
name: testing-policy
description: Integration tests in this repo must hit a real database
type: working-style
---

Integration tests in this repo must hit a real database.

Why:
A previous production migration failure was missed by mock-based coverage.

How to apply:
When changing data access or migrations, prefer real-db integration coverage over mocks.

The index file should stay short:

- [Testing Policy](testing-policy.md) - Real database integration tests are expected here

What not to save as durable memory

Do not save these unless there is a strong reason and the non-obvious part is the actual point:

• file structure
• code architecture visible in the repo
• git history
• recent diff summaries
• temporary task state
• obvious commands already documented in project instructions

If it can be recovered cheaply from the current repo, prefer not to save it as durable memory.

Recall discipline

Never trust durable memory blindly.

Before acting on it:

• verify named files still exist
• grep for named functions or flags
• prefer current repo state over historical memory if they conflict
• update or remove stale memories when you discover drift

Promotion workflow

When reviewing memory, classify each item:

• Promote to instruction memory
• Keep in durable memory
• Keep only in session memory
• Delete as stale, duplicate, or overfit

Promote into the instruction layer when the item has become a rule. Keep it in durable memory when it remains useful context but is not a rule. Keep it only in session memory when it is tied to the present thread.

Review workflow

When the user asks to review memory:

1. Read the host instruction file such as CLAUDE.md
2. Read .agent-memory/MEMORY.md
3. Read the most relevant durable topic files
4. Read .agent-memory/session/summary.md if current-thread context matters
5. Produce a report with:
   • promotions
   • cleanup
   • conflicts
   • ambiguous items

Do not modify durable memory or instruction files without user approval unless the user explicitly asked you to apply the cleanup.

File layout used by this skill

.agent-memory/
├── MEMORY.md
├── user/
├── style/
├── project/
├── references/
└── session/
    └── summary.md

References

• Architecture notes: references/architecture.md
• Host tool mapping: references/host-tool-mapping.md
• Example durable memory files: examples/persistent-memory/MEMORY.md
• Example session summary: examples/session-memory/summary.md