# everos-mcp — Local EverOS MCP for Claude Code

A stdio [MCP](https://modelcontextprotocol.io) server that connects **Claude Code** to a **self-hosted, local [EverOS](https://github.com/EverMind-AI/EverOS)** instance — so your coding assistant can search and save long-term memory **without sending anything to the cloud**.

> **Why this exists:** EverMind's official `evermem-claude-code` and the third-party `evermemos-mcp` are both **cloud** clients — they require an EverMem API key and route data through EverMind's servers. If you run EverOS locally (your own keys, your own machine, data stays home), there was no ready-made MCP. This is it.

## Features

- 4 tools: `search_memory` · `remember` · `briefing` · `list_memories`
- Auto `project_id` from cwd, matching `~/.claude/projects/<dir>` encoding — so already-ingested conversations are findable
- Auto-starts EverOS via `everos-up` if it's down
- Data never leaves your machine

## Prerequisites

- A running local [EverOS](https://github.com/EverMind-AI/EverOS) server at `http://127.0.0.1:8000` (`pip install everos && everos server start`)
- Python 3.10+ and [uv](https://github.com/astral-sh/uv) (or plain pip)
- [Claude Code](https://claude.com/claude-code) CLI

## Install

```bash
git clone https://github.com/Marvisatron/everos-mcp.git ~/everos-mcp
cd ~/everos-mcp
uv venv .venv --python 3.14
uv pip install --python .venv/bin/python -e .

# self-check: remember a fact + search it back
.venv/bin/everos-mcp --smoke
```

## Register with Claude Code

```bash
claude mcp add everos -s user \
  -e EVEROS_USER_ID="$USER" \
  -e EVEROS_APP_ID=claude-code \
  -e EVEROS_AGENT_ID=claude \
  -- "$HOME/everos-mcp/.venv/bin/everos-mcp"

claude mcp list   # → everos ... ✔ Connected
```

Restart Claude Code; the 4 tools are now available in every session.

## Tools

| Tool | What it does |
|------|--------------|
| `search_memory(query, top_k=5, project_id?, include_profile?)` | Semantic search of your local EverOS memory |
| `remember(content, project_id?, session_id?)` | Store a fact / decision / note for later recall |
| `briefing(top_k=5, project_id?)` | Session-start recall: recent episodes + your profile |
| `list_memories(memory_type="episode", project_id?, page?, page_size?)` | Paginate episode / profile / agent_case / agent_skill |

## Configuration (env)

| Variable | Default | Description |
|----------|---------|-------------|
| `EVEROS_URL` | `http://127.0.0.1:8000` | Local EverOS URL |
| `EVEROS_USER_ID` | `$USER` | User id (matches `everos-ingest-claude`) |
| `EVEROS_APP_ID` | `claude-code` | App/source id |
| `EVEROS_AGENT_ID` | `claude` | Assistant id |
| `EVEROS_PROJECT_ID` | auto from cwd | Pin a project_id instead of deriving from cwd |
| `EVEROS_MCP_AUTOSTART` | `1` | Auto-start EverOS via `everos-up` if down |

## How `project_id` works

EverOS scopes memory by `project_id`. This MCP derives it from the current working directory using Claude Code's own encoding (`/Users/alice` → `-Users-alice`, matching `~/.claude/projects/-Users-alice`), so memories you ingested for that project are searchable without any config. Override with the `project_id` arg or `EVEROS_PROJECT_ID`.

## Troubleshooting

- **MCP not connected / tools missing** — `claude mcp list`; ensure the binary path is absolute and exists; restart Claude Code.
- **"EverOS not reachable"** — start it (`everos server start`); with `EVEROS_MCP_AUTOSTART=1` (default) the MCP auto-starts it via `everos-up`.
- **Search finds nothing** — check `project_id` matches the project you ingested into; ingest conversations first (e.g. via `everos-ingest-claude` or EverOS's `/api/v1/memory/add`).
- **Transient 502 on search** — handled internally (retry with backoff on 502/503/429). If EverOS's LLM provider is flaky under extraction load, wait and retry.

## License

[Apache-2.0](./LICENSE). Built on top of the open-source [EverMind-AI/EverOS](https://github.com/EverMind-AI/EverOS).