memkit-mcp

A local MCP server that gives AI coding agents persistent memory across conversations — scoped per workspace.

Works with any MCP-compatible client:

• VS Code (GitHub Copilot, Continue, etc.)
• Cursor
• Windsurf
• Claude Desktop
• Any tool that supports the MCP protocol

Tools

| Tool | Description | |------|-------------| | memory_add | Store a new memory entry (useFile: true saves long content as a .md file) | | memory_read | List all keys + descriptions, or read a specific key | | memory_edit | Update an existing memory | | memory_delete | Remove a memory entry |

Recommended Usage Pattern

Always use the two-step flow:

1. List first — call memory_read with no key to get all keys + descriptions
2. Read what's relevant — call memory_read with a specific key to get full content

This keeps context loading fast and focused.

At the start of a conversation, prompt your agent:

"Read my memory list and load anything relevant"

At the end of a conversation:

"Save that we decided to use JWT with refresh token rotation"

Setup

VS Code

Add .vscode/mcp.json to your project:

{
  "servers": {
    "memkit-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "memkit-mcp@latest"],
      "env": {
        "WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memkit-mcp": {
      "command": "npx",
      "args": ["-y", "memkit-mcp@latest"],
      "env": {
        "WORKSPACE_FOLDER": "/absolute/path/to/your/project"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memkit-mcp": {
      "command": "npx",
      "args": ["-y", "memkit-mcp@latest"],
      "env": {
        "WORKSPACE_FOLDER": "/absolute/path/to/your/project"
      }
    }
  }
}

Requires Node.js to be installed on your machine.

Manual (no Node.js / offline)

1. Clone this repo and build:

npm install
npm run build

2. Point your MCP config to the built file:

{
  "command": "node",
  "args": ["/absolute/path/to/memkit-mcp/dist/index.js"],
  "env": {
    "WORKSPACE_FOLDER": "/absolute/path/to/your/project"
  }
}

Auto-load memory on every conversation (recommended)

Instead of manually prompting the agent each time, add an agent instructions file to your project so memory loads automatically on every conversation.

VS Code — create .github/copilot-instructions.md:

At the start of every conversation, call memory_read with no key to load
the memory list, then read anything relevant to the current task.

When saving new information, use useFile=true for content longer than a
few sentences.

Cursor / Windsurf — create .cursorrules with the same content:

At the start of every conversation, call memory_read with no key to load
the memory list, then read anything relevant to the current task.

When saving new information, use useFile=true for content longer than a
few sentences.

Where memories are stored

Memories are saved locally to:

<your-project>/.vscode/work-memory.json
<your-project>/.vscode/memory/       <- .md files for long content

Each workspace gets its own memory file — no cross-project leakage.

You can override the default path with an env variable:

"env": {
  "MEMORY_FILE": "/custom/path/memory.json"
}

Example memory entries

{
  "key": "auth-approach",
  "description": "Auth strategy decided for this project",
  "value": "Using JWT with refresh token rotation. Tokens expire in 15min."
}

For long content, use useFile: true:

{
  "key": "architecture",
  "description": "Full system architecture overview",
  "value": "# Architecture\n\nDetailed notes here...",
  "useFile": true
}