Skip to main content
Glama
evermemos-mcp
by tt-a1i

evermemos-mcp

PyPI Python CI License: MIT

English | 简体中文

Long-term memory for AI coding assistants. Remember once, recall forever.

evermemos-mcp overview

You spent thirty minutes explaining your architecture, naming conventions, and why you dropped MongoDB. Next session — gone. You explain it all over again.

evermemos-mcp fixes this. One remember call stores it. One briefing call brings it back — across any session, any client.

Benchmark: 60/60 recall vs 0/60 baseline. Zero attribution errors. P95 < 2s. (evidence)

Intro video: Watch on Bilibili

Demo video: Watch on Bilibili


Quick Start

Get your API key from EverMemOS Cloud, then add to your MCP client config:

{
  "mcpServers": {
    "evermemos-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["evermemos-mcp@latest"],
      "env": {
        "EVERMEMOS_API_KEY": "your-key-here"
      }
    }
  }
}

Or run directly:

uvx evermemos-mcp@latest

Works with Claude Code, Cursor, Cline, Cherry Studio, OpenClaw, Gemini CLI, Aider, and any MCP-compatible client or agent. See docs/05-client-integrations.md for client-specific setup.

git clone https://github.com/tt-a1i/everos-mcp.git
cd everos-mcp
cp .env.example .env   # set EVERMEMOS_API_KEY
uv run evermemos-mcp

MCP client config for source installs:

{
  "mcpServers": {
    "evermemos-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/evermemos-mcp", "evermemos-mcp"],
      "env": { "EVERMEMOS_API_KEY": "your-key-here" }
    }
  }
}

Related MCP server: evermemos-mcp-server

What You Get

7 Tools

Tool

What it does

list_spaces

Discover available memory spaces

remember

Store context into long-term memory. Auto-detects sensitive content (API keys, passwords) and checks for conflicting memories

request_status

Check if a queued write has been extracted

recall

Search memories with 6 retrieval strategies (keyword / hybrid / vector / RRF / agentic / auto)

briefing

One-call session-start context restore: profile + episodes + facts + foresights

forget

Targeted deletion with verification workflow

fetch_history

Paginate through memory timeline by type

Key Capabilities

  • Space isolation — coding:my-app, chat:preferences, study:ml-notes — memories never bleed across projects

  • Multi-space search — Query up to 10 spaces in one recall call with automatic source attribution

  • Sensitive content guard — Blocks API keys, passwords, tokens, private keys before storing. Asks user to confirm

  • Memory conflict detection — Auto-checks for similar memories in chat:* spaces. Surfaces conflicts so the agent can decide

  • Lifecycle tracking — Every result labeled queued, provisional, fallback, or searchable across all tools

  • Traceable citations — memory_type, snippet, timestamp, score, source_message_id on every result

  • Git auto-detection — Omit space_id and it infers coding:<repo-name> from git remote

  • Robust error handling — Retry with backoff (429/5xx); legacy v0 GET-body proxy/WAF fallback (default v1 fetch/search use POST bodies); structured error codes


Use Cases

Persistent architecture context:

You: remember we chose PostgreSQL because our data is highly relational
     [space_id: coding:my-saas]

-- next day, new session --

You: what database did we choose and why?
     → "Chose PostgreSQL — highly relational data model"

Personal preferences that stick:

You: remember I prefer dark mode, vim keybindings, and concise responses
     [space_id: chat:preferences]

-- any future session --

You: recall my UI preferences
     → "dark mode, vim keybindings, concise responses"

Cross-session learning notes:

You: remember bias-variance tradeoff — high bias = underfitting, high variance = overfitting
     [space_id: study:ml-notes]

-- later --

You: briefing for study:ml-notes
     → profile + recent episodes + key facts + foresights

Why evermemos-mcp

There are other memory MCP servers. Here's what makes this one different:

evermemos-mcp

Mem0 MCP

Letta/MemGPT

Official MCP memory

Space isolation

domain:slug per project/topic

No

No

No

Lifecycle tracking

queued → provisional → fallback → searchable

No

No

No

Sensitive content guard

API keys, passwords, tokens blocked

No

No

No

Conflict detection

Auto for chat spaces

No

No

No

Multi-space search

Up to 10 spaces in one call

No

No

No

Retrieval strategies

6 methods + auto merge

Semantic only

Semantic only

None

Benchmark verified

60/60 recall, 0 errors

—

—

—

Setup

uvx evermemos-mcp

Cloud or self-host

Self-host required

npx


Benchmark

Tested on a fixed 60-query set across coding, chat, and study spaces.

Metric

With memory

Without memory

Hit rate

60/60 (100%)

0/60 (0%)

Attribution errors

0

—

P95 latency

1958 ms

—

Evidence:


How It Works

MCP Client (Claude Code / Cursor / Cline / Cherry Studio / OpenClaw / any agent)
        │
        │  MCP stdio
        ▼
┌─────────────────────────────┐
│     evermemos-mcp server    │
│  ┌───────────────────────┐  │
│  │   7 Tool Handlers     │  │
│  └──────────┬────────────┘  │
│  ┌──────────▼────────────┐  │
│  │   Memory Service      │  │  Content guard → Conflict check → Cloud write → Lifecycle tracking
│  └──────────┬────────────┘  │
│  ┌──────────▼────────────┐  │
│  │ Space Catalog Service │  │  Space registry, metadata sync, cross-session recovery
│  └──────────┬────────────┘  │
│  ┌──────────▼────────────┐  │
│  │  EverMemOS HTTP Client│  │  Auth, retries, rate-limit backoff, error normalization
│  └──────────┬────────────┘  │
└─────────────┼───────────────┘
              │  HTTPS
              ▼
       EverMemOS Cloud API
  • Cloud-first — All memories live in EverMemOS Cloud. No local state to lose.

  • Async extraction — remember queues content for AI extraction. Use request_status to track progress.

  • Not a thin wrapper — 2500+ lines of orchestration: fallback hierarchies, multi-method search merging, identity mirroring, partial failure recovery.


Space Templates

Template

Use it for

chat:preferences

Durable personal preferences, names, tone, UI likes

chat:daily

Ongoing chat context that shouldn't leak into projects

coding:<repo>

Architecture decisions, conventions, bugs, project context

study:<topic>

Learning notes, topic progress, revision context

Which Tool When

Goal

Tool

Why

Start a new session

briefing

Fastest way to restore context in one call

Find a specific fact

recall

Relevance-ranked search across spaces

Review what happened

fetch_history

Chronological timeline > ranked search for audits

Verify before/after delete

fetch_history

Stable timeline for pre/post-delete checks


Configuration

Variable

Default

Description

EVERMEMOS_API_KEY

(required)

EverMemOS Cloud API key

EVERMEMOS_USER_ID

mcp-user

Default user identity

EVERMEMOS_DEFAULT_SPACE

(auto)

Default space. Auto-detected from git remote as coding:<repo>

EVERMEMOS_BASE_URL

https://api.evermind.ai

API endpoint

EVERMEMOS_DEFAULT_TIMEZONE

UTC

Timezone for metadata

EVERMEMOS_ENABLE_CONVERSATION_META

true

Sync conversation metadata

Variable

Default

Description

EVERMEMOS_API_VERSION

v1

API version (v0 legacy)

EVERMEMOS_LLM_CUSTOM_SETTING_JSON

—

Custom LLM extraction settings

EVERMEMOS_USER_DETAILS_JSON

—

User profile details for conversations

flush Rules

Scenario

flush

Mid-conversation, more messages coming

false

End of session / topic switch / summary

true

Uncertain

true (safer)


State

Meaning

queued

Write accepted, extraction not yet confirmed

provisional

Answer from pending_messages while extraction is in progress

fallback

Answer from pending_messages and/or metadata fallback while formal memories are not searchable yet; on Cloud v1, only limited Groups metadata (name/description) is durably mirrored

searchable

Answer from formal extracted memories

All 7 tools expose compatible lifecycle blocks so agents always know memory maturity.

Cloud deletion is async and best-effort. evermemos-mcp provides a verification-first workflow:

  1. Confirm target memory_id via fetch_history or recall

  2. Call forget(memory_ids=[...], space_id=...)

  3. Verify with fetch_history

  4. If target persists, the lifecycle model surfaces this transparently

This is deliberate: expose real state to the agent rather than pretend deletion is instant.


Development

uv sync --group dev       # Install dev dependencies
uv run ruff check         # Lint
uv run pytest             # Tests (285 pass)

Documentation

Document

Description

docs/02-architecture.md

Technical architecture

docs/05-client-integrations.md

Client setup guides

docs/auto-memory-prompt.md

Auto-memory prompt templates

docs/06-benchmark.md

Benchmark protocol

CHANGELOG.md

Version history

Also Check Out

MCO — Agent orchestration CLI. Let your main agent (Claude Code, Cursor, Aider) dispatch tasks to multiple coding agents in parallel. Pairs well with evermemos-mcp: MCO handles parallel execution, evermemos-mcp handles persistent memory.

License

MIT

Available Tools

7 tools
briefingA

Get a structured context briefing for a memory space. Call this at the start of a new session to restore high-value context quickly. Returns: user profile, recent episodes, key facts, and foresights. When formal profile memories are unavailable, briefing may surface explicit fallback metadata and label it as such. This is the fastest way to catch up on the most important currently available context in a space.

Inputs: space_id (required), user_id, end_time, max_items, +1 more.

fetch_historyA

Page through historical memories in a space by memory_type. Useful for chronological timeline review when recall's relevance ranking is not sufficient, or when you need to browse all memories of a type. This is the primary tool for timeline review, pre-delete verification, and post-delete re-checks.

Inputs: space_id (required), limit, offset, user_id, +4 more.

forgetA

Request deletion of specific memories from a space. Use fetch_history or recall to identify targets first — results may include a parent_id (memcell ID) which is the effective delete key used by EverMemOS Cloud. The server resolves parent_id automatically when available (recent 100 items per type). Verify deletion afterwards with fetch_history; some IDs may remain unmatched if the memory was already deleted or outside the resolution window.

Inputs: space_id (required), memory_ids (required), reason, user_id.

list_spacesA

List MCP-visible memory spaces that this server can route and recover. Call this first to discover which space_id values are available before using other memory tools. Each space isolates memories by project or topic (e.g. coding:my-app, study:ml-notes, chat:preferences). Note: some native EverMemOS Cloud spaces created outside the MCP naming and catalog flow may not appear here. If no spaces exist yet, create one by calling remember with a new space_id and description.

Inputs: limit, query.

recallA

Search for relevant memories in one or more spaces. Use this when you need context about prior decisions, preferences, conventions, or anything discussed in previous sessions. Returns matching memories with traceable citations (memory_type, snippet, timestamp, relevance score). Also reports whether current results are searchable, provisional, or fallback. Pending signals depend on upstream pending_messages support and may be absent even while extraction is still in progress. If you need chronological review, delete verification, or a complete timeline, prefer fetch_history instead of relying on relevance-ranked recall alone. If space_id and space_ids are both omitted, auto-detected from git remote (coding:).

Inputs: query (required), top_k, radius, user_id, +8 more.

rememberA

Store information in long-term memory within a specific space. Use this proactively to save architecture decisions, user preferences, project conventions, bug solutions, and key context. Content is scanned for sensitive patterns (API keys, passwords, tokens) before sending to Cloud. If detected, the write is blocked and findings are returned with a hint on how to proceed. For chat:* spaces, similar existing memories are checked automatically and surfaced as conflicts in the response. Use check_conflicts to override. Content is queued for AI extraction and becomes searchable only after upstream processing completes. For important writes, prefer remember(include_status=true) so the write-after status check runs immediately. Use request_status, recall, or briefing to distinguish queued, provisional, fallback, and searchable states. Set flush=true at end of session or topic switch; flush=false during ongoing work. Provide a description when creating a new space for the first time.

Inputs: content (required), role, flush, sender, +6 more.

request_statusA

Check the async processing status for a prior remember request. Use this when remember returned a request_id and you need to know whether extraction is still queued or has been reported complete by upstream. Check success/error first, then interpret lifecycle.state.

Inputs: request_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation4/5

    Each tool has a specific role: discovery, storage, status check, search, briefing, deletion, and history. The retrieval tools (recall, fetch_history, briefing) overlap somewhat, but their descriptions clearly distinguish relevance search, chronological paging, and structured summaries.

    Naming Consistency4/5

    Most tool names follow a verb or verb_noun pattern (list_spaces, remember, request_status, recall, forget, fetch_history). 'briefing' is a noun-only deviation, breaking the otherwise consistent style.

    Tool Count5/5

    Seven tools is well-scoped for a memory management server, covering discovery, write, status, search, summary, delete, and history without being bloated.

    Completeness3/5

    Core operations are covered (create, read, search, delete, list), but there is no explicit update tool, and 'remember' references a nonexistent 'check_conflicts' tool. Minor gaps exist around memory editing and conflict handling.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding assistants with persistent, context-rich memory of a codebase, including documentation and git history, enabling recall across sessions.
      105
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI coding assistants to store and retrieve persistent long-term memory across sessions, remembering project preferences, build steps, and architecture decisions.
      4
      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.
      89 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.
      14 npm
      2
      MIT