> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evermind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# EverOS MCP Server

> Give Claude, ChatGPT, Claude Code, Cursor, Codex and any other MCP client a memory that lasts across sessions, with no code.

Your AI assistant forgets everything when the session ends. The EverOS MCP server
([`everos-mcp`](https://pypi.org/project/everos-mcp/)) plugs EverOS memory into any
[MCP](https://modelcontextprotocol.io) client, so the assistant remembers what you told
it, builds a profile of how you work, and learns from how past tasks were solved, on
every machine you use.

> [!NOTE]
>
> Building your own app? Call EverOS from code with the
> [Python SDK](https://docs.evermind.ai/cloud/quickstart.md) instead. This page is for adding memory to an AI tool
> you already use.

## What your assistant can do

* **Remember across sessions.** Facts, decisions and preferences you mention are stored
  and recalled when they are relevant, not pasted into every prompt.
* **Know who you are.** EverOS builds a profile from your conversations, and the
  assistant loads it at the start of each session.
* **Learn from experience.** How a task was solved, tool calls included, is distilled
  into cases and skills the assistant recalls the next time a similar task comes up
  (local server only).
* **Use memory when it helps.** The server describes when to load the profile, store
  new facts and recall context, so capable assistants do it without a prompt from you.
  Ask it not to remember something and it won't.
* **Keep secrets out.** Writes that contain API keys, tokens, private keys or passwords
  are refused, and recalled memories are treated as data, never as instructions.

## Choose how to connect

| | Connector | Local server |
| - | - | - |
| **For** | Claude (web, desktop, mobile), ChatGPT, Claude Code | Claude Code, Codex, Cursor, Claude Desktop, any MCP client |
| **Install** | Nothing: add a URL and sign in | [uv](https://docs.astral.sh/uv/), then one command |
| **Sign-in** | Your EverOS account, in the browser | An EverOS API key |
| **Backend** | EverOS Cloud | EverOS Cloud or [self-hosted EverOS](#self-hosted-everos) |
| **Tools** | Five memory tools | All seven, including agent experience |

## Connect Claude or ChatGPT

The connector runs on EverOS Cloud at `https://everos-mcp.evermind.ai/mcp`. You sign in
with your EverOS account and choose which memory space the app can use. No API key is
involved.

**1. Add the connector**

> [tab] Claude
>
> In [Claude](https://claude.ai), open **Settings → Connectors**, choose
> **Add custom connector**, and enter:
>
> ```text theme={null}
> https://everos-mcp.evermind.ai/mcp
> ```
>
> The connector then works in Claude on the web, desktop and mobile.

> [tab] ChatGPT
>
> In [ChatGPT](https://chatgpt.com), turn on **Developer mode** under
> **Settings → Apps & Connectors → Advanced settings**, then create a connector
> with this URL and OAuth authentication:
>
> ```text theme={null}
> https://everos-mcp.evermind.ai/mcp
> ```
>
> Developer mode needs a paid ChatGPT plan.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http everos https://everos-mcp.evermind.ai/mcp
> ```
>
> Then run `/mcp` in Claude Code, pick `everos`, and choose **Authenticate**.

**2. Sign in and choose a space**

Your browser opens the EverOS consent page. Sign in, check the app and the address
it returns to, pick the memory space it may read and
write (or create a new one), and choose **Allow**.

**3. Try it**

Tell the assistant something worth remembering, start a new chat, and ask about it.

### Manage connected apps

Every app you connect is listed under **Connected Apps** in the
[EverOS Console](https://everos.evermind.ai/connected-apps), with its memory space and
when it was last used.

* **Revoke** disconnects the app at once. Its stored memories stay in the space.
* **Reconnect with a different space** disconnects the app; reconnect from the app and
  pick the new space on the consent page.
* A connection that goes unused for 30 days is disconnected automatically. Connect again
  from the app to continue.

## Run the server locally

**1. Get an API key**

Create one in the [EverOS Console](https://everos.evermind.ai/api-keys).

**2. Install uv**

The server runs with `uvx`, so there is nothing else to install. If you don't have
[uv](https://docs.astral.sh/uv/getting-started/installation/) yet:

```bash theme={null}
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**3. Add the server to your client**

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add everos -e EVEROS_API_KEY=your_api_key -- uvx everos-mcp
> ```

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add everos --env EVEROS_API_KEY=your_api_key -- uvx everos-mcp
> ```

> [tab] Cursor, Claude Desktop, others
>
> Add this to the client's MCP config file, for example `~/.cursor/mcp.json` for
> Cursor or `claude_desktop_config.json` for Claude Desktop:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "everos": {
>       "command": "uvx",
>       "args": ["everos-mcp"],
>       "env": {
>         "EVEROS_API_KEY": "your_api_key"
>       }
>     }
>   }
> }
> ```
>
> Restart the client after saving.

**4. Try it**

Tell your assistant something worth remembering, start a new session, and ask about
it.

## Tools

| Tool | What it does | Connector | Local |
| - | - | - | - |
| `search_memory` | Finds stored memories relevant to a query, optionally with the user profile | ✅ | ✅ |
| `add_memory` | Stores a fact or exchange. Saves in the background by default; pass `wait=true` to block until extraction has finished | ✅ | ✅ |
| `get_profile` | Returns the profile EverOS has built: facts, traits and preferences | ✅ | ✅ |
| `list_memories` | Browses stored memories in time order, page by page | ✅ | ✅ |
| `forget_session` | Deletes what this conversation (connector) or this server run (local) stored. The profile and learned skills are kept | ✅ | ✅ |
| `record_trajectory` | Records how a task was solved, tool calls included, so it can be reused | | ✅ |
| `recall_agent_experience` | Finds cases and skills relevant to the task at hand | | ✅ |

Read-only tools are marked as such, so clients can run them without a permission prompt.
`forget_session` is marked destructive.

> [!NOTE]
>
> The profile, cases and skills are built in the background and appear seconds to minutes
> after a write. A memory saved with `wait=true` can also take a moment to show up in
> search, because the index catches up after extraction finishes. A trajectory needs more than three tool-call rounds to become a case;
> shorter ones are still stored as memories.

## Your data

* **What is stored**: the facts and exchanges the assistant saves with `add_memory`,
  and the profile EverOS builds from them. The local server also stores the task
  trajectories it records. Beyond that, EverOS receives only what a tool call carries,
  such as the query for a search.
* **Where**: in your EverOS account, in the memory space you chose (connector) or the
  space of your API key (local server).
* **Removing it**: ask the assistant to forget the current conversation
  (`forget_session`), or delete the whole memory space under **Memory Spaces** in the
  [EverOS Console](https://everos.evermind.ai/memory-spaces). Revoking a connected app
  stops its access but keeps what it stored.

See the [Privacy Policy](https://evermind.ai/privacy-policy) and
[Terms of Service](https://evermind.ai/terms-of-service).

## Configuration (local server)

Set these as environment variables in the client config, next to `EVEROS_API_KEY`.

| Variable | Default | What it controls |
| - | - | - |
| `EVEROS_API_KEY` | (required for Cloud) | Your EverOS API key |
| `EVEROS_USER_ID` | `default-user` | Whose memory this is. Everything under one key shares one memory by default, on every machine. Set a different id per person to keep people apart under one key |
| `EVEROS_APP_ID` / `EVEROS_PROJECT_ID` | `default` | The scope memories are stored under. Use the same values as your app to share its memory |
| `EVEROS_SESSION_ID` | a new id per run | The session everything is stored under. If you fix it, `forget_session` deletes everything ever stored under that id |
| `EVEROS_ASSISTANT_SENDER_ID` | `assistant-<user_id>` | The agent identity cases and skills belong to. Give a team the same value to pool what their assistants learn |
| `EVEROS_BASE_URL` | `https://api.evermind.ai` | Where to send requests. Point it at your own deployment to use self-hosted EverOS |

### Self-hosted EverOS

Point the server at your own [EverOS](https://docs.evermind.ai/open-source/quickstart.md) deployment. No API key is
needed for a host that is not on evermind.ai.

```bash theme={null}
claude mcp add everos -e EVEROS_BASE_URL=http://127.0.0.1:8000 -- uvx everos-mcp
```

## Learn more

> [card] [everos-mcp on GitHub](https://github.com/EverMind-AI/EverOS-MCP)
>
> Source, security policy, and running it as a shared HTTP server for a team.

> [card] [Memory lifecycle](https://docs.evermind.ai/cloud/concepts/memory-lifecycle.md)
>
> How EverOS turns conversations into episodes, profiles, cases and skills.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.