How to share memory between Cursor and Claude Code

You prototype a change in Cursor, then move to Claude Code to finish it.

The branch moves with you. The uncommitted diff moves with you. The reasoning doesn't.

Claude can inspect what changed, but it can't see why Cursor rejected the first approach, which test still fails, or which product decision limits the fix. You spend ten minutes rebuilding the brief. Miss one detail and the second agent "fixes" something the first one already learned not to touch.

The same thing happens at a larger scale when a whole project moves from Cursor to Claude Code. The rule lived in .cursor/rules. The unfinished task lived in a Cursor chat. The MCP connection was configured only in Cursor. The architecture choice existed as a remembered correction. The code moved because it was in Git. The context didn't.

Cursor and Claude Code don't need identical memories. They need a small, vendor-neutral bridge. (This is one case of a broader problem; the AI coding agent memory guide covers why agents forget and the five layers that fix it.)

Why can't the two tools just sync memory?

Cursor has project rules and its own ways of retaining context. Claude Code reads CLAUDE.md and keeps machine-local auto memory. Each improves continuity inside its own tool. Neither is a shared database, and a teammate's memory is different again.

Mirroring every native memory creates a sync problem and a privacy problem: personal preferences, temporary observations, and abandoned ideas get mixed with rules the whole team must follow. The bridge should carry four things, and only four.

What crosses between tools	Where it lives	Why there
Stable repository instructions	AGENTS.md, imported by CLAUDE.md	Both tools read it; one copy to maintain
Current task state	A short handoff file	Lets the next agent continue without replaying chat
Live reference data	MCP servers configured in each tool	Tickets and errors change; query, don't copy
Approved team decisions	A shared decision source both can query	Survives the task, the tool, and the person

Where should shared instructions live?

In a root AGENTS.md. Cursor reads it directly, including nested ones. Claude Code doesn't read AGENTS.md by default, but its documentation recommends importing it from CLAUDE.md when a repository already uses it:

# AGENTS.md

## Commands
- Install with `pnpm install`.
- Run focused tests before the full suite.

## Boundaries
- Do not change public API fields without an accepted contract.
- Read matching records in `docs/adr/` before changing service boundaries.

## Workflow
- Keep task handoffs in `.handoffs/current.md`.
- Report exact tests run and failures.

# CLAUDE.md
@AGENTS.md

## Claude Code specifics
- Use plan mode before cross-service changes.
- Use `.claude/rules/` for path-specific guidance.

Now there's one copy of the team's rules and two thin adapters. Avoid maintaining the same paragraph by hand in three places; that's how instructions start disagreeing. More on what a neutral file can and can't carry in our AGENTS.md guide.

Sources: Cursor Rules and Claude Code CLAUDE.md

How do Cursor rules translate to Claude Code?

Only the scoped ones need translating. Cursor project rules are .mdc files with description, globs, and alwaysApply metadata. Claude Code path-scoped rules are Markdown files in .claude/rules/ with paths frontmatter.

---
description: Payment provider rules
globs: services/payments/**
alwaysApply: false
---
Never retry a capture unless the provider operation is idempotent.

becomes

---
paths:
  - "services/payments/**"
---
Never retry a capture unless the provider operation is idempotent.

Read each rule as you translate it. Old rules often conflict or describe failures that no longer exist, and migration is a chance to delete them. Keep scope too: a frontend rule shouldn't load as always-on CLAUDE.md content during a database migration.

Before you start, take an inventory so nothing is left behind in the old tool:

Cursor context	Destination
Common project instruction	AGENTS.md
Claude-specific instruction	CLAUDE.md
Path-scoped .mdc rule	.claude/rules/*.md
Legacy .cursorrules	Review, then AGENTS.md or delete
Cursor user rules (personal)	~/.claude/CLAUDE.md or CLAUDE.local.md
MCP server	Claude Code MCP config
Unfinished task in a chat	Committed handoff
Accepted decision remembered as a correction	Shared decision record or ADR

What about personal preferences?

Keep them personal. Cursor user rules often hold tone, shortcuts, or preferred tooling that shouldn't become team requirements. Claude Code separates ~/.claude/CLAUDE.md (you, every project), CLAUDE.local.md (you, this project), project CLAUDE.md (the team), and managed policy (the organization). The test for each rule: would a new teammate need this to work safely in the repository? If not, it stays personal.

The same goes for auto memory. One person's learned notes can include preferences that shouldn't govern anyone else. Promote only the stable, team-approved parts.

Do MCP servers carry over?

No. Both tools support MCP, but configuration locations and authentication flows differ. For each server you used in Cursor, write down its purpose, local command or remote URL, environment variables, auth method (OAuth or API key), the tools the project actually needs, and whether it's personal or project-scoped. Recreate it in Claude Code and verify with a harmless read.

Never put secrets in CLAUDE.md, AGENTS.md, or committed config; use environment variables, a secret store, or OAuth. And check permissions as you go: an MCP server can expose tools that change things, and moving a connection shouldn't quietly widen what the new client may do. Our comparison of MCP servers for engineering teams covers the common sources.

Sources: Cursor MCP and Claude Code MCP

What should a Cursor-to-Claude Code handoff say?

The requested outcome, branch and files changed, approaches tried and rejected, tests run with exact failures, open questions, and the next safe step. For example:

Goal: move guest checkout analytics to the server. Cursor changed checkout/events.ts and added two tests. The client-only approach was rejected because retries produced duplicate events. One test still fails when payment confirmation arrives asynchronously. Active decision: guest checkout identity is created before payment until migration M-42 ends; Priya owns exceptions. Next step: inspect the server idempotency key before changing the event order.

That's enough for Claude Code to continue. It doesn't paste 40 pages of chat or ask the model to guess which paragraph matters.

The handoff is working state, so close it when the task ends. The active decision it mentions should live beyond the task, in the shared record and tied to the checkout paths. If the migration ends or Priya changes the call, the record gets superseded without rewriting old handoffs.

What not to carry across

• Full chat histories. Exploration, wrong turns, pasted secrets, statements later corrected. More text isn't clearer authority.
• Unreviewed generated summaries. A summary can drop the exact exception that made a decision safe. Treat it as a draft and check the load-bearing constraints.
• Stale copies of live systems. A copied ticket or API doc goes wrong quietly. Link or query the source.
• Secrets and tokens. Re-authenticate through supported flows.
• Superseded decisions as if current. Keep history, but mark it superseded and link the replacement.

A layout both tools can use

repo/
  AGENTS.md                    # common instructions
  CLAUDE.md                    # imports AGENTS.md + Claude specifics
  .cursor/rules/               # Cursor-scoped rules
  .claude/rules/               # Claude-scoped rules
  docs/adr/                    # repository decisions
  .handoffs/current.md         # temporary work state

To check it, open a clean Claude Code session and ask: which command runs focused payment tests, which paths have special retry rules, what's the current migration step, why does dual write stay enabled, and which decision would this refactor conflict with? Then ask Cursor the same questions. Any difference shows context that's still stuck in one tool, or stale.

This is also the fix when Cursor loses context mid-project, and the Claude Code side of it is covered in Claude Code keeps forgetting context.

Where Lockstep fits

Lockstep holds the decision layer of that bridge. It captures possible decisions from Slack, docs, tickets, and code discussions, asks the owner to approve them, and ties the approved version to what it affects. Cursor, Claude Code, and other MCP-compatible agents query the same current decisions before they act, so switching clients doesn't change what the team has agreed.

It doesn't replace Cursor rules, CLAUDE.md, AGENTS.md, or a handoff. Those carry repository instructions and current execution state. If you already keep a decision log, compare the options and their tradeoffs; what matters is whether both agents receive the active answer before they change the code.