evermemos-mcp

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.

git clone https://github.com/tt-a1i/evermemos-mcp.git
cd evermemos-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" }
    }
  }
}

What You Get

7 Tools

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), GET body fallback for proxy/WAF, 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:

Benchmark

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

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

Which Tool When

Configuration

flush Rules

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

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