MCP 服务器

everos-mcp

Connects Claude Code to a local EverOS instance for searching and storing long-term memory, keeping data entirely on your machine.

README

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.