files

The files command syncs your AI tool config directories across machines. This includes instruction files, commands, skills, rules, tasks, and essential configs — everything you need to recreate your AI coding environment.

Why sync files?

When you switch between machines or set up a new environment, you lose all your carefully curated:

Instruction files (.agents/instructions.md, CLAUDE.md, GEMINI.md)
Custom commands (slash commands for Claude Code, etc.)
Skills (reusable agent capabilities)
Rules (tool-specific coding rules)
Tasks (project task definitions)
MCP configs (mcp.json)

The files command stores these in your local database (and optionally syncs to cloud), so they're available everywhere.

What gets synced

The command intelligently syncs only meaningful configuration files, not cache or temp data.

Per-tool sync targets

Tool	Files Synced
`.agents/`	`instructions.md`, `settings.json`, `commands/.md`, `tasks/.md`, `skills/*/`
`.claude/`	`CLAUDE.md`, `settings.json`, `commands/.md`, `rules/.md`, `hooks/`, `tasks/.md`, `skills/*/`
`.cursor/`	`mcp.json`, `rules.md`, `rules/.md`, `skills//`
`.codex/`	`config.toml`, `AGENTS.md`, `instructions.md`, `rules/`, `tasks/.md`, `skills/*/`
`.kiro/`	`settings/mcp.json`, `skills/*/`
`.kilo/`	`mcp.json`, `skills/*/`
`.trae/`	`mcp.json`, `skills/*/`
`.antigravity/`	`mcp.json`, `mcp_config.json`, `skills/*/`
`.goose/`	`rules/.md`, `skills//`
`.windsurf/`	`rules.md`, `cascade.json`, `rules/.md`, `skills//`
`.cline/`	`rules.md`, `CLINE.md`, `cline_rules.md`, `rules/.md`, `skills//`
`.github/copilot/`	`instructions.md`
`.gemini/`	`GEMINI.md`, `settings.json`, `skills/*/`
`.roo/`	`config.json`, `rules.md`, `rules/.md`, `skills//`
`.amp/`	`AGENTS.md`, `rules.md`, `rules/.md`, `skills//`
`opencode.json`	`opencode.json`
`.opencode/`	`instructions.md`, `skills/*/`
`.factory/`	`config.json`, `instructions.md`, `droids/.md`, `tasks/.md`, `skills/*/`
`~/.openclaw/workspace/`	`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `BOOT.md`, `MEMORY.md`, `memory/.md`, `skills//`

Optional app config JSON (`--include-config`)

Use --include-config when you also want to port app-level config JSON files:

Path	Notes
`~/.config/opencode/opencode.json`	OpenCode global config
`~/.openclaw/openclaw.json`	OpenClaw runtime config

Sensitive fields (for example keys/tokens/secrets) are automatically redacted to [REDACTED] before storing in synced file records. Keep real secret values in Supabase Vault or environment variables.

File types included

.md, .txt — Instructions, rules, documentation
.json, .yaml, .yml, .toml — Configs
.sh — Hook scripts
.rules, .mdc — Tool-specific rule formats

What's excluded

The command automatically excludes:

Session data, history, cache directories
Telemetry, debug logs, lock files
UUID-named directories (Claude session folders)
Temp files, .DS_Store, node_modules

Commands

List synced files

memories files list
# or
memories files ls

Filter by scope:

memories files list --scope global
memories files list --scope github.com/your-org/your-project

Import files (ingest)

Import global config files from your home directory:

memories files ingest

Preview what would be imported:

memories files ingest --dry-run

Example output:

Would import 317 files:

  G .agents/instructions.md [Agents]
  G .agents/commands/review.md [Agents]
  G .agents/commands/deploy.md [Agents]
  G .agents/skills/frontend-design/SKILL.md [Agents]
  G .claude/CLAUDE.md [Claude]
  G .claude/commands/review.md [Claude]
  G .claude/hooks/session-context.sh [Claude]
  G .cursor/mcp.json [Cursor]
  ...

Import project-specific configs (from current directory):

memories files ingest --project

Import both global and project configs:

memories files ingest --global --project

Include app config JSON too:

memories files ingest --global --include-config

Apply files to disk

Restore synced files to your local machine:

# Apply global files to home directory
memories files apply --global

# Apply project files to current directory
memories files apply --project

# Preview without writing
memories files apply --global --dry-run

# Force overwrite existing files
memories files apply --global --force

Include app config JSON too:

memories files apply --global --include-config --force

View file content

memories files show .agents/instructions.md

Output:

# .agents/instructions.md
# Scope: global | Source: Agents
# Updated: 2026-02-04T14:30:00.000Z
──────────────────────────────────────────────────
# instructions.md

You are an AI coding assistant...

Remove a file from sync

memories files forget .agents/skills/old-skill/SKILL.md

Workflows

Initial setup (on your main machine)

# Import all your existing configs
memories files ingest --dry-run   # preview first
memories files ingest             # then import

# Enable cloud sync (Pro feature)
memories login
memories sync enable
memories sync push

New machine setup

# Install CLI
pnpm add -g @memories.sh/cli

# Login to sync
memories login
memories sync enable

# Apply all your configs
memories files apply --global --force
memories files apply --project --force

# Verify
memories files list

Keep configs in sync

After making changes to your config files:

# Re-import changed files
memories files ingest

# Push to cloud (if syncing)
memories sync push

Project-specific workflow

When working on a project with shared task definitions:

cd your-project

# Import project configs (including tasks)
memories files ingest --project

# Later, on another machine
memories files apply --project

Global vs Project scope

Global files (~/.agents/, ~/.claude/, etc.): Your personal configs that apply everywhere. These are stored with scope: "global".
Project files (./.agents/, ./.claude/ in a repo): Project-specific configs shared with your team or tied to a specific codebase. These are stored with the project's git remote URL as the scope.

Tips

Start with dry-run: Always use --dry-run first to see what will be imported
Check file counts: The ingest command shows how many files will be imported — if you see thousands, something might be wrong
Use with cloud sync: Files sync works best when combined with memories sync for multi-device access
Use --include-config intentionally: App-level JSON config is opt-in and may be machine-specific
Keep secrets out of synced stores: Real secret values belong in Supabase Vault or env vars

On this page