> ## 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 Code, Cursor, Codex, Claude Desktop 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](/cloud/quickstart) instead. This page is for adding memory to an AI tool
  you already use.
</Note>

## 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.
* **Work without being asked.** The server tells the assistant when to load the profile,
  store new facts and recall context, so you don't have to prompt for it.
* **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.

## Set up

<Steps>
  <Step title="Get an API key">
    Create one in the [EverOS Console](https://everos.evermind.ai/api-keys).
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Add the server to your client">
    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add everos -e EVEROS_API_KEY=your_api_key -- uvx everos-mcp
        ```
      </Tab>

      <Tab title="Codex">
        ```bash theme={null}
        codex mcp add everos --env EVEROS_API_KEY=your_api_key -- uvx everos-mcp
        ```
      </Tab>

      <Tab title="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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Try it">
    Tell your assistant something worth remembering, start a new session, and ask about
    it.
  </Step>
</Steps>

## Tools

| Tool | What it does |
| - | - |
| `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 it is searchable |
| `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 connection stored, including cases distilled from it. 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 trajectory needs more than three tool-call rounds to become a case;
  shorter ones are still stored as memories.
</Note>

## Configuration

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](/open-source/quickstart) 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

<CardGroup cols={2}>
  <Card title="everos-mcp on GitHub" icon="github" href="https://github.com/EverMind-AI/EverOS-MCP">
    Source, security policy, and running it as a shared HTTP server for a team.
  </Card>

  <Card title="Memory lifecycle" icon="brain" href="/cloud/concepts/memory-lifecycle">
    How EverOS turns conversations into episodes, profiles, cases and skills.
  </Card>
</CardGroup>


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