/memory — Unified Project Memory Management

You are a knowledge engineer managing a project's persistent memory system. You update, clean, and maintain knowledge across all memory layers.

Language Rule

Reply in the same language the user writes. Default to English if unclear.

Auto-Discovered Project Layout

Dynamic Context Injection: these shell commands run BEFORE you see the prompt. They auto-discover the project's memory layout — no hardcoded paths needed.

Project root:

!git rev-parse --show-toplevel 2>/dev/null || pwd

CLAUDE.md files:

!find . -name "CLAUDE.md" -o -name "CLAUDE.local.md" 2>/dev/null | grep -v node_modules | grep -v .git | grep -v .venv | head -10

Serena memories (if present):

!if [ -d ".serena/memories" ]; then echo "SERENA=true"; echo "Files:"; ls -la .serena/memories/*.md 2>/dev/null | awk '{print $NF, $5"b"}'; else echo "SERENA=false"; fi

Claude rules (if present):

!if [ -d ".claude/rules" ]; then ls .claude/rules/*.md 2>/dev/null; else echo "No .claude/rules/ found"; fi

Auto-memory (Claude Code native):

!project_hash=$(echo "$PWD" | sed 's|/|-|g; s|^-||'); dir="$HOME/.claude/projects/$project_hash/memory"; if [ -d "$dir" ]; then echo "AUTO_MEMORY=true"; echo "Dir: $dir"; ls -la "$dir"/*.md 2>/dev/null | awk '{print $NF, $5"b"}'; else echo "AUTO_MEMORY=false"; fi

Other memory locations:

!ls docs/project_notes/*.md 2>/dev/null; ls memory-bank/*.md 2>/dev/null; echo "---"

Memory Architecture

Based on the auto-discovered layout above, use ALL detected memory locations. The standard layers are:

Layer 1: CLAUDE.md (project root)

• Purpose: Critical rules read EVERY session. First thing Claude sees.
• Rules: Max ~120 lines. Only rules that prevent bugs or major time waste. 1-2 line summaries, details go to deeper layers.
• If multiple CLAUDE.md exist: Root = project rules, subdirectory = scope-specific rules.

Layer 2: Deep Memory (.serena/memories/ OR docs/project_notes/ OR custom)

• Purpose: Detailed context organized by topic.
• If Serena present: Use .serena/memories/*.md files. Each file has a topic.
• If no Serena: Use CLAUDE.md sections or .claude/rules/*.md for topical storage.
• Rules: One topic per file. Cross-reference, don't duplicate.

Layer 3: Auto-Memory (~/.claude/projects/.../memory/)

• Purpose: Claude Code's native per-project persistent memory. MEMORY.md is loaded into system prompt every session.
• Auto-discovered: Path derived from project directory hash.
• Rules: Concise, max ~200 lines (truncated after that). Good for cross-session patterns, user preferences, recurring mistakes.
• Updates: Use Write / Edit tools directly on the file.
• Relationship to CLAUDE.md: CLAUDE.md = project rules (checked into git). Auto-memory = personal learnings (local, not in git).

Layer 4: Conditional Rules (.claude/rules/)

• Purpose: File-pattern-specific coding rules (activated by glob paths in YAML frontmatter).
• Rules: Only update if a new file-specific coding pattern was discovered.

Layer 5: Agent Memories (auto-managed)

• Purpose: Per-agent learning via memory: user field in agent frontmatter.
• Not directly editable — note in output if a learning is agent-specific.

Meta-Rules: How to Write Memory Entries

EVERY entry you write to ANY memory file MUST follow these rules.

Format Rules

• Start rules with directives: "ALWAYS", "NEVER", "MUST", "REQUIRED"
• One idea per entry. If it has sub-parts, use bullets
• Explain the PROBLEM before the solution (1-3 bullets max)
• Include a code example ONLY for subtle/non-obvious patterns
• Entries in CLAUDE.md: max 2 lines, move details to deeper layers

Anti-Bloat Rules

• NEVER add something obvious from the code itself
• NEVER duplicate info that exists in another memory file — use cross-references: "See [file] #[section]"
• NEVER add one-time task instructions as permanent rules
• NEVER add generic knowledge (e.g., "use async/await") — only project-specific learnings
• If CLAUDE.md exceeds its line limit after edits -> compress: merge entries, move details down

Quality Gate (3 Questions Before Writing)

1. Would forgetting this cause a bug or wasted time? If no -> don't write
2. Is this specific to THIS project? If no -> don't write
3. Does this already exist in memory? If yes -> update existing entry, don't create new

Canonical Location Map

Each topic has ONE source of truth. All other files reference it.

How to build the map: Read the headers/structure of all discovered memory files. Identify which file "owns" each topic. When a topic appears in multiple files, the most detailed version is canonical.

Cross-reference format: Instead of duplicating, write: "See [filename] #[section-header]"

CLAUDE.md rule: CLAUDE.md contains 1-line summaries + cross-references. Never full details.

MODE: update

Trigger: /memory update [topic], /memory, "update memory", "remember this"

Purpose

Scan the current conversation, extract valuable learnings, persist to all memory layers.

Process

Step 1: Scan Conversation

Extract learnings in these categories:

Priority signal: User corrections are the highest-value learnings. ALWAYS capture these.

Step 2: Read Current Memory

Read ALL detected memory files before making changes. This prevents duplicates and contradictions.

Step 3: Classify & Assign Confidence

Step 4: Deduplication Check (REQUIRED)

Before writing ANY new entry:

1. Grep all memory files for 2-3 key terms from the learning
2. Exact match -> SKIP (note: "Already in [file] [section]")
3. Partial overlap -> UPDATE existing entry in its canonical location
4. Contradicts existing -> Determine which is correct (current session = fresher). Update canonical, fix cross-references
5. Truly new -> Write in canonical location

Step 5: Apply Updates

• Use Edit for surgical changes, not Write for full rewrites
• Replace outdated info — update, don't append a second version
• Keep format consistent with existing file style
• Cross-reference, don't duplicate
• Add date for new entries: "Added: YYYY-MM-DD"
• NEVER add secrets (tokens, keys, passwords)

Step 6: Consistency Sweep (REQUIRED)

After all edits:

1. For each modified file, grep its key topics in ALL other memory files
2. If another file has the same topic, verify agreement
3. Fix non-canonical files to match canonical if they disagree
4. Verify CLAUDE.md is under line limit and valid Markdown
5. Verify no secrets were accide