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.
Give your AI coding assistant (Windsurf / Cursor / Claude Desktop) persistent long-term memory across sessions.
Built on EverMemOS and the Model Context Protocol (MCP).
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: evermemos-mcp
Python 3.10+
uv package manager
EverMemOS API Key (cloud) or a local EverMemOS instance
Go to console.evermind.ai to sign up and create an API Key.
# 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 ~/.zshrccd /path/to/evermemos-mcp-server
uv venv
source .venv/bin/activate
uv pip install -e .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.
After configuration, restart Windsurf and your AI assistant will have memory capabilities.
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.
(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 ...
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.
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...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"
}
}
}
}Variable | Description | Default |
| EverMemOS Cloud API Key | (empty) |
| API URL |
|
| API version |
|
| Default user ID |
|
| Default project/group ID |
|
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 |
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 documentationMIT
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).
| Name | Required | Description | Default |
|---|---|---|---|
| user_id | No | ||
| group_id | No | ||
| memory_type | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States 'This performs a soft delete,' which is key behavioral info, but no other details on reversibility, permissions, or side effects. With no annotations, the description carries full burden but is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Compact three sentences plus a bullet list, no redundant text. Front-loaded with purpose and usage context, well-organized parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavioral detail, and parameters. Output schema exists, so missing return value info is acceptable. Lacks error conditions or idempotency, but adequate for a simple delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It adds meaning by explaining defaults and optional filters (user_id, group_id, memory_type), but lacks examples or allowed values, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete memories from EverMemOS' with a specific verb and resource. It distinguishes from siblings like get_memories, search_memory, and store_memory by being the only delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this tool when the user explicitly asks to forget or remove certain memories.' Provides clear context, though lacks explicit 'when not to use' or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| user_id | No | ||
| group_id | No | ||
| memory_type | No | episodic_memory |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It explains default values (user_id defaults to env var, memory_type defaults to episodic_memory) and limit range (1-50). However, it does not mention read-only nature, auth requirements, or any side effects. Since the tool name suggests read-only, the description is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two short sentences for purpose/guidelines, followed by a bullet-like list of parameters. Every sentence is informative, and there is no redundancy or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters (none required), no enums, and an output schema, the description fully covers the necessary context. It explains each parameter's role, default behaviors, and distinguishes from siblings. The presence of an output schema means return values need not be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining all four parameters. It provides semantic meaning for each: user_id (with env var default), memory_type (with explicit list of types), group_id (optional filter), and limit (with range). This adds significant value beyond the schema's bare property definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('retrieve stored memories') and the primary filters (user ID and type). It explicitly distinguishes from the sibling tool 'search_memory' by mentioning 'without a specific search query', which helps an agent differentiate when to use this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'Use this tool to browse a user's memory collection without a specific search query.' This implies when to use it, but it does not explicitly mention alternatives like 'search_memory' or conditions to avoid using this tool. The guidance is present but could be more explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No | ||
| user_id | No | ||
| group_id | No | ||
| retrieve_method | No | keyword |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains retrieve_method options but does not disclose behavioral traits like read-only nature, rate limits, result ordering, or whether it modifies state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear header and Args section, but some introductory sentences could be more concise. Overall, it is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and an output schema exists, the description adequately covers parameter usage and defaults. It is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the tool description provides detailed explanations for all 5 parameters, including the various retrieve_method strategies and default values, adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Search EverMemOS for relevant memories based on a natural language query' and lists specific use cases like project setup and user preferences, distinguishing it from sibling tools (delete, get, store).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this tool when you need to recall past context' and provides examples, but does not explicitly mention when not to use it or suggest alternatives. However, sibling tools are clearly different operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | user | |
| flush | No | ||
| sender | No | ||
| content | Yes | ||
| group_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behaviors. It explains the flush parameter's effect on memory extraction timing and implies persistence across sessions. However, it does not discuss idempotency, duplicate handling, or whether the tool modifies existing memories, leaving gaps for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, a bulleted list of use cases, and a clear Args section. Every sentence is informative, and the most critical information is front-loaded. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (though not shown), the description adequately covers purpose, usage, and parameters. It lacks some behavioral specifics (e.g., side effects) but is otherwise comprehensive for a straightforward storage tool. Slight deduction for missing behavioral clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the context indicating 0% schema description coverage, the description's Args section thoroughly explains each parameter: content includes advice to be specific, role clarifies acceptable values, sender and group_id specify defaults and purposes, and flush describes its effect. This adds substantial meaning beyond the schema's titles and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Save' and resource 'conversation message into EverMemOS long-term memory'. It distinguishes from siblings (delete, get, search) by focusing on storing new information, and provides specific examples of when to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this tool when the user shares important information...' and gives concrete examples, which is strong guidance. However, it does not explicitly contrast with siblings or state when not to use it, slightly lowering the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0delete_memoryget_memoriessearch_memorystore_memoryScored 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.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Long-term memory for AI assistants. Isolated per-user storage, recall across conversations.
Shared project memory that keeps teammates and AI agents aligned across sessions.
