claude-mem/docs/memory-toggle-feature.md

Memory Toggle Feature - Design Plan

Overview

Users need the ability to pause/resume claude-mem memory recording without uninstalling the plugin. This addresses use cases where users want temporary privacy, testing sessions, or simply don't want certain conversations saved.

User Requirements (from feedback)

• "I don't want to save everything always"
• Need persistent on/off state across sessions
• Should be easy to toggle without complex commands
• Should not interfere with conversation context

Design Principles

1. Non-intrusive: Toggling memory should not require special characters in prompts
2. Persistent: State should survive across Claude Code sessions
3. Simple: Clear on/off with easy status checking
4. Fast: Minimal overhead when checking enabled state

Implementation Options

Option A: Settings Flag (Recommended)

Storage: ~/.claude/settings.json

{
  "CLAUDE_MEM_ENABLED": true  // default: true
}

CLI Commands:

claude-mem pause    # Disable memory recording
claude-mem resume   # Enable memory recording
claude-mem status   # Show current state

Hook Behavior:

• All hooks check CLAUDE_MEM_ENABLED setting at start
• If false, hooks return early without saving/processing
• Worker service continues running (ready for resume)

Pros:

• Uses existing Claude settings infrastructure
• Simple boolean flag
• Easy to implement in all hooks

Cons:

• Modifies Claude Code's settings file

---

Option B: Local Config File

Storage: ~/.claude-mem/config.json

{
  "enabled": true,
  "version": "4.2.8",
  "lastToggled": "2025-10-25T01:30:00Z"
}

Same CLI commands as Option A

Pros:

• Isolated from Claude Code settings
• Can add metadata (timestamp, reason, etc.)
• Full control over config structure

Cons:

• Additional file to manage
• Hooks need to read separate config file

---

Option C: Slash Command Integration

Usage: In-session control via slash commands

/claude-mem pause
/claude-mem resume
/claude-mem status

Pros:

• No need to leave Claude Code session
• Immediate feedback
• Familiar interface for users

Cons:

• Requires slash command setup
• Need to update .claude/commands/ structure
• More complex implementation

---

Recommended Approach: Hybrid A + C

Combine Settings Flag (A) with optional Slash Commands (C):

1. Persistent State: Store in ~/.claude/settings.json or ~/.claude-mem/config.json
2. CLI Control: claude-mem pause/resume/status
3. Optional In-Session Control: /claude-mem pause/resume slash commands
4. Hook Check: All hooks read setting at startup, skip if disabled

---

Implementation Details

Hook Modifications

All hooks need to check enabled state:

// src/shared/settings.ts
export function isMemoryEnabled(): boolean {
  try {
    const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
    const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
    return settings.CLAUDE_MEM_ENABLED !== false; // default true
  } catch {
    return true; // default to enabled if settings missing
  }
}

// In each hook
import { isMemoryEnabled } from '../shared/settings.js';

export function hookFunction(input: HookInput) {
  if (!isMemoryEnabled()) {
    return; // Skip all memory operations
  }

  // Normal hook logic...
}

CLI Commands

// src/bin/cli.ts
program
  .command('pause')
  .description('Pause memory recording (sessions will not be saved)')
  .action(() => {
    updateMemorySetting(false);
    console.log('✓ Memory recording paused');
  });

program
  .command('resume')
  .description('Resume memory recording')
  .action(() => {
    updateMemorySetting(true);
    console.log('✓ Memory recording resumed');
  });

program
  .command('status')
  .description('Show current memory recording status')
  .action(() => {
    const enabled = isMemoryEnabled();
    console.log(`Memory recording: ${enabled ? '✓ ENABLED' : '✗ PAUSED'}`);
  });

Slash Commands (Optional)

Create .claude/commands/claude-mem.md:

# Claude Mem Control

Usage: /claude-mem [pause|resume|status]

- pause: Stop recording this session
- resume: Resume recording
- status: Show current state

---

User Experience

Pausing Memory

$ claude-mem pause
✓ Memory recording paused

  All future sessions will NOT be saved until you run:
  claude-mem resume

Checking Status

$ claude-mem status
Memory recording: ✗ PAUSED

To resume recording: claude-mem resume

Resume Recording

$ claude-mem resume
✓ Memory recording resumed

All sessions will now be saved to ~/.claude-mem/

---

Affected Hooks

new-hook (UserPromptSubmit)

• Skip creating session records
• Skip saving user prompts

save-hook (PostToolUse)

• Skip capturing observations
• Skip sending to worker service

summary-hook

• Skip generating summaries
• Session remains unprocessed

context-hook (SessionStart)

• Still runs (to show status message?)
• Could display: "Memory recording is currently paused"

cleanup-hook (SessionEnd)

• Skip marking sessions complete
• No cleanup needed if nothing was saved

---

Edge Cases

1. Mid-session toggle: What if user pauses during a session?

   • Decision: New state takes effect immediately
   • Observations before pause are saved, after pause are not

2. Worker service: Should it stop when paused?

   • Decision: Keep running (minimal resource usage)
   • Ready to process when resumed

3. Existing data: What happens to saved sessions when paused?

   • Decision: No change, data persists
   • Context hook can still load past sessions

4. Uninstall vs Pause: Clear distinction?

   • Pause: Temporary, easy to resume
   • Uninstall: Complete removal, requires reinstall

---

Migration & Compatibility

• Default to true (enabled) for backward compatibility
• Existing users unaffected unless they explicitly pause
• No database schema changes needed
• No breaking changes to hooks

---

Future Enhancements

1. Selective Recording: Fine-grained control

   claude-mem pause --observations-only
   claude-mem pause --summaries-only
   

2. Project-Level Control: Different settings per project

   claude-mem pause --project claude-mem
   

3. Temporary Pause: Auto-resume after duration

   claude-mem pause --duration 1h
   

4. Pause Reasons: Track why users pause

   claude-mem pause --reason "debugging session"
   

---

Open Questions

1. Should context hook still inject past context when paused?

   • Lean toward: Yes, show past but don't save current

2. Should we show a status indicator when paused?

   • Could add to context hook output: "🔴 Memory recording paused"

3. CLI command naming: pause/resume vs disable/enable vs off/on?

   • Lean toward: pause/resume (temporary feeling)

4. Should worker service stop when paused?

   • Lean toward: Keep running (fast resume)

---

Timeline

• Phase 1: Settings flag + CLI commands (1-2 days)
• Phase 2: Status indicator in context hook (1 day)
• Phase 3: Slash commands (optional, 1 day)
• Phase 4: User testing & feedback (1 week)
• Phase 5: Release in v4.3.0

---

Success Metrics

• Users report successful pausing/resuming
• No saved data when paused (verify in tests)
• Fast toggle time (< 100ms)
• Clear status feedback
• No edge case bugs in production

---

Related Issues

• GitHub feedback: "I don't want to save everything always"
• Privacy concerns: Users want control over what's saved
• Testing workflows: Developers need clean test sessions

---

Last Updated: October 25, 2025 Status: Planning / Not Yet Implemented