# EverOS MCP Server

MCP (Model Context Protocol) server wrapping the [EverOS](https://github.com/EverMind-AI/EverOS) memory runtime API. Lets any MCP-compatible coding agent (Claude Code, Cursor, Codex CLI, Gemini CLI, etc.) read and write persistent, Markdown-backed memory.

## How It Works

```
Coding Agent (MCP client)
    │  stdio JSON-RPC
    ▼
everos-mcp (this package) ──HTTP──▶ EverOS REST API (:8000)
                                         │
                                    Markdown + SQLite + LanceDB
```

The MCP server is a thin shim. It translates MCP tool calls into EverOS REST API requests and formats responses into LLM-friendly text. No state, no caching — the EverOS server is the single source of truth.

## Install

```bash
pip install everos-mcp
# or from source:
pip install -e .
```

Requires Python 3.10+.

## Prerequisites

A running EverOS server:

```bash
everos server start
# Verify: curl http://localhost:8000/health → {"status":"ok"}
```

## Register with Coding Agents

### Claude Code

Add to `~/.claude/mcp.json` or `<project>/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "everos": {
      "command": "python",
      "args": ["-m", "everos_mcp.server"],
      "env": {
        "EVEROS_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "everos": {
      "command": "python",
      "args": ["-m", "everos_mcp.server"],
      "env": {
        "EVEROS_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

### Codex CLI

```bash
codex mcp add everos -- python -m everos_mcp.server
```

Or set `EVEROS_API_URL` in Codex's MCP env block.

### Generic MCP Host

The server uses stdio transport (JSON-RPC 2.0). Configure with:

| Env Var | Default | Description |
|---|---|---|
| `EVEROS_API_URL` | `http://localhost:8000` | EverOS REST API base URL |
| `EVEROS_API_KEY` | (none) | Bearer token for authenticated EverOS instances |

## MCP Tools

### `everos_memory_add`

Add a message to a memory session. Messages accumulate until flushed.

| Parameter | Required | Description |
|---|---|---|
| `sender_id` | yes | Who sent the message (e.g., "claude-code", "alice") |
| `content` | yes | Message content in plain text or Markdown |
| `session_id` | yes | Session identifier for grouping messages |
| `role` | no | "user", "assistant", or "tool" (default: "assistant") |
| `user_id` | no | Owner user ID for scoping |
| `app_id` | no | App scope (default: "default") |
| `project_id` | no | Project scope (default: "default") |
| `timestamp_ms` | no | Unix epoch milliseconds (default: now) |

### `everos_memory_flush`

Force memory extraction and indexing for a session.

| Parameter | Required | Description |
|---|---|---|
| `session_id` | yes | Session to flush |
| `app_id` | no | App scope |
| `project_id` | no | Project scope |

### `everos_memory_search`

Hybrid search (keyword + vector) over stored memories.

| Parameter | Required | Description |
|---|---|---|
| `query` | yes | Natural language search query |
| `user_id` | no | Search user-track memories (XOR with agent_id) |
| `agent_id` | no | Search agent-track memories (XOR with user_id) |
| `method` | no | "keyword", "vector", "hybrid", or "agentic" (default: "hybrid") |
| `top_k` | no | Results to return (default: 5, max: 100) |
| `include_profile` | no | Include user profile in results |

### `everos_memory_get`

Paginated memory listing without ranking.

| Parameter | Required | Description |
|---|---|---|
| `user_id` | no | Owner user ID (XOR with agent_id) |
| `agent_id` | no | Owner agent ID (XOR with user_id) |
| `memory_type` | no | "episode", "profile", "agent_case", or "agent_skill" |
| `page` | no | Page number (default: 1) |
| `page_size` | no | Items per page (default: 20, max: 100) |

### `everos_health`

Check EverOS server connectivity. No parameters.

## Example Usage (via Claude Code)

Once registered, Claude Code can use these tools directly:

```
User: "Remember that I prefer pnpm over npm for this project."

Claude calls: everos_memory_add(sender_id="alice", content="Prefers pnpm over npm",
               role="user", session_id="<current>")

User (next session): "Set up the package scripts for me."

Claude calls: everos_memory_search(query="package manager preference", user_id="alice")
  → "Prefers pnpm over npm" found — uses pnpm without re-asking
```

## Where Memories Live

All memories are stored as Markdown files in `~/.everos/`:

```
~/.everos/
  default/default_project/users/alice/
    user.md                        # user profile
    episodes/episode-2026-07-14.md  # daily conversation log
```

You can read, edit, and version-control these files directly.

## Development

```bash
# Install with dev deps
pip install -e ".[dev]"

# Run tests
pytest src/everos_mcp/tests/ -v

# Manual smoke test (requires running EverOS)
EVEROS_API_URL=http://localhost:8000 python -m everos_mcp.server
```

## License

Apache 2.0 — same as EverOS.