[Bug] Self-reporting - I am making separate memory .md files, not adding to MEMORY.md

I asked Claude about its memories and it thinks it is not using them as it should?! I don't know since I didn't design it lol

Bug Report: Claude Code Creating Orphaned Memory Files

Severity: Low
Category: Developer Experience / Tool Behavior
Status: Documented

Problem

Claude Code (the AI agent) creates separate .md files in the auto-memory directory (~/.claude/projects/*/memory/) for task-specific notes, but these files are never actually used because only MEMORY.md is auto-loaded into the system prompt.

Evidence

Current memory directory for this project contains:

• MEMORY.md ✅ (auto-loaded, ~200 line limit)
• FIRESTORE_INDEXES_HANDOVER.md ❌ (orphaned, created Feb 9)
• newtonsoft_migration.md ❌ (orphaned, created Feb 5)
• TIMESHEETS_API.md ❌ (orphaned, created Feb 7)
• URL_ATTACHMENT_DISPLAY_IMPLEMENTATION.md ❌ (orphaned, created Feb 5)

The agent created these separate files thinking they would persist and be referenced later, but has never actually read them back—they're dead weight that just accumulate.

Root Cause

Incorrect mental model: Agent treats the memory directory like a general knowledge base where any .md file is available. In reality, only MEMORY.md gets injected into the system prompt on each invocation.

No enforcement: The system allows creation of arbitrary files without warning the agent that they won't be auto-loaded.

Impact

• User friction: Separate memory files pile up without being used, creating false sense of persistence
• Wasted effort: Agent spends time writing files that never get read
• Confusion: User sees files accumulating but agent never references them, making memory system seem useless
• System bloat: Orphaned files consume disk space and clutter the directory

Root Cause Analysis

The agent's behavior stems from:

1. Not understanding that only MEMORY.md is auto-loaded (system behavior not clearly documented in agent instructions)
2. Treating task-specific handover docs as "memory" when they're actually just conversation output
3. No feedback loop—agent never realizes the files weren't read

Solution

For the agent:

• Only write to MEMORY.md
• Keep it to ~200 lines by consolidating/archiving old entries instead of creating new files
• Proactively delete entries that are stale, resolved, or no longer relevant
• Treat memory as operational notes only (parked bugs, critical gotchas, current blockers)—not a full knowledge base

For Claude Code developers:

• Consider documenting in agent instructions that only MEMORY.md is auto-loaded
• Or: Support multiple memory files and auto-load all .md files in the memory directory
• Or: Provide agent feedback when non-MEMORY.md files are created (warning)

Recommendation

Adopt strict discipline: MEMORY.md only. It's the single source of truth for persistent context across conversations. Everything else is conversation-scoped.

Environment Info

• Platform: darwin
• Terminal: vscode
• Version: 2.1.31
• Feedback ID: e19a23dd-98b5-4720-b7b0-ab49be0ef351

Errors

[{"error":"Error: ENOENT: no such file or directory, open '/Users/lukepuplett/.claude/remote-settings.json'\n    at openSync (unknown)\n    at <anonymous> (/$bunfs/root/claude:12:947)\n    at d5 (/$bunfs/root/claude:11:40746)\n    at readSync (/$bunfs/root/claude:12:875)\n    at l5 (/$bunfs/root/claude:6127:113)\n    at rG (/$bunfs/root/claude:6129:226)\n    at bdR (/$bunfs/root/claude:121:25774)\n    at kdR (/$bunfs/root/claude:121:25937)\n    at N_ (/$bunfs/root/claude:121:27674)\n    at Lt0 (/$bunfs/root/claude:122:1170)","timestamp":"2026-02-09T17:00:47.698Z"},{"error":"Error: Request was aborted.\n    at makeRequest (/$bunfs/root/claude:361:3940)\n    at processTicksAndRejections (native:7:39)","timestamp":"2026-02-09T17:05:21.466Z"}]