Gemini Memory Sync

Documentation Delegation

Documentation Source: For authoritative memory/import syntax and current features, query

gemini-cli-docs

skill. This skill provides sync patterns;

gemini-cli-docs

provides official Gemini CLI documentation.

Overview

This skill provides patterns for keeping Claude Code (

CLAUDE.md

) and Gemini CLI (

GEMINI.md

) memory files synchronized. The core principle is CLAUDE.md as source of truth with GEMINI.md importing and adding overrides.

When to Use This Skill

Keywords: sync memory, sync context, claude.md gemini.md, memory import, context drift, @import, memport

Use this skill when:

• Setting up GEMINI.md for a new project
• Detecting drift between memory files
• Understanding the import syntax
• Troubleshooting sync issues

Core Principle: Single Source of Truth

CLAUDE.md (Source of Truth)
    │
    │ @import
    ▼
GEMINI.md (Imports + Overrides)

Why CLAUDE.md is the source:

• Claude Code is the primary development environment
• CLAUDE.md is already established in most projects
• Single point of update reduces maintenance burden
• Git history shows context evolution in one place

GEMINI.md Structure

Recommended Template

# GEMINI.md

@CLAUDE.md

## Gemini-Specific Overrides

You are Gemini CLI. Your unique capabilities:
- Large context window (Flash) / Very large (Pro)
- Interactive PTY shell (vim, git rebase -i, htop)
- Checkpointing with instant rollback
- Policy engine for tool control
- Native Google Cloud authentication

### When to Use Your Strengths

- **Bulk analysis**: Use your large context for codebase-wide exploration
- **Interactive tools**: Handle vim, git interactive commands
- **Risky operations**: Use sandbox and checkpointing
- **Second opinions**: Provide independent validation

### Model Selection

- Use **Flash** for bulk analysis and simple tasks
- Use **Pro** for complex reasoning and very large contexts

Import Syntax

Gemini CLI uses

@

prefix for imports (memport):

# Import entire file
@CLAUDE.md

# Import relative path
@./docs/conventions.md

# Import from parent
@../shared/COMMON.md

Note: Unlike CLAUDE.md's flexible import, GEMINI.md's memport has:

• Maximum import depth: 5 levels
• Circular import detection
• File access validation

Drift Detection

Manual Detection

# Quick diff (ignoring Gemini-specific sections)
diff <(grep -v "^## Gemini-Specific" CLAUDE.md) <(grep -v "^## Gemini-Specific\|^@" GEMINI.md)

Hash-Based Detection

# Store hash of CLAUDE.md
claude_hash=$(md5sum CLAUDE.md | cut -d' ' -f1)

# Store in sync state
echo "{\"claude_hash\": \"$claude_hash\", \"last_sync\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > .claude/temp/sync-state.json

Check for Drift

# Compare current hash to stored
current_hash=$(md5sum CLAUDE.md | cut -d' ' -f1)
stored_hash=$(cat .claude/temp/sync-state.json 2>/dev/null | jq -r '.claude_hash // ""')

if [ "$current_hash" != "$stored_hash" ]; then
  echo "CLAUDE.md has changed since last sync"
fi

Sync Patterns

Pattern 1: Import-Based (Recommended)

GEMINI.md simply imports CLAUDE.md - no sync needed:

# GEMINI.md
@CLAUDE.md

## Gemini-Specific
{overrides here}

Pros:

• No sync maintenance
• Always up-to-date
• Single source of truth enforced

Cons:

• GEMINI.md must start with @import
• Can't selectively import sections

Pattern 2: Section-Based Sync

Copy specific sections from CLAUDE.md:

# Extract specific sections
conventions=$(sed -n '/^## Conventions/,/^## /p' CLAUDE.md | head -n -1)
build_commands=$(sed -n '/^## Build/,/^## /p' CLAUDE.md | head -n -1)

# Rebuild GEMINI.md
cat > GEMINI.md << EOF
# GEMINI.md

## Conventions (synced from CLAUDE.md)
$conventions

## Build Commands (synced from CLAUDE.md)
$build_commands

## Gemini-Specific Overrides
{your overrides}
EOF

Pros:

• Selective control
• Can transform content

Cons:

• Requires manual sync
• Can drift easily

Pattern 3: Template Generation

Generate GEMINI.md from CLAUDE.md with transformations:

# Transform CLAUDE.md to GEMINI.md
cat CLAUDE.md | \
  sed 's/Claude Code/Gemini CLI/g' | \
  sed 's/claude/gemini/g' > GEMINI.md

# Append Gemini-specific section
cat >> GEMINI.md << 'EOF'

## Gemini-Specific Overrides
{overrides}
EOF

Common Issues

Issue: Import Not Working

Symptom: Gemini doesn't see CLAUDE.md content

Fix: Ensure correct path syntax

# Correct
@CLAUDE.md
@./CLAUDE.md

# Incorrect
@/CLAUDE.md  (absolute paths may fail)

Issue: Circular Import

Symptom: Error about circular references

Fix: Don't have CLAUDE.md import GEMINI.md

Issue: Import Depth Exceeded

Symptom: Nested imports not loading

Fix: Memport has max depth of 5. Flatten import chain.

Issue: Context Drift

Symptom: Gemini behaves differently than Claude

Fix:

1. Use

   /sync-context

   command
2. Or rebuild GEMINI.md with @import pattern

Best Practices

1. Use @Import Pattern

Always prefer import over copy:

# GEMINI.md - Good
@CLAUDE.md

## Gemini-Specific
...

2. Keep Overrides Minimal

Only override what's truly Gemini-specific:

• Model selection guidance
• Interactive shell instructions
• Sandbox usage patterns

3. Document What's Synced

If using section-based sync, note the source:

## Conventions (synced from CLAUDE.md on 2025-11-30)

4. Validate After Sync

Test that Gemini understands the context:

gemini "What are the project conventions?" --output-format json

5. Regular Drift Checks

Include in CI or pre-commit:

# In CI
./scripts/check-memory-drift.sh

Sync Workflow

Initial Setup

# 1. Ensure CLAUDE.md exists
if [ ! -f "CLAUDE.md" ]; then
  echo "CLAUDE.md not found. Create it first."
  exit 1
fi

# 2. Create GEMINI.md with import
cat > GEMINI.md << 'EOF'
# GEMINI.md

@CLAUDE.md

## Gemini-Specific Overrides

You are Gemini CLI with unique capabilities:
- Large context window (exceeds typical LLM limits)
- Interactive PTY shell
- Checkpointing with rollback
- Policy engine

Prioritize tasks that leverage these strengths.
EOF

# 3. Initialize sync state
mkdir -p .claude/temp
echo "{\"claude_hash\": \"$(md5sum CLAUDE.md | cut -d' ' -f1)\", \"last_sync\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > .claude/temp/sync-state.json

echo "GEMINI.md created with @import to CLAUDE.md"

Manual Sync

# Check if sync needed
if [ "$(md5sum CLAUDE.md | cut -d' ' -f1)" != "$(cat .claude/temp/sync-state.json | jq -r '.claude_hash')" ]; then
  echo "CLAUDE.md has changed. If using @import, no action needed."
  echo "If using section-based sync, rebuild GEMINI.md sections."

  # Update sync state
  echo "{\"claude_hash\": \"$(md5sum CLAUDE.md | cut -d' ' -f1)\", \"last_sync\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > .claude/temp/sync-state.json
fi

Related Skills

• gemini-workspace-bridge

  - Overall workspace architecture

• gemini-context-bridge

  - Legacy context sharing

Related Commands

• /sync-context

  - Trigger manual sync check

Test Scenarios

Scenario 1: Initial Setup

Query: "How do I set up GEMINI.md to use CLAUDE.md?" Expected Behavior:

• Skill activates on "sync memory" or "claude.md gemini.md"
• Provides @import syntax and template Success Criteria: User receives working GEMINI.md template with @CLAUDE.md import

Scenario 2: Drift Detection

Query: "How do I check if my memory files are out of sync?" Expected Behavior:

• Skill activates on "context drift" or "sync"
• Provides hash-based detection method Success Criteria: User receives drift detection script

Scenario 3: Import Issues

Query: "My GEMINI.md @import isn't working" Expected Behavior:

• Skill activates on "import" troubleshooting
• Provides common issues and fixes Success Criteria: User receives troubleshooting steps for path syntax

Version History

• v1.1.0 (2025-12-01): Added MANDATORY section, Test Scenarios, Version History
• v1.0.0 (2025-11-25): Initial release