everos-mcp — Local EverOS MCP for Claude Code

A stdio MCP server that connects Claude Code to a self-hosted, local 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 server at http://127.0.0.1:8000 (pip install everos && everos server start)
• Python 3.10+ and uv (or plain pip)
• Claude Code CLI

Install

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

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. Built on top of the open-source EverMind-AI/EverOS.