EverOS MCP Server

MCP (Model Context Protocol) server wrapping the EverOS memory runtime API. Lets any MCP-compatible coding agent (Claude Code, Cursor, Codex CLI, Gemini CLI, etc.) read and write persistent, Markdown-backed memory.

How It Works

Coding Agent (MCP client)
    │  stdio JSON-RPC
    ▼
everos-mcp (this package) ──HTTP──▶ EverOS REST API (:8000)
                                         │
                                    Markdown + SQLite + LanceDB

The MCP server is a thin shim. It translates MCP tool calls into EverOS REST API requests and formats responses into LLM-friendly text. No state, no caching — the EverOS server is the single source of truth.

Install

pip install everos-mcp
# or from source:
pip install -e .

Requires Python 3.10+.

Prerequisites

A running EverOS server:

everos server start
# Verify: curl http://localhost:8000/health → {"status":"ok"}

Register with Coding Agents

Claude Code

Add to ~/.claude/mcp.json or <project>/.claude/mcp.json:

{
  "mcpServers": {
    "everos": {
      "command": "python",
      "args": ["-m", "everos_mcp.server"],
      "env": {
        "EVEROS_API_URL": "http://localhost:8000"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "everos": {
      "command": "python",
      "args": ["-m", "everos_mcp.server"],
      "env": {
        "EVEROS_API_URL": "http://localhost:8000"
      }
    }
  }
}

Codex CLI

codex mcp add everos -- python -m everos_mcp.server

Or set EVEROS_API_URL in Codex's MCP env block.

Generic MCP Host

The server uses stdio transport (JSON-RPC 2.0). Configure with:

Env Var	Default	Description
EVEROS_API_URL	http://localhost:8000	EverOS REST API base URL
EVEROS_API_KEY	(none)	Bearer token for authenticated EverOS instances

MCP Tools

everos_memory_add

Add a message to a memory session. Messages accumulate until flushed.

Parameter	Required	Description
sender_id	yes	Who sent the message (e.g., "claude-code", "alice")
content	yes	Message content in plain text or Markdown
session_id	yes	Session identifier for grouping messages
role	no	"user", "assistant", or "tool" (default: "assistant")
user_id	no	Owner user ID for scoping
app_id	no	App scope (default: "default")
project_id	no	Project scope (default: "default")
timestamp_ms	no	Unix epoch milliseconds (default: now)

everos_memory_flush

Force memory extraction and indexing for a session.

Parameter	Required	Description
session_id	yes	Session to flush
app_id	no	App scope
project_id	no	Project scope

everos_memory_search

Hybrid search (keyword + vector) over stored memories.

Parameter	Required	Description
query	yes	Natural language search query
user_id	no	Search user-track memories (XOR with agent_id)
agent_id	no	Search agent-track memories (XOR with user_id)
method	no	"keyword", "vector", "hybrid", or "agentic" (default: "hybrid")
top_k	no	Results to return (default: 5, max: 100)
include_profile	no	Include user profile in results

everos_memory_get

Paginated memory listing without ranking.

Parameter	Required	Description
user_id	no	Owner user ID (XOR with agent_id)
agent_id	no	Owner agent ID (XOR with user_id)
memory_type	no	"episode", "profile", "agent_case", or "agent_skill"
page	no	Page number (default: 1)
page_size	no	Items per page (default: 20, max: 100)

everos_health

Check EverOS server connectivity. No parameters.

Example Usage (via Claude Code)

Once registered, Claude Code can use these tools directly:

User: "Remember that I prefer pnpm over npm for this project."

Claude calls: everos_memory_add(sender_id="alice", content="Prefers pnpm over npm",
               role="user", session_id="<current>")

User (next session): "Set up the package scripts for me."

Claude calls: everos_memory_search(query="package manager preference", user_id="alice")
  → "Prefers pnpm over npm" found — uses pnpm without re-asking

Where Memories Live

All memories are stored as Markdown files in ~/.everos/:

~/.everos/
  default/default_project/users/alice/
    user.md                        # user profile
    episodes/episode-2026-07-14.md  # daily conversation log

You can read, edit, and version-control these files directly.

Development

# Install with dev deps
pip install -e ".[dev]"

# Run tests
pytest src/everos_mcp/tests/ -v

# Manual smoke test (requires running EverOS)
EVEROS_API_URL=http://localhost:8000 python -m everos_mcp.server

License

Apache 2.0 — same as EverOS.