memdebug 0.2.0__tar.gz → 0.3.0__tar.gz

{memdebug-0.2.0 → memdebug-0.3.0}/CHANGELOG.md

@@ -3,6 +3,27 @@
 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.3.0] - 2026-10-07
+
+### Added
+- **Rollback for plain folders.** `memdebug rollback store NAME --to s1` restores a watched folder of notes (and, by the same command, git notes) to a
+  snapshot: a dry run first, everything it replaces saved first byte for byte in a private folder next to the ledger, every write undone if a later
+  step fails, and the rollback recorded in the ledger and itself undoable. A folder is rebuilt from the snapshot's text, so line endings are LF (or CRLF
+  if the file it replaces uses CRLF throughout), and text a snapshot could not keep faithfully is skipped, never written.
+- `memdebug selftest` has a new check, "folder rollback is safe", that proves the plain-folder rollback claims on your machine without needing git.
+- `memdebug snapshot store NAME` saves a known-good copy of a watched store to roll back to. It refuses while the ledger holds an outside-history
+  change or flagged wording since the store's last snapshot, until you add `--include-changes`.
+
+### Changed
+- **The viewer** shows how to put a store back: snapshot pages, the compare page, the page of a change made outside a store's history and the
+  overview's "Needs a look" give the `memdebug rollback store` command as text to copy (the viewer itself still only reads). A store name from the
+  ledger is only put into a command if it is safe to paste; for an outside change the snapshot offered is always one taken before it. A rollback of a
+  plain folder is described as in place with a backup, not as a commit.
+- The file-writing safety code of the git rollback engine (links, junctions, case clashes, atomic writes, undo) now lives in one shared module used by
+  both engines. No behaviour change.
+- `memdebug demo` now ends by pointing at `memdebug setup`, the guided way to watch your own agents, instead of an advanced command.
+- Documentation: the README explains installing from PyPI, with a route that works on Windows without pipx.
+
 ## [0.2.0] - 2026-10-07
 
 ### Added

{memdebug-0.2.0 → memdebug-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memdebug
-Version: 0.2.0
+Version: 0.3.0
 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
@@ -45,15 +45,29 @@ It is an **observer**: it never sits between the agent and its memory, never tal
 computer. It does not block attacks as they happen (run it next to runtime guards), and it does not yet say *which
 conversation* wrote a memory. See [docs/threat-model.md](docs/threat-model.md) for exactly what it does and does not do.
 
-> **Status: alpha (0.2).** The parts described here work. The tests run on every push on Linux, Windows and macOS (Python 3.10, 3.12 and 3.14), and
+> **Status: alpha (0.3).** The parts described here work. The tests run on every push on Linux, Windows and macOS (Python 3.10, 3.12 and 3.14), and
 > the author also runs them on Windows 11, but expect rough edges. [ROADMAP.md](ROADMAP.md) lists what is built and what is next.
 
 ## Try it in a minute
 
-    pip install .                 # needs Python 3.10+ and git 2.31+
+You need Python 3.10 or newer and git 2.31 or newer. Install memdebug from PyPI into its own virtual environment, which works the same way
+everywhere:
+
+    python -m venv memdebug-env
+    memdebug-env\Scripts\activate          # Windows (PowerShell or cmd); on macOS and Linux: source memdebug-env/bin/activate
+    pip install memdebug
+
+If you use [pipx](https://pipx.pypa.io/), `pipx install memdebug` does the same and keeps the `memdebug` command available everywhere. pipx is not
+installed on Windows by default; to get it: `py -m pip install --user pipx`, then `py -m pipx ensurepath`, then open a new terminal. If your shell
+cannot find the `memdebug` command after installing, `python -m memdebug` (on Windows `py -m memdebug`) does the same thing.
+
+Then:
+
     memdebug demo                 # made-up agent, made-up attack, the real tools; nothing of yours is touched
     memdebug demo --serve         # ...and then look at it in the browser viewer
 
+(To work on memdebug itself, install from a checkout instead: see [CONTRIBUTING.md](CONTRIBUTING.md).)
+
 The demo plants an instruction into a note behind git's back, shows memdebug catching it, rolls the file back without losing
 the planted text, and shows the ledger noticing a tampered copy. It works in a throwaway folder and removes it afterwards.
 
@@ -79,7 +93,7 @@ Or register stores yourself (this is what a script would do):
 | Store | What it is | Change history | "Changed outside the history" | Rollback |
 | --- | --- | --- | --- | --- |
 | markdown (git) | markdown notes in a git repository | git history | an uncommitted edit | yes |
-| folder | markdown notes in a plain folder (for example Claude Code's per-project memory folder) | none: changes are noticed between looks | not applicable | not yet |
+| folder | markdown notes in a plain folder (for example Claude Code's per-project memory folder) | none: changes are noticed between looks | not applicable | yes, from a snapshot (see below) |
 | openwebui | the `memory` table of Open WebUI's `webui.db`, copied from its Docker container (or from a copy you made) | none | not applicable | no |
 | mem0 | self-hosted Mem0 | Mem0's `history.db` | a change made directly in storage | no |
 
@@ -92,7 +106,9 @@ provider's cloud: there is nothing local to watch, and memdebug says so rather t
 
 ## Tools for people who want more
 
-    memdebug timeline | verify | diff s1 s2 --full | snapshot ... | rollback markdown --path REPO --to s1   # a dry run; add --apply
+    memdebug snapshot store NAME [--label TEXT]        # save a known-good copy of a watched store, to roll back to later
+    memdebug rollback store NAME --to s1               # a dry run; add --apply. Works for folders and git notes
+    memdebug timeline | verify | diff s1 s2 --full | snapshot ... | rollback markdown --path REPO --to s1
     memdebug report --format markdown|json|sarif [--out FILE] [--fail-on findings|hints]    # for people, programs and CI
     memdebug witness --file E:\memdebug-witness.txt      # a second copy of the ledger's fingerprint, kept somewhere else
     memdebug verify --witness E:\memdebug-witness.txt    # catches a rewritten or cut-short ledger
@@ -129,6 +145,12 @@ the secret moves into a cookie and disappears from the address bar. It uses only
 library and sends no JavaScript at all. Run `memdebug verify` once first if the ledger is from an
 older version (the viewer itself never upgrades or creates anything).
 
+The viewer can only look, so where you may want to act it shows you the command instead, as text to paste into a terminal: a snapshot page, the
+compare page, the page of a change made outside a store's history, and the overview's "Needs a look" all say how to put a watched store back
+(`memdebug rollback store NAME --to sN`), and for an outside change they point at the last snapshot taken *before* it, never one that already includes
+it. Stores memdebug only reads (Open WebUI, Mem0) say so instead of offering a command. A rollback of a plain folder is described as it really is:
+changed in place, with the replaced files saved in a backup folder, not as a git commit.
+
 Security of the viewer, threat by threat: [docs/threat-model.md](docs/threat-model.md#the-viewer). Its limits: it is plain HTTP on your own
 machine, the first link (with the secret) stays in your browser history, and processes running as you can read the secret.
 Choose Auto, Light or Dark at the top right.
@@ -163,7 +185,38 @@ installed. Adding a store type is described in [CONTRIBUTING.md](CONTRIBUTING.md
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (everything read from a store is untrusted; adapters only read).
 
-## Rolling back (markdown/git)
+## Rolling back a watched store (folders and git notes)
+
+`memdebug rollback store NAME --to s1` does the same job by the name you see in `memdebug stores`, for a plain folder of notes as well as for
+git notes. First save a known-good copy while the store is healthy:
+
+```
+memdebug snapshot store claude-code-shop --label "good, after the move"     # a snapshot you can come back to
+memdebug snapshot list                                                       # names and dates of snapshots
+memdebug rollback store claude-code-shop --to s2                             # shows what would change; writes nothing
+memdebug rollback store claude-code-shop --to s2 --apply                     # does it, after you type the snapshot id
+```
+
+`snapshot store` refuses to save while the ledger holds a change made outside the store's own history, or wording flagged as worth a second look,
+since the store's last snapshot: a snapshot is what a rollback later treats as good. Look at the flagged changes first (`memdebug serve`), then add
+`--include-changes` if they are fine. This does not go away if you run it twice.
+
+For a **plain folder** there is no git to take exact file versions from, so it works from the snapshot's text, and it is honest about what that means:
+
+* **Backups are files.** Anything the rollback would replace or remove is first copied, byte for byte, into a private folder next to your ledger
+  (`backups\<store>\<date>-<id>`, with a `manifest.json`), and each copy is read back and checked before your notes are touched. Get a file
+  back by copying it out of that folder's `files` folder. These copies contain your memory text and memdebug never deletes them: delete old ones
+  yourself when you no longer need them.
+* **Line endings.** A snapshot does not keep them. Files come back as UTF-8 with LF line endings, or with CRLF if the file being replaced uses CRLF
+  throughout. A file with mixed endings comes back with LF.
+* **Nothing it cannot restore faithfully is written.** Text that was cut, marked too large, or had bytes that are not valid text is skipped, and
+  the dry run says which files and why.
+* **Everything else is the same** as for git notes: the plan writes nothing, applying refuses if anything changed since you saw the plan, links,
+  junctions and unsafe names are refused, every write is undone if a later step fails, and the rollback is recorded and can itself be undone.
+
+Open WebUI and Mem0 keep their memory in databases that memdebug only ever reads, so they cannot be rolled back; change those in the app.
+
+## Rolling back markdown in git, by path
 
 `memdebug rollback markdown` puts a memory folder back to what a snapshot held. It is the only command that changes
 your files, so it is cautious by design.
@@ -193,7 +246,7 @@ What it guarantees:
 * **It can be undone.** It takes a snapshot just before and just after, and records a `ROLLBACK` entry in the ledger.
   To undo a rollback, roll back to the "before" snapshot it printed.
 
-`memdebug selftest` proves the "no programs run" and "exact bytes" claims on your computer.
+`memdebug selftest` proves the "no programs run" and "exact bytes" claims, and the folder-rollback claims, on your computer.
 
 ## Fonts
 

{memdebug-0.2.0 → memdebug-0.3.0}/README.md

@@ -12,15 +12,29 @@ It is an **observer**: it never sits between the agent and its memory, never tal
 computer. It does not block attacks as they happen (run it next to runtime guards), and it does not yet say *which
 conversation* wrote a memory. See [docs/threat-model.md](docs/threat-model.md) for exactly what it does and does not do.
 
-> **Status: alpha (0.2).** The parts described here work. The tests run on every push on Linux, Windows and macOS (Python 3.10, 3.12 and 3.14), and
+> **Status: alpha (0.3).** The parts described here work. The tests run on every push on Linux, Windows and macOS (Python 3.10, 3.12 and 3.14), and
 > the author also runs them on Windows 11, but expect rough edges. [ROADMAP.md](ROADMAP.md) lists what is built and what is next.
 
 ## Try it in a minute
 
-    pip install .                 # needs Python 3.10+ and git 2.31+
+You need Python 3.10 or newer and git 2.31 or newer. Install memdebug from PyPI into its own virtual environment, which works the same way
+everywhere:
+
+    python -m venv memdebug-env
+    memdebug-env\Scripts\activate          # Windows (PowerShell or cmd); on macOS and Linux: source memdebug-env/bin/activate
+    pip install memdebug
+
+If you use [pipx](https://pipx.pypa.io/), `pipx install memdebug` does the same and keeps the `memdebug` command available everywhere. pipx is not
+installed on Windows by default; to get it: `py -m pip install --user pipx`, then `py -m pipx ensurepath`, then open a new terminal. If your shell
+cannot find the `memdebug` command after installing, `python -m memdebug` (on Windows `py -m memdebug`) does the same thing.
+
+Then:
+
     memdebug demo                 # made-up agent, made-up attack, the real tools; nothing of yours is touched
     memdebug demo --serve         # ...and then look at it in the browser viewer
 
+(To work on memdebug itself, install from a checkout instead: see [CONTRIBUTING.md](CONTRIBUTING.md).)
+
 The demo plants an instruction into a note behind git's back, shows memdebug catching it, rolls the file back without losing
 the planted text, and shows the ledger noticing a tampered copy. It works in a throwaway folder and removes it afterwards.
 
@@ -46,7 +60,7 @@ Or register stores yourself (this is what a script would do):
 | Store | What it is | Change history | "Changed outside the history" | Rollback |
 | --- | --- | --- | --- | --- |
 | markdown (git) | markdown notes in a git repository | git history | an uncommitted edit | yes |
-| folder | markdown notes in a plain folder (for example Claude Code's per-project memory folder) | none: changes are noticed between looks | not applicable | not yet |
+| folder | markdown notes in a plain folder (for example Claude Code's per-project memory folder) | none: changes are noticed between looks | not applicable | yes, from a snapshot (see below) |
 | openwebui | the `memory` table of Open WebUI's `webui.db`, copied from its Docker container (or from a copy you made) | none | not applicable | no |
 | mem0 | self-hosted Mem0 | Mem0's `history.db` | a change made directly in storage | no |
 
@@ -59,7 +73,9 @@ provider's cloud: there is nothing local to watch, and memdebug says so rather t
 
 ## Tools for people who want more
 
-    memdebug timeline | verify | diff s1 s2 --full | snapshot ... | rollback markdown --path REPO --to s1   # a dry run; add --apply
+    memdebug snapshot store NAME [--label TEXT]        # save a known-good copy of a watched store, to roll back to later
+    memdebug rollback store NAME --to s1               # a dry run; add --apply. Works for folders and git notes
+    memdebug timeline | verify | diff s1 s2 --full | snapshot ... | rollback markdown --path REPO --to s1
     memdebug report --format markdown|json|sarif [--out FILE] [--fail-on findings|hints]    # for people, programs and CI
     memdebug witness --file E:\memdebug-witness.txt      # a second copy of the ledger's fingerprint, kept somewhere else
     memdebug verify --witness E:\memdebug-witness.txt    # catches a rewritten or cut-short ledger
@@ -96,6 +112,12 @@ the secret moves into a cookie and disappears from the address bar. It uses only
 library and sends no JavaScript at all. Run `memdebug verify` once first if the ledger is from an
 older version (the viewer itself never upgrades or creates anything).
 
+The viewer can only look, so where you may want to act it shows you the command instead, as text to paste into a terminal: a snapshot page, the
+compare page, the page of a change made outside a store's history, and the overview's "Needs a look" all say how to put a watched store back
+(`memdebug rollback store NAME --to sN`), and for an outside change they point at the last snapshot taken *before* it, never one that already includes
+it. Stores memdebug only reads (Open WebUI, Mem0) say so instead of offering a command. A rollback of a plain folder is described as it really is:
+changed in place, with the replaced files saved in a backup folder, not as a git commit.
+
 Security of the viewer, threat by threat: [docs/threat-model.md](docs/threat-model.md#the-viewer). Its limits: it is plain HTTP on your own
 machine, the first link (with the secret) stays in your browser history, and processes running as you can read the secret.
 Choose Auto, Light or Dark at the top right.
@@ -130,7 +152,38 @@ installed. Adding a store type is described in [CONTRIBUTING.md](CONTRIBUTING.md
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (everything read from a store is untrusted; adapters only read).
 
-## Rolling back (markdown/git)
+## Rolling back a watched store (folders and git notes)
+
+`memdebug rollback store NAME --to s1` does the same job by the name you see in `memdebug stores`, for a plain folder of notes as well as for
+git notes. First save a known-good copy while the store is healthy:
+
+```
+memdebug snapshot store claude-code-shop --label "good, after the move"     # a snapshot you can come back to
+memdebug snapshot list                                                       # names and dates of snapshots
+memdebug rollback store claude-code-shop --to s2                             # shows what would change; writes nothing
+memdebug rollback store claude-code-shop --to s2 --apply                     # does it, after you type the snapshot id
+```
+
+`snapshot store` refuses to save while the ledger holds a change made outside the store's own history, or wording flagged as worth a second look,
+since the store's last snapshot: a snapshot is what a rollback later treats as good. Look at the flagged changes first (`memdebug serve`), then add
+`--include-changes` if they are fine. This does not go away if you run it twice.
+
+For a **plain folder** there is no git to take exact file versions from, so it works from the snapshot's text, and it is honest about what that means:
+
+* **Backups are files.** Anything the rollback would replace or remove is first copied, byte for byte, into a private folder next to your ledger
+  (`backups\<store>\<date>-<id>`, with a `manifest.json`), and each copy is read back and checked before your notes are touched. Get a file
+  back by copying it out of that folder's `files` folder. These copies contain your memory text and memdebug never deletes them: delete old ones
+  yourself when you no longer need them.
+* **Line endings.** A snapshot does not keep them. Files come back as UTF-8 with LF line endings, or with CRLF if the file being replaced uses CRLF
+  throughout. A file with mixed endings comes back with LF.
+* **Nothing it cannot restore faithfully is written.** Text that was cut, marked too large, or had bytes that are not valid text is skipped, and
+  the dry run says which files and why.
+* **Everything else is the same** as for git notes: the plan writes nothing, applying refuses if anything changed since you saw the plan, links,
+  junctions and unsafe names are refused, every write is undone if a later step fails, and the rollback is recorded and can itself be undone.
+
+Open WebUI and Mem0 keep their memory in databases that memdebug only ever reads, so they cannot be rolled back; change those in the app.
+
+## Rolling back markdown in git, by path
 
 `memdebug rollback markdown` puts a memory folder back to what a snapshot held. It is the only command that changes
 your files, so it is cautious by design.
@@ -160,7 +213,7 @@ What it guarantees:
 * **It can be undone.** It takes a snapshot just before and just after, and records a `ROLLBACK` entry in the ledger.
   To undo a rollback, roll back to the "before" snapshot it printed.
 
-`memdebug selftest` proves the "no programs run" and "exact bytes" claims on your computer.
+`memdebug selftest` proves the "no programs run" and "exact bytes" claims, and the folder-rollback claims, on your computer.
 
 ## Fonts
 

{memdebug-0.2.0 → memdebug-0.3.0}/ROADMAP.md

@@ -3,7 +3,7 @@
 Where memdebug is and where it is going. It is alpha software: the pieces below that are built work and are tested,
 but expect rough edges and breaking changes before 1.0. Order is a plan, not a promise.
 
-## Built (0.2)
+## Built (0.3)
 
 * Tamper-evident ledger (hash chain) with `verify`, snapshots whose content is chained in, and compare.
 * **Witness:** a second copy of the ledger's head kept elsewhere, so a rewritten or cut-short ledger is noticed.
@@ -16,6 +16,9 @@ but expect rough edges and breaking changes before 1.0. Order is a plan, not a p
   (exit code 1 when something needs a look), `status`, `watch`.
 * Detection of changes that bypassed a store's own history, with false-alarm guards.
 * **Reports** in Markdown, JSON and SARIF, with CI exit codes.
+* **Rollback for plain folders** (`memdebug rollback store`, and `memdebug snapshot store` to save a known-good copy first), rebuilt from the snapshot's
+  text with backups of anything replaced; Open WebUI and Mem0 still cannot be rolled back.
+* **Published on PyPI** as `memdebug` (`pip install memdebug`), released by a tag-triggered workflow that needs an approval click.
 * **A first slice of provenance for Open WebUI:** its own `created_by` label and a chat-timing comparison, as evidence only.
 * **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.
@@ -27,19 +30,16 @@ but expect rough edges and breaking changes before 1.0. Order is a plan, not a p
 
 ## Next, roughly in this order
 
-1. **Rollback for plain folders.** Folders have no git history, so this needs a private store of exact file versions kept by
-   memdebug, with the same guarantees as the git version (dry run, backups, undo on failure). It adds a second write path into
-   your files, so it gets the same adversarial testing before it ships.
+1. **Rollback for plain folders: built** (see Built). Still to do: a way to list and clean up old backups, and trying it on real agent memory folders.
 2. **More provenance.** A first slice exists for Open WebUI (the app's own label and how close a chat was). Still to do: which conversation turn
    wrote a memory and what the assistant had just read, and readers for other agents' session logs (Claude Code transcripts, OpenClaw).
    The earlier plan, in full: **Provenance from session logs.** Which conversation turn wrote a memory, and whether it came from the user or from
    something the agent read. This turns a change log into an incident-response tool. It needs a reader per agent (first
    candidates: Open WebUI chat records, Claude Code session transcripts), and depends on seeing real log formats.
 3. **More agents,** each added only once its memory location is documented (candidates: Cursor, Cline, Aider, Continue, Goose, Claude Desktop's local files).
-4. **Release.** Prepared: the package builds, passes PyPI's metadata check and installs and runs from a clean environment; the name `memdebug` was
-   free on PyPI when checked; CI builds and installs the package on every push; a tag-triggered publish workflow uses PyPI trusted publishing.
-   Left for the owner (they need accounts): register the trusted publisher on PyPI and tag the release. See docs/releasing.md.
-   CI and the release dry run have run on GitHub and passed on all three systems.
+4. **Releases.** 0.2.0 was published to GitHub and PyPI on 2026-10-07 through the tag-triggered workflow (PyPI trusted publishing, with a
+   required approval and provenance attestations). The install from PyPI has been checked in a clean Linux environment and on Windows 11 (pipx, Python 3.14); macOS
+   still needs the same check. Still to do: signed release notes and a smoother route for people without Python (item 5).
 5. **Better setup for non-advanced users:** an installer with no Python knowledge needed, and a way to keep `watch` running
    without a terminal.
 6. **Viewer:** filter by store, show hints in the overview, a status page that matches `memdebug status`.

{memdebug-0.2.0 → memdebug-0.3.0}/docs/agents.md

@@ -20,7 +20,7 @@ only. It does not list or open anything else in the folder.
 ChatGPT, Claude's apps (claude.ai on the web, desktop and phone), Gemini and Copilot keep their memory in the provider's cloud.
 There is nothing on this computer to point memdebug at, and memdebug cannot tell whether those apps are installed, so it never
 claims to have found them. Review or clear that memory 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 (`memdebug add <folder>`).
+into a markdown file now and then, in a folder you add to memdebug (`memdebug add <folder>`). A watched folder can be rolled back to a snapshot with `memdebug rollback store NAME --to s1`.
 
 ## Adding an agent
 

{memdebug-0.2.0 → memdebug-0.3.0}/docs/releasing.md

@@ -31,10 +31,11 @@ proposes new versions of the upload and download actions) so a problem shows up
 ## Each release
 
 1. Run `memdebug selftest` and the tests on your own machine (Windows is the one CI cannot fully stand in for).
-2. Update `__version__` in `src/memdebug/__init__.py` and `version` in `pyproject.toml` (they must match) and move the changelog entry from
-   "unreleased" to the release date.
+2. Update `__version__` in `src/memdebug/__init__.py` and `version` in `pyproject.toml` (they must match) and rename the changelog's `[Unreleased]` heading to the new
+   version with the release date, for example `## [0.2.1] - 2026-11-02`.
 3. Commit, then tag and push: `git tag v0.2.0 && git push origin v0.2.0`. The workflow refuses to publish if the tag and the version differ.
-4. Approve the `pypi` environment if you required that. After a minute: `pipx install memdebug`, then `memdebug demo`.
+4. Approve the `pypi` environment if you required that. After a minute, in a clean virtual environment (not your working one), check the real
+   install: `pip install memdebug==<version>`, then `memdebug --version` and `memdebug demo`. Do this on Windows as well as Linux or macOS.
 
 ## If something goes wrong
 

{memdebug-0.2.0 → memdebug-0.3.0}/docs/threat-model.md

@@ -83,6 +83,7 @@ a control, that the attack works against ordinary git, and reports SKIP rather t
 | Other users or programs on the machine | 192-bit secret, HttpOnly SameSite=Strict cookie, constant-time comparison; nothing is served without it |
 | Another program taking the port | The port is taken exclusively (matters on Windows); `selftest` checks it |
 | Changing anything | Only GET and HEAD; the ledger is opened read-only. The theme switch sets one cookie and nothing else |
+| A command shown for copying that a hostile ledger turned into something else | The "put it back" guidance is only text, never a link or a button. A store name from the ledger goes into a command only if it passes the same strict rule as a watched store's name (lowercase letters, digits, dot, dash, underscore); anything else gets a `<name>` placeholder, so pasting a command can never do more than the command says. Stores memdebug cannot write to never get one. For an outside change it names only a snapshot taken before it |
 | Odd, oversized or slow requests | Strict limits on request line, path, query, headers, connections and time; only fixed routes and validated ids; nothing from the request is echoed |
 
 ## Rollback (markdown/git)
@@ -101,6 +102,26 @@ Rollback is the only part of memdebug that changes your files, so it is the most
 | A failure half-way | Every step is journaled; on any failure (or Ctrl+C) files, index and branch are put back and you are told |
 | An unrecorded rollback | The ledger record is validated before any file is touched; the state is snapshotted before and after; a `ROLLBACK` entry is chained into the ledger; undoing is rolling back to the "before" snapshot |
 
+
+## Rollback of a plain folder
+
+Rollback of a watched store by name (`memdebug rollback store`) uses the same file-writing code as the git engine (`adapters/fileops.py`), so links,
+junctions, case clashes, atomic writes and the undo journal are identical. What differs, because a folder has no git history:
+
+| Threat | Protection |
+| --- | --- |
+| Restoring text a snapshot could not keep faithfully | The snapshot's text is the only source. Text that was cut, marked too large or had undecodable bytes is refused and named in the plan, never written. Line endings are LF, or CRLF if the file being replaced uses CRLF throughout; mixed endings become LF. |
+| Losing what the rollback replaces | Every file that would be overwritten or removed is first copied byte for byte into a private folder next to the ledger (0700/0600 on POSIX), the copy is read back and checked, and nothing in the notes is touched if that fails. |
+| Backups landing inside the notes (and being read as memories), or the notes inside the backups | The plan refuses (a blocker) when either folder contains the other, and applying refuses again. |
+| A "good" snapshot that is really an attack | `memdebug snapshot store` refuses while the ledger holds an outside-history change or flagged wording since the store's last snapshot. It reads the ledger, so looking again does not clear it; only a deliberate `--include-changes` does. |
+| The folder changing between the plan and the write | Applying re-plans and refuses if the plan differs; every target is re-checked before the first backup or write. |
+| A snapshot (or a tampered ledger) naming unsafe files | Names are validated by the same rule as the reader (no `..`, absolute, device or case-clashing names), and files outside the store's subfolder, or outside a named-files store, are never written. |
+
+Known limits: backups hold your memory text and are never deleted by memdebug; a plain-folder rollback cannot restore exact bytes for files whose
+line endings were mixed; a store with no history cannot show an outside-history bypass, only the changes observed between looks. The Windows
+permissions of the backup folder are those of your user profile (memdebug sets no ACL), and the junction guard is exercised on every platform by
+simulation, but real junctions are only tested on Windows runs of the suite.
+
 ## Stores, settings and discovery
 
 | Threat | Defence |
@@ -147,7 +168,7 @@ Read these. They are why this is alpha software.
   installation. It cannot do more than you could already do with `docker exec`, but it does require that access.
 * **Stores without a history cannot show a bypass.** For a plain folder or Open WebUI memdebug sees only the state at each look, so a change
   made and reverted between looks is invisible, and an attacker's edit looks like any other. Prefer a git repository when you can.
-* **Rollback for plain folders, Open WebUI and Mem0 does not exist yet.**
+* **Rollback for Open WebUI and Mem0 does not exist** (memdebug only reads those). Plain folders and git notes can be rolled back.
 * **Rollback restores files, not the world.** It does not change what a *running* agent has already loaded (restart the
   session), does not rebuild anything derived from the memory (summaries, embeddings), cannot undo what the agent did
   because of a bad memory, and a still-running agent can write the same text back. Stop the agent first.

{memdebug-0.2.0 → memdebug-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memdebug"
-version = "0.2.0"
+version = "0.3.0"
 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"

{memdebug-0.2.0 → memdebug-0.3.0}/src/memdebug/__init__.py

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

memdebug-0.3.0/src/memdebug/adapters/fileops.py

@@ -0,0 +1,190 @@
+"""The file-level half of a rollback, shared by the git engine (restore.py) and the plain-folder engine (folder_restore.py).
+
+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:
+
+  * links, junctions and anything that is not a plain file or folder are never followed and never written through;
+  * a file whose name differs from another in the same folder only by letter case is refused;
+  * files are written through a temporary file in the same folder and an atomic rename;
+  * every write is journaled so that a failed step can be undone, newest first.
+"""
+from __future__ import annotations
+
+import os
+import secrets
+import stat
+from typing import Sequence
+
+from ..errors import RestoreError
+from ..textsafe import safe_text
+from .markdown_git import MAX_FILE_BYTES, _is_reparse_point, _text_from_bytes
+
+_O_BINARY = getattr(os, "O_BINARY", 0)
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+
+
+def _is_link(info: os.stat_result) -> bool:
+    return stat.S_ISLNK(info.st_mode) or _is_reparse_point(info)
+
+
+class FileOps:
+    """Subclasses set `self._root` (the folder every path is relative to) and plan what to write."""
+
+    _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)
+        parts = relpath.split("/")
+        for part in parts[:-1]:
+            current = os.path.join(current, part)
+            try:
+                info = os.lstat(current)
+            except FileNotFoundError:
+                return "missing", None
+            except OSError:
+                return "unsafe", None
+            if _is_link(info) or not stat.S_ISDIR(info.st_mode):
+                return "unsafe", None
+        full = os.path.join(current, parts[-1])
+        try:
+            info = os.lstat(full)
+        except FileNotFoundError:
+            return "missing", None
+        except OSError:
+            return "unsafe", None
+        if _is_link(info) or not stat.S_ISREG(info.st_mode):
+            return "unsafe", None
+        if info.st_size > MAX_FILE_BYTES:
+            return "large", None
+        try:
+            fd = os.open(full, os.O_RDONLY | _O_BINARY | _O_NOFOLLOW | getattr(os, "O_NONBLOCK", 0))
+        except OSError:
+            return "unsafe", None
+        try:
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                return "unsafe", None
+            with os.fdopen(fd, "rb", closefd=False) as handle:
+                data = handle.read(MAX_FILE_BYTES + 1)
+        except OSError:
+            return "unsafe", None
+        finally:
+            os.close(fd)
+        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)
+        parts = rel.split("/")
+        for part in parts[:-1]:
+            current = os.path.join(current, part)
+            try:
+                info = os.lstat(current)
+            except FileNotFoundError:
+                if must_exist:
+                    raise RestoreError(f"{safe_text(rel, 60)}: a folder disappeared") from None
+                break
+            if _is_link(info) or not stat.S_ISDIR(info.st_mode):
+                raise RestoreError(f"{safe_text(rel, 60)}: a folder on the way is a link or not a folder")
+        else:
+            try:
+                names = os.listdir(current)
+            except OSError as exc:
+                raise RestoreError(f"{safe_text(rel, 60)}: cannot read its folder ({exc.strerror})") from exc
+            name = parts[-1]
+            if name not in names and any(other.casefold() == name.casefold() for other in names):
+                raise RestoreError(f"{safe_text(rel, 60)}: another file in that folder differs only by letter case")
+            target = os.path.join(current, name)
+            try:
+                info = os.lstat(target)
+            except FileNotFoundError:
+                if must_exist:
+                    raise RestoreError(f"{safe_text(rel, 60)}: the file disappeared") from None
+                return
+            if _is_link(info) or not stat.S_ISREG(info.st_mode):
+                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."""
+        created: list[str] = []
+        try:
+            current = str(self._root)
+            parts = rel.split("/")
+            for part in parts[:-1]:
+                current = os.path.join(current, part)
+                try:
+                    info = os.lstat(current)
+                except FileNotFoundError:
+                    os.mkdir(current)
+                    created.append(current)
+                    info = os.lstat(current)
+                if _is_link(info) or not stat.S_ISDIR(info.st_mode):
+                    raise RestoreError(f"{safe_text(rel, 60)}: a folder on the way is a link or not a folder")
+            target = os.path.join(current, parts[-1])
+            mode = None
+            try:
+                info = os.lstat(target)
+                if _is_link(info) or not stat.S_ISREG(info.st_mode):
+                    raise RestoreError(f"{safe_text(rel, 60)}: not a plain file")
+                mode = stat.S_IMODE(info.st_mode)
+            except FileNotFoundError:
+                pass
+            temporary = os.path.join(current, f".memdebug-{secrets.token_hex(8)}.tmp")
+            fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | _O_BINARY | _O_NOFOLLOW, 0o666)
+            try:
+                with os.fdopen(fd, "wb") as handle:
+                    handle.write(data)
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                if mode is not None and os.name == "posix":
+                    os.chmod(temporary, mode)
+                os.replace(temporary, target)
+            except BaseException:
+                try:
+                    os.unlink(temporary)
+                except OSError:
+                    pass
+                raise
+            return created
+        except BaseException:
+            for folder in reversed(created):
+                try:
+                    os.rmdir(folder)
+                except OSError:
+                    pass
+            raise
+
+    def _remove_file(self, rel: str) -> None:
+        self._check_target(rel, must_exist=True)
+        os.unlink(os.path.join(str(self._root), *rel.split("/")))
+
+    def _verify_files(self, items: Sequence) -> None:
+        """Every item must now be on disk exactly as planned."""
+        for item in items:
+            status, data = self._inspect(item.path)
+            if item.action == "remove":
+                if status != "missing":
+                    raise RestoreError(f"{safe_text(item.path, 60)} is still there after removal")
+            elif status != "ok" or _text_from_bytes(data or b"") != item.target_text:
+                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."""
+        problems: list[str] = []
+        for path, old in reversed(journal):
+            try:
+                if old is None:
+                    full = os.path.join(str(self._root), *path.split("/"))
+                    if os.path.lexists(full):
+                        os.unlink(full)
+                else:
+                    self._write_file(path, old)
+            except Exception as exc:
+                problems.append(f"{safe_text(path, 60)}: {safe_text(exc, 80)}")
+        for folder in reversed(created_dirs):
+            try:
+                os.rmdir(folder)
+            except OSError:
+                pass
+        return problems
+

{memdebug-0.2.0 → memdebug-0.3.0}/src/memdebug/adapters/folder.py

@@ -62,6 +62,11 @@ class FolderAdapter(MarkdownGitAdapter):
                 raise AdapterError("the files to watch must be 1 to 10 plain markdown file names in the folder itself")
             self._only = names
 
+    @property
+    def only(self) -> tuple[str, ...] | None:
+        """The named files this store is limited to, or None when it covers the whole folder."""
+        return self._only
+
     def read_history(self, max_rows: int) -> HistoryRead:
         return HistoryRead(events=[], refs=set(), truncated=False)