npm package: @mem2/cli
Description: Sync AI agent memories across platforms (MEMORY.md, CLAUDE.md, AGENTS.md)
Author: winrey
Latest version: 0.1.0

# @mem2/cli

> Sync AI agent memories across platforms

[![npm version](https://badge.fury.io/js/%40mem2%2Fcli.svg)](https://www.npmjs.com/package/@mem2/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**@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.

[中文文档](./docs/README.zh-CN.md) | [MEMORY.md Specification](./docs/MEMORY_SPEC.md)

## 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

```bash
# Global installation
npm install -g @mem2/cli

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

## Quick Start

### 1. Initialize

```bash
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`:

```bash
# 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

```bash
# 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:

```bash
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.

```bash
mem2 init [options]

Options:
  -f, --force    Overwrite existing configuration
```

#### `mem2 import`

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

```bash
mem2 import --from <source>

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

**Examples:**
```bash
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).

```bash
mem2 compile [options]

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

**Examples:**
```bash
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.

```bash
mem2 watch [directory]

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

**Examples:**
```bash
mem2 watch           # Watch current directory
mem2 watch ./docs    # Watch specific directory
```

## Configuration

Create a `.mem2rc.json` file to customize behavior:

```json
{
  "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:

```markdown
# 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](./docs/MEMORY_SPEC.md) 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**:
```markdown
# React App

## Tech Stack
- React 18
- TypeScript
- Vite

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

### Modular Project

**MEMORY.md**:
```markdown
# Enterprise App

## Overview
@docs/overview.md

## Setup
@docs/setup.md

## Architecture
@docs/architecture.md
```

### With Watch Mode

```bash
# 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:
```bash
# 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

```bash
# 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`:
```json
{
  "watch": {
    "onConflict": "memory-priority"  // or "ask", "pause"
  }
}
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT © [mem2](https://github.com/mem2)

## Links

- [GitHub Repository](https://github.com/mem2/cli)
- [npm Package](https://www.npmjs.com/package/@mem2/cli)
- [MEMORY.md Specification](./docs/MEMORY_SPEC.md)
- [Chinese Documentation](./docs/README.zh-CN.md)
- [Issue Tracker](https://github.com/mem2/cli/issues)

## Related Projects

- [agents.md](https://agents.md/) - Open format for AI coding agents
- [Claude Code](https://docs.claude.com/en/docs/claude-code) - AI coding assistant by Anthropic

---

Made with ❤️ for the AI coding community