Mortdecai
ea3cf45953
The original repo presented everything as equal rules. In reality, the workflow has two tiers: core practices (used in every project) and advanced rules (only in complex projects like Mortdecai). Core tier adds: - backup-before-edit (global CLAUDE.md rule) - superpowers-workflow (the actual workflow engine) - memory-system (persistent feedback and project memories) - document-hierarchy (CLAUDE.md/SESSION.md/CONTEXT.md/IDEA.md) - commit-and-push discipline - feedback-driven behaviors Updated README, docs, and dynamic-methodology to reflect the two-tier reality instead of presenting advanced rules as universal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
122 lines
4.2 KiB
Markdown
122 lines
4.2 KiB
Markdown
# Memory System
|
|
|
|
AI assistants forget everything between sessions. The memory system provides persistent, file-based memory that carries context forward.
|
|
|
|
## How It Works
|
|
|
|
Claude Code maintains a memory directory at `~/.claude/projects/<project-path>/memory/`. Each memory is a markdown file with frontmatter metadata, indexed by a `MEMORY.md` file.
|
|
|
|
## Memory Types
|
|
|
|
### User Memories
|
|
Information about who you are — role, expertise, preferences. Helps the AI tailor its approach.
|
|
|
|
```markdown
|
|
---
|
|
name: user_role
|
|
description: User is a senior infrastructure engineer with deep Linux/networking expertise
|
|
type: user
|
|
---
|
|
|
|
Senior infrastructure engineer. Deep expertise in Linux, ZFS, Proxmox, networking.
|
|
New to React frontend work — frame frontend explanations in terms of backend analogues.
|
|
```
|
|
|
|
### Feedback Memories
|
|
Corrections and confirmed approaches — what to do and what NOT to do. **The most important type.** These prevent the AI from making the same mistake twice.
|
|
|
|
```markdown
|
|
---
|
|
name: feedback_subagent_safety
|
|
description: Never use subagents for destructive server operations
|
|
type: feedback
|
|
---
|
|
|
|
Never use subagents for destructive server operations (git history changes,
|
|
bare repo operations, database modifications). Do these manually, one at a time.
|
|
|
|
**Why:** A subagent running destructive ops in parallel caused data loss.
|
|
The main conversation can't intervene if a subagent goes wrong.
|
|
|
|
**How to apply:** Before dispatching any agent, check if the task involves
|
|
destructive operations. If yes, do it in the main conversation sequentially.
|
|
```
|
|
|
|
### Project Memories
|
|
Ongoing work, decisions, and context that isn't derivable from code or git history.
|
|
|
|
```markdown
|
|
---
|
|
name: project_auth_rewrite
|
|
description: Auth middleware rewrite driven by legal compliance, not tech debt
|
|
type: project
|
|
---
|
|
|
|
Auth middleware rewrite is driven by legal/compliance requirements around
|
|
session token storage, not tech-debt cleanup.
|
|
|
|
**Why:** Legal flagged the current implementation for non-compliant token storage.
|
|
**How to apply:** Scope decisions should favor compliance over ergonomics.
|
|
```
|
|
|
|
### Reference Memories
|
|
Pointers to where information lives in external systems.
|
|
|
|
```markdown
|
|
---
|
|
name: reference_bug_tracker
|
|
description: Pipeline bugs tracked in Linear project INGEST
|
|
type: reference
|
|
---
|
|
|
|
Pipeline bugs are tracked in Linear project "INGEST".
|
|
API monitoring alerts go to #oncall-api Slack channel.
|
|
```
|
|
|
|
## MEMORY.md Index
|
|
|
|
`MEMORY.md` is a one-line-per-entry index of all memory files. It's loaded into every conversation.
|
|
|
|
```markdown
|
|
# Memory Index
|
|
|
|
- [user_role.md](user_role.md) — Senior infra engineer, new to React
|
|
- [feedback_subagent_safety.md](feedback_subagent_safety.md) — No subagents for destructive ops
|
|
- [project_auth_rewrite.md](project_auth_rewrite.md) — Auth rewrite is compliance-driven
|
|
- [reference_bug_tracker.md](reference_bug_tracker.md) — Bugs in Linear INGEST project
|
|
```
|
|
|
|
Keep entries under 150 characters. MEMORY.md is truncated after 200 lines.
|
|
|
|
## What NOT to Save
|
|
|
|
- Code patterns or architecture (derivable from reading current code)
|
|
- Git history (use `git log` / `git blame`)
|
|
- Debugging solutions (the fix is in the code, context in the commit message)
|
|
- Anything already in CLAUDE.md
|
|
- Ephemeral task details (use task tools instead)
|
|
|
|
## When to Save
|
|
|
|
- **Immediately** when the user explicitly asks to remember something
|
|
- **Proactively** when you learn about the user's role, preferences, or expertise
|
|
- **After corrections** — if the user says "don't do X", save it as feedback
|
|
- **After confirmed approaches** — if something non-obvious worked, save that too
|
|
- **When project context emerges** that won't be in code (deadlines, stakeholder decisions, compliance requirements)
|
|
|
|
## When to Read
|
|
|
|
- At conversation start (MEMORY.md index is auto-loaded)
|
|
- When the user references prior-conversation work
|
|
- Before making decisions that prior feedback might inform
|
|
- When the user says "check", "recall", or "remember"
|
|
|
|
## Stale Memory
|
|
|
|
Memories can become outdated. Before acting on a memory:
|
|
- If it names a file path: check the file exists
|
|
- If it names a function or flag: grep for it
|
|
- If the user asks about *current* state: prefer `git log` or reading code over recalling a snapshot
|
|
|
|
"The memory says X exists" is not the same as "X exists now."
|