memgraph-context-graph 0.12.2__tar.gz → 0.12.3__tar.gz

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/CONTEXT.md

@@ -78,6 +78,14 @@ _Avoid_: MCP tool (the protocol it is served over, not the thing), Graph Connect
 `ConnectorSpec` (`connectors.py`): a graph component's name, its graph class, how to build its **Graph Connector** from **Hook Configuration**, and an optional `doctor` check. Published via the `memgraph_context_graph.connectors` entry-point group; the hook runner, schema setup and `doctor` find connectors only through it. The hub keeps just what it needs before a component is installed: each installable connector's requirement (`INSTALLABLE`) and the default set.
 _Avoid_: Component (the package), Graph Connector (the object a registration builds)
 
+**Graph Epoch**:
+The version of one component's shape in the graph, an integer that only a migration raises; every graph is at epoch 1 until one does. The graph states per component the oldest epoch that may write and read it, `(:ContextGraphSchema {component, epoch, min_writer_epoch, min_reader_epoch})`, and every client checks that before writing or reading (`graph_version.py`): a client older than the graph stops, never corrupts. No node means no constraint. Clients record themselves as `(:ContextGraphClient)`, so a migration can see who still writes an old shape. Not a package version: a release that leaves the graph's shape alone keeps the epoch.
+_Avoid_: schema version, package version, migration (raises an epoch; isn't one)
+
+**Refused-Event Spool**:
+Where a connector's events go while the graph refuses it (**Graph Epoch**): a local, 0600, size-capped JSONL file beside the capture-failure log (`refused_events.py`), holding each event as the capture policy left it, original timestamp included. `update` replays it into the connectors the graph allows again. Its line format is versioned and read by later releases, so a change keeps a reader for every earlier format.
+_Avoid_: queue, buffer, outbox (nothing sends it on its own; `update` replays it)
+
 ## Relationships
 
 - **Memgraph Context Graph** belongs to broader **Context Graph** family.

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memgraph-context-graph
-Version: 0.12.2
+Version: 0.12.3
 Summary: Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)
 License: MIT
 License-File: LICENSE

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/docs/runtime-setup.md

@@ -76,6 +76,11 @@ and constraints. It then runs `doctor`'s checks. Name runtimes to refresh only t
 and the graph's data are untouched, and running it again changes nothing.
 Running agent sessions keep the hooks they loaded: restart them. Outside the uv tool (a virtualenv, say) the
 package step only warns, and you upgrade it yourself first.
+Once a newer Context Graph has reshaped your graph, an older install stops writing (and, if needed, reading) the
+parts it no longer knows instead of corrupting them: the session-start context, the capture-failure log and
+`doctor` say so, and `update` brings it level. What the agents did meanwhile isn't lost: it is kept, redacted
+like any capture, in `refused-events.jsonl` beside the capture-failure log (readable only by you, at most 64 MB),
+and `update` adds it to the graph with its original times.
 
 **Identity and connection.** setup writes `~/.config/context-graph/config.toml`; hooks read their configuration from that file at runtime (see [Configuration](configuration.md) — env vars are **not** read at hook time). To change your identity later:
 

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/docs/sdk-memory.md

@@ -31,6 +31,10 @@ from memgraph_context_graph.sdk import ContextGraphMemory
 memory = ContextGraphMemory(user_id="alice")
 ```
 
+A long-running app keeps working across a Context Graph upgrade elsewhere. About every ten minutes it checks whether
+a newer Context Graph has reshaped the graph. If it has, the app stops writing the parts it no longer knows, keeps
+those events on the machine, and `memgraph-context-graph update` adds them once this install is upgraded.
+
 ## Claude Agent SDK
 
 The SDK's hook callbacks get Claude Code's own hook payloads, so the `claude-code` rules translate them, under `source_sdk = "claude-agent-sdk"`. Python callbacks get no `SessionStart` or `SessionEnd`, which changes two things:

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memgraph-context-graph"
-version = "0.12.2"
+version = "0.12.3"
 description = "Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)"
 readme = "README.md"
 license = { text = "MIT" }

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/src/memgraph_context_graph/cli.py

@@ -405,6 +405,7 @@ def doctor_checks(runtimes: Sequence[str], connectors: Sequence[str]) -> list[_C
     # produce one, the config check already says why, and the rest would only repeat it.
     if _edition_resolves():
         checks.append(_check_memgraph())
+        checks.append(_check_graph_version(connectors))
         for connector in connectors:
             checks.append(_check_connector(connector))
         if any(normalize_connector_name(connector) == "sessions-graph" for connector in connectors):
@@ -503,6 +504,19 @@ def _check_memgraph() -> _CheckResult:
         _close(db)
 
 
+def _check_graph_version(connectors: Sequence[str]) -> _CheckResult:
+    """Whether a newer Context Graph has reshaped the graph past what this install can write or read."""
+    from memgraph_context_graph import graph_version
+
+    rules = graph_version.check_configured(fresh=True)
+    components = [graph_version.HUB, *(normalize_connector_name(connector) for connector in connectors)]
+    refused = [rules.refuse_write(c) for c in components if not rules.may_write(c)]
+    refused += [rules.refuse_read(c) for c in components if not rules.may_read(c)]
+    if refused:
+        return {"name": "graph version", "ok": False, "detail": "; ".join(dict.fromkeys(map(str, refused)))}
+    return {"name": "graph version", "ok": True, "detail": "this install can write and read the graph"}
+
+
 def _close(db: Any) -> None:
     if db is not None:
         db.close()

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/src/memgraph_context_graph/connectors.py

@@ -60,7 +60,7 @@ class ConnectorSpec:
 INSTALLABLE: dict[str, str] = {
     "skills-graph": "skills-graph[memgraph-context-graph]>=0.4.0",
     "actions-graph": "actions-graph[memgraph-context-graph]>=0.7.1",
-    "sessions-graph": "sessions-graph[memgraph-context-graph]>=0.12.2",
+    "sessions-graph": "sessions-graph[memgraph-context-graph]>=0.12.3",
     "resources-graph": "resources-graph[memgraph-context-graph]>=0.3.0",
 }
 

memgraph_context_graph-0.12.3/src/memgraph_context_graph/graph_version.py

@@ -0,0 +1,327 @@
+"""Whether this client may write or read a graph that a newer Context Graph may have reshaped.
+
+A later release may migrate a component's part of the graph to a new shape.
+Clients installed before it keep running: on other machines, against a shared
+Enterprise server, or as a harness's long-lived MCP server. They would write
+the old shape into the new graph, or read it and find nothing. So the graph
+says, per component, the oldest shape a client must know to write or read it:
+
+    (:ContextGraphSchema {component, epoch, min_writer_epoch, min_reader_epoch})
+
+and every client checks that before it writes or reads. This rule is the one
+part of graph versioning frozen into every installed client, so it stays this
+small. The migrations, their ledger and ``epoch`` itself belong to the release
+that writes these nodes. A component with no node has no constraint, so every
+graph written before this module allows everything.
+
+``memgraph-context-graph`` is the component of the shared Session Node, which
+every connector writes through, so a constraint on it holds for all of them.
+
+A client also records itself on each check as
+``(:ContextGraphClient {client_id, version, baseline_epoch, epochs, last_seen})``.
+Before a migration removes an old shape, it can then see whether clients that
+still write that shape are about.
+
+Checks are cached per graph for :data:`CHECK_INTERVAL` in a state file beside
+the capture-failure log, so a hook pays for one at most every few minutes. A
+check that can't reach the graph allows everything and isn't cached: the
+connectors then fail and log on their own.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph import capture_log
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+    from contextlib import AbstractContextManager
+    from pathlib import Path
+
+#: The component that owns the Session Node; a constraint on it covers every connector.
+HUB = "memgraph-context-graph"
+#: The shape every component is at in a graph no migration has touched.
+BASELINE_EPOCH = 1
+#: The epoch of each component's shape this release writes and reads, where it differs from the baseline.
+EPOCHS: dict[str, int] = {}
+#: How long a check holds before the graph is asked again.
+CHECK_INTERVAL = timedelta(minutes=10)
+
+UPDATE_COMMAND = "memgraph-context-graph update"
+
+
+class GraphTooNewError(Exception):
+    """The graph's shape for a component is newer than this client can safely write or read."""
+
+
+def known_epoch(component: str) -> int:
+    """The epoch of *component*'s shape this release writes and reads."""
+    return EPOCHS.get(_normalize(component), BASELINE_EPOCH)
+
+
+@dataclass(frozen=True)
+class Rules:
+    """What the graph asks of its clients: per component, the oldest epoch that may write and read it."""
+
+    min_writer: Mapping[str, int] = field(default_factory=dict)
+    min_reader: Mapping[str, int] = field(default_factory=dict)
+
+    def may_write(self, component: str) -> bool:
+        """Whether this client may write *component*'s part of the graph."""
+        return not self._newer(self.min_writer, component)
+
+    def may_read(self, component: str) -> bool:
+        """Whether this client may read *component*'s part of the graph."""
+        return not self._newer(self.min_reader, component)
+
+    def refuse_write(self, component: str) -> GraphTooNewError:
+        """The error to report for a write :meth:`may_write` refuses."""
+        return GraphTooNewError(_refusal("write", self._newer(self.min_writer, component)))
+
+    def refuse_read(self, component: str) -> GraphTooNewError:
+        """The error to report for a read :meth:`may_read` refuses."""
+        return GraphTooNewError(_refusal("read", self._newer(self.min_reader, component)))
+
+    def notice(self) -> str | None:
+        """One line for the model's session-start context while anything is refused, else None."""
+        writes = sorted(c for c, epoch in self.min_writer.items() if epoch > known_epoch(c))
+        reads = sorted(c for c, epoch in self.min_reader.items() if epoch > known_epoch(c))
+        if not writes and not reads:
+            return None
+        paused = ", ".join(dict.fromkeys(writes + reads))
+        # Refused writes are spooled for replay (refused_events); refused reads have nothing to keep.
+        kept = " What this session does is kept on this machine and added after the update." if writes else ""
+        return (
+            f"Context Graph is paused for {paused}: a newer Context Graph upgraded this graph, and the "
+            f"version installed here can't safely use it.{kept} Ask the user to run `{UPDATE_COMMAND}`."
+        )
+
+    def _newer(self, required: Mapping[str, int], component: str) -> list[str]:
+        """The components among *component* and the hub whose required epoch is above what this client knows."""
+        return [c for c in dict.fromkeys((HUB, _normalize(component))) if required.get(c, 0) > known_epoch(c)]
+
+
+def _refusal(action: str, components: list[str]) -> str:
+    return (
+        f"this graph needs a newer Context Graph to {action} {', '.join(components)} than the one installed "
+        f"here; run {UPDATE_COMMAND}"
+    )
+
+
+def setup(db: Any) -> None:
+    """Create the constraints and indexes the check and the client record use; safe to repeat."""
+    db.query("CREATE CONSTRAINT ON (s:ContextGraphSchema) ASSERT s.component IS UNIQUE;")
+    db.query("CREATE INDEX ON :ContextGraphSchema;")
+    db.query("CREATE CONSTRAINT ON (c:ContextGraphClient) ASSERT c.client_id IS UNIQUE;")
+    db.query("CREATE INDEX ON :ContextGraphClient(client_id);")
+
+
+def setup_at(memgraph_env: dict[str, str]) -> None:
+    """:func:`setup` on the graph a resolved Memgraph environment (``resolve_memgraph_env``) names."""
+    with _connect(memgraph_env) as db:
+        setup(db)
+
+
+def check(
+    connect: Callable[[], AbstractContextManager[Any]],
+    *,
+    url: str,
+    database: str = "",
+    fresh: bool = False,
+    strict: bool = False,
+    now: datetime | None = None,
+) -> Rules:
+    """The graph's rules for this client, from the cache while it holds, else from the graph.
+
+    Args:
+        connect: Opens a client for the graph, called only when the cache doesn't hold.
+        url: The graph's Bolt URL; with *database*, what the cache keys on.
+        database: The Memgraph database, empty for the default one.
+        fresh: Ask the graph even while the cache holds.
+        strict: Raise when the graph can't be asked, instead of allowing everything.
+        now: The current time, for tests.
+
+    Returns:
+        The rules; no rules (everything allowed) when the graph can't be asked and not *strict*.
+    """
+    now = now or datetime.now(timezone.utc)
+    state = _load_state()
+    key = _graph_key(url, database)
+    cached = state["graphs"].get(key)
+    if not fresh and cached is not None and _holds(cached, now):
+        return _rules_from(cached.get("rules"))
+    try:
+        with connect() as db:
+            rules = read_rules(db)
+            # A client that can read but not write the graph (a shared space) still gets its rules.
+            with contextlib.suppress(Exception):
+                _record_client(db, state["client_id"], now)
+    except Exception:
+        if strict:
+            raise
+        return Rules()
+    state["graphs"][key] = {"checked_at": now.isoformat(), "rules": _rules_to(rules)}
+    _save_state(state)
+    return rules
+
+
+def cached_rules(url: str, database: str = "") -> Rules:
+    """The rules this client last read from the graph, without asking it; none when it never has."""
+    cached = _load_state()["graphs"].get(_graph_key(url, database))
+    return _rules_from(cached.get("rules")) if cached is not None else Rules()
+
+
+def check_configured(*, fresh: bool = False) -> Rules:
+    """:func:`check` for the graph the config file names; no rules when the config can't name one."""
+    from memgraph_context_graph.adapters._identity import resolve_memgraph_env
+
+    try:
+        env = resolve_memgraph_env()
+    except Exception:
+        return Rules()
+    return check_at(env, fresh=fresh)
+
+
+def check_at(memgraph_env: dict[str, str], *, fresh: bool = False, strict: bool = False) -> Rules:
+    """:func:`check` for the graph a resolved Memgraph environment (``resolve_memgraph_env``) names."""
+    return check(
+        lambda: _connect(memgraph_env),
+        url=memgraph_env["MEMGRAPH_URL"],
+        database=memgraph_env["MEMGRAPH_DATABASE"],
+        fresh=fresh,
+        strict=strict,
+    )
+
+
+def _connect(memgraph_env: dict[str, str]) -> AbstractContextManager[Any]:
+    from memgraph_context_graph.hooks.runner import memgraph_kwargs
+    from memgraph_toolbox.api.memgraph import Memgraph
+
+    return contextlib.closing(Memgraph(**memgraph_kwargs(memgraph_env)))
+
+
+def configured_notice() -> str | None:
+    """The session-start notice for the graph the config file names, from the cache alone; never raises."""
+    from memgraph_context_graph.adapters._identity import resolve_memgraph_env
+
+    try:
+        env = resolve_memgraph_env()
+        return cached_rules(env["MEMGRAPH_URL"], env["MEMGRAPH_DATABASE"]).notice()
+    except Exception:
+        return None
+
+
+def read_rules(db: Any) -> Rules:
+    """The graph's rules, read from its ``(:ContextGraphSchema)`` nodes."""
+    rows = db.query(
+        "MATCH (s:ContextGraphSchema) "
+        "RETURN s.component AS component, s.min_writer_epoch AS min_writer, s.min_reader_epoch AS min_reader"
+    )
+    min_writer: dict[str, int] = {}
+    min_reader: dict[str, int] = {}
+    for row in rows:
+        component = row.get("component")
+        if not isinstance(component, str):
+            continue
+        if isinstance(row.get("min_writer"), int):
+            min_writer[_normalize(component)] = row["min_writer"]
+        if isinstance(row.get("min_reader"), int):
+            min_reader[_normalize(component)] = row["min_reader"]
+    return Rules(min_writer, min_reader)
+
+
+def _client_version() -> str:
+    from memgraph_context_graph import __version__
+
+    return __version__
+
+
+def _record_client(db: Any, client_id: str, now: datetime) -> None:
+    from memgraph_toolbox.api.memgraph import merge_with_retry
+
+    merge_with_retry(
+        db,
+        """
+        MERGE (c:ContextGraphClient {client_id: $client_id})
+        SET c.version = $version, c.baseline_epoch = $baseline, c.epochs = $epochs, c.last_seen = $now
+        """,
+        params={
+            "client_id": client_id,
+            "version": _client_version(),
+            "baseline": BASELINE_EPOCH,
+            "epochs": dict(EPOCHS),
+            "now": now.isoformat(),
+        },
+    )
+
+
+def _holds(cached: dict[str, Any], now: datetime) -> bool:
+    try:
+        checked_at = datetime.fromisoformat(cached["checked_at"])
+    except (KeyError, TypeError, ValueError):
+        return False
+    return timedelta(0) <= now - checked_at < CHECK_INTERVAL
+
+
+def _rules_to(rules: Rules) -> dict[str, dict[str, int]]:
+    return {"min_writer": dict(rules.min_writer), "min_reader": dict(rules.min_reader)}
+
+
+def _rules_from(raw: Any) -> Rules:
+    if not isinstance(raw, dict):
+        return Rules()
+
+    def epochs(name: str) -> dict[str, int]:
+        value = raw.get(name)
+        if not isinstance(value, dict):
+            return {}
+        return {str(c): e for c, e in value.items() if isinstance(e, int)}
+
+    return Rules(epochs("min_writer"), epochs("min_reader"))
+
+
+def _graph_key(url: str, database: str) -> str:
+    return f"{url}#{database}"
+
+
+def _normalize(component: str) -> str:
+    from memgraph_context_graph.tools import normalize_connector_name
+
+    return normalize_connector_name(component)
+
+
+def state_path() -> Path:
+    """The cache file: beside the capture-failure log, so a config chosen with ``CONTEXT_GRAPH_CONFIG`` gets its own."""
+    log = capture_log.path()
+    return log.with_name(log.name.removesuffix("capture-failures.jsonl") + "graph-version.json")
+
+
+def _load_state() -> dict[str, Any]:
+    try:
+        state = json.loads(state_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        state = {}
+    if not isinstance(state, dict):
+        state = {}
+    if not isinstance(state.get("client_id"), str):
+        state["client_id"] = uuid.uuid4().hex
+    if not isinstance(state.get("graphs"), dict):
+        state["graphs"] = {}
+    return state
+
+
+def _save_state(state: dict[str, Any]) -> None:
+    """Write the cache whole, through a rename, so a hook running at the same moment never reads half of it."""
+    target = state_path()
+    with contextlib.suppress(OSError):
+        target.parent.mkdir(parents=True, exist_ok=True)
+        temporary = target.with_name(f"{target.name}.{os.getpid()}.tmp")
+        temporary.write_text(json.dumps(state), encoding="utf-8")
+        os.replace(temporary, target)

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/src/memgraph_context_graph/hooks/runner.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import contextlib
 import json
 import os
 import sys
@@ -10,7 +11,7 @@ import threading
 import time
 from typing import TYPE_CHECKING, Any, NoReturn, TypedDict
 
-from memgraph_context_graph import capture_log
+from memgraph_context_graph import capture_log, graph_version, refused_events
 from memgraph_context_graph.capture_policy import CapturePolicy, policy_from_config
 from memgraph_context_graph.connectors import (
     INSTALLABLE,
@@ -68,6 +69,7 @@ def create_link(
     memgraph_env: dict[str, str] | None = None,
     on_error: ConnectorFailureHandler | None = None,
     policy: CapturePolicy | None = None,
+    spool_refused: bool = True,
 ) -> AgentLink:
     """Create an AgentLink with optional connectors named by CLI/config.
 
@@ -79,6 +81,13 @@ def create_link(
     Memgraph raises, since no connector could run. Without it each connector
     connects on its own, as library callers always have.
 
+    With *memgraph_env*, a connector whose part of the graph a newer Context
+    Graph has reshaped (:mod:`memgraph_context_graph.graph_version`) is not
+    added: it fails like one that can't be set up, with a
+    :class:`~memgraph_context_graph.graph_version.GraphTooNewError`, and
+    its events are spooled for ``update`` to replay
+    (:mod:`memgraph_context_graph.refused_events`).
+
     Args:
         connector_names: Connectors to enable, by distribution name.
         memgraph_env: Resolved Memgraph settings (``resolve_memgraph_env``).
@@ -86,6 +95,8 @@ def create_link(
             event, is reported here and the others still run. Without it the
             first failure raises.
         policy: The capture policy every event passes before a connector sees it.
+        spool_refused: Keep refused connectors' events for replay; off for the
+            replay itself, which keeps them on its own terms.
 
     Raises:
         ValueError: if a connector name is not supported, or Memgraph can't be reached.
@@ -98,13 +109,28 @@ def create_link(
 
     link = AgentLink(on_error=report if on_error is not None else None, policy=policy)
     shared = _hook_memgraph(memgraph_env) if names and memgraph_env is not None else None
+    rules = (
+        graph_version.check(
+            lambda: contextlib.nullcontext(shared),
+            url=memgraph_env["MEMGRAPH_URL"],
+            database=memgraph_env["MEMGRAPH_DATABASE"],
+        )
+        if shared is not None and memgraph_env is not None
+        else graph_version.Rules()
+    )
+    refused: list[str] = []
     for name in names:
         try:
+            if not rules.may_write(name):
+                refused.append(name)
+                raise rules.refuse_write(name)
             link.add_connector(_build_connector(name, memgraph_env, memgraph=shared))
         except Exception as exc:
             if on_error is None:
                 raise
             on_error(name, None, exc)
+    if refused and spool_refused:
+        link.add_connector(refused_events.Spool(refused))
     return link
 
 
@@ -420,11 +446,17 @@ def session_start_text(connector_names: list[str], payload: dict[str, Any] | Non
     its index of the user's memory files, standing in for the harness's own
     memory it replaces (#484). Each runtime wraps the text in the shape its
     session-start hook output takes (``RuntimeSpec.session_context``).
+
+    While a newer Context Graph's graph refuses this client, a notice comes first
+    (:func:`~memgraph_context_graph.graph_version.configured_notice`), so the
+    model can tell the user to update.
     """
     from memgraph_context_graph.tools import session_hints
 
+    notice = graph_version.configured_notice()
+    lines = [notice] if notice else []
     try:
-        hints = session_hints(connector_names, payload=_with_cwd(payload or {}))
+        lines += session_hints(connector_names, payload=_with_cwd(payload or {}))
     except Exception as exc:  # A tool that fails to load must not fail the hook; the model just isn't told.
         capture_log.record_failure(
             "respond",
@@ -433,8 +465,7 @@ def session_start_text(connector_names: list[str], payload: dict[str, Any] | Non
             hook_event="SessionStart",
             session_id=_payload_session_id(payload or {}),
         )
-        return None
-    return "\n".join(hints) or None
+    return "\n".join(lines) or None
 
 
 def _with_cwd(payload: dict[str, Any]) -> dict[str, Any]:

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.3}/src/memgraph_context_graph/mcp_server.py

@@ -20,7 +20,9 @@ from __future__ import annotations
 import os
 from typing import TYPE_CHECKING, Any
 
-from memgraph_context_graph.tools import Tool, ToolError, is_available, load_tools
+from memgraph_context_graph import graph_version
+from memgraph_context_graph.graph_version import GraphTooNewError
+from memgraph_context_graph.tools import Tool, ToolError, is_available, load_tools, writes_graph
 
 if TYPE_CHECKING:
     from mcp.server.lowlevel import Server
@@ -67,8 +69,8 @@ def build_server(tools: dict[str, Tool] | None = None, *, instructions: str | No
             return _error(f"Unknown tool: {name}")
         try:
             # Tools query Memgraph synchronously; a thread keeps the server responsive.
-            result = await to_thread.run_sync(tool.call, arguments or {}, config)
-        except ToolError as exc:
+            result = await to_thread.run_sync(_call_checked, tool, arguments or {}, config)
+        except (ToolError, GraphTooNewError) as exc:
             return _error(str(exc))
         return types.CallToolResult(content=[types.TextContent(type="text", text=result.text)])
 
@@ -87,6 +89,19 @@ def build_server(tools: dict[str, Tool] | None = None, *, instructions: str | No
     return Server(SERVER_NAME, instructions=instructions, on_list_tools=on_list_tools, on_call_tool=on_call_tool)
 
 
+def _call_checked(tool: Tool, arguments: dict[str, Any], config: Any) -> Any:
+    """Call *tool* unless a newer Context Graph reshaped the graph it reads, or writes (``writes_graph``).
+
+    The server outlives package upgrades, so it checks on each call rather than once at start; the check is cached.
+    """
+    rules = graph_version.check_configured()
+    if not rules.may_read(tool.connector):
+        raise rules.refuse_read(tool.connector)
+    if writes_graph(tool) and not rules.may_write(tool.connector):
+        raise rules.refuse_write(tool.connector)
+    return tool.call(arguments, config)
+
+
 def session_instructions(tools: dict[str, Tool]) -> str | None:
     """The session-start text for the directory the harness started this server in."""
     from memgraph_context_graph.hooks.runner import session_start_text