Sync agent memory and project progress across machines and agents

People mean three different things when they say they want to sync agent memory:

1. The same instructions everywhere. The build command, the coding standard, the "do not touch this folder" rule.
2. The same memory store everywhere. The decisions, the failed attempts, the note the next agent should read.
3. The same work state everywhere. What is finished, what is open, what the next session should do first.

Git solves the first. A shared server solves the second. A handoff solves the third. Mixing them up produces either a stale copy or two agents writing over each other.

Checked against each tool's documentation on 26–27 October 2026.

What syncs by itself, and what does not#

Auto memory is Claude Code's own notes about a project, written by the model as it works; it is not the same as CLAUDE.md, which you write. CLAUDE.md is Claude Code's instruction file, and AGENTS.md is Codex's.

The pattern is simple. A file in the repository is shared. A directory under your home is not. A hosted or self-hosted server is shared, if every client points at it.

Claude Code: repository instructions yes, auto memory no#

Claude Code's memory docs separate the two mechanisms:

• A project CLAUDE.md or .claude/CLAUDE.md is shared through source control. So is .claude/rules/.
• ~/.claude/CLAUDE.md is yours on every project on that machine. It is not in the repository.
• CLAUDE.local.md is yours in one project, normally gitignored.
• A managed policy file covers every user the policy reaches.

Auto memory is different. It is on by default in local sessions, stored under ~/.claude/projects/<project>/memory/, and keyed to the project: the directory is derived from the git repository, so a different repository on the same machine gets a different store. A worktree is a second checkout of the same repository; all worktrees and subdirectories of one repository on that machine share one directory. The docs say auto memory is machine-local and is not shared across machines or cloud environments.

There is no documented merge or sync command for auto memory. autoMemoryDirectory moves the store, but it is a path setting, not a sync feature. If you point two machines at the same network folder, you have created a shared directory with no conflict handling. The first 200 lines or 25KB of MEMORY.md load at session start; a concurrent writer can replace a line the other machine needed.

The practical split:

• Put standing rules, commands and architecture in the project CLAUDE.md.
• Put decisions, failed attempts and open items in a shared note store, or in a handoff file the next session reads. A handoff is a short note that says where the work stands, what was tried, and what comes next.
• Treat auto memory as a convenience on one machine. If it is lost, the repository and the shared store still carry the work.

To see what is loaded, run /context and check Memory files. To browse auto memory, run /memory and open the folder.

Codex: AGENTS.md yes, memories no#

Codex reads AGENTS.md before work. The AGENTS.md guide describes a global file in $CODEX_HOME (default ~/.codex) and a project chain from the repository root down to the working directory. The project files are committed and shared. The global file is yours on that machine.

CODEX_HOME changes the home directory Codex uses. That is useful for a work profile and a personal profile, because each gets its own global AGENTS.md, config and state. It is not a sync mechanism between two machines; it is a separate profile on each machine.

Codex memories are a separate local store. The memories page says they are off by default, stored under the Codex home (by default ~/.codex/memories/), and generated from eligible prior chats. It describes per-chat controls, not a per-repository scope and not a sync feature. It also says to treat the files as generated state and not to rely on editing them by hand as the primary control surface. Moving that directory to another machine is a file copy, not a supported merge.

There is no documented way to share one Codex memory store between two machines. CODEX_HOME can point two machines at a folder you sync, but the docs describe the home as local state, and the files are generated in the background; two machines writing one store is not a merge. The safe shape is one home per machine, with the shared facts in the repository or in a store built for sharing. Imported Claude Code project memories land in the local store too, so they do not travel to the second machine either.

The durable part is AGENTS.md. If a fact must survive a new laptop, put it there or in the shared store.

Gemini CLI: the repository file travels, the private index does not#

Run gemini --version first; this section describes v0.65.0 (20 October 2026). Gemini CLI's shared part is GEMINI.md in the repository. It loads on every machine that clones the repo, and an edit is an ordinary commit. The global ~/.gemini/GEMINI.md is the opposite: one machine, and every project on it. It does not travel, and a client rule left there follows you into every repository on that machine.

The private per-project store is under ~/.gemini/tmp/<project>/memory/. In this version <project> is a readable identifier derived from the folder name and recorded in ~/.gemini/projects.json; the same repository cloned into two folders gets two identifiers and two private stores. The store is not in the repository, and the docs describe no sync or merge command. Copying the folder to another machine is a file copy: the identifier has to match, and two machines writing one folder have no conflict handling. Treat it as a cache for this machine, not the shared record.

Sessions are also per project, under ~/.gemini/tmp/<project>/chats/. They are transcripts, not memory, and the session docs describe local storage and retention, not a sync between machines. The Auto Memory inbox is in the same project memory folder; candidates you have not applied do not exist on the other machine.

The practical split:

• Put standing rules and shared decisions in the repository GEMINI.md.
• Put a machine-specific note in the private index or a sibling note, and expect to recreate it.
• Put task state in a handoff file in the repository, or in a shared store.
• On a new laptop, recreate ~/.gemini/GEMINI.md, join or create the shared store, and let the private memory start empty.

The local paths and the check are in what the memory command shows in Gemini CLI.

Qwen Code: the repository travels, team memory travels, auto-memory does not#

In Qwen Code, what is committed travels: QWEN.md, AGENTS.md and the opt-in .qwen/team-memory/. The global instruction file, .qwen/QWEN.local.md and the private auto-memory tiers stay on the machine. Checked against the 0.26 line at 0.26.2 on 27 October 2026.

• QWEN.md and AGENTS.md in the repository are committed and travel through git.
• ~/.qwen/QWEN.md is the global instruction file: one machine, and every project on it.
• .qwen/QWEN.local.md is yours in one checkout; keep it out of git.
• Auto-memory is machine-local. The project tier is ~/.qwen/projects/<project>/memory/, and the user tier is ~/.qwen/memories/. There is no documented sync between machines.
• Team memory is .qwen/team-memory/, opt-in and committed. It is the Qwen mechanism built for sharing.
• Sessions are transcripts under ~/.qwen/projects/<project>/chats/, not memory.

The worktree rule is the one that catches people. Qwen gives each linked git worktree its own project memory folder, so on one machine a fact learned in a worktree is not in the main checkout. That is the opposite of Claude Code's shared-per-repository auto memory. If the fact must be everywhere, put it in QWEN.md or in team memory.

QWEN_HOME moves the global .qwen directory, including settings, credentials, memory and skills. It is a profile switch for one machine, not a sync: two machines pointed at the same path still have two sets of files unless something copies them.

Team memory is the shared record. Enable memory.enableTeamMemory per project or globally; Qwen then writes durable, project-wide memories to .qwen/team-memory/, with a MEMORY.md index and one file per memory. Collaborators get them with git pull; your writes are ordinary commits. The tier is secret-scanned, but it is visible to everyone with repository access.

Optional automatic sync: memory.enableTeamMemorySync makes Qwen, at session start, rebuild the team index, fast-forward-pull collaborators' changes, commit the team directory, and push only that sync commit. Two caveats from the docs: the pull is a whole-branch fast-forward, not a path-scoped one, and a diverged branch is left untouched for that session. Enable it on branches where that is acceptable, or on a dedicated checkout.

If you want one external store instead of copies, Qwen has a bundled Mem0 path: memory.mem0 points at a Mem0-compatible service, and Qwen registers an external-context server that exposes a search tool. Search is read-only by default; writes need enableWrites: true and a confirmation. Scope is keyed to the user and repository by default, so a moved checkout changes it. The Mem0 page has the configuration.

On a new machine, run qwen --version, check /context detail for the loaded instruction files, and run git status --short.qwen/team-memory if team memory is enabled.

GitHub Copilot CLI: the memory is already on the other machine#

Copilot Memory is the exception to the pattern above. It is not a directory under your home, so there is nothing to copy, merge or back up locally. Repository facts sit with the repository on GitHub; user preferences sit with your GitHub account. Sign in on a second machine and the same facts are available, subject to the same repository access and organization policy.

That does not make it a general sync layer.

• It is per account, not per machine. A colleague does not see your preferences, and you do not see theirs. Repository facts are shared with everyone who can use Copilot Memory in that repository.
• It does not reach other agents. The docs say facts and preferences captured by one Copilot feature can be used by another Copilot feature. They do not say Claude Code or Codex can read them. For a handoff between Claude Code and Copilot CLI, use a file or a shared store.
• There is no documented CLI memory export. An organization or enterprise administrator can export user-level preferences as JSONL; the documented user controls are view and delete. Repository facts have no documented export.
• It expires. A fact or preference that goes unused for 28 days is deleted; using or validating it may reset the timer. That is not a backup policy.

The local parts are still local: the session state, user instruction files and configuration under the Copilot home. The repository AGENTS.md travels through git. If a fact must survive a new laptop, put it in the repository file; if it must survive a new agent, put it in a store that agent reads.

Prompt mode is another gap. copilot -p has memory off by default; pass --enable-memory to turn it on. A CI run with the flag on can write to the same repository store if the account has write access, so decide whether the runner should be allowed to contribute facts, not just read them.

Run copilot --version first: the /memory command arrived in 1.0.49, and the current release is 1.0.104 (27 October 2026).

OpenCode: AGENTS.md yes, sessions no#

OpenCode has no memory store to sync. The repository AGENTS.md travels through git; the global ~/.config/opencode/AGENTS.md stays on the machine. V2 reads AGENTS.md only; V1 also reads CLAUDE.md when no AGENTS.md is on the path. The session database is local. opencode session export writes a transcript as JSON in V2 (opencode export in V1), and the matching import command reads it on another machine (opencode session import in V2, opencode import in V1). That moves a conversation, not the rules or a memory store.

There is no documented automatic session sync. opencode debug paths prints the data and config directories, so you can see what is local. A second machine starts with no sessions and no global file unless you create or copy them.

The durable part is the repository file. If a fact must survive a new laptop, put it in AGENTS.md or in a shared store. Put task state in a handoff file and commit it, or carry it with the repository. If you list the handoff in instructions, V2 loads it at startup and after compaction.

Status, 27 October 2026: V2 dropped the CLAUDE.md fallback. A global ~/.claude/CLAUDE.md that V1 read is not a V2 global file; move it to ~/.config/opencode/AGENTS.md.

One server instead of many copies#

The alternative to syncing files is to stop having copies. Run one store and point every machine at it.

ai-memory#

ai-memory is built for this. One server can hold the wiki, the tree of markdown pages, and its database; every machine's hooks point at it. A hook is a script the harness runs at a session event, and here it sends captured events to the server. MCP is the protocol an agent uses to call tools on another server. The repository's .ai-memory.toml selects the workspace and project, so the same repository on two machines lands in the same scope.

The security docs cover the network side. Binding beyond loopback needs a bearer token, and the docs recommend a TLS reverse proxy, which terminates HTTPS in front of the server. A remote server also means the host and its administrator are outside your machine; that is a deliberate trade.

Backups have sharp edges. The lifecycle docs describe ai-memory backup --to, which streams a gzipped tarball from the live SQLite backup plus the wiki tree. It intentionally excludes auth-tokens/, the hook-side token, and sometimes [auth].token_pepper if the config lives outside the data directory. The pepper is a secret used to hash API keys; restoring without the original token and pepper can invalidate every aim_ API key. Keep the token and config separately, and test the restore on a scratch host.

Do not copy only wiki/. Sessions, handoffs and embeddings live in db/; a schema mismatch, where the database's table layout is older or newer than the binary expects, can refuse to start. Use the documented backup, restore and reindex path. restore expects the server to be stopped and verifies the archive before swapping it in.

Our test of ai-memory 3.2.5 did not run a backup or restore cycle. That advice comes from the docs and the issue reports, not from a restore we performed.

For several agents on one project, expect writes to supersede rather than merge. The users docs say two people editing the same page produce a version chain, not a conflict: the later write becomes latest and the earlier one stays reachable. There is no merge. Give each agent its own paths, or serialise writes to the same note.

Noteheld#

Noteheld, if you use it, is the hosted version of one store: there is no server to move and no merge between machines, and every machine with the master key sees the whole workspace; a folder key sees its folder. Export returns the current tree as markdown, and Pro adds a revision archive. A free workspace warns on day 60, becomes read-only on day 90, and is deleted on day 120, so export before then. Notes are plaintext on the server, and version 1 does not encrypt note bodies end to end.

Moving to a new laptop: a checklist#

1. Clone the repository first. Confirm CLAUDE.md or AGENTS.md is tracked, not gitignored. That is the part that travels for free.
2. Recreate the user-level files and client config. ~/.claude/CLAUDE.md, ~/.claude/rules/, the global AGENTS.md under CODEX_HOME (default ~/.codex/AGENTS.md), ~/.gemini/GEMINI.md and its settings.json, ~/.qwen/QWEN.md and ~/.qwen/settings.json, the user instruction files under the Copilot home (default ~/.copilot), and your MCP config. Keep secrets out of the dotfiles repo. Export any transcript you need with /export; do not copy ~/.claude/projects by hand.
3. Choose the memory store, then verify it. Let auto memory start empty, join the ai-memory server, or paste a hosted-store key and read one note. Codex memories start empty on the new machine; recreate the durable facts in AGENTS.md rather than copying the generated store. Gemini CLI private memory also starts empty unless you copy the project temp folder; put the durable facts in GEMINI.md. Qwen Code auto memory starts empty as well; enable team memory and pull the repository for the shared tier rather than copying ~/.qwen/projects. Copilot Memory follows the account: check /memory show and the two GitHub Memory pages rather than copying ~/.copilot. Ask the agent to name the source it used, and revoke the old machine's keys.

Several agents on one project#

The hard part is not the bytes. It is two agents believing different things at the same time.

• Give each agent a distinct path or folder. A shared store with every agent writing the same note is a conflict generator.
• Put the shared rules in the repository file. Put the shared record in the store.
• Write a handoff when work changes hands. The handoff guide covers what to put in it.
• Check the write behaviour. Some stores refuse on conflict; others replace the whole page and let the later write supersede the earlier one. Git handles repository files with its own merge rules.
• In CI, the automated build and test runner, use a key from a secret store, not a committed config, and give it the smallest scope it needs. A fresh runner usually has no interactive memory directories, so the repository file and the shared store are what CI can see.