How to give Cursor memory between sessions

Short version: Cursor remembers your project only inside the current chat — a new session starts from zero. Adding long-term memory takes ten minutes: run the local MaxGraph MCP server in Docker, register it in mcp.json, and paste a protocol block into your project rules. From then on, the agent records decisions, bugs and tasks itself and restores them at the start of the next session.

What you need

• Docker (Docker Desktop on Windows/macOS, docker + compose on Linux)
• Cursor with MCP support (any recent version)
• 10 minutes

Step 1. Run the memory server

git clone https://github.com/RuMemory/maxgraph
cd maxgraph
docker compose up -d

Check:

curl http://localhost:8787/healthz
# → ok

Step 2. Get the access token

The token is generated automatically on first run:

# Linux / macOS
cat data/local_token.txt

# Windows
type data\local_token.txt

This token is the key to your memory. Don’t publish it, don’t commit it.

Step 3. Connect MaxGraph to Cursor

Cursor configures MCP servers through mcp.json — globally (~/.cursor/mcp.json) or per project (.cursor/mcp.json). We recommend the project file: memory then connects only where you actually need it.

Contents:

{
  "mcpServers": {
    "maxgraph": {
      "url": "http://localhost:8787/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

The same can be done through the UI: Settings → MCP → Add new MCP server, type HTTP, URL http://localhost:8787/mcp, header Authorization: Bearer YOUR_TOKEN.

Restart Cursor (or refresh the MCP servers in settings). The agent’s tool list now includes session_start, create_entities, add_observations, search_nodes and others. If the server shows red in Settings → MCP, the usual causes are a stopped Docker container or a typo in the token.

Step 4. Add the memory protocol to project rules

The tools are connected — now tell the agent how to use them, or it will remember to use them only by accident. Add to your project rules (.cursor/rules/memory.mdc or Project Rules in settings):

You have persistent MaxGraph memory (maxgraph/* tools).
At session start, call session_start. Save facts IMMEDIATELY via
add_observations; new topics — create_entities (name = kebab-case id,
title = human-readable name); relations — create_relations in active voice.
End the session with session_close including a summary.
Full protocol: https://github.com/RuMemory/maxgraph/blob/master/docs/PROTOCOL.md

Without this block the agent remembers “when it happens to think of it”. With the block, decisions get recorded the moment they’re made, not reconstructed later.

Step 5. Verify write and read

Ask the agent: “Remember: we deploy only through the deploy script with the preflight guard.” Close the chat. Open a new one and ask: “What do you know about our deploys?”

If the answer mentions the preflight guard, memory works. While you’re at it, open the dashboard at http://localhost:8787/app (sign in with the token): a live knowledge graph, a journal of every write, and a one-click JSON export.

What to ask it to remember in the first week

Memory fills up as you work, but a starter set speeds up the payoff. Ask the agent to record:

• Decisions with their reasoning: “Remember: we chose JWT because the mobile app can’t do cookies.” The reasoning matters more than the fact — without it, the decision gets revisited blindly a month later.
• Constraints: “Don’t touch the users table until the migration”, “deploys go only through the script with the preflight guard”.
• Open tasks: “Remember a task: finish the migration and update the worker.” Open tasks show up in every session’s digest until they’re closed.
• People and roles, if you’re not working alone: who owns decisions, who reviews.

From there, the agent writes on its own — following the protocol from step 4. Your role changes: not writing memory, but checking it in the dashboard.

What you get after a week

• Sessions start without re-explaining the project: the agent reads the digest of decisions, open bugs and tasks itself. On our own repo that’s 1.4–3.3× fewer tokens at session start.
• Decisions survive context compaction: facts live outside the chat history, so compaction can’t cut them.
• 7-day trial, no card; data stays on your machine in data/, NDJSON export in one click.

FAQ

Cursor shows the server as red. What do I check? Three things: docker compose up -d ran and the container is alive (curl http://localhost:8787/healthz returns ok); the token was copied without whitespace or a trailing newline; Cursor was restarted after editing mcp.json.

Will every project get memory at once? No, if you registered the server in a project’s .cursor/mcp.json — only that project. A global ~/.cursor/mcp.json connects memory everywhere; inside the graph, projects stay separated by the project parameter.

I’m on Claude Code / another client. We have a dedicated guide: memory for Claude Code. Any other MCP client connects the same way: URL http://localhost:8787/mcp plus the bearer-token header. Configs for popular hosts are in docs/PAIRING.md.

Is my data sent anywhere? No. Memory lives in data/ on your machine. Internet is needed once — for license activation after the trial.

What’s next

• Why agents need memory and what the options are: the agent memory guide.
• How many tokens a memory-backed start saves: our benchmark with methodology.
• Terms from this article: the agent memory glossary.