From c06e041b4bd1dd60f1503d999f428151dbdabfa9 Mon Sep 17 00:00:00 2001 From: zhanghui Date: Sat, 10 Oct 2026 16:39:14 +0800 Subject: [PATCH 1/3] docs(mcp): point users at the official everos-mcp server Add docs/mcp.md with the client setup for Claude Code, Codex and JSON-configured hosts against a self-hosted server, list it in the docs index, and replace the community evermemos-mcp card in README and docs/use-cases.md with the official package. `everos init` now ends with a pointer to the guide and `everos server start` logs the `uvx everos-mcp` line to use. Verified against a local server: all seven everos-mcp tools answer. The guide records the self-hosted limitations: no session-delete endpoint yet (#483) and about a second of index lag after saving. Co-Authored-By: Claude Fable 5.1 --- README.md | 8 +- docs/index.md | 1 + docs/mcp.md | 88 +++++++++++++++++++ docs/use-cases.md | 8 +- .../entrypoints/cli/commands/init_cmd.py | 3 + src/everos/entrypoints/cli/commands/server.py | 5 ++ 6 files changed, 105 insertions(+), 8 deletions(-) create mode 100644 docs/mcp.md diff --git a/README.md b/README.md index 3c185167..24072dbc 100644 --- a/README.md +++ b/README.md @@ -359,13 +359,13 @@ Browser-native hive-mind for CLI coding agents - Claude Code, Codex, Gemini, and -[![banner-gif](https://github.com/user-attachments/assets/867d9329-ce9a-496f-ab1e-15c77974e5fa)](https://github.com/tt-a1i/evermemos-mcp) +[![banner-gif](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)](https://github.com/EverMind-AI/EverOS-MCP) -#### AI Coding Assistants With EverOS +#### MCP Server for AI Coding Assistants -Universal long-term memory layer for AI coding assistants, powered by EverOS. +Plug EverOS memory into Claude Code, Codex, Claude Desktop or Cursor with `uvx everos-mcp`. Works with EverOS Cloud and with this self-hosted server. -[Code](https://github.com/tt-a1i/evermemos-mcp) +[Code](https://github.com/EverMind-AI/EverOS-MCP) · [Setup guide](docs/mcp.md) diff --git a/docs/index.md b/docs/index.md index e5bd160d..fb4eab17 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,6 +24,7 @@ already know what you want to do and need to know exactly how. | [knowledge.md](knowledge.md) | Knowledge base module — upload, search, taxonomy, storage layout | | [reflection.md](reflection.md) | Reflection — offline memory consolidation: enable, schedule, storage, triggering | | [cli.md](cli.md) | `everos` CLI subcommands + env var conventions | +| [mcp.md](mcp.md) | Connect MCP clients (Claude Code, Codex, Cursor, Claude Desktop) through the official `everos-mcp` server | | [storage_layout.md](storage_layout.md) | Memory-root tree + frontmatter chassis + EntryId encoding | | [prompt_slots.md](prompt_slots.md) | PromptSlot loader — bundled default prompts (Layer 1 live; app/runtime overlays planned) | | [configuration.md](configuration.md) | TOML / env-var configuration reference | diff --git a/docs/mcp.md b/docs/mcp.md new file mode 100644 index 00000000..ac0b67c9 --- /dev/null +++ b/docs/mcp.md @@ -0,0 +1,88 @@ +# Connect MCP clients + +EverOS exposes its memory to MCP (Model Context Protocol) clients — Claude Code, Codex, +Claude Desktop, Cursor and any other MCP host — through the official **everos-mcp** +server: [PyPI `everos-mcp`](https://pypi.org/project/everos-mcp/) · +[source](https://github.com/EverMind-AI/EverOS-MCP). + +`everos-mcp` is a separate process that runs next to your EverOS server. It speaks MCP to +the host over stdio and calls this server's `/api/v2/memory/*` endpoints. It does not start +or stop EverOS for you. + +- [Prerequisites](#prerequisites) +- [Add the server to your client](#add-the-server-to-your-client) +- [What the assistant gets](#what-the-assistant-gets) +- [Behaviour on a self-hosted server](#behaviour-on-a-self-hosted-server) +- [Remote hosts](#remote-hosts) + +## Prerequisites + +1. `everos init` done and the LLM / embedding API keys filled in (`everos.toml`). +2. `everos server start` running — default `http://127.0.0.1:8000`. Start it before the + host launches the MCP server, and keep it running. +3. [`uv`](https://docs.astral.sh/uv/getting-started/installation/) installed; `uvx` runs + `everos-mcp` without a manual install. + +No API key is needed when `EVEROS_BASE_URL` points at your own server. + +## Add the server to your client + +```bash +# Claude Code +claude mcp add everos -e EVEROS_BASE_URL=http://127.0.0.1:8000 -- uvx everos-mcp + +# Codex +codex mcp add everos --env EVEROS_BASE_URL=http://127.0.0.1:8000 -- uvx everos-mcp +``` + +Claude Desktop, Cursor and other JSON-configured clients: + +```json +{ + "mcpServers": { + "everos": { + "command": "uvx", + "args": ["everos-mcp"], + "env": { "EVEROS_BASE_URL": "http://127.0.0.1:8000" } + } + } +} +``` + +Optional environment variables: `EVEROS_USER_ID` (memory owner, default `default-user`), +`EVEROS_APP_ID` / `EVEROS_PROJECT_ID` (scope, default `default`). The full list is in the +[everos-mcp README](https://github.com/EverMind-AI/EverOS-MCP#configuration). + +## What the assistant gets + +| Tool | What it does | EverOS endpoint | +|---|---|---| +| `get_profile` | The synthesized user profile, fetched once per session | `POST /api/v2/memory/get` | +| `add_memory` | Stores a durable fact or exchange the moment the user states it | `POST /api/v2/memory/add` + `flush` | +| `search_memory` | Relevance search over past conversations and decisions | `POST /api/v2/memory/search` | +| `list_memories` | Chronological, paginated browsing | `POST /api/v2/memory/get` | +| `record_trajectory` | Records how a task was solved so EverOS can distill cases and skills | `POST /api/v2/memory/add` + `flush` | +| `recall_agent_experience` | Finds distilled cases and skills relevant to the task at hand | `POST /api/v2/memory/search` (agent owner) | +| `forget_session` | Deletes what this connection stored | `POST /api/v2/memory/delete` — see below | + +The server also ships an autonomy protocol through MCP `instructions`, so capable hosts load +the profile at session start, save new facts and recall context without being asked. + +## Behaviour on a self-hosted server + +- **`forget_session` is not available yet.** Self-hosted EverOS has no session-scoped delete + endpoint; the tool reports this instead of failing. Memories are Markdown files under the + memory root (`~/.everos/` by default) — delete them there. +- **New memories are searchable about a second after saving.** `add_memory` returns once + extraction has written the Markdown; the index catches up a moment later. + `list_memories` shows new entries sooner than `search_memory`. +- **Trajectories only become cases when they pass the quality gate.** Short or + straightforward runs are stored as episodes but produce no reusable case, so + `recall_agent_experience` stays empty until a substantial task has been recorded. + +## Remote hosts + +To serve MCP over HTTP instead of stdio (hosts on another machine, or OAuth-only hosts), +run `everos-mcp --transport http` on the machine that can reach your EverOS server and put +it behind your gateway. Configuration is described in the +[everos-mcp README](https://github.com/EverMind-AI/EverOS-MCP#configuration). diff --git a/docs/use-cases.md b/docs/use-cases.md index 4abf09d8..12d00b84 100644 --- a/docs/use-cases.md +++ b/docs/use-cases.md @@ -44,13 +44,13 @@ Browser-native hive-mind for CLI coding agents - Claude Code, Codex, Gemini, and -[![banner-gif](https://github.com/user-attachments/assets/867d9329-ce9a-496f-ab1e-15c77974e5fa)](https://github.com/tt-a1i/evermemos-mcp) +[![banner-gif](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)](https://github.com/EverMind-AI/EverOS-MCP) -#### AI Coding Assistants with EverOS +#### MCP Server for AI Coding Assistants -Universal long-term memory layer for AI coding assistants, powered by EverOS. +Plug EverOS memory into Claude Code, Codex, Claude Desktop or Cursor with `uvx everos-mcp`. Works with EverOS Cloud and with this self-hosted server. -[Code](https://github.com/tt-a1i/evermemos-mcp) +[Code](https://github.com/EverMind-AI/EverOS-MCP) · [Setup guide](mcp.md) diff --git a/src/everos/entrypoints/cli/commands/init_cmd.py b/src/everos/entrypoints/cli/commands/init_cmd.py index 5854e14e..9c846b8e 100644 --- a/src/everos/entrypoints/cli/commands/init_cmd.py +++ b/src/everos/entrypoints/cli/commands/init_cmd.py @@ -97,3 +97,6 @@ def init( typer.echo(f" 1. Edit {everos_toml} — fill in API keys (see comments inside)") root_flag = f" --root {resolved}" if root else "" typer.echo(f" 2. Run: everos server start{root_flag}") + typer.echo( + " 3. Connect an MCP client (Claude Code, Codex, Cursor): see docs/mcp.md" + ) diff --git a/src/everos/entrypoints/cli/commands/server.py b/src/everos/entrypoints/cli/commands/server.py index c3f5c0bf..508e7594 100644 --- a/src/everos/entrypoints/cli/commands/server.py +++ b/src/everos/entrypoints/cli/commands/server.py @@ -81,6 +81,11 @@ def start( bootstrap_logger = logging.getLogger("everos.cli.server") bootstrap_logger.info("starting everos on %s:%d", host_resolved, port_resolved) + bootstrap_logger.info( + "MCP clients: uvx everos-mcp with EVEROS_BASE_URL=http://%s:%d (docs/mcp.md)", + host_resolved, + port_resolved, + ) if host_resolved == "0.0.0.0": bootstrap_logger.warning( "binding to 0.0.0.0 exposes the API on all interfaces; EverOS " From 0b620a2470814626ae6ad7face0231abce6774a1 Mon Sep 17 00:00:00 2001 From: zhanghui Date: Mon, 12 Oct 2026 10:38:45 +0800 Subject: [PATCH 2/3] docs(mcp): make the MCP hints usable after review - The server start hint built EVEROS_BASE_URL from the bind address, so `--host 0.0.0.0` printed a URL no client can dial and `--host ::` an invalid one. `mcp_base_url()` maps wildcard binds to 127.0.0.1 and brackets IPv6 literals; the hint is worded "once up" because it is logged before uvicorn binds. - Both CLI hints linked `docs/mcp.md` by relative path, which does not exist in a pip / uvx install (the wheel ships only src/everos). They now use the GitHub URL. - docs/mcp.md no longer names `POST /api/v2/memory/delete`, which this server does not have; the tool table is replaced by a link to the everos-mcp README so it cannot go stale, and the latency note is phrased without a number. - Tests cover the URL mapping, the logged hint and the init step. Co-Authored-By: Claude Fable 5.1 --- docs/mcp.md | 28 ++++++------- .../entrypoints/cli/commands/init_cmd.py | 4 +- src/everos/entrypoints/cli/commands/server.py | 26 ++++++++++-- .../test_cli/test_init_command.py | 3 ++ .../test_cli/test_server_command.py | 41 +++++++++++++++++++ 5 files changed, 82 insertions(+), 20 deletions(-) diff --git a/docs/mcp.md b/docs/mcp.md index ac0b67c9..90a7286e 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -55,26 +55,22 @@ Optional environment variables: `EVEROS_USER_ID` (memory owner, default `default ## What the assistant gets -| Tool | What it does | EverOS endpoint | -|---|---|---| -| `get_profile` | The synthesized user profile, fetched once per session | `POST /api/v2/memory/get` | -| `add_memory` | Stores a durable fact or exchange the moment the user states it | `POST /api/v2/memory/add` + `flush` | -| `search_memory` | Relevance search over past conversations and decisions | `POST /api/v2/memory/search` | -| `list_memories` | Chronological, paginated browsing | `POST /api/v2/memory/get` | -| `record_trajectory` | Records how a task was solved so EverOS can distill cases and skills | `POST /api/v2/memory/add` + `flush` | -| `recall_agent_experience` | Finds distilled cases and skills relevant to the task at hand | `POST /api/v2/memory/search` (agent owner) | -| `forget_session` | Deletes what this connection stored | `POST /api/v2/memory/delete` — see below | - -The server also ships an autonomy protocol through MCP `instructions`, so capable hosts load -the profile at session start, save new facts and recall context without being asked. +Seven tools, all backed by this server's `/api/v2/memory/*` endpoints: `get_profile`, +`add_memory`, `search_memory`, `list_memories`, `record_trajectory`, +`recall_agent_experience` and `forget_session`. The server also ships an autonomy protocol +through MCP `instructions`, so capable hosts load the profile at session start, save new +facts and recall context without being asked. The current tool list and the protocol are +documented in the [everos-mcp README](https://github.com/EverMind-AI/EverOS-MCP#tools); +this page only covers what is specific to a self-hosted EverOS. ## Behaviour on a self-hosted server - **`forget_session` is not available yet.** Self-hosted EverOS has no session-scoped delete - endpoint; the tool reports this instead of failing. Memories are Markdown files under the - memory root (`~/.everos/` by default) — delete them there. -- **New memories are searchable about a second after saving.** `add_memory` returns once - extraction has written the Markdown; the index catches up a moment later. + endpoint ([#483](https://github.com/EverMind-AI/EverOS/issues/483)); the tool reports this + instead of failing. Memories are Markdown files under the memory root (`~/.everos/` by + default) — delete them there. +- **New memories become searchable shortly after saving.** `add_memory` returns once + extraction has written the Markdown; the search index catches up a moment later. `list_memories` shows new entries sooner than `search_memory`. - **Trajectories only become cases when they pass the quality gate.** Short or straightforward runs are stored as episodes but produce no reusable case, so diff --git a/src/everos/entrypoints/cli/commands/init_cmd.py b/src/everos/entrypoints/cli/commands/init_cmd.py index 9c846b8e..b2568dcb 100644 --- a/src/everos/entrypoints/cli/commands/init_cmd.py +++ b/src/everos/entrypoints/cli/commands/init_cmd.py @@ -19,6 +19,8 @@ from everos.config.settings import resolve_root from everos.entrypoints.cli._log_setup import configure_cli_logging +from .server import MCP_GUIDE_URL + _EVEROS_TEMPLATE = Path(__file__).resolve().parents[3] / "config" / "default.toml" _OME_TEMPLATE = Path(__file__).resolve().parents[3] / "config" / "default_ome.toml" @@ -98,5 +100,5 @@ def init( root_flag = f" --root {resolved}" if root else "" typer.echo(f" 2. Run: everos server start{root_flag}") typer.echo( - " 3. Connect an MCP client (Claude Code, Codex, Cursor): see docs/mcp.md" + f" 3. Connect an MCP client (Claude Code, Codex, Cursor): {MCP_GUIDE_URL}" ) diff --git a/src/everos/entrypoints/cli/commands/server.py b/src/everos/entrypoints/cli/commands/server.py index 508e7594..31644ac6 100644 --- a/src/everos/entrypoints/cli/commands/server.py +++ b/src/everos/entrypoints/cli/commands/server.py @@ -23,6 +23,25 @@ no_args_is_help=True, ) +# The wheel ships only ``src/everos``, so the guide has to be linked, not pathed. +MCP_GUIDE_URL = "https://github.com/EverMind-AI/EverOS/blob/main/docs/mcp.md" + +_WILDCARD_BINDS = {"0.0.0.0", "::", ""} + + +def mcp_base_url(host: str, port: int) -> str: + """The ``EVEROS_BASE_URL`` a client on this machine should use. + + ``host`` is the bind address: a wildcard bind (``0.0.0.0`` / ``::``) is + not something a client can connect to, so it becomes loopback; IPv6 + literals are bracketed so the result is a valid URL. + """ + if host in _WILDCARD_BINDS: + host = "127.0.0.1" + elif ":" in host and not host.startswith("["): + host = f"[{host}]" + return f"http://{host}:{port}" + @app.command("start") def start( @@ -82,9 +101,10 @@ def start( bootstrap_logger = logging.getLogger("everos.cli.server") bootstrap_logger.info("starting everos on %s:%d", host_resolved, port_resolved) bootstrap_logger.info( - "MCP clients: uvx everos-mcp with EVEROS_BASE_URL=http://%s:%d (docs/mcp.md)", - host_resolved, - port_resolved, + "once up, MCP clients connect with: uvx everos-mcp, " + "EVEROS_BASE_URL=%s (guide: %s)", + mcp_base_url(host_resolved, port_resolved), + MCP_GUIDE_URL, ) if host_resolved == "0.0.0.0": bootstrap_logger.warning( diff --git a/tests/unit/test_entrypoints/test_cli/test_init_command.py b/tests/unit/test_entrypoints/test_cli/test_init_command.py index da2c9e04..ed3ff68c 100644 --- a/tests/unit/test_entrypoints/test_cli/test_init_command.py +++ b/tests/unit/test_entrypoints/test_cli/test_init_command.py @@ -110,6 +110,9 @@ def test_output_shows_next_steps(runner: CliRunner, tmp_path: Path) -> None: result = runner.invoke(app, ["init", "--root", str(target)]) assert "Next steps" in result.output assert "everos server start" in result.output + assert ( + "https://github.com/EverMind-AI/EverOS/blob/main/docs/mcp.md" in result.output + ) # ``os`` imported above just to keep ruff from complaining; remove if Ruff diff --git a/tests/unit/test_entrypoints/test_cli/test_server_command.py b/tests/unit/test_entrypoints/test_cli/test_server_command.py index 025e15ad..5f410f3f 100644 --- a/tests/unit/test_entrypoints/test_cli/test_server_command.py +++ b/tests/unit/test_entrypoints/test_cli/test_server_command.py @@ -132,3 +132,44 @@ def test_start_with_root_option( result = CliRunner().invoke(root_app, ["server", "start", "--root", str(tmp_path)]) assert result.exit_code == 0, result.stdout assert "kwargs" in captured + + +@pytest.mark.parametrize( + ("host", "port", "expected"), + [ + ("127.0.0.1", 8000, "http://127.0.0.1:8000"), + ("0.0.0.0", 8000, "http://127.0.0.1:8000"), + ("::", 9000, "http://127.0.0.1:9000"), + ("::1", 8000, "http://[::1]:8000"), + ("10.0.0.5", 8765, "http://10.0.0.5:8765"), + ], +) +def test_mcp_base_url_is_something_a_client_can_dial( + host: str, port: int, expected: str +) -> None: + assert server_mod.mcp_base_url(host, port) == expected + + +def test_start_logs_mcp_hint_with_client_url(captured: dict[str, object]) -> None: + import logging + + records: list[str] = [] + + class _Collect(logging.Handler): + def emit(self, record: logging.LogRecord) -> None: + records.append(record.getMessage()) + + handler = _Collect() + logger = logging.getLogger("everos.cli.server") + logger.addHandler(handler) + try: + result = CliRunner().invoke( + root_app, ["server", "start", "--host", "0.0.0.0", "--port", "9000"] + ) + finally: + logger.removeHandler(handler) + assert result.exit_code == 0, result.stdout + hint = [r for r in records if "uvx everos-mcp" in r] + assert hint, records + assert "EVEROS_BASE_URL=http://127.0.0.1:9000" in hint[0] + assert server_mod.MCP_GUIDE_URL in hint[0] From 5c598ca7c5df70aa2e59e15ae1017d9dd4845bef Mon Sep 17 00:00:00 2001 From: Dani Date: Sun, 11 Oct 2026 23:02:06 -0400 Subject: [PATCH 3/3] docs(mcp): note forget_session is not available on self-hosted Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/mcp.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/mcp.md b/docs/mcp.md index 90a7286e..285d88e2 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -55,11 +55,11 @@ Optional environment variables: `EVEROS_USER_ID` (memory owner, default `default ## What the assistant gets -Seven tools, all backed by this server's `/api/v2/memory/*` endpoints: `get_profile`, +Seven tools, backed by this server's `/api/v2/memory/*` endpoints: `get_profile`, `add_memory`, `search_memory`, `list_memories`, `record_trajectory`, -`recall_agent_experience` and `forget_session`. The server also ships an autonomy protocol -through MCP `instructions`, so capable hosts load the profile at session start, save new -facts and recall context without being asked. The current tool list and the protocol are +`recall_agent_experience` and `forget_session` (not yet available here, see below). The +server also ships an autonomy protocol through MCP `instructions`, so capable hosts load the +profile at session start, save new facts and recall context without being asked. The current tool list and the protocol are documented in the [everos-mcp README](https://github.com/EverMind-AI/EverOS-MCP#tools); this page only covers what is specific to a self-hosted EverOS.