MCP Memory

MCP Memory is an MCP (Model Context Protocol) Server designed to give MCP Clients (such as Cursor, Claude, and Windsurf) the ability to remember user information, preferences, and behaviors across different conversations.

It utilizes vector search technology to perform semantic retrieval, meaning it can find relevant information based on the meaning of a query rather than just exact keyword matches. The system is built on Cloudflare's infrastructure, utilizing Workers, D1, Vectorize, Durable Objects, and Workers AI.

MCP Memory implements several security layers:

• Data Isolation: Each user's memories are stored in isolated namespaces within Vectorize to ensure data separation.
• Rate Limiting: A built-in rate limit is set to 100 req/min. This can be modified in the wrangler.jsonc configuration file.
• Authentication: Currently, authentication is based on userId only. While sufficient for basic use with rate limiting, additional layers like API keys or OAuth can be added.
• Encryption: All communications are secured via TLS encryption provided by Cloudflare.

To create a new repository based on the MCP Memory template using the Cloudflare CLI, run the following command:

npm create cloudflare@latest --git https://github.com/puliczek/mcp-memory

You can deploy your own instance of MCP Memory to Cloudflare using the one-click deployment button.

When prompted in the Create Vectorize section, you must use the following configuration:

• Dimensions: 1024
• Metric: cosine

After clicking "Create and Deploy", you can access your deployed worker via the Cloudflare dashboard under "Workers & Pages".

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/puliczek/mcp-memory)

If you are using the repository template or the Cloudflare CLI method, follow these steps to set up and deploy your local environment:

1. Install dependencies:

   npm install

2. Create a Vectorize index: You must create a Vectorize index with specific dimensions and a cosine metric to ensure compatibility with the embedding model.

   npx wrangler vectorize create mcp-memory-vectorize --dimensions 1024 --metric cosine

3. Run locally for development:

   npm run dev

4. Deploy to Cloudflare:

   npm run deploy

The addToMCPMemory tool allows an agent to store important user information, preferences, traits, or technical details in a persistent memory layer. This information is stored in both a Vectorize index (for semantic search) and a D1 database.

When to use:

1. When a user explicitly asks to remember something.
2. When you detect significant user preferences or patterns.
3. When technical details or emotional responses emerge that are valuable for future context.

Note: This tool requires explicit invocation via a function call; it is not a passive resource.

{
  "name": "addToMCPMemory",
  "arguments": {
    "thingToRemember": "string"
  }
}

The MyMCP instance can be mounted within a Hono application. When mounting, the service extracts the userId from the URL path and passes it to the MCP agent's properties (ctx.props). This ensures that the MCP agent operates within the correct user context.

To mount the agent, use the app.mount pattern where the path is constructed as /${userId}/sse.

// Example of how the mounting logic is structured internally
app.mount("/", async (req, env, ctx) => {
  const url = new URL(req.url);
  const pathSegments = url.pathname.split("/");
  const userId = pathSegments[1];

  ctx.props = {
    userId: userId,
  };

  // The MCP agent handles requests under the /:userId/sse path
  return await MyMCP.mount(`/${userId}/sse`).fetch(req, env, ctx);
});

The searchMCPMemory tool performs a semantic search across the user's persistent memory layer. It uses semantic matching to find relevant information even if the query doesn't use exact keywords.

When to use:

1. When you need historical context about user preferences.
2. When a user refers to something previously mentioned.
3. When you need to verify if specific information about the user exists in memory.

Returns: A list of found memories including their content and a similarity score (e.g., content (score: 0.XXXX)). If no matches are found, it returns a message indicating no relevant memories were found.

{
  "name": "searchMCPMemory",
  "arguments": {
    "informationToGet": "string"
  }
}

The entrypoint file exports the main Hono application and the MCP agent instance.

export default app; // The Hono application instance
export { MyMCP };    // The MCP agent instance