Quickstart

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 test run, and a deterministic rule, not a model, decides whether it is still verified, stale, or unconfirmed. The record is a hash-chained ledger kept by a local daemon; a new session (the same agent later, another agent, a person) reads a compact Context Pack of what holds, what is open and what to do next, and takes the work over under a rule that says when a Session left open may be ended.

It is a Rust workspace: memproved (the daemon), memprove (the command-line client, the Claude Code SessionStart hook and an MCP server with ten tools), and the crates they share. Everything runs on your machine over a Unix socket; nothing leaves it.

简体中文：中文快速上手

1. Install

On macOS on Apple silicon, or Linux x86_64 with glibc 2.35 or later (such as Ubuntu 22.04 and Debian 12):

curl -fsSL https://memprove.dev/install.sh | sh
export PATH="$HOME/.memprove/bin:$PATH"     # --write-profile puts it in the profile
memprove --version

The installer picks the release archive for the machine (aarch64-apple-darwin or x86_64-unknown-linux-gnu) from the latest GitHub release, stops unless the archive’s SHA-256 matches its .sha256 file, and runs the archive’s own scripts/install.sh --from-binaries bin: memprove goes into ~/.memprove and the daemon starts. Run it again to upgrade; the data is backed up first. Options go after sh -s --:

# also write the PATH line into the shell profile
curl -fsSL https://memprove.dev/install.sh | sh -s -- --write-profile
# change no profile and ask nothing
curl -fsSL https://memprove.dev/install.sh | sh -s -- --no-write-profile
# another directory; it then also needs the MEMPROVE_* lines it prints
curl -fsSL https://memprove.dev/install.sh | sh -s -- --prefix ~/tools/memprove
# a given release instead of the latest
curl -fsSL https://memprove.dev/install.sh | MEMPROVE_VERSION=0.1.0 sh

With neither profile option, a run in a terminal asks once before it changes the profile. Linux on arm64 is not supported yet, and the installer stops on any platform without a release archive; build from source there, as Install, upgrade and backup says.

By hand

The same steps without the installer, release 0.1.0:

target=aarch64-apple-darwin        # or x86_64-unknown-linux-gnu
base=https://github.com/memprove/memprove/releases/download/v0.1.0
curl -LO "$base/memprove-0.1.0-$target.tar.gz"
curl -LO "$base/memprove-0.1.0-$target.tar.gz.sha256"
shasum -a 256 -c "memprove-0.1.0-$target.tar.gz.sha256"
tar -xzf "memprove-0.1.0-$target.tar.gz"
cd "memprove-0.1.0-$target"
scripts/install.sh --from-binaries bin        # installs into ~/.memprove and starts the daemon
export PATH="$HOME/.memprove/bin:$PATH"       # --write-profile puts this line in your shell profile

The macOS binaries are not notarized: if a browser downloaded the archive, clear the quarantine flag first (xattr -dr com.apple.quarantine memprove-0.1.0-aarch64-apple-darwin). Archives that curl downloads, as the installer does, carry no such flag.

2. Enable a repository

From inside the repository’s Git worktree (it needs at least one commit):

memprove init

init registers the Project, keeps memprove’s own files out of your Evidence through .git/info/exclude, writes the configuration of the clients it finds (Claude Code: the SessionStart hook in .claude/settings.local.json and .mcp.json; Codex: ~/.codex/config.toml and a note in AGENTS.md; Cursor: .cursor/mcp.json and a rule), and ends with memprove doctor. Running it again changes nothing. --client names the clients; --allow-tools also writes Claude Code’s allow rules for the MCP server and memprove run. Before the first Session, doctor prints two WARN lines (workspace, ledger); both pass after it. Enabling memprove in a project has the details.

3. One session, five commands

memprove begin --new-task "parser: handle empty input"     # or a plain `begin` to continue the Task
# ... edit, commit ...
memprove run --test-format cargo -- cargo test              # the run is the Evidence; its label is r1
memprove checkpoint create \
  --fact "the parser accepts empty input and reports it as an empty document" --evidence r1 \
  --open "the error path for a truncated header is untested" \
  --next "write the truncated-header test and run cargo test"
memprove resume --pack                                     # what the next session will read
memprove end --reason "empty input handled"

begin starts a Session on a Task (and creates the Task with --new-task). run runs the command in your shell and records its result together with the repository state. checkpoint create records facts (each citing runs), open items, decisions and the next action; a fact needs a passed test run, and stays verified only while the tree matches that run (commit or ignore a file the test run creates, such as a first Cargo.lock). resume --pack prints the Context Pack: the Task’s verdict, the Sessions, the last passed run, what can be done next, every active statement with its verdict and the commit it is bound to, and what to run again. end ends the Session. In Claude Code the hook injects the Pack at the start of every session, and the MCP tools do what the commands do, except running commands: tests are always recorded with memprove run.

memprove --help lists every command; docs/guide.md is the agent’s manual, from install to takeover.

A run supports facts only while git status --short lists no untracked files. A Python test run leaves __pycache__/ behind: add it to .gitignore or .git/info/exclude before the run you cite, or the fact reads unconfirmed.

What the next session reads

This is the Pack of a real session in tinyini, a small Python repository, right after its first checkpoint (every command of that session):

$ memprove resume --pack
Pack: memprove-pack v1; capsule_digest sha256:9b2f9bd45319be25010bbe0ecbb937aaa7902f465f76af15a1f176edd669e43b; ledger sequence 7; probed HEAD 5ebf8ad58118f1d7bf8cf479951c3b36932f9676; budget 9000 UTF-16 code units
Ontology: continuity.work-state-ontology.v4 (the version of the verdict rules)
Task「parser: handle empty input」 (in_progress): verified; active claims 6: facts 4 (verified 4), open items 1, decisions 0, next actions 1; superseded 0; withdrawn 0 (facts 0)
Integrity: no inconsistency found (the event chain is valid, and every record of this Task recomputes and agrees with the ledger)
Sessions: 1 in all, 0 ended normally, 0 ended abandoned, 1 not ended, 0 declared a resumed_from Pack
Session 1 01a1dc2c-4168-7511-b3a3-220085a788c5 not ended (started 2026-11-14T22:27:30.280957974Z, last wrote to the ledger at 2026-11-14T22:27:30.825220406Z)
Last passed: 「python3 -m pytest -q」 (5ebf8ad58118; --test --test-format pytest)
Can: complete the Task (transitionTask; cites 1 passed runs of the current repository state; needs mcp-write)
Can: begin a new Session (createSession; first end it as the line of Session 1 says, or confirm it is still working; needs mcp-write)
Can: record a fact citing the latest run (createCheckpoint; needs mcp-write)
Base: 5ebf8ad58118f1d7bf8cf479951c3b36932f9676; files changed since: none
#5 open item: 「an unterminated section header such as [core is untested」 (no evidence cited; from Session 1)
#1 verified: 「parse() returns an empty document for empty or whitespace-only input」 (evidence bound to commit 5ebf8ad58118; from Session 1)
#2 verified: 「input of only comments is an empty document」 (evidence bound to commit 5ebf8ad58118; from Session 1)
#3 verified: 「keys before the first section header go into the default section」 (evidence bound to commit 5ebf8ad58118; from Session 1)
#4 verified: 「a duplicate key keeps the last value」 (evidence bound to commit 5ebf8ad58118; from Session 1)
#6 next action: 「write the unterminated-header test and run pytest」 (no evidence cited; from Session 1)
Omitted: level 0; bases with files only counted 0, bodies shortened 0, bodies omitted 0, folded into one line 0, not listed 0; full text of given numbers: memprove resume --pack --claims <numbers> (such as 3,5-7)
Digest: sha256:372b545739b632561676feda70b67506425a070275722cb3d026b26338b9551b

Taking over

A Pack lists every Session that has not ended. A session that finds one left by another agent ends it as abandoned only when all three hold: its agent is not you; it looks gone, because its last write is more than 15 minutes old or the Session that dispatched it has ended; and it is not your own parent. Otherwise the Session stays open, begin as usual, and the session’s first checkpoint records an open item that another Session may still be working. The hook’s opening gives you your name, the current UTC time and your parent, so the rule needs no read of your environment. memproved records who ended whom, and a Session that declared the sub_agent role cannot record a Decision, complete the Task, or overrule another agent’s facts; the orchestrating session or a person does that. The takeover evaluation (docs/takeover-eval.md) runs a real client through six scenarios and scores the archive.

Next

• The agent’s guide: every command, the Pack, the hook, the MCP server and the exit codes.
• How it works: the daemon, the ledger, Evidence and verdicts, with a recorded session.
• llms.txt: the same setup, written for a coding agent to follow.