Claude Desktop MCP Memory: Setup for Windsurf

Claude Desktop MCP memory is one config entry per app with no server to run: point the client at the remote MCP server, authenticate with a project key, and verify recall in a fresh conversation. This guide covers Claude Desktop and Windsurf side by side.

What MCP memory adds to desktop agents

Claude Desktop and Windsurf start every conversation with an empty context window. They know what you paste in, and nothing else. The reason you chose Postgres over SQLite, the command that runs integration tests, the header staging requires — none of it survives into the next chat unless it lives outside the conversation.

A context window is working memory with a fixed budget. As a session grows, the agent summarizes or drops older turns. You cannot prompt around that: durable facts need a store that outlives the transcript, which is what a memory layer provides. Why coding agents forget conventions covers the same failure mode.

MCP (Model Context Protocol) is the standard Claude Desktop and Windsurf already use to reach external tools. Audaxic exposes one remote endpoint at https://memory-mcp.audaxic.com/mcp, speaking Streamable HTTP and authenticating with a Bearer ak_... project key. There is no server or container to run: Claude Desktop connects through the npx mcp-remote bridge (Node.js required), and Windsurf connects to the URL directly.

Because the endpoint is remote, one project key works across machines and MCP-compatible clients. A fact saved from Claude Desktop on your laptop is retrievable from Windsurf on your desktop.

What gets stored is what you would otherwise repeat at the start of every chat: preferences like "use pnpm", decisions with their reasons, and gotchas such as a required staging header. The agent searches that store when a question relates to it, so a fact saved weeks ago can come back in today's conversation without you repeating it. Only the matches return, which keeps the context window occupied by the task rather than by an archive.

Prerequisites: one project key

You need one credential: a project key. Create it in the dashboard under Projects and copy the ak_... value when the dashboard shows it. Treat it like any other secret — it is the only thing that stands between the server and your project's memories.

The key also defines scope. Data is isolated per organization with namespace-scoped vector search, and a project key reaches only its own project namespace. Keep one project per repository and memories do not leak across codebases. Share one project on purpose and every client holding the key reads and writes the same memory. Servers run in the US and EU, and we never train on customer data.

Cursor connects through MCP only — there is no Cursor plugin — while Claude Code, Codex, and OpenCode have their own plugins. All of them can read and write the same project when they use the same key.

Claude Desktop MCP memory setup

Claude Desktop reads MCP servers from its configuration file. Add the memory server as one entry inside the existing mcpServers object. Claude Desktop uses the npx mcp-remote bridge, so the entry uses command and args rather than a plain URL:

{
  "mcpServers": {
    "audaxic-memory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://memory-mcp.audaxic.com/mcp",
        "--header",
        "Authorization: Bearer ak_your_project_key"
      ]
    }
  }
}

Save the file and restart Claude Desktop completely. The client loads MCP servers at startup, so closing the window is not enough. The MCP setup guide shows the same entry and notes that npx requires Node.js. If the file already has entries under mcpServers, add this object next to them rather than replacing what is there.

When a connection fails, check two things first: the Bearer prefix in front of the key, and whether the key belongs to the project you meant to use.

Windsurf MCP setup

Windsurf keeps MCP servers in its own MCP configuration. Open Windsurf's MCP settings, paste the same entry — note the serverUrl key — and refresh the server list:

{
  "mcpServers": {
    "audaxic-memory": {
      "serverUrl": "https://memory-mcp.audaxic.com/mcp",
      "headers": {
        "Authorization": "Bearer ak_your_project_key"
      }
    }
  }
}

The MCP setup guide shows the Windsurf entry alongside the other clients. Once connected, Cascade sees the memory server beside your other MCP tools and calls it the same way it calls a search or terminal tool.

When both clients use the same key, they share one memory: a convention saved in one appears in the other immediately. To keep each client's memories apart, create two projects and use two keys. The key decides the boundary, not the client.

Verify the connection end to end

A connected badge proves the Claude Desktop MCP memory transport opened; it does not prove retrieval works. Test the full loop:

1. Open the MCP servers panel in Claude Desktop and confirm the memory server is connected and lists its tools. The tools reference documents their names — add_memory, search_memories, get_memories, and the delete tools — along with their parameters.
2. In a new conversation, ask the agent to remember something specific: "Remember that the release branch is release/2026.09."
3. Ask for it back in the same conversation to confirm the write path.
4. Open a brand-new conversation and ask the same question again. This is the real test: a fresh chat has nothing in context, so a correct answer must have come from the memory server.
5. Cross-check storage from the dashboard or the REST API: GET /list is paginated with limit and offset, and POST /search takes a query string. The quickstart has request examples for both.

If step 4 fails while step 5 succeeds, retrieval is the problem rather than storage — rephrase the question and search again before touching configuration. Step 5 also settles whether the memory was saved at all, without guesswork.

If the server never appears in the panel, validate the JSON first: a trailing comma or a missing quote stops the whole config file from loading. Then confirm the Bearer prefix and quit the app fully, because clients load MCP configuration at startup. A corporate proxy that intercepts HTTPS traffic can break the connection for every client at once — check that when nothing connects.

Long sessions that trim their context window are harmless here: the agent rewrites the transcript, but stored facts are untouched. That is why context compaction stops being a data-loss event.

Limits, costs, and good practices

Hobby is $0 per month: 10,000 adds, 1,000 retrieves, unlimited projects, and no credit card. Starter is $12 per month for 50,000 adds and 5,000 retrieves; paid tiers scale to 1,000,000 adds and 100,000 retrieves on Enterprise. Billing is flat, with no per-token fees and no overages, and graph memory is included on every plan from Hobby through Enterprise.

Understand the counting rules before you let an agent save freely. An add request is counted per memory extracted from a message batch, so one call that extracts five facts counts as five adds. Retrieves are tiered: the first ten memories returned count as one request, and each additional ten counts as one more, so a search returning 25 memories counts as three requests.

Two operational limits matter for scripts and busy setups. Management creates are capped at 100 per hour per IP. On the data plane, 100 failed authentication attempts per four hours per IP trigger a 429 with a Retry-After header; that is a brute-force guard rather than a request cap, so normal traffic will not hit it. If you call the REST API directly, send the date-based X-Api-Version header — the current version is 2026-09-25.

Good practices for desktop agents:

• Store one fact per memory. "Staging requires the X-Env header" retrieves cleanly; a paragraph-long status summary does not.
• Save preferences, decisions with their reasons, and gotchas. Skip secrets and temporary debugging state.
• Share a key only when you mean to share a project's memory, and create one project per repository when you do not.
• If you have past Claude Code, Codex, or OpenCode sessions, the importer brings them into the same layer, so desktop and terminal agents start from the same history.

The payoff is one memory layer behind every client you connect: the same project facts in Claude Desktop, Windsurf, and any other MCP-compatible tool, without a local server to maintain.

FAQ

Written by Efe — Sep 25, 2026 · More articles · X @AudaxicTech