Seth-Workflow-April-2026/core/memory-system.md

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.

---
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.

---
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.

---
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.

---
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.

# 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."