---
title: MemPlumb 客户使用说明书
product: MemPlumb
version: 0.13.2
language: zh-CN
verified_at: 2026-08-12
default_mode: Windows x64 portable + local SQLite
audience:
  - customer
  - ai_assistant
  - ai_application_engineer
  - reviewer
  - release_operator
---

# MemPlumb 客户使用说明书

本说明书同时服务于客户和 AI 助手。客户可以按界面步骤完成操作；AI
助手应把本说明书当作执行契约，根据用户目标选择最短的安全路径，并用界面路径、
步骤、结果表和下一步完整回答。

适用版本是 `v0.13.2 Preview`。默认路径是 Windows x64 便携版、本机 SQLite
和中文 MemoryOps Console。生产共享部署、PostgreSQL、SDK、质量评审和发布门禁
在后续章节单独说明。

> 客户最快路径：[直接开始五分钟首次体验](#五分钟首次体验)。先下载并核对
> Release，再由启动器自动打开带授权链接的 Console；完成首次闭环后再按需查看
> AI 契约、SDK、质量和发布章节。

## AI 必读执行契约

AI 助手读取本说明书后必须遵守以下规则：

1. 先识别用户目标：首次体验、写入记忆、检查上下文、调查故障、质量评审、
   发布验证、应用接入、备份，或导出/删除数据。
2. 普通客户默认走 Console；只有研发、运维或自动化场景才优先给 CLI/API。
3. 每次指导都必须提供：界面路径、需要填写的内容、预期结果、成功判据和失败分支。
4. 不得索要、展示或让用户发送 Bearer Key、API Key、启动器状态文件、私钥、
   数据库连接串、完整用户记忆或身份证明。
5. 不得把文件哈希描述成发布者身份签名。`v0.13.2` Windows 包是未签名
   Preview；SHA-256 只能验证文件完整性。
6. 不得根据截图或猜测宣称质量门禁通过。只能使用 Runtime 返回的
   `passed`、`fresh`、`stale`、`blocked`、`expired` 等实际状态。
7. 不得把 SQLite 的便携检索描述成生产 ANN。生产 HNSW 需要 PostgreSQL、
   `pgvector`、合格覆盖率和真实语义基准。
8. 支持答复默认隐藏 Actor ID、Memory ID、Case ID、原始文本和评审证据；
   只有用户明确需要且有权限时才显示最少必要内容。
9. AI 无法直接看到用户当前界面时，不得声称已经点击或执行；应使用
   “请打开”“请确认”“预期看到”等措辞。
10. 除非缺少的信息会改变安全边界，否则不反复追问。默认从本机 Preview
    的五分钟流程开始。

AI 对客户的标准回答结构：

```text
当前目标
界面路径
可视化流程
操作步骤
结果判定
异常处理
下一步
```

可视化流程必须同时给出文本箭头或表格，不能只依赖颜色或一张图片。

## 先选正确路径

```mermaid
flowchart LR
  A["你现在要做什么？"] --> B{"目标"}
  B -->|第一次体验| C["Windows Preview<br/>五分钟跑通"]
  B -->|让 Agent 使用记忆| D["SDK / HTTP API<br/>写入 -> 上下文"]
  B -->|调查记忆错误| E["管线 -> 质量<br/>证据与裁决"]
  B -->|验证新策略| F["Memory Case -> Replay<br/>比较与门禁"]
  B -->|准备生产发布| G["Cohort Plan -> 新鲜度<br/>Release Artifact"]
  B -->|处理个人数据| H["导出 -> 备份边界<br/>彻底删除"]
```

| 你的目标              | 从哪里开始                        | 完成标志                                                     |
| --------------------- | --------------------------------- | ------------------------------------------------------------ |
| 看产品是否能运行      | 双击 `memplumb.exe`               | 总览显示 Runtime 和存储就绪                                  |
| 写入一条记忆          | 总览 -> 写入事件                  | 事件完成，并产生 `create`、`update`、`noop` 或 `reject` 决定 |
| 查看 Agent 会收到什么 | 记忆 -> 上下文检查器              | 产生一个持久化 Context Run                                   |
| 分析错误              | 管线 -> 事件/上下文详情           | 能看到写入阶段、候选、选择和排除证据                         |
| 建立质量案例          | 质量 -> 写入裁决/评审             | 认证裁决被保存为受治理 Memory Case                           |
| 验证候选策略          | 评估 -> Replay Lab/Runs           | Run 完成并显示真实门禁结果                                   |
| 检查能否发布          | 评估 -> Cohort Plans              | 计划完成且新鲜度为 `fresh`                                   |
| 接入业务 Agent        | TypeScript/Python SDK 或 HTTP API | 写入和 Context 请求使用同一 Actor ID                         |
| 导出或删除用户数据    | CLI 的 `export` / `purge`         | 得到导出文件或删除收据                                       |

## 五分钟首次体验

### 1. 下载并验证

从
[MemPlumb v0.13.2 Release](https://github.com/funnaz/memplumb-releases/releases/tag/v0.13.2)
下载
[Windows x64 ZIP](https://github.com/funnaz/memplumb-releases/releases/download/v0.13.2/memplumb-0.13.2-windows-x64.zip)，
解压后在 PowerShell 中运行：

```powershell
Get-FileHash .\memplumb.exe -Algorithm SHA256
Get-Content .\SHA256SUMS
```

`Get-FileHash` 的值必须同时等于 `SHA256SUMS` 和 `manifest.json` 中记录的
SHA-256。任一处不一致都不要运行。

当前 EXE 未做 Authenticode 发布者签名。普通 Windows 电脑首次运行时可能出现
“Windows 已保护你的电脑”：

1. 确认文件来自上面的正式 Release。
2. 先完成 SHA-256 核对。
3. 点击“更多信息”。
4. 点击“仍要运行”。

如果电脑由企业策略、Smart App Control、WDAC 或 AppLocker 直接阻止，不要关闭
整机安全策略来绕过；应由 IT 批准，或改用受管部署方式。

### 2. 启动

双击 `memplumb.exe`，或在 PowerShell 中运行：

```powershell
.\memplumb.exe
```

它会启动或复用一个隐藏的本机 Runtime，并自动打开带一次性授权链接的中文/英文
Console。默认从 `127.0.0.1:6066` 开始寻找空闲端口；`6066` 被其他程序占用时会
尝试后续端口，不会结束不属于 MemPlumb 的进程。浏览器没有自动打开时，请使用
启动器显示的完整 URL。该 URL 会标记为单次使用并显示失效时间，默认 60 秒内
有效；过期后重新运行 EXE 获取新链接。不要手工拼接裸的 `/console` 地址，也不要
把带授权片段的 URL 发给其他人。

本地模式不需要安装 Node.js，也不需要启动 Docker。

### 3. 确认总览

打开“总览”，确认：

| 检查项       | 正常结果             | 异常时怎么做                               |
| ------------ | -------------------- | ------------------------------------------ |
| 连接         | 已连接               | 重新双击 EXE，让启动器生成新的单次连接入口 |
| Runtime 状态 | 就绪                 | 运行 `.\memplumb.exe doctor --json`        |
| 存储         | `ready`              | 检查磁盘权限和日志                         |
| 工作区       | `default` 或指定名称 | 确认没有连错测试/生产工作区                |
| 版本         | `0.13.2`             | 重新核对下载版本和哈希                     |

![MemPlumb 总览：Runtime、存储、管线和最近事件](./assets/customer-manual/01-overview.png)

上图使用隔离的示例数据库和示例 Actor。你的计数、Build ID、时间和事件 ID
会不同。

### 4. 写入测试事件

界面路径：`总览 -> 写入事件`

空工作区会默认选择“结构化事实”，让第一次 Memory 写入结果更明确。填写：

| 字段       | 示例                   | 说明                                               |
| ---------- | ---------------------- | -------------------------------------------------- |
| Actor ID   | `demo_customer`        | 业务中的用户/主体编号；同一用户必须始终使用同一 ID |
| 事件类型   | `conversation.message` | 首次体验保留默认值                                 |
| 类型       | `profile`              | Fact 的业务分类                                    |
| 键         | `current_location`     | 同一 Actor 下稳定的记忆键                          |
| 值         | `杭州`                 | 只使用测试数据，不要先录入真实个人数据             |
| 置信度     | `0.95`                 | 范围 `0` 到 `1`                                    |
| 敏感度     | `普通`                 | 凭据应标为 `凭据`，默认策略会拒绝                  |
| 生效/过期  | 留空                   | 仅在事实有明确有效期时填写                         |
| 来源       | `console`              | 高级字段，首次体验保持默认                         |
| 来源可信度 | `1`                    | 高级字段，范围 `0` 到 `1`                          |

自然语言模式适合检查已配置的提取器。若事件成功但没有产生决定或记忆，Console
会明确提示并提供“改用结构化事实”入口；这不是写入成功的充分证据。

提交后 Console 会自动打开 Event Trace，并显示“写入结果”：

- Event 是否已记录
- 接受的 Memory 数量
- 拒绝的候选数量
- 未改变的候选数量
- 是否没有创建或更新 Memory

结果摘要只保留计数、Actor ID 和 Event ID，不保存候选值。可以从摘要直接检查同一
Actor 的 Context、查看该 Actor 的 Memory；没有候选时还可以直接切换到结构化事实。
随后也可以从 `管线 -> 事件` 再次打开该记录。正常情况下状态变为“已完成”，详情会显示：

```text
事件 -> 提取候选 -> 记忆策略 -> create/update/noop/reject -> 当前记忆
```

写入决定的含义：

| 决定     | 含义                                                |
| -------- | --------------------------------------------------- |
| `create` | 新建当前记忆                                        |
| `update` | 更新同一 `(workspace, actor, kind, key)` 的当前版本 |
| `noop`   | 已有状态无需改变                                    |
| `reject` | 候选不满足策略或安全要求                            |

“没有新记忆”不等于程序失败。先在事件详情查看提取结果和决定原因。

### 5. 检查记忆与上下文

界面路径：`记忆 -> 记忆列表`

输入刚才的 Actor ID，确认记忆的类型、键、值、置信度和更新时间。

![MemPlumb 记忆列表：按 Actor 和键值筛选](./assets/customer-manual/02-memory.png)

然后打开：`记忆 -> 上下文检查器`

填写：

| 字段       | 建议值               |
| ---------- | -------------------- |
| Actor ID   | `demo_customer`      |
| 查询       | `客户现在住在哪里？` |
| Token 预算 | `1200`               |
| 候选上限   | `12`                 |

候选上限最大为 `50`。点击“构建上下文运行”。这不是临时搜索，而是一个持久化
Context Run。
成功结果应包含：

- `context_id`
- 使用的 Context Policy
- 被选择和被排除的记忆
- 每条候选的分数和原因
- Token 预算与估算
- 检索后端、降级状态和 Replay State 可用性

如果没有选中 Memory，Console 会区分“没有候选”“候选未通过资格”和“符合资格但
受查询或预算影响未选中”，并提供查看 Actor Memory、写入结构化 Fact 和查看检索
证据的入口。若 Context 已创建但证据详情暂时加载失败，Context ID 和已有结果仍会
保留，可点击“重试获取证据”。

零选择 Context 仍是有效、可审计的 Context Run，但还没有完成首次 Memory 使用闭环。
确认“选中的记忆”大于 `0`，且组装后的 Context 包含刚写入的测试事实后，首次体验才
算成功。

首次体验到这里已经成功。你已经完成：

```mermaid
flowchart LR
  A["测试事件"] --> B["提取候选"]
  B --> C["记忆策略决定"]
  C --> D["当前记忆"]
  D --> E["上下文候选"]
  E --> F["预算内 Context"]
```

## Console 五个工作区

| 工作区 | 主要用户          | 用来完成什么                                        |
| ------ | ----------------- | --------------------------------------------------- |
| 总览   | 所有人            | 查看连接、身份、权限、Runtime、工作区计数和最近事件 |
| 记忆   | AI 应用工程师     | 搜索当前记忆，创建并检查 Context Run                |
| 管线   | 平台/可靠性工程师 | 查看 Event 和 Context Run 的持久化证据与失败阶段    |
| 评估   | 评测/发布工程师   | 管理 Memory Case、Replay Run、Cohort Plan 和新鲜度  |
| 质量   | 评审者/审计者     | 处理队列、争议、写入裁决、审计和评审策略            |

![MemPlumb 管线：事件和上下文运行列表](./assets/customer-manual/03-pipeline.png)

![MemPlumb 评估：Replay Lab、Runs 和 Cohort Plans](./assets/customer-manual/04-evaluation.png)

![MemPlumb 质量：我的工作、队列、争议、裁决与审计](./assets/customer-manual/05-quality.png)

移动端保留相同五个工作区和顺序，详情会使用完整视口：

![MemPlumb 移动端总览](./assets/customer-manual/06-mobile-overview.png)

## 日常工作流一：让 Agent 正确使用记忆

```mermaid
sequenceDiagram
  participant App as 业务应用
  participant MP as MemPlumb
  participant Agent as AI Agent
  App->>MP: 写入 Event/Facts
  MP-->>App: Event + Decisions + Memory revisions
  App->>MP: Context(actor_id, query, budget)
  MP-->>App: Context + selected/excluded evidence
  App->>Agent: 任务 + 受预算约束的 Context
  Agent-->>App: 业务结果
  App->>MP: Feedback/Outcome（可选）
```

操作原则：

1. Actor ID 必须稳定。不要为同一用户每次随机生成新 ID。
2. 优先提交结构化 Facts；自由文本提取的结果必须经过管线检查。
3. 回答前按同一 Actor ID 请求 Context，并提供真实任务 Query。
4. 只把返回的 `context` 交给 Agent，不要自行拼接数据库中的全部记忆。
5. 保留 `context_id`，用于反馈、Outcome、解释和质量复盘。
6. 重试同一次写入时复用同一个 Idempotency Key；新的业务事件使用新 Key。

### TypeScript/JavaScript 最小接入

以下 SDK 示例面向你自行启动或部署的 Runtime。`6060` 是开发命令 `npm run dev`
的默认端口；便携 EXE 会从 `6066` 起动态选择端口，并通过一次性浏览器授权连接，
不要把该浏览器凭据当作业务应用 API Key。生产环境应通过 `MEMPLUMB_BASE_URL` 和
受管 Secret 注入实际地址与密钥。

安装官方 Preview SDK：

```powershell
npm install https://github.com/funnaz/memplumb-releases/releases/download/v0.13.2/memplumb-sdk-0.13.2.tgz
```

```javascript
import { MemPlumbClient } from "@memplumb/sdk";

const memory = new MemPlumbClient({
  baseUrl: process.env.MEMPLUMB_BASE_URL || "http://127.0.0.1:6060",
  apiKey: process.env.MEMPLUMB_API_KEY,
});

const event = await memory.ingest(
  {
    actor_id: "user_123",
    facts: [
      {
        kind: "preference",
        key: "answer_style",
        value: "concise",
        confidence: 0.95,
      },
    ],
  },
  { idempotencyKey: "conversation-42-message-7" },
);

const context = await memory.context({
  actor_id: "user_123",
  query: "How should I answer?",
  budget_tokens: 1200,
});

console.log(context.data.context);
```

API Key 只能放入环境变量或受管 Secret，不得提交到仓库、浏览器代码或客户截图。

### Python 最小接入

```powershell
pip install https://github.com/funnaz/memplumb-releases/releases/download/v0.13.2/memplumb-0.13.2-py3-none-any.whl
```

```python
import os
from memplumb import MemPlumbClient

with MemPlumbClient(
    base_url=os.environ.get("MEMPLUMB_BASE_URL", "http://127.0.0.1:6060"),
    api_key=os.environ["MEMPLUMB_API_KEY"],
) as memory:
    memory.ingest(
        {
            "actor_id": "user_123",
            "facts": [
                {
                    "kind": "preference",
                    "key": "answer_style",
                    "value": "concise",
                    "confidence": 0.95,
                }
            ],
        },
        idempotency_key="conversation-42-message-7",
    )
    context = memory.context(
        actor_id="user_123",
        query="How should I answer?",
        budget_tokens=1200,
    )
    print(context["data"]["context"])
```

生产服务应复用一个 SDK Client，而不是每个请求重新创建连接。

更完整的 OpenAI Agents/LangGraph 挂载点、Outcome 记录、首个 Memory Case
路径和安全边界见[Agent 框架接入方案](./agent-integration.md)。该方案只定义
生命周期接入，不把 MemPlumb 当作 Agent 编排器；适配器失败时仍必须显示真实的
Context/Outcome 状态。注意：`agentTurn(...)` / `agent_turn(...)` 和
`demo-agent` 属于当前 source-only v0.14 迭代线，公开 v0.13.2 SDK/EXE
尚未包含它们；v0.13.2 请按文中的独立 `ingest`、`context`、`recordOutcome`
步骤执行。

如果业务暂时不需要把节点拆进自己的工作流，可直接使用 TypeScript
`agentTurn(...)` 或 Python `agent_turn(...)` helper。它按
`ingest -> context -> agent -> outcome` 执行，使用稳定 `turnId`/`turn_id`
派生两套独立幂等键；Context 失败会抛出带阶段信息的 `AgentTurnError`，不会
把空 Context 当作成功，也不会调用 Agent 回调。

生产环境应使用两个身份：业务 Agent Client 只持有 `memory:read` /
`memory:write`，受管 evaluator Client 持有 `evaluation:write`，并通过
`outcomeRecorder` / `outcome_recorder` 注入 helper。源码中的 `demo-agent`
只在本轮写入的 Memory 被本轮 Context 选中时报告演示成功；其 Outcome 永远是
`unverified`、`demo_only`，不能作为生产质量证据。

## 日常工作流二：调查一次记忆错误

从用户投诉或异常回答开始，按下面顺序调查：

```text
业务请求/Context ID
  -> 管线：Context Run
  -> 候选、选择、排除、分数和预算
  -> 上游 Event 与 Write Decision
  -> 当前/历史 Memory revision
  -> 质量裁决
  -> Memory Case
```

| 看到的问题         | 优先检查                                              |
| ------------------ | ----------------------------------------------------- |
| 应该记住却没记住   | Event 提取候选、Write Decision、策略拒绝原因          |
| 记住了错误内容     | 来源、置信度、当前版本、`create/update` 决定          |
| 有记忆但回答没用到 | Actor ID、Context Query、候选池、排除原因、Token 预算 |
| 用到了过期内容     | `valid_from`、`expires_at`、当前状态和版本            |
| 新策略表现变差     | 保存为 Memory Case，运行 baseline/candidate Replay    |
| 无法解释某次回答   | 确认业务系统保存了 `context_id` 和相关请求 ID         |

支持人员不应要求客户导出整个数据库。优先提供经过脱敏的：

- MemPlumb 版本和 Build ID
- `doctor --json` 结果
- 发生时间和时区
- 工作区名称
- 脱敏后的 Event/Context ID
- 实际状态或稳定错误码
- 复现步骤

禁止发送 `%USERPROFILE%\.memplumb\run\` 下的文件；其中包含可恢复的本地凭据。

## 日常工作流三：把故障变成质量证据

### Retrieval 质量

1. 在管线中打开目标 Context Run。
2. 在质量工作区创建或完成受管 Retrieval 评审。
3. 对候选的精确 Memory revision 标注正例、hard negative 或 ignore。
4. 形成已认证的 canonical adjudication。
5. 在 Context 详情点击“保存为 Memory Case”。
6. 在 `评估 -> Replay Lab` 选择同质 Case，比较候选 Context Policy。

### 写入质量

1. 在 Event 详情定位 Write Decision。
2. 使用 evaluator-bound 的 `evaluation:write` 身份进入
   `质量 -> 写入裁决`。
3. 填写期望动作：`create`、`update`、`noop` 或 `reject`。
4. 保存已认证裁决。
5. 有 `evaluation_execute` 权限时点击“保存为质量案例”。
6. 在 Replay Lab 的“写入质量”模式比较 baseline 和 candidate Memory Policy。

评审者身份来自受管凭据，不能由浏览器请求体伪造。旧裁决不会被覆盖；修改会追加新版本。

## 日常工作流四：验证策略并准备发布

### 小规模研发验证

在 `评估 -> Replay Lab` 中选择不超过 200 个同质 Case：

1. 选择 Retrieval、Write Counterfactual 或 Write Quality 模式。
2. 编辑匹配类型的候选 Policy。
3. 设置对应阈值。
4. 创建持久化 Replay Run。
5. 在 Runs 中查看覆盖率、指标、回归、逐 Case 分类和门禁。

不同范围不能混用指标：

| 范围                 | 可以证明什么                               | 不能证明什么                       |
| -------------------- | ------------------------------------------ | ---------------------------------- |
| Retrieval Replay     | 捕获状态上的候选生成、评分、筛选和预算变化 | 历史物理 HNSW 遍历、提取和写入策略 |
| Write Counterfactual | 候选写入策略是否增加/降低风险              | 没有生产 Oracle 时的准确率         |
| Write Quality        | 对已认证生产 Oracle 的写入动作质量         | 提取、最终状态归并和历史事务调度   |

### 完整生产写入质量

生产推荐路径：

```mermaid
flowchart LR
  A["认证 Write Adjudication"] --> B["memory-case-v6"]
  B --> C["Cohort Plan<br/>服务端选择完整人口"]
  C --> D["持久化分片 Replay"]
  D --> E["汇总门禁"]
  E --> F["新鲜度复查"]
  F --> G["Release Artifact v12"]
  G --> H["Canary / Rollback"]
```

Console 路径：

1. 打开 `评估 -> Cohort Plans`。
2. 输入 rubric 版本、候选 Memory Policy、阈值和分片大小。
3. 创建计划。调用者不能手填 Case ID 或截止时间。
4. 点击“继续执行”，直到所有分片完成。
5. 查看总结果和“发布证据新鲜度”。
6. 发布前点击“刷新新鲜度”。
7. 把 Plan ID 交给受管 CLI/CI 创建 Release Artifact。

新鲜度状态：

| 状态      | 含义                                         | 是否可继续发布          |
| --------- | -------------------------------------------- | ----------------------- |
| `fresh`   | 当前合格 Case 人口未变化，证据仍在年龄限制内 | 仅表示此门禁通过        |
| `stale`   | Case 人口有新增、移除或语义变化              | 否；创建新计划          |
| `blocked` | 无法可靠构造当前合格人口                     | 否；先解决冲突/证据问题 |
| `expired` | 证据超过允许年龄                             | 否；重新建立并执行计划  |

默认最大证据年龄为 7 天，即 `604800` 秒。`fresh` 不能替代其他质量、安全和部署门禁。

发布流水线示例：

```powershell
.\memplumb.exe cohort-plan-check `
  --plan rcp_... `
  --maximum-age-seconds 604800 `
  --json

.\memplumb.exe release-create `
  --policy policies\candidate-memory.json `
  --write-quality-cohort-plan-id rcp_... `
  --write-quality-maximum-evidence-age-seconds 604800 `
  --output release.json
```

Console 不会伪造发布通过，也不在浏览器里生成私钥或签名。

## 身份与权限

Console 以 `GET /v1/session` 返回的最终能力为准，不根据角色名称自行猜权限。

| 能力                  | 允许的工作                      |
| --------------------- | ------------------------------- |
| `memory_write`        | 写入 Event/Memory               |
| `quality_work`        | 领取并提交评审工作              |
| `quality_resolve`     | 解决争议                        |
| `quality_audit`       | 查看受保护审计证据              |
| `evaluation_read`     | 查看 Case、Run 和 Plan 摘要     |
| `evaluation_write`    | 以 evaluator-bound 身份追加裁决 |
| `evaluation_execute`  | 创建 Case、Run 和 Plan          |
| `evaluation_export`   | 查看/导出受保护的完整 Case 内容 |
| `operations_overview` | 查看精确工作区聚合              |

按钮不可见或禁用时，先确认当前身份能力，不要让用户反复刷新或共享管理员密钥。
本地单机身份适合试用；生产应按评审、解决、审计、评估和发布职责分离凭据。

## 数据、隐私和安全

默认 Windows 本地路径：

| 内容          | 路径                                  | 处理要求                         |
| ------------- | ------------------------------------- | -------------------------------- |
| SQLite 数据库 | `%USERPROFILE%\.memplumb\memplumb.db` | 包含业务数据，纳入备份和访问控制 |
| 启动器状态    | `%USERPROFILE%\.memplumb\run\`        | 敏感，绝不上传或作为诊断附件     |
| Runtime 日志  | `%USERPROFILE%\.memplumb\logs\`       | 有界轮转；分享前仍需检查和脱敏   |

默认 SQLite 和本机 Console 不会自动把数据发送到 MemPlumb 云端。只有管理员明确配置
外部模型、Embedding Provider、Webhook、遥测出口、远程 PostgreSQL 或其他集成后，
相关字段才可能离开本机。

### 备份

```powershell
.\memplumb.exe backup-create --output workspace.snapshot.json
.\memplumb.exe backup-verify --file workspace.snapshot.json --json
```

重要环境必须实际做恢复演练。备份可能包含个人数据和质量证据，应加密存储并设置保留期。

### Actor 导出和彻底删除

```powershell
.\memplumb.exe export `
  --actor user_123 `
  --output user_123-export.json

.\memplumb.exe purge `
  --actor user_123 `
  --force `
  --output deletion-receipt.json
```

`purge` 只删除当前 Store 中与 Actor 相连且需要清除的数据。外部备份、以前导出的文件、
对象存储和第三方系统必须由各自的保留策略同步删除。

## 启停和更新

停止本地 Runtime：

```powershell
.\memplumb.exe console-stop
```

停止服务不会删除数据库。不要在任务管理器里按端口猜测并结束进程；启动器会验证实例身份、
进程、工作区、数据库和凭据后，只停止它拥有的 Runtime。

更新版本前：

1. 创建并验证备份。
2. 停止当前 Runtime。
3. 阅读目标版本 Release Notes。
4. 下载新包并重新核对 SHA-256。
5. 保留旧 EXE 作为短期可恢复副本，但不要混用两个版本同时写同一数据库。
6. 启动新版本并运行 `doctor --json` 和 `schema-status --json`。
7. 完成一次测试 Event 和 Context Run 后再恢复真实流量。

## 常见问题

| 现象                    | 原因判断                                      | 处理                                                                |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------- |
| Windows 提示未知发布者  | 当前 Preview 未做 Authenticode 签名           | 只从官方 Release 下载，先核对 SHA-256，再使用“更多信息 -> 仍要运行” |
| 企业电脑没有“仍要运行”  | IT 策略或 Smart App Control 禁止绕过          | 联系 IT 或使用受管部署；不要关闭整机安全控制                        |
| 双击后浏览器没打开      | 默认浏览器启动失败或 Runtime 仍在启动         | 再运行一次 EXE；随后检查 `doctor --json` 和日志                     |
| `6066` 已占用           | 端口被其他程序使用                            | 启动器会自动尝试后续端口，无需结束其他程序                          |
| Console 显示未连接      | 单次 bootstrap 已过期或会话被清除             | 重新通过 EXE 启动 Console，不要分享或手工复制别人的凭据             |
| Event 完成但没有 Memory | 提取无候选，或策略给出 `noop/reject`          | 打开 Event 详情查看提取和决定；研发接入优先提交结构化 Facts         |
| Context 为空            | Actor ID 不一致、记忆失效、策略排除或预算限制 | 检查 Actor、Memory 状态、候选/排除证据和 Context Policy             |
| 没有质量/评估按钮       | 当前身份缺少最终能力                          | 由管理员签发职责匹配的受管凭据                                      |
| Replay 失败             | Case、Policy、阈值或执行错误                  | 查看 Run 的稳定错误、覆盖率和逐 Case 结果，不要只看总分             |
| Plan 是 `stale`         | 当前合格 Case 人口已经变化                    | 建立覆盖当前人口的新 Plan                                           |
| Plan 是 `expired`       | 证据年龄超过限制                              | 重新建立并执行 Plan                                                 |
| SQLite 语义索引不可用   | SQLite 没有生产 ANN 后端                      | 本地使用 portable postings；生产 ANN 配置 PostgreSQL + pgvector     |
| 杀毒软件判定恶意        | 不能仅按 SmartScreen 信誉警告处理             | 停止运行，核对来源/哈希并提交样本分析；不要盲目加入白名单           |

## AI 给客户返回结果的模板

AI 在指导或解释 MemPlumb 时，应使用下面的完整格式：

```markdown
### 当前目标

用一句话说明用户要完成的结果。

### 界面路径

`总览 -> 写入事件 -> 管线 -> 事件详情`

### 可视化流程

输入 -> MemPlumb 处理 -> 可验证结果 -> 下一步

### 操作步骤

1. 明确按钮、字段和值。
2. 说明提交后在哪里查看结果。
3. 给出成功判据。

### 结果判定

| 检查项  | 实际状态           | 含义         |
| ------- | ------------------ | ------------ |
| Runtime | 用户看到的真实状态 | 是否可以继续 |

### 异常处理

仅列与当前状态匹配的分支，不让用户关闭安全控制或发送秘密。

### 下一步

只给一个最合理的后续动作。
```

AI 解释结果时必须区分：

- **观察到的事实**：Runtime 返回的状态、ID、计数、Policy 和错误码。
- **推断**：根据证据提出的可能原因，必须标为“可能”。
- **建议操作**：用户尚未执行的下一步，不能描述为已完成。

## 完成检查表

本地试用完成：

- [ ] 从官方 Release 下载并核对 SHA-256。
- [ ] Console 显示已连接，Runtime 和存储就绪。
- [ ] 测试 Event 完成。
- [ ] 能在管线中解释 Write Decision。
- [ ] 能按同一 Actor ID 找到当前 Memory。
- [ ] 能创建 Context Run 并看到选择/排除证据。
- [ ] 知道如何安全停止 Runtime。

生产接入前完成：

- [ ] 测试、预生产和生产使用不同工作区/数据库/凭据。
- [ ] API Key 只存于 Secret 管理系统。
- [ ] 明确所有外部模型、Embedding、Webhook 和遥测数据出口。
- [ ] PostgreSQL 备份、恢复和迁移流程经过演练。
- [ ] 评审、解决、审计和发布职责已分离。
- [ ] 真实 Memory Case 和 Replay 门禁已建立。
- [ ] 发布证据新鲜度由 CI 再次检查。
- [ ] Windows 面向大众或企业分发前解决可信签名/受管分发问题。

## 深入文档

- [MemoryOps Console](./memoryops-console.md)
- [Windows EXE 分发](./windows-distribution.md)
- [HTTP API](./http-api.md)
- [Python SDK](./python-sdk.md)
- [Memory Case 与 Replay](./memory-case-replay.md)
- [生产写入质量](./memory-write-quality.md)
- [安全边界](./security.md)
- [自托管](./self-hosting.md)
- [灾难恢复](./disaster-recovery.md)