mcp-memory

mcp-memory

Your AI agent forgets everything between sessions. This fixes that.

An MCP server that gives any AI agent persistent memory with semantic search. Store decisions, context, and knowledge once -- recall them with natural language queries across any future session.

Built on ChromaDB embeddings, scoped per project, runs entirely locally.

Why

Every MCP-based agent (Claude Desktop, Claude Code, Cursor) starts each session with amnesia. Decisions made yesterday are gone. Context from last week is gone. You re-explain the same things every time.

mcp-memory adds four tools -- remember, recall, forget, list_memories -- that persist knowledge across sessions with vector similarity search. Your agent remembers what matters and finds it when relevant.

Features

• Semantic recall -- vector embeddings (all-MiniLM-L6-v2) find related memories, not just keyword matches
• Per-project scoping -- memories don't leak between projects
• Importance scoring -- prioritize critical decisions (1-5 scale)
• Tag-based filtering -- organize memories by category
• Fully local -- ChromaDB on disk, no cloud, no API keys, no telemetry

Installation

pip install -e .

Configuration

| Environment Variable | Default | Description | |---|---|---| | MCP_MEMORY_DATA_DIR | ~/.mcp-memory/ | Where memories are stored on disk | | MCP_MEMORY_DEFAULT_PROJECT | global | Default project scope | | MCP_MEMORY_MAX_RESULTS | 10 | Default number of recall results |

MCP Client Setup

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "mcp-memory",
      "env": {
        "MCP_MEMORY_DATA_DIR": "~/.mcp-memory"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json:

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

Tools

remember

Store a memory for later recall.

| Arg | Type | Default | Description | |---|---|---|---| | content | string | required | The text to remember | | project | string | "global" | Project scope | | tags | list[string] | [] | Tags for filtering | | source | string | "" | Where this memory came from | | importance | int | 3 | Priority 1-5 |

recall

Search memories by semantic similarity.

| Arg | Type | Default | Description | |---|---|---|---| | query | string | required | Natural language search | | project | string | all | Limit to project | | tags | list[string] | none | Filter by tags | | n_results | int | 10 | Max results | | min_relevance | float | none | Minimum relevance 0.0-1.0 |

forget

Delete stored memories.

| Arg | Type | Default | Description | |---|---|---|---| | memory_ids | list[string] | none | Specific IDs to delete | | project | string | none | Delete all in project | | tags | list[string] | none | Delete by tags |

list_memories

Browse stored memories with pagination.

| Arg | Type | Default | Description | |---|---|---|---| | project | string | all | Filter to project | | tags | list[string] | none | Filter by tags | | page | int | 1 | Page number | | page_size | int | 20 | Results per page |

Development

pip install -e ".[dev]"
pytest              # run tests
ruff check .        # lint
ruff format .       # format
mypy mcp_memory     # type check

License

MIT