memdebug 0.2.0__tar.gz → 0.4.0__tar.gz

memdebug-0.4.0/.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.0/.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.2.0 → memdebug-0.4.0}/.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.4.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+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.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
+- **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
+- **Witness:** a second copy of the ledger's head kept elsewhere, so a rewritten or cut-short ledger is noticed (`memdebug witness`, `verify --witness`).
+- **Reports** in Markdown, JSON and SARIF, with CI exit codes (`memdebug report`).
+- **Guided use:** `setup`, `add`, `stores`, `remove`, `check`, `status`, `watch`, `agents`, and a registry of watched stores.
+- **More stores:** plain folders of markdown, Open WebUI's memory (read from a copy of its database, or copied by memdebug itself from a Docker
+  container), and single-file memory for agents that keep credentials beside it (Gemini CLI, Codex CLI, Claude Code's global file).
+- **An agent catalog** (Claude Code, OpenClaw, Gemini CLI, Codex CLI, Windsurf, Open WebUI) with locations taken from each agent's documentation.
+- **Hints** ("worth a second look") for instructions to send data, remove confirmation or weaken safeguards, hidden characters and secret-like strings.
+- **A first slice of provenance for Open WebUI:** the app's own `created_by` label and how close a chat was, as evidence only.
+- `memdebug demo`, `memdebug --version`, Apache-2.0 licence, security policy, threat model, roadmap and contributing guide.
+
+### Changed
+- The release workflow re-downloads and re-checks the built files in a separate job before it can publish, so a dry run tests the whole hand-over.
+- The viewer says plainly when a store keeps no history, instead of claiming every change went through one.
+- Opaque ids (UUIDs) are shown short, with what the memory says next to them in `check`.
+- Every pattern that validates an identifier now ends with a strict end-of-text anchor (a trailing newline used to slip through some of them).
+
+### Fixed
+- The witness reader accepts Windows line endings and a byte-order mark (git's autocrlf and some editors add them).
+- Tests can no longer touch the Docker, home folder or data folder of the machine they run on.
+
+## [0.1.0] - 2026-10-05
+
+### Added
+- Tamper-evident ledger with snapshots, `verify`, and compare; markdown/git and Mem0 stores; detection of changes that bypass a store's own history.
+- A read-only browser viewer; rollback for markdown/git with backups, undo on failure and a recorded, undoable result; `selftest`.

memdebug-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,101 @@
+# 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`.
+
+## 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).