evermemos-mcp

English | 简体中文

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

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.

<details> <summary>Install from source</summary>

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" }
    }
  }
}

</details>

---

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:

• benchmark_summary.json
• benchmark_report.md
• runs.jsonl (release)

---

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 |

<details> <summary>Advanced configuration</summary>

| 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 |

</details>

flush Rules

| Scenario | flush | |----------|---------| | Mid-conversation, more messages coming | false | | End of session / topic switch / summary | true | | Uncertain | true (safer) |

---

<details> <summary><strong>Advanced: Memory Lifecycle States</strong></summary>

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

</details> <details> <summary><strong>Advanced: Forget Safety</strong></summary>

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.

</details>

---

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