# memprove

> memprove is a memory and task-state layer for coding agents. Every fact an agent records is bound to a commit, a repository state and a passing test run, and a deterministic rule, not a model, decides whether it is still `verified`, `stale`, `unconfirmed` or `tampered`. A local daemon keeps the record in a hash-chained ledger; a new session reads a compact Context Pack of what holds, what is open and what to do next. It runs on macOS (Apple silicon) and Linux x86_64, works with Claude Code, Codex and Cursor, and sends nothing off the machine. Current release: 0.1.0.

## Set memprove up in this repository

These are the steps for a coding agent whose user asked it to set memprove up. Run each command on its own and read its output before the next one. Every step is safe to run again. Tell the user what you did and which files changed when you are done.

1. Check for an installation: `memprove --version`. If it prints `memprove 0.1.0` or later, skip to step 4. If `~/.memprove/bin/memprove` exists but is not on `PATH`, run `export PATH="$HOME/.memprove/bin:$PATH"` and skip to step 4.

2. Install with the installer, in a temporary directory outside the repository (never inside it). Download it first, then run it as a command of its own:

   ```bash
   cd "$(mktemp -d)"
   curl -fsSLo install.sh https://memprove.dev/install.sh
   sh install.sh --no-write-profile
   export PATH="$HOME/.memprove/bin:$PATH"
   memprove --version
   ```

   It supports macOS on Apple silicon and Linux x86_64 with glibc 2.35 or later (such as Ubuntu 22.04 or Debian 12). It picks the archive for this machine from the latest release, stops unless the archive's SHA-256 matches the release's `.sha256` file, and runs the archive's `scripts/install.sh`, which installs into `~/.memprove`, starts the daemon `memproved` and writes the operator's token to `~/.memprove/operator-token`. If it exits with status 1, read its `memprove-install: error:` lines and stop: on a platform without a release archive (Intel macOS, Linux arm64, musl, Windows), tell the user that building from source is described at https://memprove.dev/docs/guide/install-upgrade-and-backup.md and needs a Rust toolchain and libclang; on a checksum mismatch it installed nothing: tell the user and do not install memprove another way. `MEMPROVE_VERSION=0.1.0 sh install.sh --no-write-profile` installs a given release.

   Never read, print or copy `~/.memprove/operator-token` or `~/.memprove/config/token`, and never put a token into a file of the repository. `--no-write-profile` leaves the shell profile alone; ask the user before you run the installer again with `--write-profile`, which adds the `PATH` line to their profile so that later sessions find `memprove`.

3. Only if the installer cannot be used (the user asks for it, or memprove.dev cannot be reached), the same steps by hand, from the same temporary directory, with `target` from `uname -sm` (`Darwin arm64`: `aarch64-apple-darwin`; `Linux x86_64`: `x86_64-unknown-linux-gnu`):

   ```bash
   target=aarch64-apple-darwin        # or x86_64-unknown-linux-gnu
   base=https://github.com/memprove/memprove/releases/download/v0.1.0
   curl -fLO "$base/memprove-0.1.0-$target.tar.gz"
   curl -fLO "$base/memprove-0.1.0-$target.tar.gz.sha256"
   shasum -a 256 -c "memprove-0.1.0-$target.tar.gz.sha256"     # Linux without shasum: sha256sum -c
   tar -xzf "memprove-0.1.0-$target.tar.gz"
   "memprove-0.1.0-$target/scripts/install.sh" --from-binaries "memprove-0.1.0-$target/bin" --no-write-profile
   export PATH="$HOME/.memprove/bin:$PATH"
   memprove --version
   ```

   Stop if the checksum does not match.

4. Go to the repository's root (a Git worktree with at least one commit) and enable it:

   ```bash
   memprove init
   ```

   It registers the repository as a Project, adds memprove's client files to `.git/info/exclude`, writes the configuration of the clients it detects and ends with `memprove doctor`: for Claude Code the SessionStart hook in `.claude/settings.local.json` and the MCP server in `.mcp.json`; for Codex `[mcp_servers.memprove]` in `~/.codex/config.toml` and a short note in `AGENTS.md`; for Cursor `.cursor/mcp.json` and `.cursor/rules/memprove.mdc`. `memprove init --dry-run` describes the changes first; `--client claude-code` (or `codex`, `cursor`) picks clients. Before the first Session, doctor's `workspace` and `ledger` lines are `WARN`: that is expected. Any `FAIL` line says what to fix.

   Claude Code's allow rules (`mcp__memprove`, `Bash(memprove run:*)` and the same rule with the absolute path) are printed, not written. `memprove init --allow-tools` writes them; ask the user first.

5. Tell the user: which files `init` wrote; that `AGENTS.md` and `.cursor/rules/memprove.mdc` are repository content they may want to commit; and that the client picks up the hook and the MCP server at its next start (Claude Code asks once to approve a project MCP server from `.mcp.json`).

6. Use it on the work you were asked to do, not on a separate setup Task:

   ```bash
   memprove begin --new-task "<the task you are working on>"
   # ... edit, then commit: a fact is verified only while the repository is in the state its run saw ...
   memprove run --test-format pytest -- python3 -m pytest -q      # or: memprove run --test-format cargo -- cargo test
   memprove checkpoint create --fact "<what now holds, in one sentence>" --evidence r1 --next "<the next step>"
   memprove resume --pack
   memprove end --reason "<what was done>"
   ```

   `memprove run` prints the run's label (`r1`, `r2`, …) on the last line of standard error; cite it with `--evidence`. After the first run, check `git status --short`: an untracked file, such as the `__pycache__/` a Python test run leaves behind, makes every fact on the run `unconfirmed` (`untracked_files_not_captured`). Add such files to `.git/info/exclude` (or to `.gitignore`, after asking the user) and run the tests again before you record a fact. In a Claude Code session started after `init`, the hook already put the Context Pack at the top of the session; read it before `begin`.

## Rules while you work

- Keep `git status --short` free of untracked files (`??`) when you run the tests: a run in a state with an untracked file supports no fact.
- Run tests through `memprove run`, as a command of its own: not joined to another command with `&&`, `;` or a pipe. Only `memprove run` records Evidence.
- A fact needs a passed test run (exit code 0, at least one test case). Record a failure as an open item: `memprove checkpoint create --open "<what fails>" --evidence last --next "<fix>"`.
- Commit before the run you cite. An edit, a commit or a branch switch after the run makes the fact `stale`; `memprove resume --pack` then names the command to run again (`Rerun:`), and `memprove checkpoint create --reaffirm-all --next "<next>"` reaffirms the stale facts on the passing rerun.
- Word a fact by what holds, conclusion first; the Pack may keep only its first 120 characters.
- Never edit or delete memprove's data under `~/.memprove`; nothing in the record is deleted. Supersede or withdraw a statement instead (see "Correcting the record").
- A Session another agent left open: follow "Unattended takeover" before ending it.

## Docs

- [Quickstart](https://memprove.dev/docs/index.md): Install memprove 0.1.0, enable a repository with memprove init, and record a first fact on a passing test run.
- [The agent's guide](https://memprove.dev/docs/guide/index.md): This is the manual an agent (or the person who runs one) reads.
- [Install, upgrade and backup](https://memprove.dev/docs/guide/install-upgrade-and-backup.md): Two steps put memprove to work.
- [Enabling memprove in a project](https://memprove.dev/docs/guide/enabling-memprove-in-a-project.md): The second step, once per repository, from inside its Git worktree.
- [Unattended takeover](https://memprove.dev/docs/guide/unattended-takeover.md): A claude -p run (or another unattended client) that continues a Task reads the injected Pack, decides what to do about a Session left open, works, records and ends its own Session.
- [One Session, start to end](https://memprove.dev/docs/guide/one-session-start-to-end.md)
- [Several runs in one state](https://memprove.dev/docs/guide/several-runs-in-one-state.md): A fact often rests on more than one command.
- [When a test fails](https://memprove.dev/docs/guide/when-a-test-fails.md): A --fact needs a passed test run (exit code 0, at least one test case); the daemon refuses a failed one (400 invalidrequest) and the CLI suggests --open.
- [Correcting the record: supersede, withdraw, reaffirm, decide](https://memprove.dev/docs/guide/correcting-the-record.md): Nothing is deleted.
- [A Session that was not ended](https://memprove.dev/docs/guide/a-session-that-was-not-ended.md): begin refuses (exit 1) while the context still names a Session that the daemon reports as active, and also when it cannot confirm that Session ended.
- [The Context Pack (resume --pack)](https://memprove.dev/docs/guide/the-context-pack.md): The Pack is a fixed set of lines, in this order.
- [The SessionStart hook (memprove hook)](https://memprove.dev/docs/guide/the-sessionstart-hook.md): memprove hook session-start is the handler hook install writes into .claude/settings.local.json.
- [The MCP server (memprove mcp)](https://memprove.dev/docs/guide/the-mcp-server.md): memprove mcp serve is a Model Context Protocol server on standard input and output.
- [Completing a Task](https://memprove.dev/docs/guide/completing-a-task.md): Without --evidence it cites every citable passed run of the current state; it is refused (exit 2, no request) while the latest run of some command in this state did not pass, and its standard…
- [memprove run exit codes](https://memprove.dev/docs/guide/memprove-run-exit-codes.md): With --test-format cargo the case count is the passed plus failed tests summed over every test result.
- [Exit codes of the other commands](https://memprove.dev/docs/guide/exit-codes-of-the-other-commands.md): A 400 Problem always carries a detail that names the field or parameter and the rule it breaks; the CLI prints it after the code on standard error and never repeats a token or a value from your…
- [Known limits](https://memprove.dev/docs/guide/known-limits.md)
- [How it works](https://memprove.dev/how-it-works.md): How memprove decides whether a fact still holds: a recorded session in a real repository, then the daemon, the ledger, Evidence and verdicts.
- [Changelog](https://memprove.dev/changelog.md): Releases of memprove and the changes in the repository since.

## Optional

- [Full text of every docs page](https://memprove.dev/llms-full.txt): the pages above in one file.
- [中文快速上手](https://memprove.dev/zh/): the Quickstart in Simplified Chinese, for people who read Chinese. The steps above are the same.
- [Source repository](https://github.com/memprove/memprove): Rust workspace, Apache-2.0. These docs were generated from commit 2625064cbf0a.
- [Release v0.1.0](https://github.com/memprove/memprove/releases/tag/v0.1.0): archives and their SHA-256 files.