memdebug 0.2.0__py3-none-any.whl

memdebug/agents.py

@@ -0,0 +1,128 @@
+"""Which agents are on this computer, and where each keeps what it remembers.
+
+Each entry below was checked against the agent's own documentation. Presence is judged only by whether a known folder exists
+(`lstat`; nothing is opened or read, links and junctions are ignored). Where an agent keeps memory in one file inside a folder
+that also holds settings or credentials (`~/.gemini`, `~/.codex`, `~/.claude`), only that file is offered, never the folder.
+
+Assistants that keep their memory in the provider's cloud (ChatGPT, Claude's apps, Gemini, Copilot) have nothing on this computer
+to watch, and memdebug says so instead of pretending: it cannot tell whether those apps are installed, and it could not read
+their memory if they were.
+"""
+from __future__ import annotations
+
+import os
+import stat
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .adapters.markdown_git import _is_reparse_point
+from .stores import Candidate, discover
+
+
+@dataclass(frozen=True)
+class Place:
+    parts: tuple[str, ...]      # folder, relative to the home folder
+    files: tuple[str, ...] = ()  # if set: only these files in that folder, nothing else
+    name: str = ""              # suggested store name
+    what: str = ""
+    always: bool = False        # offer even before any note exists (the agent creates the folder itself)
+
+
+@dataclass(frozen=True)
+class Agent:
+    key: str
+    name: str
+    sign: tuple[str, ...]       # a folder under home whose existence means the agent is probably installed
+    note: str
+    places: tuple[Place, ...] = ()
+
+
+AGENTS: tuple[Agent, ...] = (
+    Agent("claude-code", "Claude Code", (".claude",),
+          "keeps notes in CLAUDE.md files and a memory folder per project",
+          (Place((".claude",), ("CLAUDE.md",), "claude-code-global", "your global CLAUDE.md instructions"),)),
+    Agent("openclaw", "OpenClaw", (".openclaw",),
+          "keeps its memory as markdown in a workspace folder (MEMORY.md, memory/, USER.md); its documentation suggests keeping it in git",
+          (Place((".openclaw", "workspace"), (), "openclaw", "the OpenClaw workspace (memory, identity and instruction files)", always=True),)),
+    Agent("gemini-cli", "Gemini CLI", (".gemini",),
+          "saves what it is asked to remember in ~/.gemini/GEMINI.md",
+          (Place((".gemini",), ("GEMINI.md",), "gemini-cli", "GEMINI.md, where its memory tool saves facts", always=True),)),
+    Agent("codex-cli", "Codex CLI", (".codex",),
+          "has no memory of its own; it follows the instructions in ~/.codex/AGENTS.md, which is why planted text there matters",
+          (Place((".codex",), ("AGENTS.md", "AGENTS.override.md"), "codex-cli", "its AGENTS.md instruction files"),)),
+    Agent("windsurf", "Windsurf", (".codeium", "windsurf"),
+          "stores its automatically generated memories on this computer only",
+          (Place((".codeium", "windsurf", "memories"), (), "windsurf", "Cascade's memories (the markdown files in it)"),)),
+)
+
+CLOUD_NOTE = ("ChatGPT, Claude (claude.ai and its desktop and phone apps), Gemini and Copilot keep their memory in the provider's cloud. "
+              "memdebug cannot see it, and cannot tell whether those apps are installed. Review or clear it in each app's settings; "
+              "to keep a record of how it changes, copy it into a markdown file now and then, in a folder you add to memdebug.")
+
+
+@dataclass
+class FoundAgent:
+    agent: Agent
+    candidates: list[Candidate] = field(default_factory=list)
+
+
+def _real_folder(path: Path) -> bool:
+    try:
+        info = os.lstat(path)
+    except OSError:
+        return False
+    return stat.S_ISDIR(info.st_mode) and not stat.S_ISLNK(info.st_mode) and not _is_reparse_point(info)
+
+
+def _has_markdown(path: Path) -> bool:
+    try:
+        return any(name.lower().endswith(".md") for name in os.listdir(path)[:2000])
+    except OSError:
+        return False
+
+
+def _is_plain_file(path: Path) -> bool:
+    try:
+        info = os.lstat(path)
+    except OSError:
+        return False
+    return stat.S_ISREG(info.st_mode) and not _is_reparse_point(info)
+
+
+def scan_agents(home: Path | None = None) -> list[FoundAgent]:
+    """The known agents that appear to be installed, with what could be watched for each. Reads no file contents."""
+    root = home or Path.home()
+    found: list[FoundAgent] = []
+    for agent in AGENTS:
+        if not _real_folder(root.joinpath(*agent.sign)):
+            continue
+        entry = FoundAgent(agent)
+        for place in agent.places:
+            folder = root.joinpath(*place.parts)
+            if not _real_folder(folder):
+                continue
+            if place.files:
+                present = [name for name in place.files if _is_plain_file(folder / name)]
+                if not present and not place.always:
+                    continue
+                entry.candidates.append(Candidate("folder", place.name, folder, f"{agent.name}: {place.what}", files=place.files))
+            elif place.always or _has_markdown(folder):
+                entry.candidates.append(Candidate("folder", place.name, folder, f"{agent.name}: {place.what}"))
+        if agent.key == "claude-code":  # its per-project memory folders are found by name, as before
+            entry.candidates += [Candidate(c.kind, c.name, c.path, f"{agent.name}: {c.why}") for c in discover(root)]
+        found.append(entry)
+    return found
+
+
+def summary_lines(found: list[FoundAgent], docker_names: list[str] | None = None) -> list[str]:
+    lines = []
+    for item in found:
+        watchable = f"{len(item.candidates)} place(s) memdebug can watch" if item.candidates else "nothing to watch yet"
+        lines.append(f"  {item.agent.name}: {item.agent.note} ({watchable})")
+    for container in docker_names or []:
+        lines.append(f"  Open WebUI (running in Docker as '{container}'): keeps its memory in a database (1 place memdebug can watch)")
+    if not lines:
+        lines.append("  None of the agents memdebug knows were found.")
+    lines.append("")
+    lines.append(f"  {CLOUD_NOTE}")
+    return lines

memdebug/backends.py

@@ -0,0 +1,29 @@
+"""Small facts about store types that the viewer and the command line both need."""
+from __future__ import annotations
+
+import re
+
+from .textsafe import safe_text
+
+# Stores that keep no change history of their own: memdebug can only record what it sees between two looks, so it cannot say
+# who made a change or whether it bypassed anything.
+HISTORYLESS = frozenset({"folder", "openwebui"})
+
+_OPAQUE = re.compile(r"[0-9a-fA-F]{8}(?:-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}|[0-9a-fA-F]{32}|[0-9a-fA-F]{40}|[0-9a-fA-F]{64}")
+
+
+def is_opaque_id(memory_id: str) -> bool:
+    """A random identifier (a UUID or a hash) that tells a person nothing, as opposed to a file name or a short id."""
+    return _OPAQUE.fullmatch(memory_id) is not None
+
+
+def short_id(memory_id: str) -> str:
+    return memory_id[:8] + "…" if is_opaque_id(memory_id) else memory_id
+
+
+def friendly_id(memory_id: str, text: str | None, width: int = 40) -> str:
+    """For an opaque id: its short form and the start of what the memory says. Otherwise the id itself, which is already meaningful."""
+    if not is_opaque_id(memory_id):
+        return safe_text(memory_id, 60)
+    words = safe_text(" ".join((text or "").split()), width)
+    return f'{memory_id[:8]}… "{words}"' if words else f"{memory_id[:8]}…"