Skip to main content
Glama
Marvisatron

everos-mcp

by Marvisatron
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

Related MCP server: quarry

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.

Available Tools

4 tools
briefingA

Session-start briefing: your most recent episodes + profile for the current project. Call at the start of a session to recall recent work.

ParametersJSON Schema
NameRequiredDescriptionDefault
top_kNo
project_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It mentions returning episodes and profile but does not specify side effects, authentication needs, or read-only guarantee.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with purpose. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description need not detail return values. It provides sufficient context for a simple briefing tool among sibling memory tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It implies top_k controls number of episodes and project_id filters by project, but lacks explicit details on parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides a session-start briefing with most recent episodes and profile for the current project, distinguishing it from sibling memory tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly advises to call at the start of a session to recall recent work, giving clear context. No exclusions or alternatives are mentioned, but the usage is well-specified.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_memoriesA

Paginate through your local EverOS memories by type. memory_type: episode | profile | agent_case | agent_skill. episode/profile are user-scoped; agent_case/agent_skill are agent-scoped (uses the configured agent_id).

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
page_sizeNo
project_idNo
memory_typeNoepisode

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses pagination behavior and scoping, but lacks details on authentication, rate limits, or empty state behavior. The behavior is adequately described for basic usage but not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences plus a line with type definitions. Every sentence is efficient and front-loaded, providing key information without verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters with 0% schema coverage, the description is not complete enough. It fails to explain page, page_size, and project_id. The output schema exists but is not leveraged to describe return values. The tool is simple, but the description still has gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description only explains the memory_type parameter values and scoping. The other three parameters (page, page_size, project_id) are undocumented, relying solely on schema defaults. This is insufficient for agents to understand parameter usage without additional context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it paginates through local EverOS memories by type, using the verb 'paginate'. It specifies memory types and their scoping, which helps distinguish from sibling tools like search_memory (search) and remember (create). However, it could be more explicit about the listing action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on memory types and their scoping (user vs. agent), helping the agent choose the appropriate type. It does not include when not to use or alternatives, but the context is clear for a pagination tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

rememberA

Store a fact / decision / note into local EverOS memory for later recall. Use for high-value context worth keeping across sessions (architecture decisions, preferences, key findings) — not whole conversations. Scoped to the current project unless project_id is given.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYes
project_idNo
session_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool stores data into memory for later recall, implying non-destructiveness. However, it lacks details on idempotency, storage limits, or overwrite behavior, which would be helpful for a write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that efficiently convey purpose and usage guidelines. No redundant words; information is front-loaded and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the output schema exists (reducing need to explain return values), the description fails to cover all three parameters (missing session_id). It also doesn't mention confirmation or returned identifier, leaving some behavioral gaps. Adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must explain all parameters. It explains 'content' (store a fact) and 'project_id' (scoping), but does not mention 'session_id' at all, leaving that parameter's purpose unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Store' and the resource 'fact / decision / note into local EverOS memory'. It distinguishes from sibling tools (briefing, list_memories, search_memory) by focusing on storage rather than retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit guidance on when to use ('high-value context worth keeping across sessions') and when not to ('not whole conversations'). It also explains scoping behavior with project_id, but does not mention alternatives or when-not to use relative to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_memoryA

Search your local EverOS memory — past Claude Code conversations you ingested (via everos-ingest-claude) or facts you saved with remember. Returns the most relevant episodes for query. Scoped to the current Claude Code project unless project_id is given. Set include_profile=true to also return your user profile.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
top_kNo
project_idNo
include_profileNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It states the tool returns relevant episodes and is scoped; it doesn't mention modifications, so it's implied read-only. No contradictions, and it adequately describes behavior for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with purpose, and contains no unnecessary words. It is efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists (signal: true), the description need not detail return values. It covers key inputs, scoping, and source context (ingestion/remember). Minor gap: no mention of result limit or ordering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It explains 'query', 'project_id', and 'include_profile' but does not detail 'top_k' (only default is 5). This adds partial meaning but leaves a parameter under-specified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches local EverOS memory (past conversations and facts) and returns relevant episodes for a query, with specific scoping and profile options. It effectively distinguishes from siblings like 'list_memories' and 'remember'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (searching past data) versus siblings (listing or remembering), and explains scoping and profile inclusion. However, it lacks explicit 'use this when' or direct comparisons to alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedbriefing
    • First observedlist_memories
    • First observedremember
    • First observedsearch_memory
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: briefing for session summary, list_memories for paginating memories by type, remember for storing new facts, and search_memory for querying. No overlap or ambiguity.

Naming Consistency4/5

Three tools follow a verb_noun pattern (list_memories, remember, search_memory), but 'briefing' is a noun command, breaking the pattern. Otherwise consistent.

Tool Count5/5

Four tools cover the essential memory operations (ingest, list, store, search) without being too few or excessive, well-scoped for the server's purpose.

Completeness2/5

The set supports create (remember) and read (list_memories, search_memory, briefing) but lacks update and delete operations, leaving a significant gap for full CRUD lifecycle.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • LiteFarm MCP Server

    Bundelkund
    F
    license
    Not graded
    quality
    D
    maintenance
    Connects Claude Desktop to a local LiteFarm installation, enabling farm management, task operations, crop browsing, and direct SQL database operations through natural language commands.
    -

  • quarry

    punt-labs
    A
    license
    A
    quality
    A
    maintenance
    Enables local semantic search over documents and code for Claude Code and Claude Desktop, running entirely offline with local embeddings and vector storage.
    12
    3
    MIT

  • cc-history

    Straska7
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides local-first, cross-session memory for Claude Code, enabling semantic search across past sessions to retrieve procedures, decisions, or answers without exposing secrets.
    Apache 2.0

  • agentic-rag

    phense
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables persistent, searchable memory for Claude Code by storing session knowledge in a local PostgreSQL + pgvector database, with hybrid vector and full-text search, automatic session mining, and knowledge graph curation.
    MIT