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

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.4}/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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memgraph-context-graph
-Version: 0.12.2
+Version: 0.12.4
 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.4}/docs/memory.md

@@ -93,7 +93,11 @@ Opting in does three things, in this order:
      project already put a different memory of the same name there, this one
      goes to its own project's folder instead, so neither is lost;
    - `project`/`reference` memories go to that project's folder;
-   - `MEMORY.md` is skipped, and anything already in the graph is never overwritten.
+   - `MEMORY.md` is skipped, and anything already in the graph is never overwritten;
+   - each file remembers the project it came from and keeps its own
+     modification time, so the session-start index can still put a project's
+     `user`/`feedback` memories with that project. Running the switch again
+     records this for files an earlier import brought in.
 2. Sets `autoMemoryEnabled: false` in `~/.claude/settings.json`, the user-level
    settings file, because a plugin can't set it itself. The file is backed up
    once to `settings.json.context-graph.bak`.
@@ -122,8 +126,8 @@ its global store, with three differences:
   compaction (`compact`), so the memory index comes back once the context is
   summarized.
 
-Codex caps hook context at about 2,500 tokens, so pinned files come before the
-index and a long index is cut from its tail. See
+Codex caps hook context at about 2,500 tokens, so its session-start text is
+kept to 9,000 characters, with pinned files before the index. See
 [the Codex research note](research/2026-10-codex-memory.md).
 
 If the import can't run, for example because Memgraph is down, nothing is
@@ -192,10 +196,22 @@ change shows from the next session.
 At session start the hook loads the memory, the way the harness's built-in
 memory would have. It adds:
 - an index of the root and the current project's files, one line each with
-  the file's `description:` frontmatter or first line, up to 200 lines;
+  the file's `description:` frontmatter or first line, up to 200 lines. The
+  current project's files come first, then root files from this project
+  (imported from its memory, or written in its sessions by an SDK app), then
+  the rest, newest first, so an import of every project's `user`/`feedback`
+  memories can't crowd this project's out;
 - the full text of any file with `pin: true` in its frontmatter;
 - the current project's folder.
 
+All of that, with recall's "where you left off", fits in what the agent shows
+its model at session start: 10,000 characters, Claude Code's cap on a hook's
+context (past it, the model sees only a 2,000-character preview), and 9,000 for
+Codex. Pinned text takes at most half. The index lists every file by its path
+before it describes any, then gives descriptions in its order, so the current
+project's files keep theirs longest. When even the paths don't fit, it ends
+with how many it left out and where to list them.
+
 The index is generated from the graph, so the model never maintains an index
 file and it can't go stale. The project folder is keyed by the checkout's git
 `origin` remote (e.g. `github.com_memgraph_ai-toolkit`), so every clone of a

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.4}/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.4}/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.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memgraph-context-graph"
-version = "0.12.2"
+version = "0.12.4"
 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.4}/src/memgraph_context_graph/adapters/_identity.py

@@ -30,6 +30,7 @@ from dataclasses import dataclass, field, replace
 from pathlib import Path
 from typing import Any
 
+from memgraph_context_graph.adapters._text_file import write_text_keeping_newlines
 from memgraph_context_graph.config_schema import (
     CONFIG_KEYS,
     SECTIONS,
@@ -355,7 +356,7 @@ def _write_config_file(content: str) -> Path:
     global _cached_config
     path = config_file()
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content, encoding="utf-8")
+    write_text_keeping_newlines(path, content)
     path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0600: the file holds credentials.
     _cached_config = None
     return path

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.4}/src/memgraph_context_graph/adapters/_spec.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Literal
 
 from memgraph_context_graph.adapters._identity import resolve_user_id
+from memgraph_context_graph.adapters._text_file import write_text_keeping_newlines
 from memgraph_context_graph.events import (
     AgentEndEvent,
     AgentStartEvent,
@@ -30,6 +31,7 @@ from memgraph_context_graph.events import (
     TurnEndEvent,
 )
 from memgraph_context_graph.protocols import RuntimeAdapter
+from memgraph_context_graph.tools import SESSION_CONTEXT_CHARS
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -115,7 +117,8 @@ class RuntimeSpec:
     modifying the call. ``session_context`` renders the stdout JSON that puts
     the session-start text (memory index, where the user left off) in front of
     the model when ``session_context_event`` fires; None where no hook output
-    reaches the model at session start.
+    reaches the model at session start. ``session_context_limit`` is how many
+    characters of that text the runtime shows its model.
     """
 
     name: str
@@ -133,6 +136,7 @@ class RuntimeSpec:
     context_before_tool: Callable[[str], Mapping[str, Any]] | None = None
     session_context: Callable[[str], Mapping[str, Any]] | None = None
     session_context_event: str = "SessionStart"
+    session_context_limit: int = SESSION_CONTEXT_CHARS
 
     def event_name(self, payload: Mapping[str, Any]) -> str:
         """Return *payload*'s canonical event name."""
@@ -251,6 +255,11 @@ class SpecPlugin:
         """Return the runtime's registered name."""
         return self.spec.name
 
+    @property
+    def session_context_limit(self) -> int:
+        """Return how many characters of session-start text the runtime shows its model."""
+        return self.spec.session_context_limit
+
     @property
     def probe_payload(self) -> Mapping[str, Any]:
         """Return the payload ``doctor`` replays to smoke-test the runtime."""
@@ -377,7 +386,7 @@ def write_hook_config(
     document[spec.config.root_key] = merged
 
     config_path.parent.mkdir(parents=True, exist_ok=True)
-    config_path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    write_text_keeping_newlines(config_path, json.dumps(document, indent=2) + "\n")
     return config_path
 
 
@@ -408,7 +417,7 @@ def remove_hook_config(spec: RuntimeSpec, project_dir: Path) -> bool:
     if set(document) <= {"version"}:
         config_path.unlink()
     else:
-        config_path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+        write_text_keeping_newlines(config_path, json.dumps(document, indent=2) + "\n")
     return True
 
 

memgraph_context_graph-0.12.4/src/memgraph_context_graph/adapters/_text_file.py

@@ -0,0 +1,23 @@
+"""Writing a user's files without changing their line endings.
+
+``Path.write_text`` turns ``\\n`` into the platform's line ending, so on Windows every file setup or
+the memory switch rewrote came back CRLF, even when its content didn't change. A rewrite here keeps
+the ending the file already had, and a new file gets ``\\n`` on every platform.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def write_text_keeping_newlines(path: Path, text: str) -> None:
+    """Write *text* to *path* as UTF-8 with the line ending *path* already uses.
+
+    *text* may use ``\\n`` or ``\\r\\n``; it is written with ``\\r\\n`` only if the existing file holds one,
+    else with ``\\n``.
+    """
+    newline = "\r\n" if path.is_file() and b"\r\n" in path.read_bytes() else "\n"
+    path.write_text(text.replace("\r\n", "\n"), encoding="utf-8", newline=newline)

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.4}/src/memgraph_context_graph/adapters/agent_mcp.py

@@ -27,6 +27,7 @@ import sys
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
+from memgraph_context_graph.adapters._text_file import write_text_keeping_newlines
 from memgraph_context_graph.memory_backend import MemoryBackendError
 
 if TYPE_CHECKING:
@@ -322,5 +323,5 @@ def _write(path: Path, rendered: str) -> list[str]:
     if path.exists() and not backup.exists():
         shutil.copy2(path, backup)
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(rendered, encoding="utf-8")
+    write_text_keeping_newlines(path, rendered)
     return [f"Wrote {path}"]

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.4}/src/memgraph_context_graph/adapters/claude_code_memory.py

@@ -21,9 +21,11 @@ import re
 import shutil
 import subprocess
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from memgraph_context_graph.adapters._text_file import write_text_keeping_newlines
 from memgraph_context_graph.memory_backend import ExportReport, ImportReport, MemoryBackendError
 
 if TYPE_CHECKING:
@@ -92,9 +94,16 @@ class ClaudeCodeMemory:
         goes under its project's folder under its own filename instead, where
         handing memory back finds it again. ``MEMORY.md`` is skipped: the index
         is generated now. The original files are left as they are.
+
+        Each file is marked with the project it came from and when it last
+        changed there, which the session-start index ranks by. A file already
+        in the graph with the same text is marked too, so re-running the import
+        fills that in for an earlier one.
         """
         from sessions_graph.memory_index import project_key_for
 
+        # An older sessions-graph can't record where a file came from; the import still works without it.
+        mark = getattr(files, "mark_imported", None)
         report = ImportReport()
         for memory_dir in sorted((home / ".claude" / "projects").glob("*/memory")):
             checkout = _checkout_for(memory_dir.parent.name)
@@ -112,13 +121,15 @@ class ClaudeCodeMemory:
                     lineage = _lineage(files, target)
                 if lineage:
                     report.skipped.append(target)
-                    continue
-                try:
-                    files.create(target, text)
-                except Exception:  # Too large, or the path is taken by a directory: keep going.
-                    report.skipped.append(target)
-                    continue
-                report.imported.append(target)
+                else:
+                    try:
+                        files.create(target, text)
+                    except Exception:  # Too large, or the path is taken by a directory: keep going.
+                        report.skipped.append(target)
+                        continue
+                    report.imported.append(target)
+                if mark is not None and (not lineage or text in lineage):
+                    mark(target, project, text=text, modified=_modified(source))
         return report
 
     def export_from(self, source: MemorySource, home: Path) -> ExportReport:
@@ -226,7 +237,7 @@ def _write_memory(folder: Path, name: str, text: str, lineage: set[str]) -> bool
         if current == text or current not in lineage:
             return False
     folder.mkdir(parents=True, exist_ok=True)
-    path.write_text(text, encoding="utf-8")
+    write_text_keeping_newlines(path, text)
     return True
 
 
@@ -240,7 +251,7 @@ def _write_index(folder: Path) -> None:
         title = match["value"].strip("\"'") if (match := _NAME_RE.search(frontmatter)) else path.stem
         hook = match["value"].strip("\"'") if (match := _DESCRIPTION_RE.search(frontmatter)) else ""
         lines.append(f"- [{title}]({path.name})" + (f" — {hook}" if hook else ""))
-    (folder / _INDEX_FILE).write_text("\n".join(lines) + "\n", encoding="utf-8")
+    write_text_keeping_newlines(folder / _INDEX_FILE, "\n".join(lines) + "\n")
 
 
 def _frontmatter(text: str) -> str:
@@ -308,6 +319,11 @@ def _walk(directory: Path, tokens: list[str]) -> Path | None:
     return None
 
 
+def _modified(source: Path) -> str:
+    """When *source* last changed, in the ISO 8601 UTC form the graph's ``updated_at`` uses."""
+    return datetime.fromtimestamp(source.stat().st_mtime, timezone.utc).isoformat()
+
+
 def _fallback_key(slug: str) -> str:
     """A key for a project whose checkout is gone: the whole slug, since its last part alone may collide."""
     from sessions_graph.memory_index import safe_key
@@ -344,7 +360,7 @@ def _set(path: Path, value: bool | None) -> list[str]:
     if path.exists() and not backup.exists():
         shutil.copy2(path, backup)
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(settings, indent=2) + "\n", encoding="utf-8")
+    write_text_keeping_newlines(path, json.dumps(settings, indent=2) + "\n")
     state = "removed" if value is None else json.dumps(value)
     return [f"Wrote {path} ({_SETTING} {state})"]
 

memgraph_context_graph-0.12.4/src/memgraph_context_graph/adapters/codex.py

@@ -0,0 +1,248 @@
+"""OpenAI Codex command-hook runtime adapter."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import re
+import time
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    hook_specific_session_context,
+    pre_tool_use_context,
+    session_end,
+    session_start,
+    tool_end,
+    tool_start,
+    turn_end,
+    write_hook_config,
+)
+from memgraph_context_graph.adapters._text_file import write_text_keeping_newlines
+from memgraph_context_graph.adapters.codex_memory import CODEX_MEMORY
+from memgraph_context_graph.events import MessageEvent, ToolEndEvent
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from memgraph_context_graph.events import Event
+
+#: Enough of the rollout to hold the turn being handled, without reading a long session's whole file.
+_ROLLOUT_TAIL_BYTES = 4 * 1024 * 1024
+#: How long PostToolUse waits for Codex's rollout writer to record the call it is about.
+_ITEM_WAIT_SECONDS = 0.5
+_ITEM_POLL_SECONDS = 0.05
+#: Rollout item types for the tools Codex's hooks report, and the ``tool_name`` the hooks give each.
+_ITEM_TOOL_NAMES = {"CommandExecution": "Bash", "FileChange": "apply_patch"}
+_TOOL_ITEM_TYPES = frozenset({*_ITEM_TOOL_NAMES, "McpToolCall"})
+
+
+def _user_prompt(context: EventContext) -> MessageEvent:
+    return MessageEvent(
+        **context.base(),
+        role="user",
+        content=context.value("prompt", ""),
+        model=context.optional_text("model"),
+    )
+
+
+def _permission(context: EventContext) -> MessageEvent:
+    return MessageEvent(**context.base(), role="system", content=context.text("tool_name", "permission_request"))
+
+
+def _completed_items(context: EventContext) -> dict[str, dict[str, Any]]:
+    """This turn's ``item_completed`` records in Codex's rollout (``transcript_path``), by item id.
+
+    An item's id is the ``tool_use_id`` the tool hooks carry. Only the rollout's tail is read: the turn
+    being handled is the last one written. An unreadable rollout yields nothing.
+    """
+    path, turn_id = context.optional_text("transcript_path"), context.optional_text("turn_id")
+    if not path or not turn_id:
+        return {}
+    try:
+        with open(path, "rb") as file:
+            start = max(0, file.seek(0, os.SEEK_END) - _ROLLOUT_TAIL_BYTES)
+            file.seek(start)
+            lines = file.read().split(b"\n")[1 if start else 0 :]
+    except OSError:
+        return {}
+    items = {}
+    for line in lines:
+        if b'"item_completed"' not in line:
+            continue
+        try:
+            record = json.loads(line)
+        except ValueError:
+            continue
+        payload = record.get("payload") if isinstance(record, dict) else None
+        if not isinstance(payload, dict) or payload.get("type") != "item_completed":
+            continue
+        item = payload.get("item")
+        if payload.get("turn_id") == turn_id and isinstance(item, dict) and isinstance(item.get("id"), str):
+            items[item["id"]] = item
+    return items
+
+
+def _item_result(item: dict[str, Any]) -> Any:
+    """What the tool behind a rollout item returned, shaped as its hook result would be."""
+    result = item.get("result")
+    if isinstance(result, dict):
+        return result.get("content", result)
+    return result if result is not None else item.get("aggregated_output", item.get("stdout"))
+
+
+def _failure(item: dict[str, Any]) -> str | None:
+    """The error message of a failed rollout item, or None if it succeeded."""
+    exit_code = item.get("exit_code")
+    if item.get("status") != "failed" and exit_code in (None, 0):
+        return None
+    blocks = _item_result(item)
+    texts = (
+        [b["text"] for b in blocks if isinstance(b, dict) and isinstance(b.get("text"), str)]
+        if isinstance(blocks, list)
+        else []
+    )
+    detail = "\n".join(texts) or item.get("error") or item.get("aggregated_output") or item.get("stderr")
+    if detail:
+        return str(detail)
+    return f"exit code {exit_code}" if exit_code not in (None, 0) else f"{item.get('type', 'tool')} failed"
+
+
+def _hook_tool_name(item: dict[str, Any]) -> str:
+    """The ``tool_name`` Codex's hooks give the tool behind a rollout item."""
+    if item.get("type") == "McpToolCall":
+        server = re.sub(r"[^A-Za-z0-9_]", "_", str(item.get("server", "")))
+        return f"mcp__{server}__{item.get('tool', '')}"
+    return _ITEM_TOOL_NAMES[item["type"]]
+
+
+def _tool_end(context: EventContext) -> ToolEndEvent:
+    """Codex's tool end, failed when the rollout says so.
+
+    A ``Bash`` call that exits non-zero still reaches PostToolUse, but the hook gets only its output;
+    the exit code is in the rollout, whose record of the call Codex normally writes before running the
+    hook (hence the short wait). A result stored as completed here stays so: :func:`_turn_end` can't
+    correct it. Other tools reach PostToolUse only when they succeeded.
+    """
+    event = tool_end(context)
+    if event.tool_name != "Bash" or not event.tool_use_id:
+        return event
+    deadline = time.monotonic() + _ITEM_WAIT_SECONDS
+    while (item := _completed_items(context).get(event.tool_use_id)) is None and time.monotonic() < deadline:
+        time.sleep(_ITEM_POLL_SECONDS)
+    message = _failure(item) if item else None
+    return dataclasses.replace(event, is_error=True, error_message=message) if message else event
+
+
+def _rollout_tool_end(context: EventContext, item_id: str, item: dict[str, Any]) -> ToolEndEvent:
+    message = _failure(item)
+    return ToolEndEvent(
+        **context.base(),
+        tool_name=_hook_tool_name(item),
+        tool_use_id=item_id,
+        result=_item_result(item),
+        is_error=message is not None,
+        error_message=message,
+    )
+
+
+def _turn_end(context: EventContext) -> list[Event]:
+    """End the turn, first recording the outcome of every tool call that finished in it.
+
+    PostToolUse misses calls: Codex runs none for a failed tool (an MCP error, a rejected patch), nor for
+    a command that outlived its first yield and finished later. The turn's rollout records every one,
+    so each is recorded from there; one PostToolUse already recorded is the same event again, which
+    connectors store once. A patch Codex rejects before applying leaves no rollout item and stays a call
+    without a result.
+    """
+    outcomes: list[Event] = [
+        _rollout_tool_end(context, item_id, item)
+        for item_id, item in _completed_items(context).items()
+        if item.get("type") in _TOOL_ITEM_TYPES
+    ]
+    # Stop fires after every turn; SessionEnd, registered separately, ends the session.
+    return [*outcomes, *turn_end(context, reply=context.value("reply"))]
+
+
+_HOOKS_PATH = ".codex/hooks.json"
+SPEC = RuntimeSpec(
+    name="codex",
+    source_sdk="codex",
+    event_key="hook_event_name",
+    hooks=("SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop", "SessionEnd"),
+    rules={
+        "SessionStart": session_start,
+        "UserPromptSubmit": _user_prompt,
+        "PreToolUse": tool_start,
+        "PostToolUse": _tool_end,
+        "PermissionRequest": _permission,
+        "Stop": _turn_end,
+        "SessionEnd": session_end,
+    },
+    metadata_keys=(
+        "cwd",
+        "source",
+        "transcript_path",
+        "turn_id",
+        "permission_mode",
+        "tool_name",
+        "tool_input",
+        "tool_use_id",
+        "reason",
+        "decision",
+        "stop_hook_active",
+    ),
+    config=HookConfig(
+        path=_HOOKS_PATH,
+        layout="nested",
+        matchers={"SessionStart": "startup|resume|clear|compact", "PreToolUse": "*", "PostToolUse": "*"},
+    ),
+    responses={"Stop": {"continue": True}},
+    context_before_tool=pre_tool_use_context,
+    session_context=hook_specific_session_context,
+    # Codex cuts hook context at about 2,500 tokens (docs/research/2026-10-codex-memory.md);
+    # 9,000 characters stays under that even with multi-byte text.
+    session_context_limit=9_000,
+    probe_payload={"hook_event_name": "Stop", "session_id": "doctor"},
+)
+
+
+class CodexHooksAdapter(SpecAdapter):
+    """Convert Codex command-hook payloads into Event Protocol events."""
+
+    SPEC = SPEC
+
+
+def init(
+    project_dir: Path,
+    connectors: list[str],
+    *,
+    hook_command: str | None = None,
+    timeout: int = 30,
+    force: bool = False,
+) -> None:
+    """Generate private Codex ``config.toml`` and ``hooks.json`` files.
+
+    Raises:
+        FileExistsError: if either file exists and *force* is false.
+    """
+    config_path = project_dir / ".codex" / "config.toml"
+    hooks_path = project_dir / _HOOKS_PATH
+    existing = [path for path in (config_path, hooks_path) if path.exists()]
+    if existing and not force:
+        names = ", ".join(str(path) for path in existing)
+        raise FileExistsError(f"Refusing to overwrite existing Codex config: {names} (pass force=True to replace)")
+
+    write_hook_config(SPEC, project_dir, connectors, hook_command=hook_command, timeout=timeout, force=True)
+    write_text_keeping_newlines(config_path, "[features]\nhooks = true\n")
+    print(f"Wrote {config_path}")
+    print(f"Wrote {hooks_path}")
+
+
+PLUGIN = SpecPlugin(SPEC, CodexHooksAdapter, init=init, native_memory=CODEX_MEMORY)

{memgraph_context_graph-0.12.2 → memgraph_context_graph-0.12.4}/src/memgraph_context_graph/adapters/opencode.py

@@ -19,6 +19,7 @@ from memgraph_context_graph.adapters._spec import (
     tool_start,
     turn_end,
 )
+from memgraph_context_graph.adapters._text_file import write_text_keeping_newlines
 from memgraph_context_graph.adapters.agent_memory import NO_BUILT_IN_MEMORY
 from memgraph_context_graph.events import ErrorOccurredEvent, MessageEvent, ToolEndEvent
 
@@ -162,7 +163,7 @@ def init(
     )
     plugin = template.replace("__MEMGRAPH_CONTEXT_GRAPH_COMMAND__", json.dumps(argv))
     target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(plugin, encoding="utf-8")
+    write_text_keeping_newlines(target, plugin)
     print(f"Wrote {target}")
 
 

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

@@ -311,7 +311,9 @@ def _join(argv: list[str]) -> int:
     """Point the config file at an Enterprise Memgraph as one login, then prove the login works."""
     import getpass
 
-    from memgraph_context_graph.adapters._identity import config_file, reload_config, write_config
+    import neo4j
+
+    from memgraph_context_graph.adapters._identity import MEMORY_BACKEND_GRAPH, config_file, reload_config, write_config
     from memgraph_context_graph.spaces import EDITION_ENTERPRISE, SpaceError, spaces_for
 
     parser = argparse.ArgumentParser(
@@ -340,9 +342,21 @@ def _join(argv: list[str]) -> int:
     except (SpaceError, ValueError) as exc:
         print(f"Wrote {config_file()}, but the login doesn't work yet: {exc}", file=sys.stderr)
         return 1
+    except neo4j.exceptions.Neo4jError as exc:
+        refused = "Unauthenticated" in str(exc.code)
+        reason = f"Memgraph refused the login {args.login!r}; check its password" if refused else exc.message
+        print(f"Wrote {config_file()}, but the login doesn't work yet: {reason}", file=sys.stderr)
+        return 1
     print(f"Wrote {config_file()}: edition = enterprise, login {args.login!r}.")
     print(f"Personal space: {row['Current']}. Shared spaces: {', '.join(shared) or 'none yet'}.")
-    print("Next: memgraph-context-graph setup <runtime> (e.g. claude-code) if this machine isn't set up yet.")
+    if reload_config().memory_backend == MEMORY_BACKEND_GRAPH:
+        print("Your agents' memory tool reaches them under /memories/spaces/<space>/.")
+    else:
+        # Shared spaces are only reachable through the memory tool, and that is on only with this backend (ADR 0006).
+        print(
+            "Next: memgraph-context-graph setup <runtime> (e.g. claude-code) --memory-backend context-graph\n"
+            "  Shared spaces are reached through the memory tool, which only that backend turns on."
+        )
     return 0
 
 
@@ -405,6 +419,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 +518,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.4}/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.4",
     "resources-graph": "resources-graph[memgraph-context-graph]>=0.3.0",
 }