memgraph-context-graph 0.5.0__py3-none-any.whl

memgraph_context_graph/hooks/runner.py

@@ -0,0 +1,311 @@
+"""Generic command-hook CLI runner, shared by every registered runtime plugin.
+
+Every command-hook adapter (``adapters/codex.py``, ``adapters/claude_code.py``)
+used to duplicate this exact stdin-loading / connector-construction / run
+sequence, differing only in which adapter class to instantiate and a handful
+of env var names. This collapses that into one implementation driven by a
+``RuntimeCLIPlugin`` (see ``runtime_plugin.py``).
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from typing import TYPE_CHECKING, Any, TypedDict
+
+from memgraph_context_graph.events import ToolStartEvent
+from memgraph_context_graph.link import AgentLink
+from memgraph_context_graph.protocols import GraphConnector
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from memgraph_context_graph.events import Event
+    from memgraph_context_graph.hooks.runtime_plugin import RuntimeCLIPlugin
+
+
+def load_payload(stream: Any | None = None) -> dict[str, Any]:
+    """Read one JSON hook payload from a text stream (stdin by default)."""
+    if stream is None:
+        stream = sys.stdin
+    raw = stream.read()
+    if not raw.strip():
+        return {}
+    payload = json.loads(raw)
+    if not isinstance(payload, dict):
+        msg = "Hook payload must be a JSON object"
+        raise TypeError(msg)
+    return payload
+
+
+def create_link(connector_names: Iterable[str] = (), *, memgraph_env: dict[str, str] | None = None) -> AgentLink:
+    """Create an AgentLink with optional connectors named by CLI/config.
+
+    Runtime-agnostic: connectors (skills-graph, actions-graph, sessions-graph, resources-graph)
+    are graph components, not tied to any particular runtime adapter.
+    """
+    link = AgentLink()
+    for connector_name in connector_names:
+        normalized = connector_name.strip().replace("-", "_")
+        if not normalized:
+            continue
+        if normalized == "skills_graph":
+            _add_skills_graph_connector(link, memgraph_env)
+        elif normalized == "actions_graph":
+            _add_actions_graph_connector(link, memgraph_env)
+        elif normalized == "sessions_graph":
+            _add_sessions_graph_connector(link, memgraph_env)
+        elif normalized == "resources_graph":
+            _add_resources_graph_connector(link, memgraph_env)
+        else:
+            msg = f"Unsupported connector: {connector_name}"
+            raise ValueError(msg)
+    return link
+
+
+_SCHEMA_COMPONENTS = {
+    "skills_graph": ("skills_graph", "SkillGraph"),
+    "actions_graph": ("actions_graph", "ActionsGraph"),
+    "sessions_graph": ("sessions_graph", "SessionsGraph"),
+    "resources_graph": ("resources_graph", "ResourcesGraph"),
+}
+
+
+def setup_connector_schemas(connector_names: Iterable[str], *, memgraph_env: dict[str, str] | None = None) -> None:
+    """Create the Memgraph schema (indexes, constraints) for each named connector.
+
+    Raises:
+        ValueError: if a connector name is not supported.
+    """
+    kwargs = _memgraph_kwargs(memgraph_env)
+    for connector_name in connector_names:
+        normalized = connector_name.strip().replace("-", "_")
+        if not normalized:
+            continue
+        if normalized not in _SCHEMA_COMPONENTS:
+            raise ValueError(f"Unsupported connector: {connector_name}")
+        module_name, class_name = _SCHEMA_COMPONENTS[normalized]
+        component_class = getattr(importlib.import_module(module_name), class_name)
+        component_class(**kwargs).setup()
+
+
+def _env_prefix(runtime_name: str) -> str:
+    return "MEMGRAPH_CONTEXT_GRAPH_" + runtime_name.strip().replace("-", "_").upper()
+
+
+def _connectors_from_env(runtime_name: str) -> list[str]:
+    value = os.environ.get(f"{_env_prefix(runtime_name)}_CONNECTORS", "")
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+def _debug_log(runtime_name: str, message: str) -> None:
+    if os.environ.get(f"{_env_prefix(runtime_name)}_DEBUG") == "1":
+        print(message, file=sys.stderr)
+
+
+def run_hook(plugin: RuntimeCLIPlugin, argv: Sequence[str] | None = None) -> int:
+    """Read one hook payload from stdin, run it through *plugin*, print a response.
+
+    This is what ``memgraph-context-graph hook run <runtime>`` invokes: parse
+    the shared CLI flags, resolve Memgraph config, translate the payload via
+    ``plugin.adapter_class``, and write back whatever ``plugin.response_for_payload``
+    says the runtime expects -- identical flow for every registered runtime.
+    """
+    parser = argparse.ArgumentParser(description=f"Bridge {plugin.name} hooks to memgraph-context-graph.")
+    parser.add_argument(
+        "--connector",
+        action="append",
+        default=None,
+        help="Graph connector to enable. Currently supported: skills-graph, actions-graph, sessions-graph, resources-graph.",
+    )
+    parser.add_argument(
+        "--session-id",
+        default=None,
+        help="Override the session id from the hook payload.",
+    )
+    parser.add_argument(
+        "--event-name",
+        default=None,
+        help="Supply the event name when the runtime payload omits it.",
+    )
+    parser.add_argument("--memgraph-url", default=None, help="Memgraph Bolt URL. Overrides config file value.")
+    parser.add_argument("--memgraph-user", default=None, help="Memgraph username. Overrides config file value.")
+    parser.add_argument("--memgraph-password", default=None, help="Memgraph password. Overrides config file value.")
+    parser.add_argument("--memgraph-database", default=None, help="Memgraph database. Overrides config file value.")
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Return a non-zero status if the hook payload cannot be recorded.",
+    )
+    args = parser.parse_args(argv)
+
+    connector_names = args.connector
+    if connector_names is None:
+        connector_names = _connectors_from_env(plugin.name)
+
+    from memgraph_context_graph.adapters._identity import resolve_memgraph_env
+
+    payload: dict[str, Any] = {}
+    try:
+        # Inside the guard: an edition the config can't resolve skips the hook like any other failure.
+        memgraph_env = resolve_memgraph_env(
+            url=args.memgraph_url,
+            user=args.memgraph_user,
+            password=args.memgraph_password,
+            database=args.memgraph_database,
+        )
+        payload = load_payload()
+        if args.event_name is not None:
+            payload.setdefault("hook_event_name", args.event_name)
+        link = create_link(connector_names, memgraph_env=memgraph_env)
+        tool_starts = _ToolStarts()
+        link.add_connector(tool_starts)
+        adapter = plugin.adapter_class(link, session_id=args.session_id)
+        adapter.handle_payload(payload)
+        _print_response(plugin, payload, connector_names, before_tool=_context_before_tool(link, tool_starts.events))
+    except Exception as exc:
+        strict_env = os.environ.get(f"{_env_prefix(plugin.name)}_STRICT") == "1"
+        if args.strict or strict_env:
+            raise
+        _print_response(plugin, payload, connector_names)
+        _debug_log(plugin.name, f"memgraph-context-graph {plugin.name} hook skipped: {exc}")
+    return 0
+
+
+def _print_response(
+    plugin: RuntimeCLIPlugin, payload: dict[str, Any], connector_names: list[str], *, before_tool: Sequence[str] = ()
+) -> None:
+    response = plugin.response_for_payload(payload) or {}
+    if payload.get("hook_event_name") == "SessionStart":
+        response.update(session_start_context(connector_names, payload))
+    render = getattr(plugin, "context_before_tool_response", None)
+    if before_tool and render is not None:
+        response.update(render("\n".join(before_tool)) or {})
+    if response:
+        print(json.dumps(response))
+
+
+class _ToolStarts(GraphConnector):
+    """Keeps the tool-start events one payload produced, to ask the connectors about afterwards."""
+
+    def __init__(self) -> None:
+        self.events: list[ToolStartEvent] = []
+
+    def supports(self, event: Event) -> bool:
+        return isinstance(event, ToolStartEvent)
+
+    def on_event(self, event: Event) -> None:
+        if isinstance(event, ToolStartEvent):
+            self.events.append(event)
+
+
+def _context_before_tool(link: AgentLink, events: list[ToolStartEvent]) -> list[str]:
+    """Every connector's line for the tools about to run; a connector that fails adds nothing."""
+    lines: list[str] = []
+    for event in events:
+        for connector in link.connectors:
+            try:
+                line = connector.context_before_tool(event)
+            except Exception:
+                line = None
+            if line:
+                lines.append(line)
+    return lines
+
+
+def session_start_context(connector_names: list[str], payload: dict[str, Any] | None = None) -> dict[str, Any]:
+    """The SessionStart output telling the model which memory tools it has; empty when none.
+
+    Recall is announced in one line and never pushes retrieved content: the
+    model calls it when a question needs memory (#394). The ``memory`` tool
+    adds its index of the user's memory files instead, standing in for the
+    harness's own memory it replaces (#484). Claude Code and Codex read the
+    same shape.
+    """
+    from memgraph_context_graph.tools import session_hints
+
+    try:
+        hints = session_hints(connector_names, payload=payload)
+    except Exception:  # A tool that fails to load must not fail the hook.
+        return {}
+    if not hints:
+        return {}
+    return {"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "\n".join(hints)}}
+
+
+def _add_skills_graph_connector(link: AgentLink, memgraph_env: dict[str, str] | None = None) -> None:
+    try:
+        from skills_graph import SkillGraph
+        from skills_graph.connector import SkillGraphConnector
+    except ImportError as exc:
+        msg = "skills-graph is required for the skills-graph connector"
+        raise ImportError(msg) from exc
+
+    kwargs = _memgraph_kwargs(memgraph_env)
+    graph = SkillGraph(**kwargs)
+    link.add_connector(SkillGraphConnector(graph))
+
+
+def _add_sessions_graph_connector(link: AgentLink, memgraph_env: dict[str, str] | None = None) -> None:
+    try:
+        from sessions_graph import SessionsGraph
+        from sessions_graph.connector import SessionsGraphConnector
+    except ImportError as exc:
+        msg = "sessions-graph is required for the sessions-graph connector"
+        raise ImportError(msg) from exc
+
+    from memgraph_context_graph.adapters._identity import resolve_auto_reconcile
+
+    kwargs = _memgraph_kwargs(memgraph_env)
+    graph = SessionsGraph(**kwargs)
+    link.add_connector(SessionsGraphConnector(graph, auto_reconcile=resolve_auto_reconcile()))
+
+
+def _add_actions_graph_connector(link: AgentLink, memgraph_env: dict[str, str] | None = None) -> None:
+    try:
+        from actions_graph import ActionsGraph
+        from actions_graph.connector import ActionsGraphConnector
+    except ImportError as exc:
+        msg = "actions-graph is required for the actions-graph connector"
+        raise ImportError(msg) from exc
+
+    kwargs = _memgraph_kwargs(memgraph_env)
+    graph = ActionsGraph(**kwargs)
+    link.add_connector(ActionsGraphConnector(graph))
+
+
+def _add_resources_graph_connector(link: AgentLink, memgraph_env: dict[str, str] | None = None) -> None:
+    try:
+        from resources_graph import ResourcesGraph
+        from resources_graph.connector import ResourcesGraphConnector
+    except ImportError as exc:
+        msg = "resources-graph is required for the resources-graph connector"
+        raise ImportError(msg) from exc
+
+    kwargs = _memgraph_kwargs(memgraph_env)
+    link.add_connector(ResourcesGraphConnector(ResourcesGraph(**kwargs)))
+
+
+# A closed key set (never `memgraph`) so `Component(**kwargs)` below can't be
+# read as colliding with that parameter's `Memgraph | None` type, unlike a
+# plain `dict[str, str]`.
+class _MemgraphKwargs(TypedDict, total=False):
+    url: str
+    username: str
+    password: str
+    database: str
+
+
+def _memgraph_kwargs(memgraph_env: dict[str, str] | None) -> _MemgraphKwargs:
+    """Convert resolved memgraph env dict to kwargs for graph component constructors."""
+    if memgraph_env is None:
+        return {}
+    return {
+        "url": memgraph_env["MEMGRAPH_URL"],
+        "username": memgraph_env["MEMGRAPH_USER"],
+        "password": memgraph_env["MEMGRAPH_PASSWORD"],
+        "database": memgraph_env["MEMGRAPH_DATABASE"],
+    }

memgraph_context_graph/hooks/runtime_plugin.py

@@ -0,0 +1,85 @@
+"""Registry for command-hook runtime plugins.
+
+A command-hook runtime (Codex, Claude Code, ...) registers itself by exposing
+an object with this shape under the ``memgraph_context_graph.runtimes`` entry
+point group, in its own package's ``pyproject.toml``:
+
+    [project.entry-points."memgraph_context_graph.runtimes"]
+    codex = "memgraph_context_graph.adapters.codex:PLUGIN"
+
+No changes to memgraph-context-graph itself are needed to add a new runtime.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+_ENTRY_POINT_GROUP = "memgraph_context_graph.runtimes"
+
+
+@runtime_checkable
+class RuntimeCLIPlugin(Protocol):
+    """What a runtime must supply to be usable by memgraph-context-graph's CLI.
+
+    ``init`` is optional -- a runtime that has no project-local hook-config
+    file to generate (or hasn't implemented one yet) may omit it; callers
+    should use ``getattr(plugin, "init", None)`` rather than assume it exists.
+    """
+
+    # Both read-only: a plain mutable attribute here would require every
+    # plugin's own fields to be writable with these exact types (invariance),
+    # rejecting real plugins that are frozen dataclasses (name) or declare a
+    # narrower adapter_class (type[RuntimeAdapter] instead of type[Any]).
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def adapter_class(self) -> type[Any]: ...
+
+    @property
+    def probe_payload(self) -> Mapping[str, Any]: ...
+
+    def response_for_payload(self, payload: dict[str, Any]) -> dict[str, Any] | None: ...
+
+    def build_hooks_config(self, command: str, *, timeout: int = 30) -> dict[str, Any]: ...
+
+    # Deliberately not a protocol member beyond this point: `init` is optional
+    # (see class docstring) and accessed via `getattr(plugin, "init", None)`,
+    # never through a RuntimeCLIPlugin-typed reference.
+
+
+class UnknownRuntimeError(KeyError):
+    """Raised when no plugin is registered for a requested runtime name."""
+
+
+def _normalize(name: str) -> str:
+    return name.strip().replace("_", "-")
+
+
+def load_runtime_plugins() -> dict[str, RuntimeCLIPlugin]:
+    """Discover every registered runtime plugin, keyed by its normalized ``name``."""
+    plugins: dict[str, RuntimeCLIPlugin] = {}
+    for entry_point in metadata.entry_points(group=_ENTRY_POINT_GROUP):
+        plugin = entry_point.load()
+        plugins[_normalize(plugin.name)] = plugin
+    return plugins
+
+
+def get_runtime_plugin(name: str) -> RuntimeCLIPlugin:
+    """Look up a registered runtime plugin by name.
+
+    Raises ``UnknownRuntimeError`` (listing what *is* registered) if none
+    matches -- the CLI catches this to print a clear error instead of a
+    traceback.
+    """
+    plugins = load_runtime_plugins()
+    normalized = _normalize(name)
+    if normalized not in plugins:
+        available = ", ".join(sorted(plugins)) or "(none registered)"
+        msg = f"Unknown runtime: {name!r}. Available: {available}"
+        raise UnknownRuntimeError(msg)
+    return plugins[normalized]

memgraph_context_graph/link.py

@@ -0,0 +1,50 @@
+"""AgentLink — the central hub that routes events to graph connectors.
+
+An ``AgentLink`` instance holds a list of :class:`GraphConnector` instances.
+Runtime adapters call :meth:`emit` to broadcast events to every registered
+connector.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .events import Event
+    from .protocols import GraphConnector
+
+
+class AgentLink:
+    """Routes :class:`Event` objects from runtime adapters to graph connectors.
+
+    Usage::
+
+        link = AgentLink()
+        link.add_connector(SkillGraphConnector(skill_graph))
+        link.add_connector(MyGraphConnector(graph))
+
+        adapter = ClaudeAdapter(link, session_id="s-1")
+        hooks = adapter.get_runtime_hooks()
+    """
+
+    def __init__(self) -> None:
+        self._connectors: list[GraphConnector] = []
+
+    def add_connector(self, connector: GraphConnector) -> None:
+        """Register a graph connector."""
+        self._connectors.append(connector)
+
+    def remove_connector(self, connector: GraphConnector) -> None:
+        """Unregister a graph connector."""
+        self._connectors.remove(connector)
+
+    @property
+    def connectors(self) -> list[GraphConnector]:
+        """Return all registered connectors (read-only snapshot)."""
+        return list(self._connectors)
+
+    def emit(self, event: Event) -> None:
+        """Broadcast an event to all connectors that support it."""
+        for connector in self._connectors:
+            if connector.supports(event):
+                connector.on_event(event)

memgraph_context_graph/mcp_server.py

@@ -0,0 +1,102 @@
+"""``memgraph-context-graph mcp``: a stdio MCP server for every registered tool.
+
+The harness starts it (the Claude Code and Codex plugins bundle it), so like
+the hooks it reads configuration from the config file alone. Needs the
+``mcp`` extra: ``memgraph-context-graph[mcp]``.
+
+A result carries the tool's text only, never ``structuredContent``: Claude
+Code and Codex both show the model the structured JSON *instead of* the text
+when a result has both, and the text is the form recall was benchmarked in.
+Programs get the JSON from the CLI (``memgraph-context-graph recall --json``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.tools import Tool, ToolError, is_available, load_tools
+
+if TYPE_CHECKING:
+    from mcp.server.lowlevel import Server
+
+SERVER_NAME = "context-graph"
+
+
+def build_server(tools: dict[str, Tool] | None = None) -> Server:
+    """An MCP server exposing ``tools``, all registered tools by default.
+
+    Each listing and call re-checks the config file, so a tool whose
+    ``available`` check fails (e.g. ``memory`` before the user opts in) is
+    hidden and refused. Harnesses list tools once per session, so turning a
+    tool on shows up in the next session.
+
+    Supports mcp 1.x, which registers handlers through decorators, and 2.x,
+    which takes them as constructor arguments; the protocol is the same.
+    """
+    import mcp.types as types
+    from anyio import to_thread
+    from mcp.server.lowlevel import Server
+
+    from memgraph_context_graph.adapters._identity import reload_config
+
+    tools = load_tools() if tools is None else tools
+
+    def current_config() -> Any:
+        # The server lives as long as the harness session; re-read so
+        # `setup --memory-backend` or `config set` take effect mid-session.
+        return reload_config()
+
+    async def list_tools() -> list[types.Tool]:
+        config = current_config()
+        return [
+            types.Tool(name=tool.name, description=tool.description, inputSchema=tool.input_schema)
+            for tool in tools.values()
+            if is_available(tool, config)
+        ]
+
+    async def call_tool(name: str, arguments: dict[str, Any] | None) -> types.CallToolResult:
+        config = current_config()
+        tool = tools.get(name)
+        if tool is None or not is_available(tool, config):
+            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:
+            return _error(str(exc))
+        return types.CallToolResult(content=[types.TextContent(type="text", text=result.text)])
+
+    if hasattr(Server, "call_tool"):  # mcp 1.x
+        server: Server = Server(SERVER_NAME)
+        server.list_tools()(list_tools)
+        server.call_tool()(call_tool)
+        return server
+
+    async def on_list_tools(ctx: Any, params: Any) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=await list_tools())
+
+    async def on_call_tool(ctx: Any, params: Any) -> types.CallToolResult:
+        return await call_tool(params.name, params.arguments)
+
+    return Server(SERVER_NAME, on_list_tools=on_list_tools, on_call_tool=on_call_tool)
+
+
+def serve() -> int:
+    """Serve over stdio until the harness closes the stream."""
+    import anyio
+    from mcp.server.stdio import stdio_server
+
+    server = build_server()
+
+    async def run() -> None:
+        async with stdio_server() as (read, write):
+            await server.run(read, write, server.create_initialization_options())
+
+    anyio.run(run)
+    return 0
+
+
+def _error(message: str) -> Any:
+    import mcp.types as types
+
+    return types.CallToolResult(content=[types.TextContent(type="text", text=message)], isError=True)

memgraph_context_graph/memory_backend.py

@@ -0,0 +1,144 @@
+"""Switching a user's harness memory between the harness's own and Context Graph.
+
+Neither Claude Code nor Codex lets another store stand in for its built-in
+memory, so "Context Graph as the memory backend" means: turn the harness's
+memory off in its own user-level config, record ``[memory] backend =
+"context-graph"`` in ours (which turns on the ``memory`` tool and the
+session-start index), and bring the harness's existing memories across once,
+so opting in never starts from empty.
+
+A runtime plugin takes part by exposing ``native_memory``, an object with the
+:class:`NativeMemory` shape. Runtimes without one can't switch.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol
+
+from memgraph_context_graph.adapters._identity import (
+    MEMORY_BACKEND_GRAPH,
+    MEMORY_BACKEND_NATIVE,
+    load_config,
+    write_config,
+)
+from memgraph_context_graph.spaces import spaces_for
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.hooks.runtime_plugin import RuntimeCLIPlugin
+
+
+@dataclass
+class ImportReport:
+    """What an import brought across, and what it left alone."""
+
+    imported: list[str] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+
+
+class MemoryFiles(Protocol):
+    """The part of sessions-graph's ``MemoryStore`` an import writes through."""
+
+    def view(self, path: str, view_range: tuple[int, int] | None = None) -> str: ...
+
+    def create(self, path: str, file_text: str) -> str: ...
+
+
+class NativeMemory(Protocol):
+    """A harness's built-in memory, as far as switching away from it needs."""
+
+    def enabled(self, home: Path) -> bool:
+        """Whether the harness's own memory is on for this user."""
+        ...
+
+    def disable(self, home: Path) -> list[str]:
+        """Turn the harness's memory off in its user-level config; returns what changed."""
+        ...
+
+    def enable(self, home: Path) -> list[str]:
+        """Undo :meth:`disable`; returns what changed."""
+        ...
+
+    def import_into(self, files: MemoryFiles, home: Path) -> ImportReport:
+        """Copy the harness's existing memories into *files*, never overwriting a path."""
+        ...
+
+
+class MemoryBackendError(Exception):
+    """The switch can't be made; the message says why and what to do."""
+
+
+def native_memory_of(plugin: RuntimeCLIPlugin) -> NativeMemory | None:
+    """The runtime's built-in memory, or None for a runtime that can't switch."""
+    return getattr(plugin, "native_memory", None)
+
+
+def use_graph_memory(plugin: RuntimeCLIPlugin, *, home: Path | None = None) -> list[str]:
+    """Make Context Graph *plugin*'s memory for this user: harness memory off, ours on, old memories imported.
+
+    The import runs first, so a failure (Memgraph down, sessions-graph
+    missing) leaves the user on their harness memory rather than on an
+    empty one. Re-running is safe: imported paths are skipped.
+
+    Raises:
+        MemoryBackendError: the runtime can't switch, no user is configured,
+            sessions-graph isn't installed, or Memgraph can't be reached.
+    """
+    native = _require_native(plugin)
+    home = home or Path.home()
+    config = load_config()
+    user_id = spaces_for(config).user_id()
+    if not user_id:
+        raise MemoryBackendError(
+            "No user is configured, so there is no memory to move into. "
+            "Set one first: memgraph-context-graph config set identity.user_id <name>"
+        )
+    report = native.import_into(_memory_files(config, user_id), home)
+    lines = [f"Imported {path}" for path in report.imported]
+    lines += [f"Kept existing {path}" for path in report.skipped]
+    lines += native.disable(home)
+    write_config(memory_backend=MEMORY_BACKEND_GRAPH)
+    lines.append(
+        f"Set memory.backend = {MEMORY_BACKEND_GRAPH}; the memory tool is on from the next {plugin.name} session."
+    )
+    return lines
+
+
+def use_native_memory(plugin: RuntimeCLIPlugin, *, home: Path | None = None) -> list[str]:
+    """Hand memory back to *plugin*'s own: harness memory on, ours off. Graph memories stay in Memgraph.
+
+    Raises:
+        MemoryBackendError: the runtime can't switch.
+    """
+    native = _require_native(plugin)
+    lines = native.enable(home or Path.home())
+    write_config(memory_backend=MEMORY_BACKEND_NATIVE)
+    lines.append(
+        f"Set memory.backend = {MEMORY_BACKEND_NATIVE}; {plugin.name}'s own memory is back from its next session."
+    )
+    return lines
+
+
+def _require_native(plugin: RuntimeCLIPlugin) -> NativeMemory:
+    native = native_memory_of(plugin)
+    if native is None:
+        raise MemoryBackendError(f"{plugin.name} has no memory Context Graph can replace.")
+    return native
+
+
+def _memory_files(config: Any, user_id: str) -> MemoryFiles:
+    try:
+        from sessions_graph import SessionsGraph
+    except ImportError as exc:
+        raise MemoryBackendError(
+            "Context Graph memory needs sessions-graph: "
+            "uv tool install 'memgraph-context-graph[mcp]' --with 'sessions-graph[memgraph-context-graph]'"
+        ) from exc
+    target = spaces_for(config).personal().target
+    try:
+        graph = SessionsGraph(**target.client_kwargs())
+        graph.setup()
+    except Exception as exc:
+        raise MemoryBackendError(f"Can't reach Memgraph at {target.url}: {exc}") from exc
+    return graph.memory_store(user_id)