[ 中文快速上手 · memprove 0.1.0 ]

快速上手

memprove 是给 coding agent 用的记忆和任务状态层。agent 记录的每条 fact 都绑定到一个 commit、一个仓库状态和一次测试运行，由确定性的规则（不是模型）判断它现在是 verified、stale 还是 unconfirmed。记录保存在本地 daemon 维护的哈希链 ledger 里。新的会话（之后的同一个 agent、另一个 agent，或者一个人）读一份紧凑的 Context Pack：哪些仍然成立、哪些还没解决、下一步做什么；再按一条规则接手工作，这条规则说明什么时候可以结束别人留下的 Session。

它是一个 Rust workspace：memproved（daemon）、memprove（命令行客户端、Claude Code 的 SessionStart hook，以及一个有十个工具的 MCP server），还有它们共用的 crate。所有东西都在你的机器上通过 Unix socket 运行，没有数据离开你的机器。

memprove 的命令、输出和完整文档都是英文的，本页只翻译说明文字。Task、Session、fact、Evidence、Pack 这些词保留英文，因为命令和输出里就是这些词。英文原文：Quickstart。

1. 安装

支持 Apple 芯片的 macOS，以及 glibc 2.35 或更高版本的 Linux x86_64（比如 Ubuntu 22.04、Debian 12）：

bash

$ curl -fsSL https://memprove.dev/install.sh | sh

# 加 --write-profile 时，安装器会把下面这一行写进 shell 配置文件

$ export PATH="$HOME/.memprove/bin:$PATH"

$ memprove --version

安装器从最新的 GitHub release 里挑出适合这台机器的发布包（aarch64-apple-darwin 或 x86_64-unknown-linux-gnu），发布包的 SHA-256 和它的 .sha256 文件对不上就停下，然后运行发布包自带的 scripts/install.sh --from-binaries bin：memprove 装进 ~/.memprove，daemon 随之启动。再运行一次就是升级，数据会先备份。选项写在 sh -s -- 后面：

bash · 选项

# 同时把 PATH 这一行写进 shell 配置文件

$ curl -fsSL https://memprove.dev/install.sh | sh -s -- --write-profile

# 不改任何配置文件，也不提问

$ curl -fsSL https://memprove.dev/install.sh | sh -s -- --no-write-profile

# 装到别的目录；这时还需要它打印出的那几行 MEMPROVE_*

$ curl -fsSL https://memprove.dev/install.sh | sh -s -- --prefix ~/tools/memprove

# 装指定的版本，而不是最新版

$ curl -fsSL https://memprove.dev/install.sh | MEMPROVE_VERSION=0.1.0 sh

两个配置文件选项都不加时，如果是在终端里运行，安装器会在修改配置文件之前问一次。Linux arm64 暂不支持；在没有发布包的平台上安装器会直接停下，这时请按 Install, upgrade and backup（英文）从源码构建。

手动安装

不用安装器，同样的步骤，版本 0.1.0：

bash · 手动安装

# Linux 上改成 target=x86_64-unknown-linux-gnu

$ target=aarch64-apple-darwin

$ 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"

# 装进 ~/.memprove 并启动 daemon；加 --write-profile 会把 PATH 这一行写进 shell 配置文件

$ scripts/install.sh --from-binaries bin

$ export PATH="$HOME/.memprove/bin:$PATH"

macOS 的二进制没有经过公证：如果发布包是用浏览器下载的，先清除隔离标记（xattr -dr com.apple.quarantine memprove-0.1.0-aarch64-apple-darwin）。用 curl 下载的包（安装器就是这样下载的）没有这个标记。

安装器和手动安装都从 GitHub 下载。如果你的网络访问 GitHub 很慢，可以先用浏览器或代理下载发布包和它的 .sha256 文件（macOS：发布包、.sha256；Linux：发布包、.sha256），放进同一个目录，再从上面的 shasum 那一行接着做。

2. 在仓库里启用

在仓库的 Git 工作区里运行（仓库至少要有一个 commit）：

bash

$ memprove init

init 会注册这个 Project；通过 .git/info/exclude 把 memprove 自己的文件排除在 Evidence 之外；为它找到的客户端写配置（Claude Code：.claude/settings.local.json 里的 SessionStart hook 和 .mcp.json；Codex：~/.codex/config.toml 和 AGENTS.md 里的一段说明；Cursor：.cursor/mcp.json 和一条 rule）；最后运行 memprove doctor。再运行一次不会改变任何东西。--client 指定客户端；--allow-tools 还会写入 Claude Code 对 MCP server 和 memprove run 的 allow 规则。第一个 Session 之前，doctor 会打印两行 WARN（workspace、ledger），之后两项都会通过。细节见 Enabling memprove in a project（英文）。

3. 一次会话，五条命令

bash · 一次会话

# 开始一个 Session；不带 --new-task 的 begin 继续当前 Task

$ memprove begin --new-task "parser: handle empty input"

# ……编辑、提交……

# 运行测试：这次运行就是 Evidence，标签是 r1

$ memprove run --test-format cargo -- cargo test

# 记录 fact（引用 r1）、open item 和 next action

$ 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

# 结束 Session

$ memprove end --reason "empty input handled"

begin 在一个 Task 上开始一个 Session（加 --new-task 时同时创建这个 Task）。run 在你的 shell 里运行命令，并把结果和当时的仓库状态一起记录下来。checkpoint create 记录 fact（每条都引用运行）、open item、decision 和 next action；fact 需要一次通过的测试运行，并且只有在工作区和那次运行一致时才保持 verified（测试运行生成的文件要提交或忽略，比如第一次生成的 Cargo.lock）。

resume --pack 打印 Context Pack：Task 的判定、各个 Session、最近一次通过的运行、接下来能做什么、每条有效陈述的判定和它绑定的 commit，以及需要重新运行什么。end 结束 Session。在 Claude Code 里，hook 会在每个会话开始时注入 Pack；MCP 工具能做命令能做的事，只有运行命令除外：测试总是用 memprove run 记录。

memprove --help 列出所有命令；The agent's guide（英文）是 agent 的手册，从安装讲到接手。

只有 git status --short 没有列出未跟踪文件时，一次运行才能支持 fact。Python 的测试运行会留下 __pycache__/：在你要引用的那次运行之前，把它加进 .gitignore 或 .git/info/exclude，否则 fact 会是 unconfirmed。

下一个会话读到什么

下面是 tinyini（一个小的 Python 仓库）里一次真实会话在第一个 checkpoint 之后的 Pack（这次会话的每条命令，英文）：

memprove resume --pack

$ 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

Task「…」 (in_progress): verified：Task 的判定，以及各类陈述的数量。
Sessions: 和 Session 1 … not ended：还没结束的 Session，接手规则看的就是这几行。
Last passed:：最近一次通过的测试运行，和它对应的 commit。
Can:：接下来能做什么，以及每一步需要的权限。
#1 verified: …：每条有效陈述的判定，和它的 Evidence 绑定的 commit。
Omitted:：在预算内省略了什么，以及怎样读到全文。

接手

Pack 会列出每个还没结束的 Session。会话发现另一个 agent 留下的 Session 时，只有同时满足三条才会把它作为 abandoned 结束：它的 agent 不是你；它看起来已经不在了，因为它最后一次写入超过 15 分钟，或者派发它的 Session 已经结束；它不是你自己的父 Session。否则那个 Session 保持打开，你照常 begin，本会话的第一个 checkpoint 会记录一条 open item，说明另一个 Session 可能还在工作。hook 的开场会告诉你你的名字、当前的 UTC 时间和你的父 Session，所以这条规则不需要读取你的环境。

memproved 会记录谁结束了谁。声明了 sub_agent 角色的 Session 不能记录 Decision、不能完成 Task，也不能推翻其他 agent 的 fact，这些由负责编排的会话或者人来做。接手评测（docs/takeover-eval.md，英文）用真实的客户端跑六个场景，并给归档打分。

下一步

The agent's guide（英文）：所有命令、Pack、hook、MCP server 和退出码。
How it works（英文）：daemon、ledger、Evidence 和判定，附一次录制下来的会话。
llms.txt（英文）：同样的安装步骤，写给 coding agent 照着做。
问题和 bug：GitHub issues。