Skip to main content
Glama
evermemos-mcp-server

evermemos-mcp-server

by wyh0626

EverMemOS MCP Server

Python 3.10+ License: MIT MCP

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

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 ~/.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

Available Tools

4 tools
delete_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

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: store, get, search, and delete. No overlap between them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case: store_memory, get_memories, search_memory, delete_memory.

    Tool Count5/5

    Four tools is appropriate for a memory management system, covering core CRUD operations plus search without being excessive.

    Completeness4/5

    Covers create, read, search, and delete. Missing an explicit update tool, but store_memory may be used for overwriting; still a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Provides 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.
      16
      61 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent memory for AI coding tools, enabling AI assistants to store and recall project decisions, conventions, and context across sessions.
      59 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides persistent memory for AI coding tools, allowing them to remember corrections, decisions, and preferences across sessions and different tools.
      9 npm
      2
      MIT