@mem2/cli

Sync AI agent memories across platforms

@mem2/cli is a command-line tool that synchronizes AI agent memory files across different platforms, enabling seamless collaboration between Claude Code, Cursor, Codex, Gemini, and other AI coding assistants.

中文文档 | MEMORY.md Specification

Features

• 🔄 Bidirectional Sync: Convert between MEMORY.md, CLAUDE.md, and AGENTS.md formats
• 👀 Watch Mode: Automatically sync changes across formats in real-time
• 📦 Modular Content: Support for @import syntax to organize large memory files
• 🎯 Smart Conflict Resolution: Detects and helps resolve simultaneous changes
• 🚫 Flexible Ignore Rules: Respects .gitignore, .mem2ignore, and custom patterns
• 🎨 Beautiful CLI: Colorful, interactive prompts with intuitive UX
• 🔧 Configurable: Extensive configuration options via .mem2rc.json

Why @mem2/cli?

Different AI coding assistants use different memory formats:

• Claude Code uses CLAUDE.md with hierarchical memory
• Cursor, Codex, Gemini use AGENTS.md following the agents.md standard

@mem2/cli introduces MEMORY.md as a unified intermediate format that:

• Converts seamlessly between platforms
• Supports modular content organization via @import
• Acts as a single source of truth for your project's AI memory

Installation

# Global installation
npm install -g @mem2/cli

# Or use with npx (no installation needed)
npx @mem2/cli --help

Quick Start

1. Initialize

cd your-project
mem2 init

This creates a .mem2rc.json configuration file and detects existing memory files.

2. Import Existing Memory

If you have an existing CLAUDE.md or AGENTS.md:

# Import from CLAUDE.md
mem2 import --from CLAUDE.md

# Import from AGENTS.md
mem2 import --from AGENTS.md

This converts your existing file to MEMORY.md.

3. Compile to Target Formats

# Compile to both AGENTS.md and CLAUDE.md (default)
mem2 compile

# Compile to specific formats
mem2 compile --to AGENTS.md
mem2 compile --to CLAUDE.md AGENTS.md

# Using format aliases
mem2 compile --to codex gemini claude

4. Watch Mode

Enable automatic syncing:

mem2 watch

# Watch a specific directory
mem2 watch ./docs

Watch mode will:

• Auto-generate missing files
• Sync changes between MEMORY.md ↔ CLAUDE.md ↔ AGENTS.md
• Detect and help resolve conflicts

Usage

Commands

mem2 init

Initialize configuration in the current directory.

mem2 init [options]

Options:
  -f, --force    Overwrite existing configuration

mem2 import

Import CLAUDE.md or AGENTS.md to MEMORY.md.

mem2 import --from <source>

Options:
  --from <source>    Source file (CLAUDE.md, AGENTS.md, codex, gemini)

Examples:

mem2 import --from CLAUDE.md
mem2 import --from AGENTS.md
mem2 import --from codex      # Alias for AGENTS.md

mem2 compile

Compile MEMORY.md to target format(s).

mem2 compile [options]

Options:
  --to <targets...>    Target formats (CLAUDE.md, AGENTS.md, codex, gemini)

Examples:

mem2 compile                          # Use default targets
mem2 compile --to AGENTS.md           # Single target
mem2 compile --to CLAUDE.md AGENTS.md # Multiple targets
mem2 compile --to codex gemini        # Format aliases

mem2 watch

Watch and auto-sync memory files.

mem2 watch [directory]

Arguments:
  directory    Directory to watch (defaults to current directory)

Examples:

mem2 watch           # Watch current directory
mem2 watch ./docs    # Watch specific directory

Configuration

Create a .mem2rc.json file to customize behavior:

{
  "import": {
    "autoGitignore": "ask"
  },
  "compile": {
    "defaultTargets": ["AGENTS.md", "CLAUDE.md"],
    "expandImportsInAgents": true,
    "importPosition": "append",
    "strictMode": false
  },
  "watch": {
    "autoConvert": true,
    "defaultIgnore": [
      "node_modules/**",
      ".git/**",
      "dist/**",
      "build/**"
    ],
    "additionalIgnore": [],
    "excludeGitignored": true,
    "onConflict": "ask"
  },
  "gitignore": {
    "recommendIgnoreCompiled": "ask"
  }
}

Configuration Options

import.autoGitignore

• "ask" (default): Prompt user to create/update .gitignore
• "auto": Automatically add compiled files to .gitignore
• "never": Don't modify .gitignore

compile.defaultTargets

Default formats for mem2 compile command.

compile.expandImportsInAgents

• true (default): Resolve @import statements when compiling to AGENTS.md
• false: Keep @import statements as-is

compile.importPosition

• "append" (default): Add imported content at the end
• "inline": Replace @import with content at declaration point

compile.strictMode

• false (default): Warn about missing imports but continue
• true: Fail compilation if imports can't be resolved

watch.autoConvert

• true (default): Automatically convert CLAUDE.md/AGENTS.md to MEMORY.md
• false: Ask user first

watch.onConflict

• "ask" (default): Prompt user to resolve conflicts
• "memory-priority": Always use MEMORY.md as source
• "pause": Stop watching on conflict

MEMORY.md Format

MEMORY.md is standard Markdown with optional @import syntax:

# My Project

## Overview
Brief description of the project...

## Development Setup
@docs/setup.md

## Code Style
- Use TypeScript
- Follow ESLint rules
- Write tests for new features

## API Documentation
@docs/api/README.md

@import Syntax

• Relative paths: @docs/file.md (relative to MEMORY.md)
• Absolute paths: @/docs/file.md
• Nested imports: Up to 5 levels deep
• Protected in code blocks: Imports in ``` or ` are not evaluated

See the MEMORY.md Specification for complete details.

Ignore Files

.mem2ignore

Create a .mem2ignore file to exclude directories from watch mode:

# Ignore build outputs
dist/
build/
out/

# Ignore dependencies
node_modules/
vendor/

# Ignore temporary files
*.tmp
.cache/

Syntax is compatible with .gitignore.

.gitignore Integration

By default, mem2 respects .gitignore patterns (configurable via watch.excludeGitignored).

Special handling: Even if .gitignore contains CLAUDE.md or AGENTS.md, mem2 will still watch these files.

Platform Support

| Platform | Format | Supported | |----------|--------|-----------| | Claude Code | CLAUDE.md | ✅ | | Cursor | AGENTS.md | ✅ | | OpenAI Codex | AGENTS.md | ✅ | | Google Gemini | AGENTS.md | ✅ | | Custom | MEMORY.md | ✅ |

Examples

Basic Project

MEMORY.md:

# React App

## Tech Stack
- React 18
- TypeScript
- Vite

## Development
\`\`\`bash
npm install
npm run dev
\`\`\`

Modular Project

MEMORY.md:

# Enterprise App

## Overview
@docs/overview.md

## Setup
@docs/setup.md

## Architecture
@docs/architecture.md

With Watch Mode

# Terminal 1: Start watch mode
mem2 watch

# Terminal 2: Edit MEMORY.md
vim MEMORY.md

# AGENTS.md and CLAUDE.md auto-update!

Best Practices

1. Use MEMORY.md as source of truth: Edit MEMORY.md and let mem2 sync to other formats
2. Ignore compiled files in git: Add AGENTS.md and CLAUDE.md to .gitignore
3. Modularize large files: Use @import to break content into logical sections
4. Enable watch mode during development: Auto-sync saves manual compilation steps
5. Configure conflict resolution: Set watch.onConflict based on your workflow

Troubleshooting

Import errors

If you see import warnings:

# Check if imported files exist
ls -la docs/

# Enable strict mode to fail on errors
# Edit .mem2rc.json: "strictMode": true

Watch mode not detecting changes

# Check ignore patterns
cat .mem2ignore
cat .gitignore

# Ensure files aren't ignored
mem2 watch --verbose  # (planned feature)

Conflicts during watch

Configure behavior in .mem2rc.json:

{
  "watch": {
    "onConflict": "memory-priority"  // or "ask", "pause"
  }
}

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © mem2

Links

• GitHub Repository
• npm Package
• MEMORY.md Specification
• Chinese Documentation
• Issue Tracker

Related Projects

• agents.md - Open format for AI coding agents
• Claude Code - AI coding assistant by Anthropic

Made with ❤️ for the AI coding community