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:

• Use /sync-context command

• 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