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

memgraph_context_graph/adapters/claude_code_memory.py

@@ -0,0 +1,181 @@
+"""Claude Code's auto memory, as Context Graph switches away from and imports it.
+
+Auto memory is Markdown files in ``~/.claude/projects/<project>/memory/``, one
+folder per project. ``<project>`` is the project's absolute path with every
+character other than a letter or digit replaced by ``-``. ``MEMORY.md`` there
+is the index Claude Code loads at session start; the other files are
+memories, each with frontmatter naming its ``type``. The ``autoMemoryEnabled``
+setting turns it off; a plugin can't set it, so this edits the user's own
+``~/.claude/settings.json``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.memory_backend import ImportReport, MemoryBackendError
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.memory_backend import MemoryFiles
+
+_SETTING = "autoMemoryEnabled"
+_INDEX_FILE = "MEMORY.md"
+_BACKUP_SUFFIX = ".context-graph.bak"
+_TYPE_RE = re.compile(r"^\s*type:\s*[\"']?(?P<type>[A-Za-z]+)", re.MULTILINE)
+_PREFIX_RE = re.compile(r"^(user|feedback|project|reference)_")
+_SLUG_RE = re.compile(r"[^A-Za-z0-9]")
+#: Types about the user, which apply in every project; the rest are about one project.
+_USER_WIDE_TYPES = frozenset({"user", "feedback"})
+
+
+@dataclass(frozen=True)
+class ClaudeCodeMemory:
+    """Claude Code's auto memory (``NativeMemory``)."""
+
+    def enabled(self, home: Path) -> bool:
+        """On unless a user-level setting turns it off."""
+        settings = _read_settings(_settings_path(home))
+        return settings.get(_SETTING) is not False
+
+    def disable(self, home: Path) -> list[str]:
+        """Set ``autoMemoryEnabled: false`` in ``~/.claude/settings.json``, keeping every other setting.
+
+        Raises:
+            MemoryBackendError: the settings file isn't a JSON object.
+        """
+        return _set(_settings_path(home), False)
+
+    def enable(self, home: Path) -> list[str]:
+        """Drop the ``autoMemoryEnabled: false`` that :meth:`disable` wrote.
+
+        Raises:
+            MemoryBackendError: the settings file isn't a JSON object.
+        """
+        return _set(_settings_path(home), None)
+
+    def import_into(self, files: MemoryFiles, home: Path) -> ImportReport:
+        """Copy every project's auto-memory files into the graph's ``/memories`` tree.
+
+        ``user``/``feedback`` memories go under ``/memories/<type>/``, since they
+        apply everywhere; ``project``/``reference`` (and untyped) ones under
+        that project's ``/memories/projects/<key>/``, keyed as the session-start
+        index keys the checkout. ``MEMORY.md`` is skipped: the index is
+        generated now. The original files are left as they are.
+        """
+        from sessions_graph.memory_index import project_key_for
+
+        report = ImportReport()
+        for memory_dir in sorted((home / ".claude" / "projects").glob("*/memory")):
+            checkout = _checkout_for(memory_dir.parent.name)
+            project = (project_key_for(checkout) if checkout else None) or _fallback_key(memory_dir.parent.name)
+            for source in sorted(memory_dir.glob("*.md")):
+                if source.name == _INDEX_FILE:
+                    continue
+                text = source.read_text(encoding="utf-8")
+                if not text.strip():
+                    continue
+                target = _target_path(source.name, text, project)
+                if _exists(files, target):
+                    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)
+        return report
+
+
+def _target_path(filename: str, text: str, project: str) -> str:
+    match = _TYPE_RE.search(text.split("\n---", 1)[0]) if text.startswith("---") else None
+    memory_type = match["type"].lower() if match else "project"
+    name = _PREFIX_RE.sub("", filename)
+    if memory_type in _USER_WIDE_TYPES:
+        return f"/memories/{memory_type}/{name}"
+    return f"/memories/projects/{project}/{name}"
+
+
+def _exists(files: MemoryFiles, path: str) -> bool:
+    try:
+        files.view(path)
+    except Exception:
+        return False
+    return True
+
+
+def _checkout_for(slug: str) -> Path | None:
+    """The directory Claude Code named *slug*, found by walking the filesystem from ``/``.
+
+    The slug is lossy: ``/repos/ai-toolkit`` and ``/repos/ai/toolkit`` give
+    the same one. So each step matches the directory's real entries by their
+    own slugs, preferring the longest, and backtracks when a path dead-ends.
+    """
+    tokens = slug.lstrip("-").split("-")
+    return _walk(Path("/"), tokens) if tokens and tokens[0] else None
+
+
+def _walk(directory: Path, tokens: list[str]) -> Path | None:
+    if not tokens:
+        return directory
+    try:
+        entries = [entry for entry in directory.iterdir() if entry.is_dir()]
+    except OSError:
+        return None
+    by_slug: dict[str, Path] = {}
+    for entry in entries:
+        by_slug.setdefault(_SLUG_RE.sub("-", entry.name), entry)
+    for width in range(len(tokens), 0, -1):
+        entry = by_slug.get("-".join(tokens[:width]))
+        if entry is not None and (found := _walk(entry, tokens[width:])) is not None:
+            return found
+    return None
+
+
+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
+
+    return safe_key(slug.strip("-"))
+
+
+def _settings_path(home: Path) -> Path:
+    return home / ".claude" / "settings.json"
+
+
+def _read_settings(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        settings = json.loads(path.read_text(encoding="utf-8") or "{}")
+    except json.JSONDecodeError as exc:
+        raise MemoryBackendError(f"{path} is not valid JSON ({exc}); fix it, then re-run.") from exc
+    if not isinstance(settings, dict):
+        raise MemoryBackendError(f"{path} must hold a JSON object; fix it, then re-run.")
+    return settings
+
+
+def _set(path: Path, value: bool | None) -> list[str]:
+    """Write ``autoMemoryEnabled`` (None removes it), backing the file up once before the first change."""
+    settings = _read_settings(path)
+    if settings.get(_SETTING) == value or (value is None and _SETTING not in settings):
+        return [f"Unchanged {path}"]
+    if value is None:
+        settings.pop(_SETTING)
+    else:
+        settings[_SETTING] = value
+    backup = path.with_name(path.name + _BACKUP_SUFFIX)
+    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")
+    state = "removed" if value is None else json.dumps(value)
+    return [f"Wrote {path} ({_SETTING} {state})"]
+
+
+CLAUDE_CODE_MEMORY = ClaudeCodeMemory()

memgraph_context_graph/adapters/codex.py

@@ -0,0 +1,118 @@
+"""OpenAI Codex command-hook runtime adapter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    pre_tool_use_context,
+    session_start,
+    tool_end,
+    tool_start,
+    turn_end,
+    write_hook_config,
+)
+from memgraph_context_graph.adapters.codex_memory import CODEX_MEMORY
+from memgraph_context_graph.events import MessageEvent
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from memgraph_context_graph.events import Event
+
+
+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 _turn_end(context: EventContext) -> list[Event]:
+    # Codex has no session-end hook, and Stop fires after every turn, so it is
+    # only ever a turn end.
+    return turn_end(context, reply=context.payload.get("last_assistant_message"))
+
+
+_HOOKS_PATH = ".codex/hooks.json"
+SPEC = RuntimeSpec(
+    name="codex",
+    source_sdk="codex",
+    event_key="hook_event_name",
+    hooks=("SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop"),
+    rules={
+        "SessionStart": session_start,
+        "UserPromptSubmit": _user_prompt,
+        "PreToolUse": tool_start,
+        "PostToolUse": tool_end,
+        "PermissionRequest": _permission,
+        "Stop": _turn_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,
+    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)
+    config_path.write_text("[features]\nhooks = true\n", encoding="utf-8")
+    print(f"Wrote {config_path}")
+    print(f"Wrote {hooks_path}")
+
+
+PLUGIN = SpecPlugin(SPEC, CodexHooksAdapter, init=init, native_memory=CODEX_MEMORY)

memgraph_context_graph/adapters/codex_memory.py

@@ -0,0 +1,185 @@
+"""Codex's built-in memories, as Context Graph switches away from and imports them.
+
+Codex keeps one global memory store in ``$CODEX_HOME/memories/`` (default
+``~/.codex``), written by its own background pipeline. Only
+``memory_summary.md`` is injected into a session; the model opens
+``MEMORY.md`` and the rest on demand. Memories are injected only while both
+``[features] memories`` (off by default) and ``[memories] use_memories`` are
+on, and ``generate_memories`` controls whether new threads feed the pipeline.
+
+Switching to Context Graph turns all three off in the user-level
+``config.toml``, the same scope ``[memory] backend`` has. Handing memory back
+restores whatever they were before. The plugin's MCP server allows every tool
+unless the user's own ``[mcp_servers.context-graph]`` narrows it with
+``enabled_tools``; then ``memory`` is added there too.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.memory_backend import ImportReport, MemoryBackendError
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.memory_backend import MemoryFiles
+
+_BACKUP_SUFFIX = ".context-graph.bak"
+_SERVER = "context-graph"
+#: (table, key) pairs this switch owns, and the value that turns each off.
+_SWITCHES = (
+    (("features", "memories"), False),
+    (("memories", "use_memories"), False),
+    (("memories", "generate_memories"), False),
+)
+#: Files a Codex memory store may hold, under v1's ``memories/`` or v2's ``memories_v2/``,
+#: and where each lands in ``/memories``. Codex's store is global, so nothing is per project.
+_IMPORTS = (
+    ("memory_summary.md", "/memories/user/codex-memory-summary.md", "What Codex had learned about the user", "user"),
+    ("MEMORY.md", "/memories/codex/memory.md", "Codex's task-by-task memory, as it consolidated it", "reference"),
+)
+
+
+@dataclass(frozen=True)
+class CodexMemory:
+    """Codex's built-in memories (``NativeMemory``)."""
+
+    def enabled(self, home: Path) -> bool:
+        """Whether Codex would inject its memories: ``features.memories`` on and ``use_memories`` not off."""
+        config = _read(_config_path(home))
+        return (
+            bool(_get(config, ("features", "memories"), False))
+            and _get(config, ("memories", "use_memories"), True) is not False
+        )
+
+    def disable(self, home: Path) -> list[str]:
+        """Turn Codex's memories off in its user ``config.toml`` and let the ``memory`` tool through.
+
+        Raises:
+            MemoryBackendError: the config file isn't valid TOML.
+        """
+        path = _config_path(home)
+        config = _read(path)
+        for keys, off in _SWITCHES:
+            _set(config, keys, off)
+        server = config.get("mcp_servers", {}).get(_SERVER)
+        if (
+            server is not None
+            and isinstance(server.get("enabled_tools"), list)
+            and "memory" not in server["enabled_tools"]
+        ):
+            server["enabled_tools"].append("memory")
+        return _write(path, config)
+
+    def enable(self, home: Path) -> list[str]:
+        """Restore the memory keys to what they were before :meth:`disable` first ran.
+
+        Keys that didn't exist then are removed, which leaves Codex's own
+        defaults (``features.memories`` is off by default).
+
+        Raises:
+            MemoryBackendError: the config file or its backup isn't valid TOML.
+        """
+        path = _config_path(home)
+        backup = path.with_name(path.name + _BACKUP_SUFFIX)
+        before = _read(backup) if backup.exists() else {}
+        config = _read(path)
+        for keys, _off in _SWITCHES:
+            previous = _get(before, keys, None)
+            if previous is None:
+                _remove(config, keys)
+            else:
+                _set(config, keys, previous)
+        return _write(path, config)
+
+    def import_into(self, files: MemoryFiles, home: Path) -> ImportReport:
+        """Copy Codex's consolidated memories into ``/memories``, never overwriting a path.
+
+        The summary Codex injected each session becomes a ``user`` memory;
+        its task-group ``MEMORY.md`` a ``reference`` file the model can open.
+        Rollout summaries and raw memories are Codex's intermediate state and
+        stay where they are.
+        """
+        report = ImportReport()
+        codex_home = _codex_home(home)
+        for store in ("memories", "memories_v2"):
+            for source_name, target, description, memory_type in _IMPORTS:
+                source = codex_home / store / source_name
+                if not source.is_file() or not (text := source.read_text(encoding="utf-8")).strip():
+                    continue
+                if store == "memories_v2":
+                    target = target.replace(".md", "-v2.md")
+                try:
+                    files.view(target)
+                except Exception:
+                    try:
+                        files.create(target, f"---\ndescription: {description}\ntype: {memory_type}\n---\n{text}")
+                    except Exception:  # Too large for one memory file: leave it in Codex's store.
+                        report.skipped.append(target)
+                        continue
+                    report.imported.append(target)
+                    continue
+                report.skipped.append(target)
+        return report
+
+
+def _codex_home(home: Path) -> Path:
+    override = os.environ.get("CODEX_HOME")
+    return Path(override) if override else home / ".codex"
+
+
+def _config_path(home: Path) -> Path:
+    return _codex_home(home) / "config.toml"
+
+
+def _read(path: Path) -> Any:
+    import tomlkit
+    from tomlkit.exceptions import ParseError
+
+    if not path.exists():
+        return tomlkit.document()
+    try:
+        return tomlkit.parse(path.read_text(encoding="utf-8"))
+    except ParseError as exc:
+        raise MemoryBackendError(f"{path} is not valid TOML ({exc}); fix it, then re-run.") from exc
+
+
+def _get(config: Any, keys: tuple[str, str], default: Any) -> Any:
+    table = config.get(keys[0])
+    return table.get(keys[1], default) if hasattr(table, "get") else default
+
+
+def _set(config: Any, keys: tuple[str, str], value: Any) -> None:
+    import tomlkit
+
+    table = config.get(keys[0])
+    if not hasattr(table, "get"):
+        table = tomlkit.table()
+        config[keys[0]] = table
+    table[keys[1]] = value
+
+
+def _remove(config: Any, keys: tuple[str, str]) -> None:
+    table = config.get(keys[0])
+    if hasattr(table, "get") and keys[1] in table:
+        del table[keys[1]]
+
+
+def _write(path: Path, config: Any) -> list[str]:
+    import tomlkit
+
+    rendered = tomlkit.dumps(config)
+    if path.exists() and path.read_text(encoding="utf-8") == rendered:
+        return [f"Unchanged {path}"]
+    backup = path.with_name(path.name + _BACKUP_SUFFIX)
+    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")
+    return [f"Wrote {path}"]
+
+
+CODEX_MEMORY = CodexMemory()