memgraph-context-graph 0.7.2__tar.gz → 0.7.3__tar.gz

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/PKG-INFO

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

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/pyproject.toml

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

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/src/memgraph_context_graph/cli.py

@@ -257,9 +257,9 @@ def _ui(argv: list[str]) -> int:
         from context_graph_viewer.cli import main as viewer_main
     except ImportError:
         print(
-            "memgraph-context-graph ui needs the context-graph-viewer package in the same tool environment.\n"
-            "Add it to the `uv tool install memgraph-context-graph ...` command your plugin's bootstrap runs:\n"
-            "  --with context-graph-viewer",
+            "memgraph-context-graph ui needs the context-graph-viewer package, which isn't installed.\n"
+            "Run setup again and say yes to the viewer:\n"
+            "  memgraph-context-graph setup",
             file=sys.stderr,
         )
         return 1
@@ -305,6 +305,7 @@ def _join(argv: list[str]) -> int:
     parser.add_argument("--password", default=None, help="Prompted for when omitted.")
     args = parser.parse_args(argv)
     password = args.password if args.password is not None else getpass.getpass(f"Password for {args.login}: ")
+    _ensure_enterprise_package()
 
     write_config(
         edition=EDITION_ENTERPRISE, memgraph_url=args.url, memgraph_user=args.login, memgraph_password=password
@@ -328,6 +329,21 @@ def _join(argv: list[str]) -> int:
     return 0
 
 
+def _ensure_enterprise_package() -> None:
+    """Install ``context-graph-spaces`` when this is the uv tool and it is missing; else the error says how."""
+    from memgraph_context_graph.setup import tool
+    from memgraph_context_graph.spaces import EDITION_ENTERPRISE, _edition_factory
+
+    if _edition_factory(EDITION_ENTERPRISE) is not None or not tool.uv_tool_environment():
+        return
+    print("Enterprise spaces need one more package, with the local extraction models; installing it.", flush=True)
+    print("This can take a minute.", flush=True)
+    try:
+        tool.install(viewer=False, spaces=True, log=lambda line: None)
+    except tool.ToolError as exc:
+        print(str(exc), file=sys.stderr)
+
+
 def _doctor(argv: list[str]) -> int:
     from memgraph_context_graph.hooks.runtime_plugin import load_runtime_plugins
 

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/src/memgraph_context_graph/setup/cli.py

@@ -90,7 +90,7 @@ def setup_main(argv: Sequence[str]) -> int:
     _print_plan(choices, env)
     print()
     outcomes = engine.run(choices, env, log=_log, report=_report)
-    return _finish(outcomes)
+    return _finish(outcomes, choices, env)
 
 
 def uninstall_main(argv: Sequence[str]) -> int:
@@ -141,11 +141,16 @@ def _report(outcome: engine.Outcome) -> None:
         print(f"       {line}")
 
 
-def _finish(outcomes: Sequence[engine.Outcome]) -> int:
+def _finish(outcomes: Sequence[engine.Outcome], choices: engine.Choices, env: engine.Environment) -> int:
     failures = [outcome for outcome in outcomes if outcome.status == "fail"]
     print()
     if not failures:
-        print("Context Graph is set up. Use your agents as usual; `memgraph-context-graph ui` shows what they capture.")
+        print("Context Graph is set up.")
+        print()
+        steps = engine.next_steps(choices, env)
+        print(steps[0])
+        for line in steps[1:]:
+            print(f"  {line}")
         return 0
     print(f"{len(failures)} step(s) failed. To fix:")
     for outcome in failures:

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/src/memgraph_context_graph/setup/engine.py

@@ -269,11 +269,7 @@ def _agent(agent: agents_mod.Agent, choices: Choices, log: Callable[[str], None]
     fix = f"memgraph-context-graph setup {agent.runtime}"
     if agent.wiring == "plugin":
         try:
-            summary = agents_mod.wire_plugin(agent, log)
-            if agent.runtime == "codex":
-                # Codex skips an untrusted plugin's hooks without a word, and `codex exec` never asks.
-                summary += "; Codex records nothing until you trust its hooks: open codex and accept them (/hooks)"
-            return Outcome(agent.label, "ok", summary)
+            return Outcome(agent.label, "ok", _with_trust_note(agent, agents_mod.wire_plugin(agent, log)))
         except agents_mod.WiringError as exc:
             return Outcome(agent.label, "fail", str(exc), fix=fix)
     if not choices.project_dirs:
@@ -287,7 +283,65 @@ def _agent(agent: agents_mod.Agent, choices: Choices, log: Callable[[str], None]
     if errors:
         dirs = " ".join(f"--project-dir {path}" for path in choices.project_dirs)
         return Outcome(agent.label, "fail", "; ".join(errors + summaries), fix=f"{fix} {dirs}")
-    return Outcome(agent.label, "ok", "; ".join(summaries))
+    return Outcome(agent.label, "ok", _with_trust_note(agent, "; ".join(summaries)))
+
+
+#: Agents that skip hooks they haven't been told to trust, without a word: nothing is recorded until then.
+_TRUST_NOTES = {
+    "codex": "Codex records nothing until you trust its hooks: open codex and accept them (/hooks)",
+    "grok": "Grok records nothing until you trust this project's hooks: run /hooks-trust in grok",
+}
+
+
+def _with_trust_note(agent: agents_mod.Agent, summary: str) -> str:
+    note = _TRUST_NOTES.get(agent.runtime)
+    return f"{summary}; {note}" if note else summary
+
+
+#: What setup says before it asks anything: what the user is about to get, in plain words.
+WELCOME = (
+    "Your coding agents are about to get a memory.",
+    "Each session is kept as one graph in Memgraph, on your machine by default:",
+    "prompts, replies and tool activity. No account or cloud needed.",
+    "A few questions, then setup does the rest. Nothing changes until you confirm.",
+)
+
+#: What a user does once, so an agent starts recording; the same facts as :data:`_TRUST_NOTES`, for the last screen.
+_FIRST_RUN = {
+    "codex": "in Codex, open it and accept its hooks (/hooks)",
+    "grok": "in Grok, run /hooks-trust once per wired project",
+}
+
+
+def next_steps(choices: Choices, env: Environment) -> list[str]:
+    """What happens now and what to try, for the end of a successful setup: short, and only what applies.
+
+    The first line is the heading; each bullet after it fits one terminal line, or continues on an indented one.
+    """
+    from memgraph_context_graph.adapters._identity import MEMORY_BACKEND_GRAPH
+
+    graph_memory = choices.memory_backend == MEMORY_BACKEND_GRAPH or (
+        choices.memory_backend is None and env.configured_memory_backend == MEMORY_BACKEND_GRAPH
+    )
+    lines = [
+        "Your agents now remember. What to expect:",
+        "· Every session is kept in your graph. Finish one, start another, and ask:",
+        '  "what did we do last time?"',
+    ]
+    remembering = [agents_mod.BY_RUNTIME[r].label for r in choices.runtimes if has_native_memory(r)]
+    if graph_memory and remembering:
+        lines += [
+            f"· {' and '.join(remembering)} remember through the graph now.",
+            '  Say "remember that ..." and every agent can recall it.',
+        ]
+    if choices.viewer:
+        lines.append("· Watch it grow: memgraph-context-graph ui")
+    lines += [f"· To start recording {_FIRST_RUN[r]}" for r in choices.runtimes if r in _FIRST_RUN]
+    lines += [
+        "· Change anything any time: memgraph-context-graph setup",
+        "· Undo the wiring: memgraph-context-graph uninstall (your graph stays)",
+    ]
+    return lines
 
 
 def _memory(runtime: str, backend: str) -> Outcome | None:

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/src/memgraph_context_graph/setup/prompts.py

@@ -223,13 +223,14 @@ class Prompts:
         self.write("\n" + "".join(f"{self.style.wordmark(row)}\n" for row in WORDMARK))
         self.write("".join(f"{self.style.graph(row, width)}\n" for row in GRAPH) + "\n")
 
-    def intro(self, title: str, subtitle: str = "") -> None:
-        """The orange graph divider, some space, then the title: the questions start apart from what came before."""
+    def intro(self, title: str, subtitle: str | Sequence[str] = "") -> None:
+        """The orange graph divider, some space, then the title and its lines: the questions start apart from what came before."""
         rule = RULE[: min(len(WORDMARK[0]), self.term.columns - 1)]
         rule = rule[: rule.rfind("●") + 1]  # cut short, it still ends on a node
         self.write(f"\n{self.style.accent(rule)}\n\n")
         self.write(f"{self.style.accent('◆')}  {self.style.bold(title)}\n")
-        self.line(self.style.muted(subtitle))
+        for text in [subtitle] if isinstance(subtitle, str) else subtitle:
+            self.line(self.style.muted(self.fit(text)))
 
     def answered(self, label: str, value: str) -> None:
         value = self.fit(value, _ANSWER_COLUMN)
@@ -400,7 +401,7 @@ def ask(prompts: Prompts, choices: Choices, env: Environment, *, preselect: bool
 
     *preselect* starts the agent list with *choices*' agents ticked; off, the user ticks every one.
     """
-    prompts.intro("Context Graph setup", "Memory for your coding agents. Nothing changes until you confirm.")
+    prompts.intro("Context Graph setup", engine.WELCOME)
     enterprise = env.edition == "enterprise"
     prompts.answered("Memgraph", "from your Enterprise login" if enterprise else _memgraph_summary(choices, env))
 
@@ -418,7 +419,7 @@ def ask(prompts: Prompts, choices: Choices, env: Environment, *, preselect: bool
     def name(answers: _Answers) -> str | _Back:
         if enterprise:
             return SKIPPED
-        answer = prompts.text("Your name", answers.user_id, hint="how the graph knows you")
+        answer = prompts.text("Your name", answers.user_id, hint="your memories are filed under it")
         if isinstance(answer, str):
             answers.user_id = answer
         return answer if isinstance(answer, _Back) else DONE
@@ -444,7 +445,7 @@ def ask(prompts: Prompts, choices: Choices, env: Environment, *, preselect: bool
         answer = prompts.confirm(
             "Install the terminal viewer?",
             answers.viewer,
-            note="Browse what your agents capture, in this terminal: memgraph-context-graph ui.",
+            note="Watch your agents' memory grow, right in this terminal: memgraph-context-graph ui.",
             short="Viewer",
         )
         if isinstance(answer, bool):
@@ -459,7 +460,7 @@ def ask(prompts: Prompts, choices: Choices, env: Environment, *, preselect: bool
         answer = prompts.confirm(
             f"Use Context Graph as the memory of {' and '.join(switchable)}?",
             answers.use_graph_memory,
-            note="Their own memory is switched off and copied into the graph; they remember from there.",
+            note="Their memories move into the graph, shared across agents. Switch back any time.",
             short="Agent memory",
         )
         if isinstance(answer, bool):
@@ -524,7 +525,7 @@ def run(prompts: Prompts, choices: Choices, env: Environment) -> int:
     style = prompts.style
     marks = {"ok": style.success("✓"), "skip": style.muted("–"), "warn": style.warning("!"), "fail": style.error("✗")}
     prompts.line()
-    prompts.line(style.muted("Working… (the first Memgraph start downloads about 1 GB)"))
+    prompts.line(style.muted("Setting up… (a first Memgraph start downloads about 1 GB)"))
 
     def log(text: str) -> None:
         prompts.line(style.muted(f"  {text}"))
@@ -537,10 +538,12 @@ def run(prompts: Prompts, choices: Choices, env: Environment) -> int:
     outcomes = engine.run(choices, env, log=log, report=report)
     failures = [outcome for outcome in outcomes if outcome.status == "fail"]
     if not failures:
-        prompts.outro(
-            style.success("Context Graph is set up.")
-            + " Use your agents as usual; `memgraph-context-graph ui` shows what they capture."
-        )
+        steps = engine.next_steps(choices, env)
+        prompts.line()
+        prompts.line(style.bold(steps[0]))
+        for text in steps[1:]:
+            prompts.line(prompts.fit(text))
+        prompts.outro(style.success("Context Graph is set up."))
         return 0
     prompts.line()
     prompts.line(style.error(f"{len(failures)} step(s) failed. To fix:"))
@@ -577,7 +580,7 @@ def _memgraph_summary(choices: Choices, env: Environment) -> str:
         return choices.memgraph_url
     if env.configured_url:
         return f"{env.configured_url} (configured)"
-    return "find one on localhost:7687, or start one in Docker"
+    return "uses Memgraph on localhost:7687, or starts one in Docker for you"
 
 
 def _agent_options(selected: Sequence[str], wired: Sequence[str]) -> list[_Option]:

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/src/memgraph_context_graph/setup/tool.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import importlib
+import shlex
 import shutil
 import subprocess
 import sys
@@ -14,13 +15,14 @@ if TYPE_CHECKING:
     from collections.abc import Callable
 
 #: Kept in step with the plugins' bootstrap scripts and install.sh, which install the same set first.
-BASE = "memgraph-context-graph[mcp]>=0.7.0"
+BASE = "memgraph-context-graph[mcp]>=0.7.2"
 CONNECTORS = {
     "skills-graph": "skills-graph[memgraph-context-graph]>=0.2.1",
     "actions-graph": "actions-graph[memgraph-context-graph]>=0.5.0",
     "sessions-graph": "sessions-graph[memgraph-context-graph]>=0.8.1",
 }
 VIEWER = ("context-graph-viewer", "context-graph-viewer>=0.1.0")
+SPACES = ("context-graph-spaces", "context-graph-spaces>=0.1.0")
 
 
 class ToolError(Exception):
@@ -59,8 +61,29 @@ def uv_tool_environment() -> bool:
     return Path(sys.prefix).resolve() == tool_dir.resolve()
 
 
-def install(*, viewer: bool, log: Callable[[str], None]) -> None:
-    """Install the tool with every connector (and the viewer), keeping what is already there.
+def requirements(*, viewer: bool = False, spaces: bool = False) -> list[str]:
+    """The ``uv tool install`` arguments for the tool, every connector, and the optional packages.
+
+    An optional package already installed is kept: ``uv tool install`` replaces the tool's requirements with
+    what it is given, so leaving one out would remove it.
+    """
+    argv = [BASE]
+    for requirement in CONNECTORS.values():
+        argv += ["--with", requirement]
+    if viewer or installed(VIEWER[0]):
+        argv += ["--with", VIEWER[1]]
+    if spaces or installed(SPACES[0]):
+        argv += ["--with", SPACES[1]]
+    return argv
+
+
+def install_command(*, spaces: bool = False) -> str:
+    """The whole ``uv tool install`` command as one line a person can paste, with *spaces* added."""
+    return " ".join(["uv tool install", *map(shlex.quote, requirements(spaces=spaces))])
+
+
+def install(*, viewer: bool, log: Callable[[str], None], spaces: bool = False) -> None:
+    """Install the tool with every connector (and the viewer, and the spaces package), keeping what is already there.
 
     The full set is always passed: ``uv tool install`` replaces the tool's requirements with what it is
     given, so naming only the missing package would drop the others.
@@ -71,11 +94,7 @@ def install(*, viewer: bool, log: Callable[[str], None]) -> None:
     uv = shutil.which("uv")
     if uv is None:
         raise ToolError("uv isn't on PATH")
-    argv = [uv, "--color", "never", "tool", "install", BASE]
-    for requirement in CONNECTORS.values():
-        argv += ["--with", requirement]
-    if viewer or installed(VIEWER[0]):
-        argv += ["--with", VIEWER[1]]
+    argv = [uv, "--color", "never", "tool", "install", *requirements(viewer=viewer, spaces=spaces)]
     log(" ".join(["uv", *argv[3:]]))
     process = subprocess.Popen(argv, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
     last = ""

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/src/memgraph_context_graph/spaces.py

@@ -192,9 +192,11 @@ def _build(config: HookConfig) -> SpaceResolver:
     if edition == EDITION_ENTERPRISE:
         factory = _edition_factory(edition)
         if factory is None:
+            from memgraph_context_graph.setup import tool
+
             raise SpaceError(
-                "edition = enterprise needs the context-graph-spaces package: "
-                "uv tool install 'memgraph-context-graph[mcp]' --with context-graph-spaces"
+                f"edition = enterprise needs the context-graph-spaces package. Install it, with the rest: "
+                f"{tool.install_command(spaces=True)}"
             )
         return factory(config)
     raise SpaceError(f"Unknown edition {edition!r} in the config file; use one of: {', '.join(sorted(EDITIONS))}.")

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/tests/test_dev_scripts.py

@@ -107,6 +107,6 @@ def test_installer_installs_the_tool_then_hands_its_arguments_to_setup(tmp_path)
     )  # fmt: skip
 
     lines = calls.read_text().splitlines()
-    assert lines[0].startswith("uv tool install memgraph-context-graph[mcp]>=")
+    assert lines[0].startswith("uv tool install --quiet memgraph-context-graph[mcp]>=")
     assert "--with sessions-graph[memgraph-context-graph]>=" in lines[0]
     assert lines[-1] == "memgraph-context-graph setup --no-tui codex --memgraph-url bolt://my-host:7687"

{memgraph_context_graph-0.7.2 → memgraph_context_graph-0.7.3}/tests/test_setup.py

@@ -440,6 +440,16 @@ def test_the_uv_tool_is_recognised_even_when_the_shell_forces_colour(monkeypatch
     assert tool.uv_tool_environment()
 
 
+def test_grok_is_reported_with_the_trust_it_still_needs(fake_agents, setup_home, project):
+    env = engine.look_around(cwd=project)
+    choices = engine.default_choices(env, cwd=project)
+
+    grok = engine._agent(BY_RUNTIME["grok"], choices, lambda _: None)
+
+    assert grok.status == "ok"
+    assert "/hooks-trust" in grok.summary
+
+
 def test_codex_is_reported_with_the_trust_it_still_needs_and_claude_code_is_not(fake_agents, setup_home, project):
     env = engine.look_around(cwd=project)
     choices = engine.default_choices(env, cwd=project)
@@ -450,3 +460,105 @@ def test_codex_is_reported_with_the_trust_it_still_needs_and_claude_code_is_not(
     assert codex.status == "ok"
     assert "records nothing until you trust its hooks" in codex.summary
     assert "trust" not in claude.summary
+
+
+def test_reinstalling_the_tool_keeps_the_spaces_package_once_it_is_there(monkeypatch):
+    from memgraph_context_graph.setup import tool
+
+    monkeypatch.setattr(tool, "installed", lambda package: package == "context-graph-spaces")
+
+    argv = tool.requirements()
+
+    assert tool.BASE in argv
+    assert all(requirement in argv for requirement in tool.CONNECTORS.values())
+    assert tool.SPACES[1] in argv
+    assert tool.VIEWER[1] not in argv
+
+    monkeypatch.setattr(tool, "installed", lambda package: False)
+    assert tool.SPACES[1] not in tool.requirements()
+    assert tool.SPACES[1] in tool.requirements(spaces=True)
+
+
+def test_the_enterprise_hint_names_the_whole_install_not_just_the_spaces_package(monkeypatch):
+    import pytest
+
+    from memgraph_context_graph import spaces
+    from memgraph_context_graph.adapters._identity import HookConfig
+
+    monkeypatch.setattr(spaces, "_edition_factory", lambda edition: None)
+    spaces._reset_cache()
+
+    with pytest.raises(spaces.SpaceError) as excinfo:
+        spaces.spaces_for(HookConfig(edition="enterprise"))
+
+    hint = str(excinfo.value)
+    assert "context-graph-spaces" in hint
+    assert "skills-graph" in hint and "sessions-graph" in hint
+    spaces._reset_cache()
+
+
+def test_join_installs_the_spaces_package_inside_the_uv_tool_and_not_elsewhere(monkeypatch, setup_home, capsys):
+    from memgraph_context_graph import spaces
+    from memgraph_context_graph.setup import tool
+
+    installs = []
+    monkeypatch.setattr(spaces, "_edition_factory", lambda edition: None)
+    monkeypatch.setattr(tool, "install", lambda **kwargs: installs.append(kwargs))
+
+    monkeypatch.setattr(tool, "uv_tool_environment", lambda: False)
+    spaces._reset_cache()
+    assert main(["join", "bolt://localhost:1", "ante", "--password=x"]) == 1
+    assert installs == []
+    assert "uv tool install" in capsys.readouterr().err
+
+    monkeypatch.setattr(tool, "uv_tool_environment", lambda: True)
+    spaces._reset_cache()
+    main(["join", "bolt://localhost:1", "ante", "--password=x"])
+    assert [kwargs["spaces"] for kwargs in installs] == [True]
+    spaces._reset_cache()
+
+
+def test_the_welcome_says_what_the_user_is_getting_before_any_question(fake_agents, setup_home, project):
+    from memgraph_context_graph.setup.prompts import ENTER, Prompts, ask
+
+    env = engine.look_around(cwd=project)
+    term = ScriptedTerminal(keys=[ENTER] * 5, columns=100)
+
+    ask(Prompts(term), engine.default_choices(env, cwd=project), env, preselect=False)
+
+    first_question = term.text.index("Your name")
+    for line in ("about to get a memory", "No account or cloud needed", "Nothing changes until you confirm"):
+        assert term.text.index(line) < first_question
+
+
+def test_the_last_screen_says_what_to_expect_and_only_what_applies():
+    choices = engine.Choices(
+        runtimes=["claude-code", "codex", "grok"], project_dirs=[], user_id="carol", memory_backend="context-graph"
+    )
+    env = engine.Environment(edition="community", configured_url=None, configured_user=None, found_agents=())
+
+    text = "\n".join(engine.next_steps(choices, env))
+
+    assert "Claude Code and Codex remember through the graph now." in text
+    assert "memgraph-context-graph ui" in text
+    assert "in Codex, open it and accept its hooks" in text
+    assert "in Grok, run /hooks-trust" in text
+    assert "memgraph-context-graph uninstall" in text
+
+    plain = engine.Choices(runtimes=["opencode"], project_dirs=[], user_id="carol", viewer=False)
+    quiet = "\n".join(engine.next_steps(plain, env))
+
+    assert "remember through the graph" not in quiet
+    assert "memgraph-context-graph ui" not in quiet
+    assert "accept the hooks" not in quiet
+    assert "what did we do last time" in quiet
+
+
+def test_every_line_of_the_welcome_and_the_last_screen_fits_a_narrow_terminal():
+    choices = engine.Choices(
+        runtimes=["claude-code", "codex", "grok"], project_dirs=[], user_id="carol", memory_backend="context-graph"
+    )
+    env = engine.Environment(edition="community", configured_url=None, configured_user=None, found_agents=())
+
+    for line in (*engine.WELCOME, *engine.next_steps(choices, env)):
+        assert len(line) <= 78, line