memdebug

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, an MCP memory server's file, or a self-hosted Mem0.

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: 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). 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 for exactly what it does and does not do.

Status: 1.0. The interfaces in docs/stability.md are stable, and a ledger written by any earlier release keeps working (tested). The tests run on every push on Linux, Windows and macOS (Python 3.10, 3.12 and 3.14). Be clear about how much has been tried by a person: Claude Code and Open WebUI on a real installation; every other agent in docs/agents.md follows its own documentation and may be out of date, and the background watcher's Linux and macOS forms have not been applied on a real system. ROADMAP.md lists what is still open.

Try it in a minute

You need git 2.31 or newer, and either Python 3.10 or newer or the stand-alone program (see below).

pipx install memdebug
memdebug demo                 # made-up agent, made-up attack, the real tools; nothing of yours is touched

No pipx? Use a virtual environment, which works the same way everywhere:

python -m venv memdebug-env
memdebug-env\Scripts\activate          # Windows; on macOS and Linux: source memdebug-env/bin/activate
pip install memdebug

If your shell cannot find the memdebug command, python -m memdebug (on Windows py -m memdebug) does the same thing.

No Python? Download the program for your system from the latest release (memdebug-windows-x64.exe, memdebug-linux-x64 or memdebug-macos-arm64) and run it from a terminal in the folder you saved it to, in place of memdebug in everything below:

.\memdebug-windows-x64.exe demo                       # Windows (PowerShell)
chmod +x memdebug-linux-x64 && ./memdebug-linux-x64 demo   # Linux; on macOS use memdebug-macos-arm64

It is the same program with Python packed inside, and it still needs git. It is not signed, so Windows SmartScreen or macOS Gatekeeper may warn the first time (see docs/windows.md); compare the file with the SHA256SUMS on the release page before you run it. Mem0 needs the pip install, and the programs take about a second to start. Tried by the author on Windows 11; the Linux and macOS programs are built and smoke-tested by CI on those systems. Double-clicking it only shows a short explanation (it is a command-line program), so start it from a terminal.

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. memdebug demo --serve then shows it in the browser viewer.

Watch your own agent's memory

You point memdebug at the memory; it does not hook into the agent.

memdebug agents      # which AI agents are on this computer, and what each keeps (looks at folder names only)
memdebug setup       # finds that memory, asks before adding anything, saves a first snapshot of each
memdebug check       # looks for changes once; exit code 1 means something needs a look or a note could not be read
memdebug watch       # keeps looking and says so when something changes (Ctrl+C to stop)
memdebug serve       # the same story in your browser, read-only
memdebug autostart install   # keeps `watch` running from login on, so a change made and undone while you were away is still seen

If something looks wrong, put it back:

memdebug rollback store NAME --to s1           # a dry run: shows what would change, writes nothing
memdebug rollback store NAME --to s1 --apply   # does it, after you type the snapshot id

Run memdebug selftest once on any new machine: it proves the platform-dependent protections hold there, and says SKIP (never PASS) for anything it could not prove. Treat the ledger as sensitive: it contains your agent's memory text.

Learn more

• docs/usage.md: adding stores by hand, which stores can be rolled back, reports, the witness, hints, the browser viewer.
• docs/rollback.md: what a rollback guarantees, for plain folders and for git notes.
• docs/how-it-works.md: the design, how the pieces fit, and how the project is tested and released.
• docs/agents.md: which agents it knows and where each keeps its memory. docs/windows.md: Windows notes.
• docs/open-webui-tools.md: why an Open WebUI model may never save a memory, and an example router that fixes it.
• docs/threat-model.md: what is defended, against whom, and the known limits.
• docs/stability.md: what is stable from 1.0, and how the ledger stays readable across versions.
• ROADMAP.md, CHANGELOG.md and docs/releasing.md.
• SECURITY.md: how to report a problem. CONTRIBUTING.md: how to help.

Development

pip install -e ".[dev]"
pytest -n auto
memdebug selftest
ruff check src tests && mypy

See CONTRIBUTING.md for the ground rules (everything read from a store is untrusted; adapters only read).

License

Copyright 2026 Juraj Jumić. Apache License 2.0. See LICENSE and NOTICE.