# @eleboucher/pi-memini 中文文档

规范地址：https://npmcn.com/package/%40eleboucher/pi-memini/

版本：0\.7\.38
npm 元数据更新时间：2026-10-31T23:36:59.749Z
中文译文更新时间：2026-11-01T01:57:09.761Z
软件包许可：未声明

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eleboucher/pi-memini
原文对照：https://npmcn.com/package/%40eleboucher/pi-memini/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：114 kB，3 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.22\.1
- 运行依赖：0 个
- peer 依赖：typebox \*，@earendil-works/pi-tui \*，@earendil-works/pi-coding-agent \*
- 首次发布：2026-06-28T16:09:03.601Z
- 最新版本发布：2026-10-31T23:36:59.606Z
- 已发布版本数：61（近 12 个月 61 个）

## 中文简介

Pi编码代理的共享跨会话内存，由memini服务提供支持。

## 安装

```sh
npm install @eleboucher/pi-memini
```

也可以使用：`pnpm add @eleboucher/pi-memini`、`yarn add @eleboucher/pi-memini`、`bun add @eleboucher/pi-memini`

## README

# memini + Pi

[π](https://pi.dev/) 一个开源的编码代理是一流的吗 [扩展API](https://pi.dev/docs/latest/extensions)． Pi没有内置MCP 因此，memini提供了一个本地Pi包 [`plugin/`](https://npmcn.com/package/%40eleboucher/pi-memini/plugin/)． 它增加了 自动会话内存，本机 `memory_*` 工具、生命周期持久性，以及 没有MCP适配器的紧凑转录呈现。

## 安装

包发布为 [`@eleboucher/pi-memini`](https://www.npmjs.com/package/@eleboucher/pi-memini) 并且要求Pi 0.0.8或更新（Node.js 22.19或更新）：

```sh
pi install npm:@eleboucher/pi-memini
```

使用 `-l` 用于项目本地安装。Pi将全局包记录在 `~/.pi/agent/settings.json` 和项目包 `.pi/settings.json`. 等效手动配置为：

```json
{
  "packages": ["npm:@eleboucher/pi-memini"]
}
```

项目本地包仅在项目受信任后加载。运行 `pi config` 启用或禁用已安装的资源。

对于开发，一次运行加载构建的扩展：

```sh
npm --prefix integrations/pi/plugin run build
pi -e ./integrations/pi/plugin/dist/index.js
```

Pi还可以自动发现放置的源扩展 `~/.pi/agent/extensions/` 或者 `.pi/extensions/`;这些地点可以是 hot-reloaded与 `/reload`.

## 扩展的作用是什么

### 自动记忆和生命周期

-   **`session_start` / `session_tree`** 重建分支局部抑制和 捕获状态，然后在活动模型时注入一个有界分层简报 上下文还没有包含它。启动、恢复、fork和重新加载则不行 复制一份完整的简报。
-   **`before_agent_start`** 搜索提交的提示并注入有用的内容 匹配为不受信任的只读上下文。空白文本、命令形提示、 少于12个字符的引导文本会被跳过；搜索查询包括 上限为2000个字符。
-   **`agent_settled`** 仅捕获最终成功的用户/助手回合 重试后，溢出压缩和排队延续已经解决。 同一辅助条目的重复已确定事件是幂等的。
-   **`session_before_compact` / `session_compact`** 可选检查点边界 状态更改活动，清除上下文耦合抑制，并排队刷新 在不开始额外回合的情况下进行简报。
-   **`session_shutdown`** 可选地记录有界活动摘要 关闭/开关/叉事件。因为会话仍在继续，所以跳过重新加载。
-   **Branch-aware dedupe** 仅在匹配之后才在Pi自定义项中保留 召回/工具结果消息已完成。自动简报和即时召回； 加上明确的回忆/简报/列表/获取/历史/回答结果，共享一个冷却时间 状态;成功的更新、删除和ID更新会使更正后的内容立即生效， 即使同级工具同时完成。 集 `MEMINI_INJECT_DEDUPE=0` 禁用排除、过滤和记录 在一起。

来自的服务器授权名称空间 `POST /v1/handshake` 范围自动 明确的要求 `X-Memini-Namespace`． 自动生命周期工作 权限不可用时无操作；显式工具会重试一次握手 然后返回一个可操作的错误，而不是请求本地猜测的分区。 兼容性重试掉落 `exclude_ids` 只有在服务器明确拒绝之后 该字段与HTTP 400；超时、节流和不相关的故障不会禁用它。

### 本机工具

Pi直接注册这些工具 `pi.registerTool`：

| 工具 | 目的 |
| --- | --- |
| `memory_briefing` | 阅读固定的上下文、持久事实、过程、最近的工作和嵌套项目汇总。 |
| `memory_recall` | 混合语义/关键字召回与过滤器，时间旅行，范围，排除，和来源。 |
| `memory_list` | 浏览和页面最新的第一记忆没有搜索查询。 |
| `memory_remember` | 存储或撤销原子内存，包括有效性、置信度、元数据和可见性。 |
| `memory_get` | 获取一个完整的内存DTO。 |
| `memory_history` | 先读取记忆的替换历史。 |
| `memory_update` | 部分正确的内容、摘要、层次、级别、标签、元数据、重要性或置信度。 |
| `memory_forget` | 永久删除内存。 |

`memory_answer` 仅在经过身份验证后才动态添加 `GET /healthz?verbose=1` 返回布尔字面值。 `deps.llm.configured: true`． 失踪，畸形，虚假，无法到达，或 未路由能力的证据使该工具未被宣传。

rest支持的回答工具有意省略了MCP `reasoning_level` 因为 当前的 `/v1/answer` REST请求不接受它。REST简报 不公开服务的截断子数，因此Pi保留每个截断子数 返回的孩子卷起但不捏造 `children_note`.

读取结果包括名称空间/来源证据。无论是继承的还是个人的 回忆，复制回来 `namespace` 逐字输入get/history/update/forget； 不要发明命名空间路径。写选择语义 `visibility` 代替。

### 紧凑的呈现

所有显式工具都在发送的工具结果中保留完整的结构化JSON 到模型并存储在会话中。他们的TUI渲染器显示了简洁 折叠时的单行，使用Pi的工具扩展键(`Ctrl+O` 由 默认)，一个有界的人类可读视图，最多有8个内存/源项 再加上特定类型的答案、确认、合并和子rollup详细信息。

自动简报和召回消息同样保持持久模型 上下文，而已注册的消息呈现器将正常的文本保存为一个 线。呈现永远不会截断或重写面向模型的有效负载。

## 配置

扩展有两个配置层：

1.  **交通和身份** 来自Pi过程的环境。
2.  **行为设置** 解决, **环境覆盖→握手服务器 设置→内置默认**． 这允许一个服务器设置团队默认值，而一个 本地环境可以覆盖特定的旋钮。

### 交通与身份环境

| 环境变量 | 默认的 | 效果 |
| --- | --- | --- |
| `MEMINI_BASE_URL` | `http://localhost:8080` | memini REST基础URL。 |
| `MEMINI_API_KEY` | 设置 | 不记名令牌。 |
| `MEMINI_REQUIRE_HTTPS` | 从 | 设置为 `1` 在非环回明文HTTP上拒绝承载令牌。 |
| `MEMINI_HOME` | 设置 | 个人名称空间发送为 `X-Memini-Home`;未设置意味着没有个人阅读腿。 |
| `MEMINI_NAMESPACE` | 设置 | 声明的名称空间事实和脱机的机器本地回退；服务器引脚仍然获胜。 |
| `MEMINI_NAMESPACE_PREFIX` | 设置 | 前缀仅应用于派生名称空间、联机和降级回退。 |
| `MEMINI_AGENT` | 设置 | 可选的每个代理命名空间后缀事实。 |
| `MEMINI_TIMEOUT_MS` | `30000` | 每个请求超时（以毫秒为单位）。 |
| `MEMINI_FALLBACK` | 在 | `0`/`false` 使自动生命周期传输故障浮出水面，而不是降级到警告/无操作。 |

初始握手发送git远程、存储库根、cwd basename和 认同上述事实。服务器解析pin和其他服务器端策略 返回权威命名空间。结果要记住十分钟； 设置或清除引脚会立即使其失效。如果握手是 不可达时，Pi仅为诊断而派生一个命名空间，并将其标记为降级； 自动内存流量暂停和显式工具拒绝路由直到服务器 权威得到恢复。

### Pi使用的行为设置

| 环境覆盖 | 内置的默认 | 效果 |
| --- | --- | --- |
| `MEMINI_RECALL` | 在 | 自动提示召回。 |
| `MEMINI_CAPTURE` | 在 | Settled-turn捕捉。 |
| `MEMINI_RECALL_LIMIT` | `3` | 最大自动召回命中。 |
| `MEMINI_INJECT_RECALL_MAX_TOK` | `250` | 召回注入令牌上限； `0` 是无限的。 |
| `MEMINI_INJECT_RECALL_MIN_SCORE` | `0.5` | 最低自动召回分数（综合后秩量表）； `0` 禁用地板。 |
| `MEMINI_INJECT_DEDUPE` | 在 | 共享的跨表面抑制状态。 |
| `MEMINI_INJECT_COOLDOWN_MS` | `1800000` | 重复注射时间冷却； `0` 禁用此维度。 |
| `MEMINI_INJECT_COOLDOWN_PROMPTS` | `3` | 提示冷却时间; `0` 禁用此维度。两个冷却时间都在 `0` 对会话进行抑制。 |
| `MEMINI_INJECT_LABELS` | 空 | 逗号/管道分隔的自动项目符号标签： `tier`， `confidence`， `age`. |
| `MEMINI_INJECT_BRIEFING_PINNED` | `5` | 启动固定内存帽。 |
| `MEMINI_INJECT_BRIEFING_FACTS` | `5` | 启动持久事实上限。 |
| `MEMINI_INJECT_BRIEFING_PROCEDURES` | `5` | 启动过程上限。 |
| `MEMINI_INJECT_BRIEFING_RECENT` | `3` | 启动最近内存上限。 |
| `MEMINI_INJECT_BRIEFING_MAX_TOK` | `600` | 整个简报令牌上限； `0` 是无限的。 |
| `MEMINI_SESSION_DIGEST` | 在 | 预压缩和关闭活动检查点。 |
| `MEMINI_MIN_CAPTURE_CHARS` | `0` | 捕获所需的最小用户文本长度。 |
| `MEMINI_CAPTURE_USER_MAX_CHARS` | `1000` | 每回合捕获的用户文本上限； `0` 是无限的。 |
| `MEMINI_CAPTURE_ASSISTANT_MAX_CHARS` | `3000` | 每回合捕获的辅助文本上限； `0` 是无限的。 |

已经注入的内存在 **要么** 配置 冷却时间仍然有效，只有在两次失效后才能恢复。显式读取工具 使用保守抑制，直到一个修正清除陈旧的条目。

## 削减命令

键入带有前导的命令 `/` 在Pi的编辑器中：

| 命令 | 效果 |
| --- | --- |
| `/memini:status` | 显示有效的设置和来源、解析的名称空间、连接状态、读取集、编校验证和警告。 |
| `/memini:namespace` | 显示当前服务器解析的名称空间和引脚来源。 |
| `/memini:namespace <namespace>` | 设置此项目的服务器端名称空间引脚。 |
| `/memini:namespace --clear` | 清除服务器端引脚并返回到自动解析。 |

命令诊断保存为仅限gui的自定义条目，并且永远不会输入 模型上下文，包括服务器授权的pin注释和读集标签。

pin由memini服务器(`PUT`/`DELETE /v1/pins`)，并由 项目的git远程和/或存储库根目录。他们全程跟进这个项目 机器和节拍 `MEMINI_NAMESPACE` 故意。Pin写入需要 访问服务器; `MEMINI_NAMESPACE` 保持离线本地覆盖。

## 构建和验证

从包目录：

```sh
cd integrations/pi/plugin
npm ci
npm test
```

`npm test` 标准验证路径。它对源代码和测试进行类型检查 在圆周率0.0.80.6时，构建 `dist/index.js`，运行bundle和helper/lifecycle/tool 契约测试、打包发布构件，并将其安装到干净的 并且只使用pi提供的对等模块导入已安装的ESM。

有用的集中命令：

```sh
npm run typecheck
npm run build
npm run test:unit
npm run test:package
npm pack --dry-run
```

包的 `prepack` 钩子直接重复类型检查和构建 `npm pack` 或者发布不能发布陈旧的源代码。 `@memini/client` 被捆绑在 单个扩展文件； `typebox`， `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui` 按照Pi包的要求保留主机提供的对等节点。

来自存储库根的相关交叉集成奇偶校验如下：

```sh
pnpm --filter @memini/client test
node --test plugin/scripts/_test.mjs
```

## 可选：MCP线

圆周率可以达到memini `memory_*` 然后通过第三方MCP扩展 连接到 `http://<host>:8080/mcp` 或者 `memini mcp` (它的)。本机包 以上是首选，因为它还提供自动召回/捕获，生命周期 状态、能力门控和紧凑呈现。

## 常见问题

### @eleboucher/pi-memini 是什么？

Pi编码代理的共享跨会话内存，由memini服务提供支持。

### 如何安装 @eleboucher/pi-memini？

在项目目录运行 npm install @eleboucher/pi-memini，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typebox（\*）、@earendil-works/pi-tui（\*）、@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @eleboucher/pi-memini 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/eleboucher\_\_pi-memini 是否存在。

### @eleboucher/pi-memini 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @eleboucher/pi-memini 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.22\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eleboucher/pi-memini 可以商用吗？

@eleboucher/pi-memini 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @eleboucher/pi-memini 还在维护吗？

最新版本 0\.7\.38 发布于 2026/11/01（2 天前）；至今共发布 61 个版本，其中过去 12 个月发布了 61 个；首次发布于 2026/06/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。