memento

Bi-directional memory sync for AI coding agents

Keep Claude Code, Codex CLI, Gemini CLI, Antigravity, Cursor, and Windsurf memory files aligned without choosing a single permanent source of truth.

Quick Setup | Provider Matrix | CLI | Configuration | Safety

Korean

What is memento?

memento is a Node.js CLI that synchronizes long-lived instruction and memory files used by AI coding agents.

Different agents store context in different places:

Claude Code: CLAUDE.md, ~/.claude/CLAUDE.md
Codex CLI: AGENTS.md, ~/.codex/AGENTS.md
Gemini CLI: GEMINI.md, ~/.gemini/GEMINI.md
Cursor: .cursor/rules/*.mdc
Windsurf: .windsurf/rules/*.md
Antigravity: .agent/skills/**, memory-bank/**, selected global memory paths

When you switch tools or use several agents in the same repository, those files can drift. memento reads each provider's native file format, normalizes it into a shared internal document model, resolves conflicts, writes changes back to the original provider files, and creates backups before modifying anything.

The design goal is practical local synchronization:

CLAUDE.md \
AGENTS.md  > memento sync > same project memory everywhere
GEMINI.md /

.cursor/rules/typescript.mdc \
.windsurf/rules/typescript.md  > same rule identity

memento does not run a server, does not upload memory files, and does not replace git. It is a local CLI for keeping agent context consistent on your machine and in your repository.

What's new in 0.3.0

Version 0.3.0 includes the broader assistant context portability added across the 0.2 and 0.3 line:

Skills: synchronize provider skill bundles such as Claude Code .claude/skills/* and Codex .agents/skills/*.
MCP servers: synchronize project and local MCP server definitions across supported providers.
Resource-aware commands: status, sync, diff, and watch accept --resources, --scope, --no-skills, and --no-mcp.
Cross-project import: memento import <source> brings memory from another project into the current project.
Safer automation: release CI skips already published npm versions, and CLI help/version/install output includes the memento ANSI banner.

Quick Setup

Prerequisites

Node.js 18 or newer
npm
At least one supported agent memory file in the project, or an explicit provider list passed to memento init

1. Install the CLI

npm i -g @dantelabs/memento

Verify the install:

memento --version
memento --help

2. Initialize a project

Run this from the repository root:

memento init

init creates .memento/config.toml and adds these runtime files to .gitignore:

.memento/cache.json
.memento/backup/

If memento cannot auto-detect a provider, force the providers you want:

memento init --providers claude-code,codex,gemini-cli,cursor,windsurf

Valid provider ids are:

claude-code, codex, gemini-cli, antigravity, cursor, windsurf

3. Inspect status

memento status

Typical output shows which providers are active and how memory files are grouped:

memento status

Providers
ok claude-code (active)
ok codex (active)
ok gemini-cli (active)

project
ok synced  agents-md:main  claude-code, codex, gemini-cli

4. Preview or run a sync

Preview first:

memento sync --dry-run

Then write changes:

memento sync

Sync skills and MCP definitions too:

memento sync --resources memory,skills,mcp --scope project

For an interactive conflict prompt:

memento sync --strategy prompt

For CI or scripts that should fail on unresolved conflicts:

memento sync --strategy fail

5. Keep files synchronized while you work

memento watch

watch uses last-write-wins conflict handling and is designed for local development sessions where provider memory files may change as you switch tools.

Core Concepts

Memory tiers

memento treats memory files as one of three tiers:

Tier	Meaning	Typical location	Git behavior
`project`	Shared repository memory	`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/*.mdc`	Usually committed
`project-local`	Local project memory for one machine	`CLAUDE.local.md`, `AGENTS.local.md`, `*.local.mdc`	Usually ignored
`global`	User-level memory outside a project	`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`	Not committed

By default, project commands sync project and project-local tiers. Use --include-global to include global files, or use memento global ... to operate only on global memory.

Memory identities

memento does not simply copy every file to every other file. It groups files by semantic identity.

File	Identity
`CLAUDE.md`	`agents-md:main`
`AGENTS.md`	`agents-md:main`
`GEMINI.md`	`agents-md:main`
`.cursor/rules/typescript.mdc`	`rule:typescript`
`.windsurf/rules/typescript.md`	`rule:typescript`
`.agent/skills/git-flow/SKILL.md`	`skill:git-flow`
`memory-bank/core/state.md`	`memory-bank:core/state`

Files with the same tier and identity are compared and synchronized as a group, for example project/agents-md:main.

No permanent source of truth

memento is bi-directional. The winning version for a group is chosen during each sync:

if all files are identical, nothing is written
if one file changed since the last sync, that change is propagated
if multiple files changed differently, the configured conflict strategy decides what happens

This lets you edit memory in whichever agent you are using at the moment.

Resource sync

In addition to markdown memory files, memento can synchronize structured assistant resources.

Resource	What it represents	Examples
`memory`	Long-lived instruction files and rules	`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, Cursor/Windsurf rules
`skill`	Skill directories with a `SKILL.md` entry file and related files	`.claude/skills/review`, `.agents/skills/review`
`mcp`	MCP server definitions in provider config files	`.mcp.json`, `.codex/config.toml`, `.codeium/mcp_config.json`

Resource commands use scopes:

Scope	Meaning
`local`	Include the provider's local/default resource locations for the current machine
`project`	Use project-level resource files inside the current repository
`cross-cli`	Use shared or global resource locations where supported

Default sync, status, diff, and watch resource selection is memory,skill,mcp. memento import is more conservative and imports memory only unless --resources is provided.

Provider Matrix

Provider	Provider id	`project`	`project-local`	`global`
Claude Code	`claude-code`	`CLAUDE.md`, `AGENTS.md`	`CLAUDE.local.md`	`~/.claude/CLAUDE.md`
Codex CLI	`codex`	`AGENTS.md`	`AGENTS.local.md`	`~/.codex/AGENTS.md`
Gemini CLI	`gemini-cli`	`GEMINI.md`	`GEMINI.local.md`	`~/.gemini/GEMINI.md`
Antigravity	`antigravity`	`.agent/skills/`, `memory-bank/`	`memory-bank/**.local.md`	`~/.gemini/antigravity/skills/**`, `~/.gemini/GEMINI.md`, `~/.antigravity/`
Cursor	`cursor`	`.cursor/rules/*.mdc`, legacy `.cursorrules`	`.cursor/rules/*.local.mdc`	`~/.cursor/rules/*.mdc`
Windsurf	`windsurf`	`.windsurf/rules/*.md`, legacy `.windsurfrules`	`.windsurf/rules/*.local.md`	`~/.windsurf/rules/*.md`

Gemini CLI and Antigravity can both reference ~/.gemini/GEMINI.md; memento deduplicates that shared global path.

0.2.0 resource coverage

Provider	Skills	MCP
Claude Code	`.claude/skills/`, `~/.claude/skills/`	`.mcp.json`
Codex CLI	`.agents/skills/`, `~/.agents/skills/`, read-only `/etc/codex/skills`	`.codex/config.toml`, `~/.codex/config.toml`
Windsurf	`.windsurf/skills/`, `.agents/skills/`	`.codeium/mcp_config.json`
Cursor	Memory/rules only in this release	Not enabled in this release
Gemini CLI	Memory only in this release	Not enabled in this release
Antigravity	Existing memory-bank and skill-like memory paths	Not enabled in this release

MCP values are copied as provider configuration text. Dry-run and diff output redact secret-like fields by default.

Common Workflows

Start with Claude Code and Codex only

memento init --providers claude-code,codex
memento status
memento sync --strategy prompt

Sync only one provider

memento sync --provider codex

This is useful when you want to write the resolved memory back to one provider after changing another provider's file.

Sync only one tier

memento sync --tier project
memento sync --tier project-local

Include global memory from a project sync

memento sync --include-global

Sync skills and MCP servers

Preview resource writes first:

memento sync --resources memory,skills,mcp --scope project --dry-run

Then run the sync:

memento sync --resources memory,skills,mcp --scope project

To skip one resource type:

memento sync --resources memory,skills --no-mcp
memento status --resources mcp --scope project

Import memory from another project

From the target project root:

memento import ../old-project --dry-run
memento import ../old-project --to codex --strategy replace

Import skills explicitly:

memento import ../old-project --resources memory,skills --scope project

Import MCP definitions only after reviewing the dry-run output:

memento import ../old-project --resources mcp --scope project --dry-run
memento import ../old-project --resources mcp --scope project --strategy prompt

Manage only global memory

memento global init --providers claude-code,codex,gemini-cli
memento global status
memento global sync --strategy prompt
memento global watch

Global commands use ~/.memento/config.toml and operate on global provider paths only.

Use memento in CI

Use --strategy fail to make the command fail when provider memory files disagree:

memento sync --strategy fail --dry-run

Exit code 2 means unresolved conflicts were found.

Restore a previous version

memento restore --list
memento restore --at 2026-04-30T07-37-00_342Z

Restore a single group:

memento restore --at 2026-04-30T07-37-00_342Z --group project/agents-md:main

CLI

Global options

Option	Description
`-v, --version`	Print the installed memento version
`--debug`	Print debug output and stack traces
`--json`	Emit JSON lines where supported
`--quiet`	Suppress non-error output

Commands

Command	Description
`memento init`	Create `.memento/config.toml` for the current project
`memento status`	Show provider detection, tiers, and sync state
`memento sync`	Synchronize memory files across active providers
`memento watch`	Watch memory files and synchronize changes continuously
`memento diff`	Show differences between grouped memory documents
`memento import`	Import assistant memory from another project into the current project
`memento restore`	List, restore, or prune automatic backups
`memento global`	Run `init`, `status`, `sync`, `watch`, `diff`, or `restore` against global memory
`memento update`	Update the global memento CLI install
`memento install-skill`	Install the bundled Claude Code skill manually
`memento uninstall-skill`	Remove the installed Claude Code skill

Run memento <command> --help for the exact options supported by your installed version.

`memento init`

memento init [--force] [--providers <list>]

Option	Description
`--force`	Overwrite an existing `.memento/config.toml`
`--providers <list>`	Comma-separated provider ids to enable

init probes all supported providers, creates a config, and updates .gitignore for runtime cache and backup files.

`memento status`

memento status [--tier <tier>] [--resources <list>] [--scope <scope>] [--include-global] [--json]

Option	Description
`--tier <tier>`	Filter to `project`, `project-local`, or `global`
`--resources <list>`	Filter resource kinds: `memory`, `skills`, `mcp`
`--scope <scope>`	Resource scope: `local`, `project`, or `cross-cli`
`--no-mcp`	Exclude MCP resources
`--no-skills`	Exclude skill resources
`--include-global`	Include global files in project status
`--json`	Emit JSON output

`memento sync`

memento sync [--dry-run] [--strategy <strategy>] [--tier <tier>] [--provider <id>] [--resources <list>] [--scope <scope>] [--yes] [--include-global]

Option	Description
`--dry-run`	Preview the sync without writing files
`--strategy <strategy>`	Conflict strategy: `lww`, `prompt`, or `fail`
`--tier <tier>`	Filter to one memory tier
`--provider <id>`	Filter to one provider id
`--resources <list>`	Resource kinds to sync: `memory`, `skills`, `mcp`
`--scope <scope>`	Resource scope for skills and MCP
`--no-mcp`	Exclude MCP resources
`--no-skills`	Exclude skill resources
`--allow-project-secrets`	Allow project MCP secret writes when policy permits it
`--yes`	Accept non-interactive defaults; currently uses `lww`
`--include-global`	Include global memory in a project sync

`memento watch`

memento watch [--debounce <ms>] [--tier <tier>] [--provider <id>] [--resources <list>] [--scope <scope>] [--include-global]

watch monitors provider memory files and runs sync after changes settle.

Option	Description
`--debounce <ms>`	Debounce interval in milliseconds; default is `500`
`--tier <tier>`	Watch only one tier
`--provider <id>`	Watch only one provider
`--resources <list>`	Resource kinds to watch and sync
`--scope <scope>`	Resource scope for skills and MCP
`--no-mcp`	Exclude MCP resources
`--no-skills`	Exclude skill resources
`--include-global`	Include global memory in project watch mode

`memento diff`

memento diff [--group <key>] [--all] [--unified] [--tier <tier>] [--provider <id>] [--resources <list>] [--scope <scope>] [--include-global] [--json]

Option	Description
`--group <key>`	Show one conflict group, such as `project/agents-md:main`
`--all`	Show all diff groups
`--unified`	Print unified diff output
`--tier <tier>`	Filter to one memory tier
`--provider <id>`	Filter to one provider id
`--resources <list>`	Resource kinds to diff
`--scope <scope>`	Resource scope for skills and MCP
`--no-mcp`	Exclude MCP resources
`--no-skills`	Exclude skill resources
`--show-secrets`	Show raw secret-like values in diff output after explicit use
`--include-global`	Include global memory in project diff mode
`--json`	Emit JSON output

`memento import`

memento import <source> [--dry-run] [--from <providers>] [--to <providers>] [--strategy <strategy>] [--resources <list>]

import reads assistant memory from another project directory and writes it into the current initialized project. By default it imports memory only. Add --resources skills,mcp when you explicitly want skills or MCP server definitions copied too.

Option	Description
`--dry-run`	Preview the import without writing files
`--from <providers>`	Comma-separated source provider ids
`--to <providers>`	Comma-separated target provider ids enabled in the current config
`--strategy <strategy>`	Existing-target strategy: `prompt`, `skip`, `replace`, or `append`
`--resources <list>`	Resource kinds to import: `memory`, `skills`, `mcp`
`--scope <scope>`	Resource scope for skills and MCP: `local`, `project`, or `cross-cli`
`--tier <tier>`	Import one memory tier
`--yes`	Accept non-interactive defaults; currently replaces existing target content

`memento restore`

memento restore [--list] [--at <timestamp>] [--group <key>] [--prune <count>]

Option	Description
`--list`	List available restore points
`--at <timestamp>`	Restore from a timestamp listed by `--list`
`--group <key>`	Restore one memory group
`--prune <count>`	Keep the newest N backups and remove older backups

`memento global`

memento global init
memento global status
memento global sync
memento global watch
memento global diff
memento global restore

The global subcommands mirror the project commands but use the global memento context at ~/.memento.

`memento update`

memento update
memento update --dry-run

update runs the npm global install command for the latest published release and shows the same memento ANSI header used by help and version output.

Exit codes

Code	Meaning
`0`	Success
`1`	Generic error
`2`	Unresolved conflict, usually from `--strategy fail`
`3`	Not initialized; run `memento init`
`4`	No active providers

Configuration

Project configuration lives at:

.memento/config.toml

Global configuration lives at:

~/.memento/config.toml

Example:

[providers.claude-code]
enabled = true
auto = true
include_orphan = false

[providers.codex]
enabled = true
auto = true
include_orphan = false

[providers.gemini-cli]
enabled = true
auto = true
include_orphan = false

[providers.cursor]
enabled = true
auto = true
include_orphan = false

[providers.windsurf]
enabled = true
auto = true
include_orphan = false

[providers.antigravity]
enabled = false
auto = true
include_orphan = false

[resources.memory]
enabled = true

[resources.skill]
enabled = true
include = []
exclude = []

[resources.mcp]
enabled = true
redact_output = true
project_secret_policy = "wizard"

[mapping]
"rule:typescript" = [
  "cursor:.cursor/rules/typescript.mdc",
  "windsurf:.windsurf/rules/typescript.md",
]

[exclude]
paths = [
  "**/private/**",
  "**/generated/**",
]

Provider settings

Field	Meaning
`enabled`	Whether the provider participates in sync
`auto`	Whether automatic detection should be respected
`include_orphan`	Include memory files even when the provider app or CLI is not installed

Resource settings

Field	Meaning
`resources.memory.enabled`	Enable markdown memory synchronization
`resources.skill.enabled`	Enable skill bundle synchronization
`resources.skill.include`	Optional include patterns for skill resources
`resources.skill.exclude`	Optional exclude patterns for skill resources
`resources.mcp.enabled`	Enable MCP server definition synchronization
`resources.mcp.redact_output`	Redact secret-like MCP values in command output
`resources.mcp.project_secret_policy`	Policy for project-level MCP secrets; default is `wizard`

Mapping overrides

Use [mapping] when two files should be treated as the same identity but their default filenames would not match.

[mapping]
"rule:backend-style" = [
  "cursor:.cursor/rules/backend.mdc",
  "windsurf:.windsurf/rules/api-style.md",
]

Excludes

Use excludes for private, generated, large, or high-churn files.

[exclude]
paths = [
  "**/secrets/**",
  "**/scratch/**",
]

Conflict Resolution

memento compares normalized document bodies and the previous sync cache.

Strategy	Behavior	Best for
`lww`	Last write wins; the newest modified file becomes the winner	automation, watch mode, quick local sync
`prompt`	Ask which version should win, show diff, or edit manually	interactive terminal sessions
`fail`	Exit with code `2` without writing conflicting groups	CI, pre-commit checks, strict workflows

Examples:

memento sync --strategy lww
memento sync --strategy prompt
memento sync --strategy fail --dry-run

memento watch always uses lww, because a long-running file watcher cannot safely stop for interactive prompts.

Backup & Restore

Before writing provider memory files, memento saves the previous contents under:

.memento/backup/<timestamp>/

Backups are local runtime artifacts and should not be committed.

Common commands:

memento restore --list
memento restore --at <timestamp>
memento restore --at <timestamp> --group project/agents-md:main
memento restore --prune 10

Use restore when a sync chose the wrong winner, when you want to inspect older memory contents, or when a provider file was manually damaged after a sync.

Claude Code Skill

The npm package includes a Claude Code skill for operating memento from inside Claude Code.

During npm i -g @dantelabs/memento, the package postinstall step attempts to copy the skill into Claude's skills directory when that directory is available. If auto-install is skipped or you want to reinstall manually:

memento install-skill

Remove it with:

memento uninstall-skill

Skip automatic skill installation during npm install:

MEMENTO_SKIP_SKILL_INSTALL=1 npm i -g @dantelabs/memento

Safety Model

memento is intentionally conservative around writes.

Local-only: files are read and written on your machine; memento does not upload memory content.
Explicit config: project sync requires .memento/config.toml.
Dry-run support: use memento sync --dry-run before writing.
Resource dry-run support: preview skills and MCP changes with --resources ... --dry-run.
Automatic backups: every write has a restore point.
Conflict strategies: choose prompt for manual control or fail for CI.
MCP secret awareness: secret-like fields are redacted in output by default.
Shared global dedupe: shared Gemini/Antigravity global paths are handled once.
Watch ignore rules: .memento cache and backup writes do not retrigger sync loops.

Recommended team practice:

Commit shared project memory files when they are meant for the whole repository.
Keep project-local and .memento/cache.json out of git.
Review memento diff --all --unified before the first sync in an existing repository.
Use memento sync --strategy fail --dry-run in CI if memory drift should block merges.

Developer & Support

memento is built and maintained by Dante Labs as part of a broader toolkit for practical AI-agent workflows.

Link	Description
GitHub	dandacompany/memento
npm	@dantelabs/memento
YouTube	@dante-labs
Email	dante@dante-labs.com
Support	Buy Me a Coffee

If memento saves you time, helps keep your agent context clean, or becomes part of your daily workflow, sponsorship is appreciated and helps fund continued maintenance, new provider adapters, and real-world compatibility testing.

Issues, bug reports, and provider mapping requests are welcome on GitHub.

License

Dante Labs · YouTube @dante-labs · Email dante@dante-labs.com · Support Buy Me a Coffee

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
.github/workflows		.github/workflows
.memento		.memento
bin		bin
skill		skill
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation