---
title: Import & Export
description: Import and export memories in various formats
---

# Import & Export

## generate

Write agent config files directly to disk. Unlike `export` (which prints to stdout), `generate` creates the files for you.

```bash
npx memctl generate
```

### Flags

| Flag | File written | Format | Frontmatter |
| ---- | ------------ | ------ | ----------- |
| _(none)_ | `AGENTS.md` | agents_md (always written) | |
| `--claude` | `CLAUDE.md` | agents_md | |
| `--claude-rule` | `.claude/rules/memctl.md` | agents_md | |
| `--gemini` | `GEMINI.md` | agents_md | |
| `--cursor` | `.cursorrules` | cursorrules | |
| `--cursor-rule` | `.cursor/rules/memctl.mdc` | agents_md | `alwaysApply: true` |
| `--copilot` | `.github/copilot-instructions.md` | agents_md | `applyTo: "**"` |
| `--windsurf` | `.windsurf/rules/memctl.md` | agents_md | `trigger: always_on` |
| `--cline` | `.clinerules/memctl.md` | agents_md | |
| `--roo` | `.roo/rules/memctl.md` | agents_md | |
| `--codex` | `codex.md` | agents_md | |
| `--amazonq` | `.amazonq/rules/memctl.md` | agents_md | |
| `--all` | All of the above | | |
| `--link` | Symlink to `AGENTS.md` instead of copying | | |

Flags are combinable. `--all` writes all targets. Tools that support YAML frontmatter (Windsurf, Cursor rules, Copilot) get activation metadata prepended automatically.

Directories are created automatically (e.g. `.github/`).

### Examples

```bash
# AGENTS.md only
npx memctl generate

# AGENTS.md + CLAUDE.md
npx memctl generate --claude

# AGENTS.md + CLAUDE.md + .cursorrules
npx memctl generate --claude --cursor

# All agent config files
npx memctl generate --all

# All files, but symlink CLAUDE.md, GEMINI.md, and copilot-instructions.md to AGENTS.md
npx memctl generate --all --link
```

### Example output

```
Wrote 1 file(s): AGENTS.md
```

With `--all`:

```
Wrote 12 file(s): AGENTS.md, CLAUDE.md, .claude/rules/memctl.md, GEMINI.md, .cursorrules, .cursor/rules/memctl.mdc, .github/copilot-instructions.md, .windsurf/rules/memctl.md, .clinerules/memctl.md, .roo/rules/memctl.md, codex.md, .amazonq/rules/memctl.md
```

With `--all --link`:

```
Wrote 5 file(s): AGENTS.md, .cursorrules, .cursor/rules/memctl.mdc, .github/copilot-instructions.md, .windsurf/rules/memctl.md
Linked 7 file(s): CLAUDE.md -> AGENTS.md, .claude/rules/memctl.md -> AGENTS.md, GEMINI.md -> AGENTS.md, .clinerules/memctl.md -> AGENTS.md, .roo/rules/memctl.md -> AGENTS.md, codex.md -> AGENTS.md, .amazonq/rules/memctl.md -> AGENTS.md
```

### --link

Files that use the plain `agents_md` format (`CLAUDE.md`, `GEMINI.md`, `.claude/rules/memctl.md`, `.clinerules/memctl.md`, `.roo/rules/memctl.md`, `codex.md`, `.amazonq/rules/memctl.md`) have content identical to `AGENTS.md`. With `--link`, these become symlinks instead of separate copies, avoiding content drift.

Files that need tool-native YAML frontmatter (`.windsurf/rules/memctl.md`, `.cursor/rules/memctl.mdc`, `.github/copilot-instructions.md`) and `.cursorrules` (different format) are always written as real files.

### Difference from export

`export` prints to stdout so you can pipe or redirect it. `generate` writes files to disk in a single step. Use `export` when you need to pipe into another tool or customize the output path. Use `generate` when you want the standard files written with no extra flags.

## export

Export memories to stdout in various formats.

```bash
npx memctl export [format]
```

| Format        | Description                |
| ------------- | -------------------------- |
| `agents_md`   | AGENTS.md format (default) |
| `cursorrules` | .cursorrules format        |
| `json`        | Raw JSON                   |

### Examples

```bash
# Export as AGENTS.md
npx memctl export agents_md > AGENTS.md

# Export as .cursorrules
npx memctl export cursorrules > .cursorrules

# Export as JSON for scripting
npx memctl export json > backup.json
```

### Use with Aider

```bash
npx memctl export agents_md > AGENTS.md
aider --read AGENTS.md
```

## import

Import memories from a file. Headings become separate memory entries.

```bash
npx memctl import <file>
```

### How it works

1. Reads the file
2. Splits by markdown headings (`#`, `##`, `###`)
3. Each section becomes a memory with key `agent/context/imported/<slug>`
4. Metadata includes the source filename and original heading

### Examples

```bash
# Import an AGENTS.md
npx memctl import AGENTS.md

# Import a .cursorrules file
npx memctl import .cursorrules

# Import Copilot instructions
npx memctl import .github/copilot-instructions.md
```

### Output

```
Imported 8 sections from AGENTS.md
```

### MCP tool equivalent

The `import_export` MCP tool provides the same functionality for agents:

```
Tool: import_export
Action: agents_md_import | cursorrules_import | export_agents_md | export_memories
```

Use `dryRun: true` to preview what would be imported.
