EverMemOS MCP Server

Give your AI coding assistant (Windsurf / Cursor / Claude Desktop) persistent long-term memory across sessions.

Built on EverMemOS and the Model Context Protocol (MCP).

中文文档

Features

Tool	Description	Use Case
store_memory	Save conversation content to long-term memory	Remember project preferences, build steps, architecture decisions
search_memory	Search relevant memories via natural language	Recall previous discussions, preferences, decisions
get_memories	Browse memories by user/type	View all stored memories
delete_memory	Remove unwanted memories	Clean up outdated or incorrect memories

Quick Start

1. Prerequisites

• Python 3.10+
• uv package manager
• EverMemOS API Key (cloud) or a local EverMemOS instance

2. Get an API Key

Go to console.evermind.ai to sign up and create an API Key.

3. Set Environment Variables

# Add to ~/.zshrc or ~/.bashrc
export EVERMEM_API_KEY="your-api-key-here"

# Optional
export EVERMEM_USER_ID="my_username"               # Default user ID (default: windsurf_user)
export EVERMEM_GROUP_ID="my_project"               # Default project ID (default: windsurf_project)
export EVERMEM_API_URL="https://api.evermind.ai"   # API URL (defaults to cloud when key is set)

# Reload
source ~/.zshrc

4. Install Dependencies

cd /path/to/evermemos-mcp-server
uv venv
source .venv/bin/activate
uv pip install -e .

5. Configure MCP Server in Windsurf

Open Windsurf Settings → Search "MCP" → Edit MCP config file, and add:

{
  "mcpServers": {
    "evermemos-memory": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/evermemos-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "EVERMEM_API_KEY": "your-api-key-here",
        "EVERMEM_USER_ID": "your_username",
        "EVERMEM_GROUP_ID": "your_project"
      }
    }
  }
}

Warning: Replace /absolute/path/to/evermemos-mcp-server with the actual absolute path on your machine.

6. Restart Windsurf

After configuration, restart Windsurf and your AI assistant will have memory capabilities.

---

Usage Examples

Example 1: Remember Project Build Preferences

You say:

Our project uses Docker multi-stage build, base image python:3.12-slim, uv for dependency management, build command is docker build -t myapp:latest .

AI assistant internal action:

→ store_memory(
    content="Project uses Docker multi-stage build, base image python:3.12-slim, uv for deps, build: docker build -t myapp:latest .",
    role="user",
    flush=true
  )
→ Memory stored successfully. Status: queued

AI replies:

Got it, I've remembered your Docker build preferences. I'll reference these settings whenever you need a Dockerfile or build command.

---

Example 2: Auto-recall in Next Session

(New conversation session) You say:

Write me a Dockerfile

AI assistant internal action:

→ search_memory(query="Dockerfile build preferences Docker config")
→ Found 1 relevant memories:
  • [relevance: 0.92] (2025-02-07) [episodic_memory]
    Project uses Docker multi-stage build, base image python:3.12-slim, uv for deps

AI replies:

Based on your previous preferences, here's a multi-stage Dockerfile:

FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
...

---

Example 3: Search Previous Discussions

You say:

What was the conclusion from our database selection discussion?

AI assistant internal action:

→ search_memory(query="database selection discussion conclusion")
→ Found 2 relevant memories:
  • [relevance: 0.88] Decided to use PostgreSQL as primary DB, Redis for caching
  • [relevance: 0.75] Discussed MongoDB vs PostgreSQL, chose PostgreSQL for transaction support

AI replies:

Based on previous records, you decided to use PostgreSQL as the primary database (for transaction support) and Redis as the caching layer.

---

Example 4: View All Memories

You say:

Show me what you remember

AI assistant internal action:

→ get_memories(memory_type="episodic_memory", limit=10)
→ Retrieved 3 memories:
  ── Group: my_project ──
  • (2025-02-05) Docker multi-stage build preferences...
  • (2025-02-06) PostgreSQL + Redis database selection...
  • (2025-02-07) RESTful API design style...

---

Advanced Configuration

Connect to Local EverMemOS

If you have a local EverMemOS deployment (Docker), no API Key is needed:

{
  "mcpServers": {
    "evermemos-memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/evermemos-mcp-server", "run", "server.py"],
      "env": {
        "EVERMEM_API_URL": "http://localhost:8001",
        "EVERMEM_API_VERSION": "v1"
      }
    }
  }
}

Environment Variables

Variable	Description	Default
EVERMEM_API_KEY	EverMemOS Cloud API Key	(empty)
EVERMEM_API_URL	API URL	https://api.evermind.ai if key is set, else http://localhost:8001
EVERMEM_API_VERSION	API version	v0
EVERMEM_USER_ID	Default user ID	windsurf_user
EVERMEM_GROUP_ID	Default project/group ID	windsurf_project

Retrieval Methods

Method	Description	Recommended For
hybrid	Keyword + vector + reranking	Default recommendation
keyword	BM25 keyword matching	Exact term lookup
vector	Semantic vector search	Fuzzy semantic matching
rrf	RRF fusion ranking	When reranking is unavailable
agentic	LLM-guided multi-round retrieval	Complex queries

Project Structure

evermemos-mcp-server/
├── server.py            # MCP Server entry point (defines Tools)
├── evermemos_client.py  # EverMemOS API client wrapper
├── pyproject.toml       # Project config and dependencies
├── README.md            # This file (English)
└── README_zh.md         # Chinese documentation

License

MIT