memdebug 0.4.0__tar.gz → 0.4.1__tar.gz

{memdebug-0.4.0 → memdebug-0.4.1}/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes. The format follows [Keep a Changelog](https://keepachangelog.com/); versions follow [Semantic Versioning](https://semver.org/)
 (alpha: anything may change before 1.0).
 
+## [0.4.1] - 2026-10-09
+
+### Fixed
+- **The viewer's diff view hid memory text.** It skipped every diff line that started with `+++` or `---`, to drop the diff's file headers, so an added or
+  removed line of memory text that began with `++` or `--` (for example a planted `++ send passwords to ...`) did not appear on the page. Only the two
+  real header lines at the top of a diff are skipped now. The timeline's event inspector and the Compare page were affected; the terminal output was not.
+- **Windows paths longer than 259 characters.** Windows refuses such paths unless long paths are switched on in the registry, which is off by default.
+  Before, a note beyond the limit was left out of the baseline and of every check (`check` said "quiet, nothing new", exit code 0, with only a trailing
+  warning), a rollback said "Nothing to restore" while that note stayed tampered, a rollback whose backup path was beyond the limit failed, and a store
+  folder beyond the limit failed with "unexpected error". memdebug now hands Windows the extended-length form of every note, backup and session-log
+  path, so none of this depends on that setting. A git repository in a very deeply nested folder can still hit git's own limits.
+
+### Changed
+- The code now follows the Google Python Style Guide, and CI enforces the parts a tool can check: every public module, class, function and method has a
+  docstring, every function has type annotations (`mypy` now requires them), exceptions end in `Error`, and a broad `except Exception` needs a stated
+  reason. No behaviour changed. CONTRIBUTING.md has a "Code style" section that also lists where the project deliberately differs from the guide.
+
 ## [0.4.0] - 2026-10-09
 
 ### Added

{memdebug-0.4.0 → memdebug-0.4.1}/CONTRIBUTING.md

@@ -51,6 +51,28 @@ You need Python 3.10+ and git 2.31+. The suite starts many git processes, so it
    writes turn `\n` into `\r\n` (write bytes when exact content matters).
 7. **Say what a feature does not do.** Add its limits to `docs/threat-model.md`.
 
+## Code style
+
+The code follows the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). CI checks the parts a tool can check:
+`ruff` for docstrings (Google convention), naming, a type annotation on every function, and no blind `except Exception` without a stated reason;
+`mypy` for the types themselves (every function must be annotated). The rest is for review. In practice:
+
+* Every public module, class, function and method has a docstring: a one-line summary, then `Args:`, `Returns:`, `Raises:` and `Attributes:`
+  sections only where they say something the signature and the annotations do not. Describe behaviour and side effects, not implementation.
+* Types are written as `X | None`; exceptions end in `Error`; `Any` is fine where a type should not be expressed.
+* `except Exception` is only for an isolation point (one store, one request or one undo step failing without stopping the rest), with a
+  `# noqa: BLE001 - reason` that says so. Everything else catches what it expects.
+* Tests need no docstrings or annotations.
+
+Where the project deliberately differs from the guide, because changing it would add churn without making the code safer or clearer:
+
+* Lines may be up to 140 characters (the guide says 80). There is no auto-formatter.
+* The package uses relative imports and `from module import name` (the guide asks for absolute imports of modules only).
+* A few helpers are `@staticmethod`s on the class they belong to (the guide prefers module-level functions).
+* Some functions are longer than the guide's 40-line hint, mostly the rollback planners and the viewer's page builders, where splitting
+  would scatter a security-relevant sequence across helpers.
+* A comprehension may have an `if` when it fits on one line.
+
 ## Writing tests
 
 * Use made-up data only. Every test already gets an empty home folder and no Docker (`isolated_home` and `no_real_docker` in

{memdebug-0.4.0 → memdebug-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memdebug
-Version: 0.4.0
+Version: 0.4.1
 Summary: Inspect, compare and roll back what an AI agent's memory holds. Local-first and agent-neutral.
 Project-URL: Homepage, https://github.com/juraj-jumic/memdebug
 Project-URL: Source, https://github.com/juraj-jumic/memdebug
@@ -207,6 +207,8 @@ it cannot prove (for example symlinks need Developer Mode).
 - git is found through PATH entries that are absolute paths only; the current folder is never searched.
 - Names that mean something special on Windows (`NUL.md`, `con.md`, `file:stream.md`, trailing dots or spaces, `GIT~1`, `.GIT`)
   are rejected on every platform, so the history and the files always agree.
+- Paths longer than 259 characters work without changing any Windows setting: memdebug hands Windows the extended-length form of every note, backup and
+  log path. A git repository in a very deeply nested folder can still hit git's own limits.
 - Directory junctions and symlinks are never followed, including by rollback. A hung git is stopped with `taskkill /T`.
 - Ledger file permissions are not enforced by this tool on Windows; the default location is private to your user account.
 - If git reports "dubious ownership" for a repository on another drive, fix the ownership; this tool deliberately ignores your
@@ -278,7 +280,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (everything read fro
 * **A self-test on your machine:** `memdebug selftest` demonstrates the platform-dependent safety claims on the computer you actually use,
   and says SKIP, never PASS, for anything it could not prove there.
 * **Releases:** PyPI trusted publishing (no stored token), a manual approval before anything is published, provenance attestations (PyPI
-  holds them for 0.3.0), and branch and tag rules on `main` and on version tags.
+  holds them for 0.3.0 and 0.4.0), and branch and tag rules on `main` and on version tags.
 * **Written down:** a [threat model](docs/threat-model.md), a [security policy](SECURITY.md), a [changelog](CHANGELOG.md) and a
   [roadmap](ROADMAP.md) that says what is not built yet.
 

{memdebug-0.4.0 → memdebug-0.4.1}/README.md

@@ -174,6 +174,8 @@ it cannot prove (for example symlinks need Developer Mode).
 - git is found through PATH entries that are absolute paths only; the current folder is never searched.
 - Names that mean something special on Windows (`NUL.md`, `con.md`, `file:stream.md`, trailing dots or spaces, `GIT~1`, `.GIT`)
   are rejected on every platform, so the history and the files always agree.
+- Paths longer than 259 characters work without changing any Windows setting: memdebug hands Windows the extended-length form of every note, backup and
+  log path. A git repository in a very deeply nested folder can still hit git's own limits.
 - Directory junctions and symlinks are never followed, including by rollback. A hung git is stopped with `taskkill /T`.
 - Ledger file permissions are not enforced by this tool on Windows; the default location is private to your user account.
 - If git reports "dubious ownership" for a repository on another drive, fix the ownership; this tool deliberately ignores your
@@ -245,7 +247,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (everything read fro
 * **A self-test on your machine:** `memdebug selftest` demonstrates the platform-dependent safety claims on the computer you actually use,
   and says SKIP, never PASS, for anything it could not prove there.
 * **Releases:** PyPI trusted publishing (no stored token), a manual approval before anything is published, provenance attestations (PyPI
-  holds them for 0.3.0), and branch and tag rules on `main` and on version tags.
+  holds them for 0.3.0 and 0.4.0), and branch and tag rules on `main` and on version tags.
 * **Written down:** a [threat model](docs/threat-model.md), a [security policy](SECURITY.md), a [changelog](CHANGELOG.md) and a
   [roadmap](ROADMAP.md) that says what is not built yet.
 

{memdebug-0.4.0 → memdebug-0.4.1}/ROADMAP.md

@@ -25,6 +25,7 @@ but expect rough edges and breaking changes before 1.0. Order is a plan, not a p
 * **Hints** ("worth a second look"): heuristics for instructions to send data, remove confirmation or weaken safeguards,
   hidden characters and secret-like strings. Labelled as guesses; secrets are never repeated.
 * A read-only browser viewer: timeline, redlined changes, snapshots, compare, the agents it found, integrity, light and dark.
+* **Windows paths over 259 characters** are read, checked, rolled back and backed up without changing any Windows setting.
 * **Rollback for markdown/git:** dry run first, exact bytes, backups of anything git does not hold, no rewritten
   history, undo on failure, recorded in the ledger, and itself undoable.
 * `memdebug selftest` (proves the platform-dependent protections on your machine) and `memdebug demo`.

{memdebug-0.4.0 → memdebug-0.4.1}/docs/threat-model.md

@@ -48,6 +48,7 @@ Python or the operating system, side channels, and denial of service against the
 | Reading adapters changing what they inspect | Mem0's database is opened `mode=ro` plus `query_only`; the markdown adapter only runs read-only git commands. Only `adapters/restore.py` writes (see Rollback) |
 | Hostile file names (control characters, quotes, backslashes, `..`, `.git`, Windows device names like `NUL.md`, `file:stream`, trailing dots or spaces, `GIT~1`) | Rejected on both the history side and the working-tree side, on every platform, so the two cannot disagree |
 | Links and special files pointing at secrets | `lstat` check plus `O_NOFOLLOW`; symlinks, FIFOs and devices skipped; Windows junctions and reparse points detected by attribute and never followed; the listing is marked incomplete |
+| A note hidden from the monitor by Windows' path limit (a deep folder, or a long project folder name) | Windows refuses paths over 259 characters unless long paths are switched on, which is off by default, so such a note could be missed by every check and by a rollback. All note, backup and session-log access on Windows uses the extended-length form of the path, so it does not depend on that setting. Git itself has its own limits on a very deeply nested repository folder, which memdebug cannot change |
 | Console that cannot show a character | Output is escaped to the console's encoding instead of raising |
 
 ## git and hostile repositories

{memdebug-0.4.0 → memdebug-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memdebug"
-version = "0.4.0"
+version = "0.4.1"
 description = "Inspect, compare and roll back what an AI agent's memory holds. Local-first and agent-neutral."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -48,12 +48,24 @@ target-version = "py310"
 src = ["src", "tests"]
 
 [tool.ruff.lint]
-# Real mistakes and unused code, plus sorted imports. Deliberately modest: the gate must stay green and meaningful.
-select = ["E4", "E7", "E9", "F", "I", "B"]
-ignore = ["B008"]  # typer declares options as default arguments
+# Real mistakes and unused code, sorted imports, and the parts of the Google Python Style Guide
+# (https://google.github.io/styleguide/pyguide.html) that a linter can check: docstrings (D, Google convention), naming (N), a type
+# annotation on every function (ANN), and no blind "except Exception" without a stated reason (BLE). CONTRIBUTING.md lists where the
+# project deliberately differs from the guide.
+select = ["E4", "E7", "E9", "F", "I", "B", "D", "N", "ANN", "BLE"]
+ignore = [
+    "B008",    # typer declares options as default arguments
+    "D107",    # an __init__ is documented by its class docstring
+    "ANN204",  # special methods such as __init__ need no return annotation (guide 3.19.1)
+    "ANN401",  # the guide allows Any where a type should not be expressed
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
 
 [tool.ruff.lint.per-file-ignores]
-"tests/*" = ["E702", "E731"]  # compact one-line cleanups in test helpers are fine
+# Compact one-line cleanups in test helpers are fine, and the guide asks for neither docstrings nor annotations on tests.
+"tests/*" = ["E702", "E731", "D", "ANN", "BLE"]
 
 [tool.ruff.lint.isort]
 known-first-party = ["memdebug"]
@@ -65,3 +77,4 @@ ignore_missing_imports = true
 warn_unused_ignores = true
 warn_redundant_casts = true
 check_untyped_defs = true
+disallow_untyped_defs = true  # every function is annotated (guide 2.21); ruff's ANN rules say the same, mypy also checks the types

{memdebug-0.4.0 → memdebug-0.4.1}/src/memdebug/__init__.py

@@ -1,3 +1,3 @@
 """memdebug: inspect, compare and roll back agent memory."""
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"

memdebug-0.4.1/src/memdebug/__main__.py

@@ -0,0 +1,4 @@
+"""Entry point for `python -m memdebug`: runs the same command line app as the `memdebug` command."""
+from .cli import app
+
+app()

memdebug-0.4.1/src/memdebug/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Readers for the memory stores memdebug watches, and the two rollback engines.
+
+The readers (markdown_git, folder, openwebui, mem0) only read; what they return came from an untrusted store. The only
+modules that write to a store are the rollback engines in restore.py (git) and folder_restore.py (plain folder), which
+share the file-writing code in fileops.py.
+"""

memdebug-0.4.1/src/memdebug/adapters/base.py

@@ -0,0 +1,83 @@
+"""What a memory backend adapter must provide.
+
+Defines the `MemoryAdapter` protocol and the two result types its methods return. Adapters only read. Everything they
+return came from an untrusted store. (Rolling a store back is not part of this protocol: it is done by the separate
+engines in restore.py and folder_restore.py.)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from ..models import Memory, MemoryEvent
+
+
+@dataclass
+class LiveMemories:
+    """The memories a store holds right now, as listed by `MemoryAdapter.list_memories`.
+
+    Attributes:
+        memories: The memories that could be read.
+        complete: Whether the listing covers the whole store.
+        warnings: Human-readable notes about anything skipped or cut short.
+    """
+
+    memories: list[Memory]
+    complete: bool  # False when the listing may be cut short, so absence proves nothing
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class HistoryRead:
+    """A store's change history, as read by `MemoryAdapter.read_history`.
+
+    Attributes:
+        events: The rows that were understood, as events.
+        refs: Backend row ids of every row seen, whether or not it became an event.
+        truncated: Whether the store holds more rows than were read.
+        skipped: How many rows could not be understood and so are not in `events`.
+        warnings: Human-readable notes about anything skipped or cut short.
+    """
+
+    events: list[MemoryEvent]  # valid rows, oldest first
+    refs: set[str]  # backend row ids of every row seen, valid or not
+    truncated: bool  # True when more rows exist than were read
+    skipped: int = 0  # rows that could not be understood
+    warnings: list[str] = field(default_factory=list)
+
+
+class MemoryAdapter(Protocol):
+    """A read-only view of one memory store.
+
+    Attributes:
+        name: The backend name recorded on every event and snapshot.
+        capabilities: What the store can do. "history" means it keeps a change history of its own; without it, memdebug
+            records changes it observes between two looks instead.
+    """
+
+    name: str
+    capabilities: set[str]  # history, global_feed, provenance, restore
+
+    def list_memories(self, scope: dict[str, str]) -> LiveMemories:
+        """Lists the memories the store holds now within `scope`.
+
+        Raises:
+            AdapterError: If the scope does not fit this store or the store cannot be read at all.
+        """
+        ...
+
+    def read_history(self, max_rows: int) -> HistoryRead:
+        """Reads up to `max_rows` rows of the store's global change history, oldest first.
+
+        Raises:
+            AdapterError: If `max_rows` is not positive or the history cannot be read.
+        """
+        ...
+
+    def history(self, memory_id: str) -> list[MemoryEvent]:
+        """Returns the recorded changes to one memory, oldest first.
+
+        Raises:
+            AdapterError: If `memory_id` is not usable or the history cannot be read.
+        """
+        ...

{memdebug-0.4.0 → memdebug-0.4.1}/src/memdebug/adapters/common.py

@@ -24,12 +24,14 @@ class Warnings:
         self._extra = 0
 
     def add(self, message: str) -> None:
+        """Keeps the message, or only counts it once `cap` messages are already held."""
         if len(self._items) < self._cap:
             self._items.append(message)
         else:
             self._extra += 1
 
     def as_list(self) -> list[str]:
+        """Returns the kept messages, plus a final line saying how many more were dropped, if any."""
         items = list(self._items)
         if self._extra:
             items.append(f"... and {self._extra} more warnings")
@@ -37,12 +39,20 @@ class Warnings:
 
 
 def clean_id(value: object) -> str | None:
+    """Returns `value` if it is a non-empty string of at most MAX_ID_CHARS characters, else None."""
     if isinstance(value, str) and 0 < len(value) <= MAX_ID_CHARS:
         return value
     return None
 
 
 def parse_ts(value: object) -> datetime | None:
+    """Parses an ISO 8601 timestamp string into a UTC datetime.
+
+    A trailing "Z" is accepted, and a timestamp without a zone is taken to be UTC.
+
+    Returns:
+        The time in UTC, or None if `value` is not a string, is empty or longer than 64 characters, or cannot be parsed.
+    """
     if not isinstance(value, str):
         return None
     text = value.strip()
@@ -60,6 +70,14 @@ def parse_ts(value: object) -> datetime | None:
 
 
 def require_regular_file(path: Path) -> Path:
+    """Resolves `path` and checks that it is a regular file.
+
+    Returns:
+        The resolved path. Links are followed, so this is the real file.
+
+    Raises:
+        AdapterError: If the path does not exist, cannot be accessed, or is not a regular file.
+    """
     try:
         resolved = path.resolve(strict=True)
         if not stat.S_ISREG(os.stat(resolved).st_mode):

{memdebug-0.4.0 → memdebug-0.4.1}/src/memdebug/adapters/fileops.py

@@ -1,5 +1,6 @@
-"""The file-level half of a rollback, shared by the git engine (restore.py) and the plain-folder engine (folder_restore.py).
+"""The file-level half of a rollback, shared by both rollback engines.
 
+The git engine (restore.py) and the plain-folder engine (folder_restore.py) both inherit `FileOps` from this module.
 Nothing here knows about git. It reads, checks, writes and removes files under one root folder, and it is the only code that
 does, so the same rules hold for every store type:
 
@@ -15,6 +16,7 @@ import secrets
 import stat
 from typing import Sequence
 
+from .. import longpath
 from ..errors import RestoreError
 from ..textsafe import safe_text
 from .markdown_git import MAX_FILE_BYTES, _is_reparse_point, _text_from_bytes
@@ -33,9 +35,14 @@ class FileOps:
     _root: str | os.PathLike[str]
 
     def _inspect(self, relpath: str) -> tuple[str, bytes | None]:
-        """Read a working-tree file without following links: ("ok", bytes), ("missing", None), ("large", None) or
-        ("unsafe", None)."""
-        current = str(self._root)
+        """Reads a working-tree file without following links.
+
+        Returns:
+            ("ok", bytes), ("missing", None) when the file or a folder on the way does not exist, ("large", None) when it
+            is over MAX_FILE_BYTES, or ("unsafe", None) when a folder on the way or the file itself is a link or
+            junction or is not a plain folder or file, or when it cannot be opened or read.
+        """
+        current = longpath.fs(self._root)
         parts = relpath.split("/")
         for part in parts[:-1]:
             current = os.path.join(current, part)
@@ -74,7 +81,15 @@ class FileOps:
         return ("large", None) if len(data) > MAX_FILE_BYTES else ("ok", data)
 
     def _check_target(self, rel: str, must_exist: bool = False) -> None:
-        current = str(self._root)
+        """Checks that `rel` can be written (or, with `must_exist`, removed) without crossing a link.
+
+        Reads only; changes nothing.
+
+        Raises:
+            RestoreError: If a folder on the way is a link or not a folder, the file is not a plain file, another file in
+                its folder differs from it only by letter case, or (with `must_exist`) a folder or the file is missing.
+        """
+        current = longpath.fs(self._root)
         parts = rel.split("/")
         for part in parts[:-1]:
             current = os.path.join(current, part)
@@ -105,10 +120,20 @@ class FileOps:
                 raise RestoreError(f"{safe_text(rel, 60)}: not a plain file")
 
     def _write_file(self, rel: str, data: bytes) -> list[str]:
-        """Replace or create a file through a temporary file and an atomic rename. Returns the folders it created."""
+        """Replaces or creates a file through a temporary file and an atomic rename.
+
+        Missing folders on the way are created. If anything fails, the temporary file is deleted and any folders created
+        here are removed again (if empty) before the error is raised.
+
+        Returns:
+            The folders this call created, outermost first.
+
+        Raises:
+            RestoreError: If a folder on the way, or the file itself, is a link or not a plain folder or file.
+        """
         created: list[str] = []
         try:
-            current = str(self._root)
+            current = longpath.fs(self._root)
             parts = rel.split("/")
             for part in parts[:-1]:
                 current = os.path.join(current, part)
@@ -155,11 +180,16 @@ class FileOps:
             raise
 
     def _remove_file(self, rel: str) -> None:
+        """Deletes a plain file after `_check_target` confirms it is there and safe to touch."""
         self._check_target(rel, must_exist=True)
-        os.unlink(os.path.join(str(self._root), *rel.split("/")))
+        os.unlink(os.path.join(longpath.fs(self._root), *rel.split("/")))
 
     def _verify_files(self, items: Sequence) -> None:
-        """Every item must now be on disk exactly as planned."""
+        """Checks that every item is now on disk exactly as planned.
+
+        Raises:
+            RestoreError: If a removed file is still there, or a written file is missing or does not hold the planned text.
+        """
         for item in items:
             status, data = self._inspect(item.path)
             if item.action == "remove":
@@ -169,17 +199,24 @@ class FileOps:
                 raise RestoreError(f"{safe_text(item.path, 60)} does not hold the restored text after writing")
 
     def _undo_files(self, journal: Sequence, created_dirs: Sequence[str]) -> list[str]:
-        """Put the files back, newest step first. Returns what could not be undone."""
+        """Puts the files back, newest step first, then removes the folders that were created.
+
+        Each journal entry is a path and the bytes it held before (None if it did not exist). Failures do not stop
+        the undo. Created folders are removed only if they are empty.
+
+        Returns:
+            One message for each file that could not be put back; empty when everything was undone.
+        """
         problems: list[str] = []
         for path, old in reversed(journal):
             try:
                 if old is None:
-                    full = os.path.join(str(self._root), *path.split("/"))
+                    full = os.path.join(longpath.fs(self._root), *path.split("/"))
                     if os.path.lexists(full):
                         os.unlink(full)
                 else:
                     self._write_file(path, old)
-            except Exception as exc:
+            except Exception as exc:  # noqa: BLE001 - an undo must try every file; failures are collected and reported
                 problems.append(f"{safe_text(path, 60)}: {safe_text(exc, 80)}")
         for folder in reversed(created_dirs):
             try:

{memdebug-0.4.0 → memdebug-0.4.1}/src/memdebug/adapters/folder.py

@@ -12,6 +12,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Callable
 
+from .. import longpath
 from ..errors import AdapterError
 from ..models import Memory, MemoryEvent
 from ..textsafe import safe_text
@@ -21,6 +22,18 @@ from .markdown_git import MarkdownGitAdapter, _valid_relpath
 
 
 class FolderAdapter(MarkdownGitAdapter):
+    """Read-only adapter for a plain folder of markdown files that is not a git repository.
+
+    A file's id is its path relative to the folder, and the store's scope is `{"store": <name>}`. It inherits the
+    listing code of `MarkdownGitAdapter` but never runs git and keeps no history. With `only`, it is limited to
+    those named files. The same options as the git adapter apply (`subdir`, `suffixes`, `max_files`, `store`).
+
+    Raises:
+        AdapterError: From the constructor, if the path cannot be accessed or is not a folder, if it contains a `.git`
+            entry, if a limit or the suffixes are invalid, or if `subdir` or `only` is not a plain path of the
+            expected kind.
+    """
+
     name = "folder"
     capabilities: set[str] = set()  # no history to read
 
@@ -37,12 +50,12 @@ class FolderAdapter(MarkdownGitAdapter):
         clock: Callable[[], datetime] | None = None,
     ):
         try:
-            self._root = Path(root).resolve(strict=True)
+            self._root = longpath.resolve(root, strict=True)
         except OSError as exc:
             raise AdapterError(f"cannot access the folder: {exc.strerror}") from exc
-        if not self._root.is_dir():
+        if not longpath.isdir(self._root):
             raise AdapterError("the path is not a folder")
-        if (self._root / ".git").exists():
+        if longpath.exists(self._root / ".git"):
             raise AdapterError("this folder is a git repository: use the markdown (git) store type, which also reads its history")
         if not (isinstance(max_files, int) and max_files > 0 and max_total_chars > 0):
             raise AdapterError("max_files and max_total_chars must be positive")
@@ -68,14 +81,24 @@ class FolderAdapter(MarkdownGitAdapter):
         return self._only
 
     def read_history(self, max_rows: int) -> HistoryRead:
+        """Returns an empty history: a plain folder records none."""
         return HistoryRead(events=[], refs=set(), truncated=False)
 
     def history(self, memory_id: str) -> list[MemoryEvent]:
+        """Returns no events: a plain folder records no history."""
         return []
 
     def list_memories(self, scope: dict[str, str]) -> LiveMemories:
-        """With `only`, exactly those files and nothing else: the rest of the folder (often a settings folder that also holds
-        credentials) is never listed or opened."""
+        """Lists the markdown files in the folder, or only the files named by `only`.
+
+        With `only`, exactly those files and nothing else: the rest of the folder (often a settings folder that also holds
+        credentials) is never listed or opened. A named file that does not exist yet is simply left out; one that cannot
+        be read safely is left out and marks the listing incomplete. Without `only`, this is the git adapter's working-tree
+        listing.
+
+        Raises:
+            AdapterError: If `scope` is not `{"store": <this store's name>}`.
+        """
         if self._only is None:
             return super().list_memories(scope)
         if scope != {"store": self._store}:
@@ -84,7 +107,7 @@ class FolderAdapter(MarkdownGitAdapter):
         memories: list[Memory] = []
         complete = True
         for name in self._only:
-            full = os.path.join(self._root, name)
+            full = os.path.join(longpath.fs(self._root), name)
             try:
                 os.lstat(full)
             except FileNotFoundError: