memdebug 0.3.0__tar.gz → 0.4.1__tar.gz

memdebug-0.4.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,87 @@
+name: Bug report
+description: Something does not work as the documentation says
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Please read this first
+
+        **Never paste memory contents or session transcripts into this issue.** An agent's memory and its conversation logs hold private text,
+        and an issue is public and stays public even if you edit or delete it. Describe what the text *did*, or replace it with a made-up
+        example that behaves the same way.
+
+        Also leave out: the ledger (`*.db`), `stores.json`, backup folders, the link printed by `memdebug serve` (it contains a secret),
+        API keys, and personal paths (replace them with `<home>`). Be careful with the output of `memdebug check`, `timeline`, `diff` and
+        `report`: it can quote the start of changed notes.
+
+        **A security problem?** Do not open an issue. Report it privately: https://github.com/juraj-jumic/memdebug/security/advisories/new
+        (see [SECURITY.md](https://github.com/juraj-jumic/memdebug/blob/main/SECURITY.md)).
+  - type: checkboxes
+    id: safe
+    attributes:
+      label: Before you submit
+      options:
+        - label: I have not included memory contents, session transcripts, a ledger, `stores.json`, a viewer link or personal paths.
+          required: true
+        - label: This is not a security problem.
+          required: true
+  - type: textarea
+    id: happened
+    attributes:
+      label: What happened
+      description: What you did, and what memdebug did.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: The commands you ran, ideally against a made-up folder of notes. `memdebug demo` shows what a healthy run looks like.
+  - type: input
+    id: version
+    attributes:
+      label: memdebug version
+      description: The output of `memdebug --version`. If you use pipx and a virtual environment, make sure it is the copy you actually ran.
+    validations:
+      required: true
+  - type: dropdown
+    id: system
+    attributes:
+      label: Operating system
+      options:
+        - Windows
+        - macOS
+        - Linux
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: tools
+    attributes:
+      label: Python and git versions
+      description: The output of `python --version` and `git --version`.
+  - type: dropdown
+    id: store
+    attributes:
+      label: Kind of store involved
+      multiple: true
+      options:
+        - Markdown notes in git
+        - Plain folder of markdown notes
+        - Open WebUI
+        - Mem0
+        - The viewer (memdebug serve)
+        - Not about a store
+  - type: textarea
+    id: output
+    attributes:
+      label: Output or error message
+      description: Only text you have read through and are sure holds no memory contents. The output of `memdebug selftest` is useful here, but it names your user folder on Windows, so replace that with `<home>` first.
+      render: text

memdebug-0.4.1/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## What this changes, and why
+
+<!-- One or two sentences. Link the issue if there is one. -->
+
+## How it was checked
+
+Run these with the repository's own environment (see [CONTRIBUTING.md](https://github.com/juraj-jumic/memdebug/blob/main/CONTRIBUTING.md)):
+
+- [ ] `python -m pytest -q -n auto`, `ruff check src tests`, `mypy` and `python -m memdebug selftest` all pass
+- [ ] If this adds or changes a protection: I removed it on purpose and a test failed (CONTRIBUTING, ground rule 5). Otherwise: no protection changed
+- [ ] Hostile input is handled: text read from a store, log or repository is bounded, shown through `safe_text` or the viewer's builder, and any name from the ledger is validated (validators end with `\Z`, never `$`) before it reaches a command or a path
+- [ ] Windows is covered: file names that differ only by case, CRLF, and junctions are considered; a POSIX-only test is marked skipped with a reason
+
+## Documents
+
+- [ ] `CHANGELOG.md` has a line under `[Unreleased]` for anything a user would notice
+- [ ] Anything the change makes untrue is updated, and a new limit is written into `docs/threat-model.md`
+
+## Private data
+
+- [ ] The diff and the commit messages contain no memory text, session transcripts, `*.db` files, `stores.json`, `backups/`, `copies/` or personal paths. Test data is made up
+- [ ] I understand the history is public. A GitHub no-reply address is fine as the commit email
+
+By contributing you agree that your contribution is licensed under the Apache License 2.0 (see [LICENSE](https://github.com/juraj-jumic/memdebug/blob/main/LICENSE)).

{memdebug-0.3.0 → memdebug-0.4.1}/.gitignore

@@ -26,7 +26,11 @@ htmlcov/
 *.partial
 stores.json
 copies/
+backups/
 memdebug-report*
+# Rollback backups hold the notes byte for byte, and agent session logs are whole conversations. If a test ever needs a made-up .jsonl file,
+# add a negation for that one path (!tests/data/example.jsonl) instead of removing the rule.
+*.jsonl
 
 # Secrets
 .env

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

@@ -3,6 +3,51 @@
 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
+- **Who wrote it.** For a changed note that looks suspicious, or that changed outside git, `memdebug check` and `memdebug watch` now also say which
+  logged Claude Code session wrote it, from that agent's session logs ("who wrote it: ..."), or that no logged edit explains it. It returns only a
+  session id, a time and a tool name, never a path or any text from a log. It is evidence, not proof: a deleted log looks the same as a note nobody
+  wrote, and shell-made changes cannot be matched (they are only counted). See `docs/threat-model.md`.
+- The viewer has an **Agents** page (`memdebug serve`): the known agents that appear to be installed and what memdebug could watch for each, with the command
+  to run (`memdebug setup`). It only checks that folders exist, opens no file, and works even while the ledger is busy.
+- Cline is in the agent catalog: `memdebug agents` and `memdebug setup` offer its global rules folder (`~/Documents/Cline/Rules`) once it holds markdown rules.
+
+### Changed
+- `memdebug selftest`, "rollback is safe" and "hostile repository config cannot run programs": the control (ordinary git, tripwires armed) now runs in
+  a separate repository with its own marker files, so nothing it leaves behind can be mistaken for an escape from the protected run, which is still
+  asserted to run no tripwire. The tripwires now record what started them (time, arguments, and the parent and grandparent command lines where the
+  platform shows them: `/proc` on Linux, `ps` on macOS, nothing on Windows), and a failure prints those records and `git --version`. This follows a
+  failure on CI that passed on a re-run and could not be reproduced.
+- The repository's ignore file also excludes `backups/` and `*.jsonl` (session logs), and the release hygiene test checks both rules.
+
+### Documentation
+- The README has badges, a recorded demo (`docs/demo.gif`, with the unpaced recording in `docs/demo.cast`), and new "Why this matters", "How it works" and
+  "Engineering" sections, checked against the code; claims about snapshots, the ledger and rollback that overstated what the code does were corrected.
+- CONTRIBUTING.md now starts with the private-data rule and covers reporting a security problem, setup, writing tests, changing the viewer and the pull
+  request process; its second ground rule names both rollback engines. There is a pull request template and a bug-report form that tells people never
+  to paste memory contents or session transcripts.
+- `docs/threat-model.md` has a section on the session-log reader, and `docs/agents.md` has a row for Cline and records Claude Code's per-project memory
+  folder as confirmed on Windows 11.
+
 ## [0.3.0] - 2026-10-07
 
 ### Added

memdebug-0.4.1/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing
+
+Thanks for helping. memdebug is a security tool, so the bar for changes is "what happens if the input is hostile?".
+
+## Private data comes first
+
+memdebug reads people's agent memory, so this repository must never hold any of it. Never commit, attach or paste (in an issue, a pull
+request, a test or a commit message): real memory text, session transcripts, a ledger or any other `*.db` file, `stores.json`, backup or copy
+folders, the link `memdebug serve` prints (it contains a secret), tokens or keys, or paths that name your user account. Test data is made up.
+The ignore file keeps the common cases out (databases, `stores.json`, copy and backup folders, `*.jsonl` session logs, reports, keys), but it
+is only a safety net: read `git status` and `git diff --cached` before every commit. The history is public, and a pushed commit cannot be
+taken back without rewriting it.
+
+## Reporting a security problem
+
+Do not open a public issue or pull request for a security problem. Report it privately through GitHub
+(https://github.com/juraj-jumic/memdebug/security/advisories/new); [SECURITY.md](SECURITY.md) says what counts and what to include. Keep private
+text out of the report as well: a made-up example that behaves the same way is enough.
+
+## Setup
+
+    python -m venv .venv
+    .venv\Scripts\activate           # Windows (PowerShell or cmd); on macOS and Linux: source .venv/bin/activate
+    pip install -e ".[dev]"
+    python -m pytest -n auto         # the whole suite, in parallel; plain `python -m pytest` works too
+    python -m memdebug selftest      # proves the protections on THIS machine
+    ruff check src tests             # lint (CI enforces it)
+    mypy                             # types (CI enforces it)
+
+You need Python 3.10+ and git 2.31+. The suite starts many git processes, so it is slower on Windows. Run everything through this environment's
+`python -m ...`: a `memdebug` command on your PATH (a pipx install, say) can be an older release than the code you are editing, while
+`python -m memdebug` is always your checkout. Two release-hygiene tests are skipped unless PyYAML is installed (`pip install pyyaml`).
+
+## Ground rules
+
+1. **Everything read from a memory store or repository is untrusted.** Bound its size, never print it raw (use
+   `safe_text`), and never let it become markup (use the viewer's builder, never string-built HTML).
+2. **Adapters only read.** The only code allowed to change a memory store is the two rollback engines, `adapters/restore.py` (git
+   notes) and `adapters/folder_restore.py` (plain folders), which share the file-writing code in `adapters/fileops.py`. They have their
+   own rules: a dry run first, a plan the person confirms, a backup of anything not already held (in git, or in a private backup folder),
+   no rewritten history, undo on failure.
+3. **No shell, fixed argument lists, no programs named by the data.** git runs with a scrubbed environment and the
+   repository's risky settings overridden. Do not add a git command without checking it cannot run a hook, filter or
+   external helper.
+4. **Explicit text encodings** everywhere (`encoding="utf-8"`); a test enforces this because Windows defaults to a legacy
+   code page.
+5. **A protection without a test that fails when it is removed is not a protection.** Break your own code on purpose
+   (remove the check) and confirm a test notices. Several tests exist only because that exercise found a gap.
+6. **Windows is a first-class platform.** Avoid POSIX-only assumptions; if a test truly needs POSIX, mark it and say why. Two traps that only show up
+   there: file names ignore case ("A.db" and "a.db" are one file, so never name files after values that can differ only by case), and text-mode
+   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
+  `tests/conftest.py`), so never read a real home folder, agent folder, session log or container, and never put a real transcript in a
+  fixture. Write a made-up log, as `tests/test_provenance.py` does. A test that sets the home folder sets both `HOME` and `USERPROFILE`.
+* A new protection needs a test that fails when it is removed (ground rule 5). A new validator or route pattern ends with `\Z`, never `$`,
+  and is added to `test_no_validator_accepts_a_trailing_line_break` in `tests/test_docker_source.py`, which tries every pattern with a
+  trailing line break.
+* Give parametrized tests short `ids=`, and mark a POSIX-only test skipped with a reason (see `posix_only` in `tests/test_provenance.py`).
+
+## Changing the viewer
+
+The viewer (`memdebug serve`) only looks. It answers GET and HEAD only, sends no JavaScript, and cannot change a store or the ledger (the
+theme switch sets one cookie and nothing else). Pages are built with the escaping builder in `src/memdebug/viewer/html.py`, never by joining
+strings. The only form is the Compare picker, which uses `method="get"` and just navigates; a test fails if any form uses another method.
+Where a person may want to act, show the command as text to paste, as the "put it back" guidance does, and build it only from names that pass
+`valid_name`. A new page needs a route anchored with `\Z`, an entry in the trailing-line-break test, and an entry in `ALL_PAGES` in
+`tests/test_viewer.py`. What is defended, and what is not: [docs/threat-model.md](docs/threat-model.md#the-viewer).
+
+## Adding a backend
+
+Implement the `MemoryAdapter` protocol in `adapters/base.py` (`list_memories`, `read_history`, `history`), read-only,
+validating every row. Look at `adapters/mem0.py` and `adapters/markdown_git.py` for the expected hardening, and add the
+same kinds of tests (hostile rows, oversized values, odd encodings). A backend without a change history should record
+what it observes instead of raising "outside the history" alarms.
+
+## Adding an agent to the catalog
+
+See `docs/agents.md`: a documented location (with a link), a test using a fake home folder, and watch only the named files when the
+folder also holds credentials.
+
+## Workflows and Dependabot
+
+Dependabot proposes updates to the pinned actions in one grouped pull request a week. Let CI run on it, and for changes to the release
+workflow also run its dry run (docs/releasing.md) from the pull request's branch before merging.
+
+## Releases
+
+See `docs/releasing.md`. A test keeps the version, the changelog, the licence files and the links in the documents in agreement.
+
+## Pull requests
+
+Keep them focused (one topic), include tests, update the docs that your change makes untrue, and run the whole suite; the pull request
+template lists what to check. Add a line under `[Unreleased]` in `CHANGELOG.md` for anything a user would notice, and write a new limit into
+`docs/threat-model.md`. Do not bump the version or rename the changelog's heading: that is part of a release. The required checks must pass
+before a pull request can merge, and only the maintainer creates release tags (the maintainer can bypass both rules, so they guard against
+mistakes, not against the maintainer). Commits stay public for good, so use a GitHub no-reply address as your commit email if you would
+rather not publish your own. By contributing you agree that your contribution is licensed under the Apache License 2.0 (see LICENSE).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memdebug
-Version: 0.3.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
@@ -33,21 +33,63 @@ Description-Content-Type: text/markdown
 
 # memdebug
 
+[![CI](https://github.com/juraj-jumic/memdebug/actions/workflows/ci.yml/badge.svg)](https://github.com/juraj-jumic/memdebug/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/memdebug)](https://pypi.org/project/memdebug/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/memdebug/)
+[![License](https://img.shields.io/github/license/juraj-jumic/memdebug)](LICENSE)
+
 **See what your AI agent's memory holds, what changed, and put it back.** A local, agent-neutral tool for people who run
 agents whose memory they can reach: notes in a folder or git repository, Open WebUI's memory, or a self-hosted Mem0.
 
+![memdebug demo: an edit that bypassed git is caught and undone without losing anything, and a tampered copy of the record is detected](docs/demo.gif)
+
+That is `memdebug demo` as released in 0.3.0, paced for reading (the real run takes about a second on Linux and a few seconds on Windows).
+The unpaced recording is [`docs/demo.cast`](docs/demo.cast): `asciinema play docs/demo.cast`.
+
 An agent's memory is built from text it read at runtime, and text can be planted: an email, a web page, a document.
 Nobody reviews all of it. memdebug records what the memory holds in a tamper-evident ledger, shows what changed and when,
 catches edits that bypassed the store's own history, compares snapshots, flags wording worth a second look, and rolls markdown memory
 back safely.
 
 It is an **observer**: it never sits between the agent and its memory, never talks to the agent, and runs entirely on your
-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.
+computer. It does not block attacks as they happen (run it next to runtime guards). For Claude Code it can point at the logged session
+behind a flagged change, as evidence and never as proof; for any other agent it cannot 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.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
+> **Status: alpha (0.4).** 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.
 
+## Why this matters
+
+An agent's memory is text that is read back into the model at the start of every session. That makes it an unusual kind of state: it
+persists, nobody reviews it, and anything the agent reads (an email, a web page, a document) can try to write itself into it. A poisoned
+note does not fail loudly. It quietly changes behaviour later, in sessions that look unrelated. memdebug treats memory like any other
+critical state: something to inspect, compare, prove and recover. The design problems it takes on:
+
+* **Non-deterministic behaviour, deterministic state.** You cannot replay a language model, but you can pin down what it was *given*. A
+  snapshot is the memory's text at a moment, as memdebug read it (line endings normalised, and a very long text cut with a hash of the whole),
+  a diff is exactly what changed between two snapshots, and for git notes and plain folders a rollback puts a known-good state back. "What was
+  the agent working from when it did that?" becomes a question you can answer from evidence, provided memdebug was watching at the time.
+* **Views of memory that can disagree.** For markdown in git and for Mem0 there are three: the store's own history, what is actually there
+  now, and memdebug's own record. They are reconciled, and the case that matters most is flagged: a change that **bypassed the store's own
+  history**. A plain folder and Open WebUI keep no history, so there memdebug records what changed between two looks but cannot call
+  anything "outside the history".
+* **A record that shows tampering.** Entries are only ever appended, and each is hash-chained to the one before, so editing or removing an
+  old entry is detectable (`memdebug verify`). Someone who can rewrite the whole ledger file can rebuild a valid chain, and cutting off the
+  newest entries is only detectable against a copy of the head hash kept somewhere else (`memdebug witness`). The threat model says so.
+* **Safe recovery, not just detection.** A rollback is a plan you review first, and the plan writes nothing. What it would replace is saved
+  before anything is touched: for a plain folder every replaced file is copied byte for byte into a private backup folder next to the ledger;
+  for git notes, anything git does not already hold is saved under `refs/memdebug/backups/`. The written files are checked against the plan,
+  a failure while writing puts the files back, and the rollback is recorded in the ledger and can itself be undone.
+* **Hostile input by design.** Memory text is untrusted: its size is bounded, it is never executed, and everything shown is escaped (terminal
+  output through `safe_text`, the viewer through an escaping HTML builder with no JavaScript). git runs with a scrubbed environment and with
+  hooks, filters, pagers, external diff helpers and file-system monitors switched off. `memdebug selftest` checks the platform-dependent
+  protections on your own machine instead of asking you to take them on trust, and [docs/threat-model.md](docs/threat-model.md) lists what is
+  protected and what is not.
+
+What it deliberately is not: it does not hook into your agent, intercept prompts or optimise tokens. It reads the stores your agent already
+writes, from outside (and, for Claude Code, its session logs, read-only, only to say which session logged an edit to a flagged note).
+
 ## Try it in a minute
 
 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
@@ -97,7 +139,7 @@ Or register stores yourself (this is what a script would do):
 | 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 |
 
-Which agents does it know? Claude Code, OpenClaw, Gemini CLI, Codex CLI, Windsurf and Open WebUI (in Docker): see [docs/agents.md](docs/agents.md)
+Which agents does it know? Claude Code, OpenClaw, Gemini CLI, Codex CLI, Windsurf, Cline and Open WebUI (in Docker): see [docs/agents.md](docs/agents.md)
 for where each keeps its memory and where that was verified. Where memory sits in one file beside credentials (`~/.gemini`, `~/.codex`,
 `~/.claude`), memdebug watches only that file. If Open WebUI runs in Docker, `memdebug setup` finds it and takes a read-only copy of its database before every look; there is nothing to
 set up by hand (`windows-tools/copy-webui-db.ps1` is only a fallback for other setups). A store with no history can still be watched, but memdebug cannot tell an
@@ -139,8 +181,8 @@ user service or a login item. memdebug does not install anything that starts by
 
 ## The viewer
 
-`memdebug serve` starts a read-only web page (timeline with an inspector, snapshots, compare,
-integrity) on **127.0.0.1 only**, and prints a link that contains a random secret. Open that link;
+`memdebug serve` starts a read-only web page (timeline with an inspector, snapshots, compare, the agents it
+found, integrity) on **127.0.0.1 only**, and prints a link that contains a random secret. Open that link;
 the secret moves into a cookie and disappears from the address bar. It uses only Python's standard
 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).
@@ -165,11 +207,54 @@ 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
   global `safe.directory` setting.
 
+## How it works
+
+```
+                    your agent (Claude Code, Open WebUI, Mem0, ...)
+                    runs as usual: memdebug never hooks into it
+                                       |  writes its memory
+                                       v
+        +--------------------------- memory store ---------------------------+
+        |  markdown notes in git  |  plain folder  |  Open WebUI  |  Mem0     |
+        +------------------------------------+------------------------------+
+                                             |  read-only readers: nothing the store holds is executed
+                                             v
+   +-------------------+   +---------------------------------+   +--------------------------+
+   | sync              |-->| events: added, changed, deleted,|-->| hints: "worth a second   |
+   | the store's       |   | OUTSIDE the store's history     |   | look" (heuristics)       |
+   | history vs what   |   +----------------+----------------+   +--------------------------+
+   | is there now vs   |                    | append
+   | the ledger        |                    v
+   | (check, watch and |   +-------------------------------------+
+   | snapshot run it)  |   | ledger: hash-chained, tamper-evident |   snapshots = the text
+   +-------------------+   | + snapshots                          |   of the memory at a moment
+                           +-----+----------------+---------+-----+
+                                 |                |         |
+                                 v                v         v
+                       check / watch /       serve (read-only   diff s1 s2
+                       timeline / verify     browser viewer)    compare two moments
+                       in the terminal
+                                 |
+                                 |  you decide to go back
+                                 v
+   rollback:  plan (writes nothing) -> you confirm -> save what is replaced
+              -> write -> check the written files against the plan -> record in the ledger
+              a failure while writing puts the files back (if only the final ledger entry fails,
+              the files stay restored and you are told)
+              the only code that writes to a memory store: git notes and plain folders, never databases
+```
+
+memdebug's own files (the ledger, the list of watched stores, folder-rollback backups, copies of Open WebUI's database) live in its own data
+folder, or where you point `--db`, `--out` or `--file`; memdebug does not write them inside a store. For Claude Code, `check` and `watch` also read
+its session logs (read-only, ids and times only) to say which session logged an edit to a flagged note: evidence, not proof.
+
 ## How it is built
 
 The core (model, ledger, sync, reconcile) imports no backend. Each store type is a read-only adapter: `markdown-git` and `folder`
@@ -185,6 +270,20 @@ 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).
 
+## Engineering
+
+* **Tests:** 1,500+ `pytest` tests, run on every push to `main` and every pull request on Linux, Windows and macOS with Python 3.10, 3.12 and
+  3.14, including platform-specific cases (real NTFS junctions made with `mklink /J`, case-insensitive file names, CRLF). CI also runs
+  `memdebug selftest` and `memdebug demo` on each of those, and builds the package and installs it into a clean environment.
+* **Protections are proven, not assumed:** the project's rule is that a protection only counts once removing it makes a test fail. See
+  [CONTRIBUTING.md](CONTRIBUTING.md).
+* **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 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.
+
 ## 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