Multi Machine Setup - robwhite4/claude-memory GitHub Wiki

Multi-Machine Setup

This guide covers how to use Claude Memory across multiple computers while maintaining consistent project context.

Overview

When you work on the same project from different machines (home desktop, work laptop, etc.), you want your AI context to stay synchronized. Claude Memory supports this through selective Git synchronization.

Basic Setup

Step 1: Configure .gitignore

By default, the entire .claude/ directory is ignored. To sync across machines, modify your .gitignore:

# Original (everything ignored)
.claude/

# Multi-machine setup (sync context, ignore personal data)
.claude/sessions/
.claude/backups/
.claude/memory.json
.claude/config.json
!.claude/context/

This configuration:

✅ Syncs context files (knowledge, patterns, decisions, tasks)
❌ Ignores personal config and temporary data
❌ Ignores session-specific information
❌ Ignores backup files

Step 2: Initial Commit

After configuring .gitignore:

# Add context files to Git
git add .claude/context/
git add CLAUDE.md
git commit -m "Add Claude Memory context files"
git push

Step 3: Setup on Other Machines

On your other computers:

# Clone or pull the repository
git pull

# Initialize Claude Memory
cmem init

# Your context is now synchronized!

Workflow

Daily Workflow

Starting work (any machine):

# Get latest changes
git pull

# Work normally - Claude Memory updates automatically
# Make your changes, use cmem commands as usual

Ending work (any machine):

# Commit your work including memory updates
git add .
git commit -m "Update project and memory context"
git push

Handling Conflicts

If you get merge conflicts in context files:

# Option 1: Accept remote changes (recommended)
git checkout --theirs .claude/context/
git add .claude/context/
git commit -m "Resolve memory conflicts - accept remote"

# Option 2: Keep local changes
git checkout --ours .claude/context/
git add .claude/context/
git commit -m "Resolve memory conflicts - keep local"

# Option 3: Manual merge
# Edit the conflicted files manually
git add .claude/context/
git commit -m "Resolve memory conflicts - manual merge"

Advanced Configurations

Selective Sync

For more control, you can sync specific context files:

# Sync only specific context files
.claude/
!.claude/context/knowledge.md
!.claude/context/decisions.md

Personal vs Shared Context

Maintain both personal and shared context:

# Use categories for organization
cmem knowledge add "personal_note" "My local setup" --category personal
cmem knowledge add "api_endpoint" "https://api.example.com" --category shared

# In .gitignore, you could potentially filter by category
# (requires custom scripting)

Branch-Specific Memory

Different memory for different branches:

# On feature branch
git checkout feature/new-api
cmem session start "API Feature Development"

# Memory updates are branch-specific
cmem decision "Use REST over GraphQL" "Simpler implementation" "GraphQL"

# Merge memory with code
git add .
git commit -m "Implement API with decision context"

Best Practices

1. Commit Frequency

Commit memory updates with related code changes
Don't commit after every single cmem command
Group logical changes together

2. Commit Messages

Include memory updates in commit messages:

git commit -m "Add user authentication

- Implemented JWT tokens
- Added login/logout endpoints
- Memory: Decided on JWT over sessions for stateless auth"

3. Pull Before Starting

Always pull latest changes before starting work:

alias work='git pull && cmem stats'

4. Avoid Conflicts

Don't edit context files manually
Use cmem commands exclusively
Coordinate with team on major memory updates

Troubleshooting

Context Not Syncing

Check your .gitignore:

# Verify context files are tracked
git check-ignore .claude/context/knowledge.md

# Should return nothing if properly configured

Stale Context

Force context regeneration:

# After pulling changes
cmem context --force

Large Context Files

If context files become too large:

# Clean up old/resolved items
cmem session cleanup
cmem pattern list --resolved  # Review and remove if needed

Example Configurations

Solo Developer, Multiple Machines

.claude/sessions/
.claude/backups/
.claude/memory.json
.claude/config.json
!.claude/context/

Small Team

.claude/
!.claude/context/knowledge.md
!.claude/context/decisions.md
# Keep patterns and tasks local

Open Source Project

# Don't sync any memory files
.claude/
# Only share CLAUDE.md for basic context

Security Considerations

Never commit sensitive data (API keys, passwords)
Review context files before pushing
Use environment variables for secrets
Consider encrypting sensitive knowledge entries

Migration Guide

Moving from single to multi-machine setup:

Backup current memory

cmem export backup-$(date +%Y%m%d).json

Update .gitignore
```
# Edit .gitignore as shown above
```

Commit context

git add .claude/context/
git commit -m "Enable multi-machine memory sync"

Setup other machines
```
# On each machine
git pull
cmem init
```