mcp-memory/

mcp-memory

Transport	VS Code	VS Code Insiders
stdio
HTTP
Docker

An MCP server that provides persistent, searchable memory storage for AI assistants. Memories are stored as Markdown files on disk and can be retrieved by text query or tag.

Features

• Persistent storage — memories survive process restarts; stored as plain Markdown files on disk
• Tag-based organisation — attach arbitrary tags to any memory and filter by them later
• Full-text search — recall searches both content and tags
• Dual transport — supports both stdio (for local tools) and Streamable HTTP (for remote deployments)
• MCP primitives — memories are exposed as Resources and Tools

Installation

# go install (requires Go 1.24+)
go install github.com/Arkestone/mcp/servers/mcp-memory/cmd/mcp-memory@latest

# Docker
docker pull ghcr.io/arkestone/mcp-memory:latest

# Pre-built binary — https://github.com/Arkestone/mcp/releases/latest

Getting Started

# Run with stdio transport (default)
mcp-memory

# Run with HTTP transport
mcp-memory -transport http -addr :8084

# Build from source
make build-memory   # → ./bin/mcp-memory

Configuration

Configuration is loaded in layers (each overrides the previous):

1. YAML file — config.yaml in the working directory, or specify with -config path/to/config.yaml
2. Environment variables
3. CLI flags

See config.example.yaml for all options.

Environment Variables

CLI Flags

-config       Path to YAML config file
-memory-dir   Directory where memories are stored
-transport    Transport: stdio (default) or http
-addr         HTTP listen address (default :8084)

MCP API

Resources

• memory://{id} — Content of a single memory by its unique ID, including body text, tags, and creation timestamp.
• memory://all — All stored memories as newline-separated plain text, suitable for bulk context injection.

Tools

• remember

  • Store a new memory with optional tags for later filtering and retrieval.
  • Input:
    • content (string, required): the text to remember.
    • tags (string array, optional): labels to attach to this memory (e.g. ["go", "architecture"]).

• recall

  • Search memories by full-text query and/or tags. Returns all memories whose content or tags match.
  • Input:
    • query (string, optional): text to search for in memory content and tags.
    • tags (string array, optional): filter to memories that carry all of the given tags.

• forget

  • Permanently delete a memory by its ID.
  • Input:
    • id (string, required): the ID of the memory to delete.

• list-memories

  • List all stored memories, optionally filtered by tags.
  • Input:
    • tags (string array, optional): return only memories that carry all of the given tags.

Memory Format

Each memory is stored as a plain Markdown file with a YAML-like header:

id: 01HXYZ...
tags: [go, architecture]
created: 2025-03-01T12:00:00Z

The content of the memory goes here.
It can span multiple lines.

Docker

# From the repo root
make docker-memory

# stdio mode
docker run -i -v ~/.local/share/mcp-memory:/data \
  -e MEMORY_DIR=/data \
  ghcr.io/arkestone/mcp-memory:latest

# HTTP mode
docker run -p 8084:8084 \
  -v ~/.local/share/mcp-memory:/data \
  -e MEMORY_DIR=/data \
  -e MEMORY_TRANSPORT=http \
  ghcr.io/arkestone/mcp-memory:latest

MCP Client Configuration

VS Code / GitHub Copilot

.vscode/mcp.json:

{
  "servers": {
    "memory": {
      "command": "mcp-memory"
    }
  }
}

Method 1: User Configuration (Recommended) Open the Command Palette (Ctrl+Shift+P) and run MCP: Open User Configuration to open your user mcp.json file and add the server configuration.

Method 2: Workspace Configuration Add the configuration to .vscode/mcp.json in your workspace to share it with your team.

See the VS Code MCP documentation for more details.

Claude Desktop

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

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory",
      "env": { "MEMORY_DIR": "~/.local/share/mcp-memory" }
    }
  }
}

Cursor

.cursor/mcp.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory",
      "env": { "MEMORY_DIR": "~/.local/share/mcp-memory" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory",
      "env": { "MEMORY_DIR": "~/.local/share/mcp-memory" }
    }
  }
}

Claude Code

.mcp.json or ~/.mcp.json:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory"
    }
  }
}

Remote (HTTP)

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "http://localhost:8084/mcp"
    }
  }
}