Cursor Agent Memory: A Practical Setup for Persistent Project Context

Cursor agent memory should preserve the decisions that are expensive to rediscover: why a subsystem uses an unusual boundary, which migration must precede a deploy, and what a flaky test actually means. A longer chat is not durable memory. Once the context is compacted, a new thread starts, or a teammate uses another agent, critical knowledge can disappear.

For durable engineering context, your agent's memory should often be files you can read, edit, diff, and self-host—not only embeddings locked behind a retrieval API. Meshnote gives Cursor and other MCP clients a shared markdown wiki that agents maintain and humans can inspect.

What the leading Cursor memory guides cover

The current top results establish the problem but leave an operational gap. A Cursor Community post introduces Recallium as a self-hosted MCP service with semantic and keyword search, cross-tool sharing, team knowledge, and Docker deployment. It reports 0.31-second average search and 88% first-result accuracy on its own workload; those are vendor-reported figures, not an independent benchmark. The discussion usefully distinguishes simple repository files from an MCP service at larger scale.

A DEV guide connects Cursor to CORE, a temporal knowledge graph. It supplies a long always-on rule telling Cursor to search before every response and store every interaction afterward. That demonstrates lifecycle policy, but saving everything can turn a memory system into a transcript dump: noisy facts compete with durable decisions, and stale claims are difficult to govern.

A 2026 agentmemory overview covers installation, support for Cursor and several coding agents, local service operation, common use cases, and warnings about stale facts and secrets. It correctly says memory cannot replace tests. None of these three provides a minimal remote configuration, a two-session acceptance test, and a reviewable write contract together. This guide does.

First choose the right memory layer

Cursor already has useful context mechanisms. Project rules are ideal for instructions that must always apply. Repository documentation is best for facts developers need without an AI. Chat history helps humans revisit a conversation. External memory is appropriate when knowledge must survive sessions, be retrieved selectively, or travel across tools. These layers complement rather than replace one another.

Approach	Best at	Trade-off
Cursor rules and repo docs	Always-on conventions near code	Manual retrieval and upkeep; usually repository-scoped
Native ChatGPT or Claude memory	Personal preferences inside one vendor's products	Less portable across coding tools; not a team wiki
Mem0	Semantic recall through a dedicated memory API and Cursor MCP integration	Excellent for fuzzy retrieval, but synthesized records are less naturally reviewed as documentation
Zep/Graphiti	Temporal relationships, changing facts, and graph traversal	More infrastructure and modeling than many codebase decision logs need
Letta	Memory-first agents; its 2026 Context Repositories add git-backed files, reflection, and defragmentation	Strongest when adopting the Letta agent workflow, rather than sharing a neutral wiki among arbitrary clients
Readable markdown over MCP	Auditable decisions, procedures, sources, and cross-agent knowledge	Requires naming, curation, and explicit write discipline; semantic recall may be weaker than vector-first systems

The practical answer can be hybrid. Keep architecture decisions and runbooks readable; use vectors for high-volume fuzzy recall; use a temporal graph when “what was true at that time?” matters. For a deeper storage comparison, see self-hosted agent memory and the Mem0 alternative guide.

Connect Cursor to persistent markdown memory

Cursor's official MCP documentation supports project configuration at .cursor/mcp.json, global configuration at ~/.cursor/mcp.json, remote Streamable HTTP servers, custom headers, and environment-variable interpolation. For memory shared across projects, use the global file.

Create an API key in your Meshnote account, then set it in the environment that launches Cursor. On macOS or Linux:

export MESHNOTE_API_KEY='mnk_REPLACE_WITH_YOUR_KEY'
mkdir -p ~/.cursor

On Windows, set MESHNOTE_API_KEY in User environment variables, then fully restart Cursor. Create ~/.cursor/mcp.json with this valid configuration:

{
  "mcpServers": {
    "meshnote": {
      "url": "https://meshnote.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MESHNOTE_API_KEY}"
      }
    }
  }
}

Open Cursor's MCP settings and confirm the server is connected. Cursor asks before MCP tool execution by default, so inspect the tool name and arguments before approving writes. If no tools appear, use Output → MCP Logs and check that Cursor inherited the environment variable. Never commit a token in project-level .cursor/mcp.json.

Run a two-session acceptance test

Do not declare memory working because the server icon is green. Test the behavior you actually need. In session one, ask Cursor:

In the "payments-api" Meshnote project, write a page named
"deployment-constraints" recording this verified decision:
"Run database migrations before switching application traffic."
Include today's date, mark the source as an operator-confirmed decision,
and link it from the project index.

Approve the relevant read and write tools, then open the page in the web viewer and verify its wording. Start a completely new Cursor chat and ask:

Before proposing a payments-api deployment plan, search its memory.
What order must migrations and traffic switching follow? Cite the page.

A pass requires the correct order and a reference to deployment-constraints. A vague answer from model priors is not a pass. This test checks connection, write, indexing, retrieval, project scoping, and cross-session persistence. The same principle appears in our MCP memory server guide, with more detail on transport and security boundaries.

Give Cursor a memory contract, not “remember everything”

Add a short project rule that controls quality:

Before architecture, deployment, or recurring-debugging work, search
project memory. Write only verified durable knowledge: decisions with
rationale, stable commands, runbooks, and resolved incident lessons.
Do not store secrets, guesses, raw chat transcripts, or temporary task
state. Update an existing page instead of creating duplicates. Cite the
memory page when it changes a recommendation.

This is deliberately selective. Search-before-action prevents contradictory recommendations. Verified-only writes reduce hallucinated “facts.” Updating instead of appending limits duplication. Citations make recall reviewable. Schedule a human review of frequently used pages, delete obsolete constraints, and use page history when an agent makes a bad edit.

When readable memory is the wrong choice

Use Mem0-style semantic memory when you have many short observations and fuzzy recall is the main job. Use Zep or Graphiti when relationships and temporal invalidation dominate. Consider Letta when you want an agent runtime that actively reorganizes its own memory using git-backed context repositories. Native memory may be sufficient for personal preferences that never need to leave one assistant.

Choose readable MCP memory when the knowledge is operational, shared, and worth auditing: architectural rationale, setup procedures, source-backed research, customer-safe product facts, and incident lessons. Meshnote is agent-agnostic, so the wiki can outlive a switch from Cursor to another MCP client. Start syncing — $8/mo, or choose Self-hosted for teams from $10/seat/month.