Problem

Memory access is fragmented across 4 different interfaces, creating confusion about which to use when:

1. Memory Skill Scripts (.claude/skills/memory/scripts/)

   • PowerShell scripts providing unified interface
   • Example: Search-Memory.ps1 (Serena-first with Forgetful augmentation)
   • Benefits: Unified router, deduplication, format options

2. Context-Retrieval Agent (.claude/agents/context-retrieval.md)

   • Agent specializing in gathering context before planning/implementation
   • Uses Memory Router skill + direct MCP tools
   • Benefits: Deep exploration, knowledge graph traversal, artifact reading

3. Forgetful Slash Commands (.claude/commands/forgetful/)

   • Direct Forgetful MCP access via slash commands
   • memory-list, memory-save, memory-explore, memory-search
   • Benefits: Quick access, user-friendly

4. Direct MCP Tool Calls

   • execute_forgetful_tool(), mcp__serena__*, mcp__plugin_claude-mem_mcp-search__*
   • Used by agents and scripts
   • Benefits: Full control, programmatic access

User Feedback

"The whole memory thing is confusing, fragmented, and duplicative. It needs to be cleaned up in order to be useful. @.claude/agents/context-retrieval.md seems to be the closest for breadth, but the protocol is in @.claude/skills/memory/ so those two need to be reconciled."

Current State

• context-retrieval.md DOES reference Memory Router (lines 18-44)
• But decision tree for "which interface to use when" is not clear
• Multiple overlapping paths to same functionality

Proposed Solutions

Option A: Decision Matrix Documentation

Keep all 4 interfaces but create clear decision matrix:

Option B: Consolidation

• Deprecate direct MCP calls in favor of Memory Skill scripts
• OR deprecate slash commands, use Memory Skill scripts exclusively
• Requires migration plan and breaking changes communication

Option C: Hybrid

• Keep skill scripts + context-retrieval agent (architectural)
• Deprecate slash commands (migrate to skill invocation)
• Keep direct MCP for low-level agent operations

Acceptance Criteria

• Analyze usage patterns: which interfaces are actually used?
• Propose consolidation plan with migration strategy
• Get stakeholder consensus on preferred approach
• Update CLAUDE.md with memory interface decision matrix
• Add "When to Use" section to memory skill SKILL.md
• Cross-reference between context-retrieval.md and memory skill
• Create migration guide if deprecating any interface

Impact

Severity: MEDIUM
Priority: Medium (cross-cutting architectural concern)

Benefits:

• Clear guidance for memory operations
• Reduced cognitive load for new contributors
• Simplified maintenance (fewer overlapping implementations)
• Better discoverability

Related

• ADR-037: Memory Router (Serena-first with Forgetful augmentation)
• ADR-038: Reflexion Memory Schema
• .claude/skills/memory/SKILL.md
• .claude/agents/context-retrieval.md
• Serena memory: memory-system-fragmentation-tech-debt.md
• Session 280: SlashCommandCreator implementation (where issue surfaced)

Next Steps

1. Gather usage data: which interfaces are actually used in practice?
2. Propose consolidation plan in issue discussion
3. Implement after consensus