evermemos-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@evermemos-mcp-server Remember: our project uses Docker multi-stage build with python:3.12-slim and uv."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Save conversation content to long-term memory | Remember project preferences, build steps, architecture decisions |
| Search relevant memories via natural language | Recall previous discussions, preferences, decisions |
| Browse memories by user/type | View all stored memories |
| Remove unwanted memories | Clean up outdated or incorrect memories |
Related MCP server: ShackleAI Memory MCP
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 ~/.zshrc4. 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-serverwith 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: queuedAI 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 depsAI 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 supportAI 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 |
| EverMemOS Cloud API Key | (empty) |
| API URL |
|
| API version |
|
| Default user ID |
|
| Default project/group ID |
|
Retrieval Methods
Method | Description | Recommended For |
| Keyword + vector + reranking | Default recommendation |
| BM25 keyword matching | Exact term lookup |
| Semantic vector search | Fuzzy semantic matching |
| RRF fusion ranking | When reranking is unavailable |
| 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 documentationLicense
MIT
Available Tools
4 toolsdelete_memoryA
Delete memories from EverMemOS.
Use this tool when the user explicitly asks to forget or remove certain memories. This performs a soft delete.
Args: user_id: User ID whose memories to delete. Defaults to EVERMEM_USER_ID env var. group_id: Optional group/project filter - only delete memories in this group. memory_type: Optional type filter - only delete this type (episodic_memory, foresight, event_log).
Inputs: user_id, group_id, memory_type. Returns: result
get_memoriesA
Retrieve stored memories by user ID and type.
Use this tool to browse a user's memory collection without a specific search query.
Args: user_id: User ID to fetch memories for. Defaults to EVERMEM_USER_ID env var. memory_type: Type of memory to retrieve - "episodic_memory" (conversation summaries), "foresight" (predicted future needs), "event_log" (atomic facts), "profile" (user profile). group_id: Optional project/group filter. limit: Maximum number of results (1-50).
Inputs: limit, user_id, group_id, memory_type. Returns: result
search_memoryA
Search EverMemOS for relevant memories based on a natural language query.
Use this tool when you need to recall past context, such as: project setup details, user preferences, previous decisions, coding patterns, deployment steps, etc.
Args: query: Natural language search query describing what you're looking for. user_id: User ID to search memories for. Defaults to EVERMEM_USER_ID env var. group_id: Optional project/group filter to narrow search scope. retrieve_method: Search strategy - "keyword" (BM25, default), "vector" (semantic), "hybrid" (keyword+vector+rerank, requires rerank service), "rrf" (fusion), "agentic" (LLM-guided multi-round). top_k: Maximum number of results to return (1-20).
Inputs: query (required), top_k, user_id, group_id, +1 more. Returns: result
store_memoryA
Save a conversation message into EverMemOS long-term memory.
Use this tool when the user shares important information that should be remembered across sessions, such as: project preferences, coding conventions, architecture decisions, deployment procedures, personal preferences, etc.
Args: content: The message content to remember. Be specific and include key details. role: Who sent this message - "user" for human messages, "assistant" for AI responses. sender: User ID for memory ownership. Defaults to EVERMEM_USER_ID env var. group_id: Project/group identifier to organize memories. Defaults to EVERMEM_GROUP_ID env var. flush: If True, force immediate memory extraction instead of waiting for natural conversation boundary detection.
Inputs: content (required), role, flush, sender, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clear, distinct purpose: store, get, search, and delete. No overlap between them.
All tool names follow a consistent verb_noun pattern in snake_case: store_memory, get_memories, search_memory, delete_memory.
Four tools is appropriate for a memory management system, covering core CRUD operations plus search without being excessive.
Covers create, read, search, and delete. Missing an explicit update tool, but store_memory may be used for overwriting; still a minor gap.
Maintenance
Related MCP Connectors
Persistent engineering memory designed to follow developers across coding agents.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Persistent memory for AI assistants: store, search, and connect knowledge across conversations.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Related MCP Servers
- AlicenseBqualityCmaintenanceProvides AI assistants with persistent memory of your project architecture, development history, and technical decisions, allowing them to give context-aware coding help without needing repeated explanations.1661 npm2MIT
- AlicenseNot gradedqualityDmaintenancePersistent memory for AI coding tools, enabling AI assistants to store and recall project decisions, conventions, and context across sessions.59 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides persistent memory for AI coding tools, allowing them to remember corrections, decisions, and preferences across sessions and different tools.9 npm2MIT

Xanther memory Engineofficial
AlicenseNot gradedqualityCmaintenancePersistent memory for AI coding assistants.3MIT