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 对客户的标准回答结构：

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

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

先选正确路径

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/>彻底删除"]

五分钟首次体验

1. 下载并验证

从 MemPlumb v0.13.2 Release 下载 Windows x64 ZIP， 解压后在 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 中运行：

.\memplumb.exe

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

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

3. 确认总览

打开“总览”，确认：

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

4. 写入测试事件

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

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

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

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

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

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

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

写入决定的含义：

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

5. 检查记忆与上下文

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

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

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

填写：

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

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

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

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

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

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

Console 五个工作区

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

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

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：

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

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 最小接入

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

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 框架接入方案。该方案只定义 生命周期接入，不把 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，不能作为生产质量证据。

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

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

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

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

• 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 分类和门禁。

不同范围不能混用指标：

完整生产写入质量

生产推荐路径：

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。

新鲜度状态：

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

发布流水线示例：

.\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 返回的最终能力为准，不根据角色名称自行猜权限。

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

数据、隐私和安全

默认 Windows 本地路径：

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

备份

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

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

Actor 导出和彻底删除

.\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：

.\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 后再恢复真实流量。

常见问题

AI 给客户返回结果的模板

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

### 当前目标

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

### 界面路径

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

### 可视化流程

输入 -> 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
• Windows EXE 分发
• HTTP API
• Python SDK
• Memory Case 与 Replay
• 生产写入质量
• 安全边界
• 自托管
• 灾难恢复