Which package? This is everos-mcp: plug EverOS memory into Claude Code, Claude Desktop, Cursor, Codex, or any other MCP client, with no code.
Calling EverOS from your own Python code? Use the
everos-cloudSDK. Want to self-host? Run the open-sourceeverosserver, then point this package at it.
Your AI assistant forgets everything when the session ends. everos-mcp gives it a memory that lasts: it remembers what you told it, builds a profile of how you work, and learns from how past tasks were solved, across every session and every machine.
- Remembers across sessions — facts, decisions, and preferences you mention are stored and recalled by relevance whenever they matter, not dumped into every prompt.
- Knows who you are — EverOS distills a user profile (facts, traits, preferences) from your conversations, and the assistant loads it at the start of each session.
- Learns from experience — record how a task was solved, tool calls included, and EverOS distills it into reusable cases and skills the agent recalls next time.
- Works on its own — the server ships an autonomy protocol through MCP
instructions, so capable hosts load the profile, store new facts, and recall context without being asked. - Safe by default — a credential guard refuses to store secrets, recalled memories are fenced as data rather than instructions, and you can delete everything a session stored.
- Cloud or self-hosted — EverOS Cloud out of the box; one environment variable points it at your own EverOS deployment.
- Get an API key from the EverOS Console.
- Make sure
uvis installed (uvxruns the server without a manual install). - Add the server to your client:
Claude Code
claude mcp add everos -e EVEROS_API_KEY=sk-... -- uvx everos-mcpCodex
codex mcp add everos --env EVEROS_API_KEY=sk-... -- uvx everos-mcpClaude Desktop, Cursor, and other JSON-configured clients — add this to the client's
MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, …):
{
"mcpServers": {
"everos": {
"command": "uvx",
"args": ["everos-mcp"],
"env": {
"EVEROS_API_KEY": "sk-..."
}
}
}
}That's it. Tell your assistant something worth remembering, start a new session, and ask about it.
| Tool | Purpose |
|---|---|
search_memory |
Relevance search over stored memories (optionally with the user profile) |
add_memory |
Store a durable fact or exchange; saves in the background by default (wait=true to block until it is searchable) |
get_profile |
The synthesized user profile (facts, traits, preferences) |
list_memories |
Chronological, paginated browsing |
forget_session |
Delete what this connection stored (memories + cases distilled from its trajectories); the profile and learned skills are kept |
record_trajectory |
Record how a task was solved (incl. tool calls) for future reuse |
recall_agent_experience |
Search distilled cases/skills relevant to the task at hand |
Read-only tools carry the MCP readOnlyHint annotation, so hosts can run them without a
permission prompt; forget_session is marked destructive.
Good to know
- Profile updates and case/skill distillation run in an offline pipeline and land seconds to minutes after the write.
- A background save that fails is reported on the next tool result, so the model never silently believes something was remembered.
- Trajectories need more than three tool-call rounds to pass the distillation quality gate; shorter ones are stored as episodes but produce no case.
| Env var | Required | Default | Meaning |
|---|---|---|---|
EVEROS_API_KEY |
yes (cloud) | — | API key; issued per environment |
EVEROS_USER_ID |
no | default-user |
Id owning the memories: one memory per API key by default, the same on every machine. Set it to keep several people apart under one key; up to 100 letters, digits and _ . @ + - |
EVEROS_BASE_URL |
no | https://api.evermind.ai |
API endpoint; point at your own deployment for self-hosted EverOS |
EVEROS_APP_ID / EVEROS_PROJECT_ID |
no | default |
Business scope |
EVEROS_SESSION_ID |
no | mcp-<user_id>-<random> |
Session everything is stored under; a fresh one per server process. Setting a fixed value makes forget_session delete everything ever stored under it, by any run |
EVEROS_ASSISTANT_SENDER_ID |
no | assistant-<user_id> |
Agent identity for trajectories and recalled experience. Per user by default; set the same value for everyone to pool agent experience across a team (their trajectories then become visible to each other) |
Set EVEROS_BASE_URL to your own EverOS
deployment. No API key is required when the URL is not an evermind.ai host.
claude mcp add everos -e EVEROS_BASE_URL=http://127.0.0.1:8000 -- uvx everos-mcpEvery write path runs a credential guard before content leaves the process. It scans
every string in the payload — including trajectory tool-call arguments and tool results —
for high-confidence secret formats (API keys, AWS/GitHub/Slack/Stripe tokens, private
keys, JWTs, bearer tokens, URLs with embedded passwords, password=/api_key:-style
assignments) and refuses the write with no bypass flag. Long-term memory is not a safe
place for secrets; store a reference instead.
Recalled memories are returned marked as stored data, and the server instructions tell the model never to follow directions found inside them.
Found a vulnerability? Please report it privately — see the security policy.
The same package runs as a shared, hosted MCP server. It holds no credentials of its own: every request brings the caller's EverOS API key, which is forwarded to the EverOS API and never stored.
everos-mcp --transport http --host 0.0.0.0 --port 8765Clients connect with their own key:
claude mcp add --transport http everos https://mcp.example.com/mcp \
--header "Authorization: Bearer sk-..."Request headers, server settings, and deployment notes
| Request header | Required | Meaning |
|---|---|---|
Authorization: Bearer <key> |
yes | The caller's EverOS API key. Missing → HTTP 401 with WWW-Authenticate: Bearer |
X-EverOS-User-Id |
no | Whose memory within the key's space (default default-user) |
| Server env var | Default | Meaning |
|---|---|---|
EVEROS_BASE_URL |
https://api.evermind.ai |
EverOS API the server talks to |
EVEROS_APP_ID / EVEROS_PROJECT_ID |
default |
Business scope for every caller |
EVEROS_MCP_HOST / EVEROS_MCP_PORT |
127.0.0.1 / 8765 |
Bind address (same as --host / --port) |
EVEROS_MCP_ALLOWED_HOSTS |
— | Comma-separated public host names to accept (DNS-rebinding protection) |
EVEROS_MCP_PUBLIC_URL |
— | Public base URL of this server, e.g. https://mcp.example.com |
EVEROS_MCP_AUTHORIZATION_SERVER |
— | OAuth issuer that signs users in. When set, the server publishes RFC 9728 metadata at /.well-known/oauth-protected-resource/mcp and points to it from the 401 challenge |
EVEROS_MCP_INTROSPECTION_URL / EVEROS_MCP_INTROSPECTION_SECRET |
— | OAuth mode (both required, together with the authorization server): bearer tokens are verified at this RFC 7662 endpoint (audience must be this server) and exchanged for the EverOS API key the user granted. The token itself is never forwarded upstream, as the MCP authorization spec requires. Contract: oauth.py |
Deployment notes:
- Terminate TLS at the ingress;
GET /healthzis the liveness probe. - Each MCP session lives in the memory of the replica that created it. With more than
one replica, route by the
Mcp-Session-Idheader (sticky sessions). - An API key is the trust boundary: anyone holding a key can read and write every user id
within that key's space (
X-EverOS-User-Idis chosen by the caller). Give separate people separate keys when that matters. - Conversations are isolated by (API key, user, MCP session): one caller never sees another's session, background-save notes, or trajectories.
- Hosts that only connect through OAuth (claude.ai connectors, ChatGPT) need an
authorization server; set
EVEROS_MCP_AUTHORIZATION_SERVERonce one exists.
uv sync --dev
uv run ruff check . && uv run pytest # offline: wire contract, tools, guard
EVEROS_API_KEY=... EVEROS_USER_ID=... python scripts/smoke_test.py # live e2eReleasing
Bump version in pyproject.toml and __version__ in src/everos_mcp/__init__.py,
merge, then push a matching tag:
git tag v0.1.0 && git push origin v0.1.0.github/workflows/release.yml tests, builds and smoke-tests the wheel, waits for
approval on the release environment, publishes to PyPI through Trusted Publishing (no
stored token), and drafts the GitHub Release.
EverMind connects memory research, production-ready products, and practical integrations into one open-source ecosystem.
| Products | |
|---|---|
| EverOS | A local-first, Markdown-native long-term memory runtime for agents and users. |
| Raven | A memory-first, self-improving agent harness with proactivity, context control, and skill evolution. |
| EverMe (CLI) | A CLI and agent plugin suite for cross-device, cross-agent personal memory. |
| Research & Evaluation | |
| SkillCorpus | Curated, retrieval-ready agent skill corpora with retrieval and evaluation tooling. |
| EverAlgo | Stateless extraction, ranking, parsing, and memory operators that power EverOS. |
| HyperMem | Hypergraph-based hierarchical memory for coarse-to-fine long-term conversation retrieval. |
| MSA | Memory Sparse Attention for scalable latent memory and 100M-token contexts. |
| EverMemBench | Evaluation of factual recall, applied reasoning, and personalized generalization in memory systems. |
| EvoAgentBench | Longitudinal evaluation of agent self-evolution, transfer efficiency, error avoidance, and skill use. |
| Integrations | |
| OpenClaw | OpenClaw plugin for automatic recall, capture, and session-memory lifecycle management. |
| Hermes Agent | Hermes plugin for persistent memory across Hermes sessions. |
| DeepSeek Harness | DSH plugin for memory-aware DeepSeek Harness agents. |
| Dify | Self-hosted and cloud tools for explicit memory search and storage in workflows and agents. |
| MCP | This server: EverOS memory for Claude Code, Claude Desktop, Cursor, Codex, and any MCP client. |
Together, these projects form EverMind's research-to-runtime stack: methods and benchmarks become reusable memory infrastructure, products, and agent integrations.