Cursor memory: rules, AGENTS.md and what Cursor remembers

Does Cursor have memory between sessions?

Cursor has persistent instructions, not autonomous long-term memory. The official Rules documentation states that large language models do not retain memory between completions; Rules provide persistent, reusable context at the prompt level. Project Rules, User Rules, Team Rules and AGENTS.md are loaded or applied according to their configuration.

That distinction matters. A rule can tell Cursor how the repository works, but it is not a searchable database of every decision, customer fact or prior incident. A durable memory layer stores selected records outside the model, retrieves the relevant subset for the current task and supports correction and deletion.

What are Cursor Rules?

Rules are system-level instructions for the coding agent. Cursor documents Project Rules in `.cursor/rules`, User Rules for the local Cursor environment, Team Rules managed from the dashboard and AGENTS.md as a simpler Markdown alternative. Project Rules are version-controlled and scoped to the codebase.

Use rules for facts that should be reviewable in source control: build commands, architecture boundaries, coding conventions, approved test procedures and paths that require extra review. A rule should be short, specific and owned like code.

Should you use AGENTS.md or .cursor/rules?

Use AGENTS.md when the same readable instructions must work across Cursor, Codex and other coding agents. Use `.cursor/rules` when you need Cursor-specific metadata such as glob activation, always-apply behavior or richer project-rule organization.

The official documentation describes AGENTS.md as a plain Markdown alternative without the metadata and configuration of Project Rules. That simplicity improves portability, but it also means you must keep the file concise and reconcile overlapping rules from other tools.

---
description: API response changes require contract tests
globs:
  - "src/app/api/**/*.ts"
alwaysApply: false
---

Run the API contract tests before changing an existing response schema.
Keep backward-compatible fields unless the change is explicitly versioned.

What are the limits of Cursor’s built-in memory?

Rules are context, not enforced configuration. A model can still miss or misapply an instruction, and unrelated rules can consume context without improving the current task. The application or coding harness should use permissions, hooks and tests when behavior must be guaranteed.

Rules also do not provide a general memory API for extracted facts, source history, relevance search or deletion across products. They are a strong instruction layer for a repository, not a replacement for durable user, project or multi-agent memory.

• Prompt-level rules can be ignored or overwhelmed by conflicting context.
• Repository files do not capture a mutable user or customer profile.
• Rules do not provide semantic retrieval across past incidents.
• Duplicated AGENTS.md and Project Rules can drift apart.
• Local User Rules do not automatically follow every teammate.
• Secrets should never be placed in rules files.

How do you add persistent memory to Cursor?

Separate stable instructions from changing memory. Keep repository policy in Rules or AGENTS.md. Store accepted decisions, project constraints and durable user preferences in an authenticated memory service, then retrieve a small context block before the coding task begins.

Cursor can connect to MCP servers, but the memory boundary must be explicit. A remote server should resolve the user and project from authentication, not from a model-supplied tenant ID. If the integration uses an API adapter instead of MCP, apply the same scopes and token budget.

What memory should be loaded for a Cursor task?

Retrieve by the current task plus authenticated user and project scope. A migration task needs the accepted database decision and prior failed migrations; a copy-only task usually needs neither. Query without that context and the memory layer becomes another noisy prompt.

Keep current code and account permissions authoritative. A remembered architecture decision cannot override what the repository contains now, and a remembered permission cannot grant access. When the two disagree, inspect the source system and create a correction rather than silently choosing the older fact.

• Use a strict item and token limit.
• Preserve source, timestamp and validity.
• Exclude superseded decisions from default retrieval.
• Treat memory as data, not as system instructions.
• Refresh repository facts through the normal code-reading tools.

How should Cursor memory be corrected and deleted?

Treat checked-in Rules as code and local User Rules as user data. Review rule changes in pull requests, remove stale instructions during refactors and confirm that AGENTS.md and Cursor-specific files do not contradict each other.

For external memory, deletion must cover the source event, extracted decision, summaries and any other agents connected to the same scope. Editing `.cursor/rules` does not erase a remote memory record. Test deletion separately for files, MCP/API memory and caches.

How do you test Cursor memory?

Start a fresh Cursor session and complete a task that depends on one repository rule. Then alter that rule and verify the next session follows the new instruction. Repeat with a path-scoped rule, a second worktree and a conflicting AGENTS.md.

For external memory, record the task and retrieve a known decision, not the whole history. Test a changed decision, a second repository, a second user, the wrong tenant and a deletion request. The test should show which memory was retrieved and why.

What mistakes make Cursor memory unreliable?

The most common failure is treating a remembered statement as current repository truth. Code, dependencies and deployment commands change, so the agent must verify them through the repository before editing. A second failure is copying every instruction into both AGENTS.md and Project Rules, which creates several competing sources for the same policy.

External memory can also become noisy when every chat message is written remotely. Store reviewed decisions and recurring constraints, not the full conversation. Keep a strict token budget so a large memory library does not crowd out the files the agent must inspect now.

• Do not let stale memory override the current codebase.
• Keep one clear source for each repository rule.
• Do not store secrets or credentials in rule files.
• Retrieve task-specific decisions, not a generic profile.
• Test the same rule in a new session and a second worktree.

What is the recommended Cursor memory architecture?

Use `.cursor/rules`, User Rules, Team Rules or AGENTS.md for explicit instruction context. Add a scoped external memory service for changing decisions and history that must survive across tools. Keep behavior that must be enforced in permissions, hooks and tests rather than in remembered text.