Design Decisions - robwhite4/claude-memory GitHub Wiki

Design Decisions

This document captures the key architectural and design decisions made during Claude Memory's development, explaining the rationale behind major choices.

Core Architecture

Decision: File-Based Storage

Choice: Use local JSON files instead of a database

Rationale:

  • Zero dependencies for users
  • Simple installation (just npm install)
  • Easy to understand and debug
  • Git-friendly for version control
  • Portable across systems

Alternatives Considered:

  • SQLite: Would add complexity and dependencies
  • Cloud storage: Privacy concerns, requires accounts
  • Binary format: Not human-readable or Git-friendly

Decision: Single Global Command

Choice: Use cmem as the single entry point for all commands

Rationale:

  • Memorable and short
  • Follows Unix philosophy
  • Clear subcommand structure
  • Easier to extend

Alternatives Considered:

  • Multiple commands (claude-task, claude-decision)
  • Longer name (claude-memory)

Memory Structure

Decision: Multi-File Context System

Choice: Split memory into multiple markdown files in .claude/context/

Rationale:

  • No information truncation
  • Better Git diffs
  • Human-readable format
  • Selective loading possible
  • Scalable to large projects

Trade-offs:

  • More files to manage
  • Slightly more complex

Decision: CLAUDE.md as Primary Context

Choice: Keep CLAUDE.md as the main context file, optimized for tokens

Rationale:

  • Single file for AI to read
  • Token-efficient
  • Maintains compatibility
  • Clear separation of concerns

Implementation:

  • CLAUDE.md: Optimized summary (~3K tokens)
  • Context files: Complete information
  • References: CLAUDE.md points to context files

Automation Features

Decision: Auto-Session Management

Choice: Automatically rotate sessions every 4 hours by default

Rationale:

  • Natural work rhythm alignment
  • Prevents unbounded session growth
  • Maintains useful context chunks
  • Zero user intervention needed

Session Periods:

  • Morning: 6am-12pm
  • Afternoon: 12pm-5pm
  • Evening: 5pm-9pm
  • Night: 9pm-6am

Decision: Auto-Backup Strategy

Choice: Backup after every 10 significant actions

Rationale:

  • Balance between safety and performance
  • Prevents data loss
  • Minimal disk usage
  • Automatic cleanup after 7 days

User Experience

Decision: Silent by Default

Choice: Minimal output unless requested

Rationale:

  • Clean terminal experience
  • Focus on results, not process
  • Verbose mode available when needed
  • Follows Unix tradition

Decision: Dry-Run Support

Choice: Implement --dry-run flag globally

Rationale:

  • Safe experimentation
  • Preview changes
  • Useful for scripts
  • Industry standard practice

Data Management

Decision: Token Optimization

Choice: Automatically optimize CLAUDE.md to ~3K tokens

Rationale:

  • Efficient AI token usage
  • Maintains essential context
  • Prioritizes recent/important items
  • Configurable limits

Priority System:

  1. Current session (40%)
  2. Recent decisions (20%)
  3. Active tasks (20%)
  4. High-priority patterns (20%)

Decision: Knowledge Categories

Choice: Require categories for knowledge entries

Rationale:

  • Better organization
  • Easier filtering
  • Team consistency
  • Scalability

Standard Categories:

  • architecture
  • decisions
  • patterns
  • debugging
  • infrastructure
  • security

Security and Privacy

Decision: Local-Only Storage

Choice: Never send data to external services

Rationale:

  • Complete privacy
  • No account required
  • Works offline
  • Enterprise-friendly

Decision: Sanitized Export

Choice: Provide sanitized export option

Rationale:

  • Safe sharing
  • Remove sensitive data
  • Maintain useful context
  • Team collaboration

Development Workflow

Decision: Git-First Design

Choice: Optimize for Git workflows

Rationale:

  • Industry standard VCS
  • Natural collaboration
  • Change tracking
  • Conflict resolution

Implementation:

  • Text-based formats
  • Meaningful diffs
  • .gitignore templates
  • Merge-friendly structure

Decision: Modular Codebase

Choice: Split code into focused modules (v1.9.0)

Rationale:

  • Easier maintenance
  • Better testing
  • Clear responsibilities
  • Reduced complexity

Structure:

lib/
├── ClaudeMemory.js      # Core logic
└── utils/
    ├── validators.js    # Input validation
    ├── sanitizers.js    # Security
    └── formatters.js    # Output formatting

Performance

Decision: Lazy Loading

Choice: Load data only when needed

Rationale:

  • Faster startup
  • Lower memory usage
  • Scalable to large projects
  • Better responsiveness

Decision: In-Memory Caching

Choice: Cache frequently accessed data

Rationale:

  • Reduce file I/O
  • Faster operations
  • Configurable TTL
  • Minimal memory overhead

Extensibility

Decision: Configuration System

Choice: JSON-based configuration with defaults

Rationale:

  • Simple format
  • Easy overrides
  • Environment variables
  • CLI flags

Priority Order:

  1. CLI flags (highest)
  2. Environment variables
  3. Config file
  4. Defaults (lowest)

Decision: No Plugin System (Yet)

Choice: Keep core focused, defer plugins to v2

Rationale:

  • Maintain simplicity
  • Establish core patterns first
  • Avoid complexity
  • Learn from usage

Error Handling

Decision: Graceful Degradation

Choice: Continue operating despite errors when possible

Rationale:

  • Better user experience
  • Prevent data loss
  • Clear error messages
  • Recovery options

Example:

  • Corrupted backup: Use older backup
  • Missing file: Create with defaults
  • Invalid data: Skip and warn

Future Considerations

Deferred Decisions

  1. Cloud Sync: Wait for user demand
  2. Database Backend: Keep simple for now
  3. GUI Interface: Focus on CLI first
  4. AI Integration: Let users choose models

Lessons Learned

  1. Simplicity Wins: Every feature adds complexity
  2. Automation Helps: Users prefer zero-config
  3. Flexibility Matters: Options for power users
  4. Privacy First: Local storage builds trust

See also: