# @eleboucher/opencode-memini 中文文档

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

版本：0\.7\.38
npm 元数据更新时间：2026-10-31T23:35:17.519Z
中文译文更新时间：2026-11-01T02:41:07.093Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：112 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-06-13T18:43:10.109Z
- 最新版本发布：2026-10-31T23:35:17.391Z
- 已发布版本数：98（近 12 个月 98 个）

## 中文简介

自动跨会话存储器的开放代码，通过记忆-回忆之前，每回合，捕获后。

## 安装

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

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

## README

# Memini +开放代码

[opencode](https://opencode.ai/) 支持 [插件](https://opencode.ai/docs/plugins/) -挂入其生命周期的JS/TS模块。Memini附带了一个本地插件 [`plugin/`](https://npmcn.com/package/%40eleboucher/opencode-memini/plugin/) 这使得记忆是自动的：它回忆起相关的记忆 在每个转弯之前和之后捕获完成的转弯，没有工具调用 需要从模型。

## 推荐使用内存插件

它系什么（两个挂钩）：

-   **`chat.message`** -在memini中搜索传入的用户消息和 在回合运行之前将匹配添加为合成上下文部分。它 排除了这个会话自己捕获的回合（已经在实时上下文中），所以 它们不会在记忆中回响；过去的会议仍在回忆。
-   **`event` （`session.idle`）** -一旦会话空闲，存储 完成用户/助手转换回memini（带有会话id标记） 以后可以回忆起来。

### 安装

将包添加到 `plugin` 数组中 `opencode.json` -一个项目 `opencode.json` 将其限定为一个回购，或者 `~/.config/opencode/opencode.json` 对于每个项目：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@eleboucher/opencode-memini"]
}
```

opencode在启动时用Bun从npm安装它。

### Opencode v2 （beta版）

Opencode的v2预览版(`opencode2`)使用不同的插件系统 `plugins` （复数）配置数组和a `Plugin.define({ id, setup })` 模块- v1 `{ id, server }` 合同下不加载。 `@eleboucher/opencode-memini` 导出两者，因此相同的包可以在v1和v2上工作：

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["@eleboucher/opencode-memini"],
}
```

`@eleboucher/opencode-memini-v2` 只提供v2模块：

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["@eleboucher/opencode-memini-v2"],
}
```

空条目解析为 `latest` 分区标签，这就是这个包 出版。 `opencode2 plugin add @eleboucher/opencode-memini-v2` 写 条目，使用您传递给它的任何指定符。

要从签出运行，请使用本地入口点。Opencode不安装 路径加载插件的依赖；这个没有，所以其他的都没有 需要:

```jsonc
{
  "plugins": ["/absolute/path/to/memini/integrations/opencode/plugin/memini-v2.js"],
}
```

对于选项，使用文档化的对象形式：

```jsonc
{
  "plugins": [
    {
      "package": "@eleboucher/opencode-memini-v2",
      "options": { "namespace": "my-project" },
    },
  ],
}
```

下面的选项和嫉妒值也适用。调用注入到请求的 `system` 提示（而不是合成消息部分）。

> **测试状态。** 验证对 `opencode2 v0.0.0-next-16502` 和复核 通过 `v0.0.0-beta-18050`：工作请求钩子为 `context` (文档 叫它 `request`）; 用户/助手的回合是从 `session.inbox.enqueued`， `session.text.ended`, `session.execution.*` 因为这些建筑释放不出 `session.idle` 并且不公开会话消息列表 方法。 `next-17444` 重命名的第一个事件 `session.input.admitted` 和 将文本从 `input.data` 来 `item.payload`;这个插件同时读取 形状，并注册两个钩子名称，因此它与 记录了拼写。

v2插件通过结构化控件发送诊断信息 `ctx.app.log` 记录器当 可用。日志记录是尽最大努力完成的，当日志记录器不在时保持沉默 或不可用。

### 配置

参数内联传递选项 `[name, options]` 形式:

```json
{
  "plugin": [["@eleboucher/opencode-memini", { "namespace": "my-project", "recall_limit": 8 }]]
}
```

| 选项 | Env var | 默认的 | 目的 |
| --- | --- | --- | --- |
| `base_url` | `MEMINI_BASE_URL` | `http://localhost:8080` | memini REST基础URL |
| `namespace` | `MEMINI_NAMESPACE` | 服务器的握手 | 项目内存的作用域为(`X-Memini-Namespace`） |
| `home` | `MEMINI_HOME` | 设置 | 呼叫者的个人名称空间，发送为 `X-Memini-Home`;未设置=没有主腿 |
| `recall` | `MEMINI_RECALL` | 在 | `false` 禁用recall-before-turn |
| `capture` | `MEMINI_CAPTURE` | 在 | `false` 禁用capture-after-turn |
| `capture_child_sessions` | `MEMINI_CAPTURE_CHILD_SESSIONS` | 从 | 捕获子会话；Off跳过子代和未知祖先（失败关闭），on记录祖先元数据 |
| `recall_limit` | `MEMINI_RECALL_LIMIT` | `3` | 最大的记忆注入每回合 |
| `recall_max_tokens` | `MEMINI_INJECT_RECALL_MAX_TOK` | `0` | 召回块令牌的硬性上限(`0` =无界);尾巴垂下来 `[… N item(s) truncated by token budget]` 页脚 |
| `recall_min_score` | `MEMINI_INJECT_RECALL_MIN_SCORE` | 服务器默认 `0.5` （`0` pre-handshake) | 复合层（>=）对最终排名得分，发送为 `min_rank_score` (服务器强制；剥离+应用于客户端pre-`min_rank_score` 服务器，且值≥1) |
| `inject_cooldown_ms` | `MEMINI_INJECT_COOLDOWN_MS` | `1800000` | repeat-injection冷却时间, **时间** 窗口（ms）：一个已经注入的内存在它可以重新服务之前被保留了这么长时间； `0` 禁用时间维度 |
| `inject_cooldown_prompts` | `MEMINI_INJECT_COOLDOWN_PROMPTS` | `3` | repeat-injection冷却时间, **提示** 窗口（每个用户消息计数）； `0` 禁用提示维度；两个冷却旋钮 `0` =整个会话的suppress |
| `recall_budget_ms` | `MEMINI_RECALL_BUDGET_MS` | `2000` | 一个回合需要等待多长时间才能被召回(`0` =等待满 `timeout_ms`） |
| `timeout_ms` | `MEMINI_TIMEOUT_MS` | `30000` | memini请求的每个请求超时 |
| `fallback_on_error` | `MEMINI_FALLBACK` | 在 | `false` 显示错误，而不是默默地降级 |
| `auto_update` | `MEMINI_AUTO_UPDATE` | 在 | `false` 禁用NPM自动更新检查（否则opencode永远不会重新获取缓存的插件） |
| \- - - - - - | `MEMINI_INJECT_LABELS` | \- - - - - - | 每个项目符号的逗号分隔标签切换： `tier`， `confidence`， `age`， `reason` |
| \- - - - - - | `MEMINI_API_KEY` | \- - - - - - | 承载令牌，如果memini需要认证（仅限env - secret） |
| \- - - - - - | `MEMINI_REQUIRE_HTTPS` | \- - - - - - | `1` 拒绝通过明文HTTP发送令牌 |

opencode等待 `chat.message` 在模型看到消息之前，所以一个缓慢的或 否则无法到达的记忆会冻结整个转弯 `timeout_ms`. 相反，回忆比赛 `recall_budget_ms`如果搜索没有及时得到回应， 在没有记忆的情况下继续前进，最终的结果被丢弃。错误 从后台请求仍然被记录。这个插件也可以ping `/healthz` 一旦启动要预热连接，那么第一次召回就不支付了 DNS / TLS本身。集 `recall_budget_ms: 0` 恢复完全阻塞 same-turn注入。

自动捕获将层选择留给服务器。在检索 消息，插件解析会话祖先。捕获根会话 违约;子会话和其祖先无法解析的会话为 默认跳过。集 `capture_child_sessions` (或 `MEMINI_CAPTURE_CHILD_SESSIONS=1`)选择加入；捕获包括 `metadata.session_type` （`root`， `child`，或者 `unknown`)和儿童捕获 包括 `metadata.parent_session_id`.

### Repeat-injection冷却时间

这两个 `inject_cooldown_*` 旋钮是窗户 **repeat-injection 冷却时间** （与Claude Code / hermes / openclaw集成共享） 已经注入的内存被排除在召回之外（通过服务器端） `exclude_ids`（与客户端支持），而它是在内部 _要么_ 窗口 -时间窗口(`inject_cooldown_ms`)或提示窗口 （`inject_cooldown_prompts`，一个提示=一条用户消息；在v2插件中， 一个 `request`\-钩子火)-是 **一旦两者都失效，就保留**． 一个 内容被就地更新的内存会立即重新注入 内容哈希绕过)，因此永远不会为窗口保留更正。

> **行为改变（原来是：永远压抑）。** 早期的版本抑制了 为整个会话注入内存。使用默认的窗口（30分钟/小时） 3提示)一个长会话是现在 **re-reminded** 仍然相关的记忆 一旦足够多的谈话已经过去了。把两个旋钮都调到 `0` 来 恢复原来的suppress-for-the-whole-session行为。

内联选项战胜了羡慕者。秘密留在环境中：设置 `MEMINI_API_KEY` (发送 `Authorization: Bearer …`)，以及可选的 `MEMINI_REQUIRE_HTTPS=1` 在启动的shell中拒绝明文HTTP 开放代码-不在 `opencode.json`.

每个选项都是可选的， `namespace` 包括: `["@eleboucher/opencode-memini"]` 运行时没有配置。在插件加载（和再次每10分钟之后）， 插件调用 `POST /v1/handshake` 用它所不知道的东西 项目(git远程/顶层，当工作树是一个repo时，加上 工作树（basename），并让服务器解析名称空间和行为 设置(`recall`， `capture`， `recall_limit`，召回注入预算) 和其他memini客户端一样。呼叫是故障软：any 错误或~2.5s超时返回到纯粹的局部解析下面，所以一个 遥不可及或更老的记忆永远不会打破一个回合。

### 名称空间解析

In full， In order：按顺序 `namespace` 选项/ `MEMINI_NAMESPACE` >的 服务器的握手解析命名空间> git工作树basename > 内置默认值(`opencode`）。

选项/嫉妒层直接且有意地胜过握手 `namespace` 选项。 `~/.config/opencode/opencode.json`，或者 全球出口 `MEMINI_NAMESPACE`，是这个积分本身的显式pin 并以此为荣，而不是被服务器猜测。缺席 要么是服务器的解析（可以在大头针上绘制），要么是git远程 一个操作符的每键默认值)胜过这个插件自己的git 工作树/默认回退，这只适用于握手本身 不可用。

每个召回/捕获设置遵循相同的形状：插件选项节拍 `MEMINI_NAMESPACE`上面的兄弟嫉妒器打败了服务器的解决方案 `ClientSettings` 比内置默认的插件要好。

### 这个 `memini_status` 工具

插件注册一个工具， `memini_status`：只读，无参数。它 报告生效的命名空间及其来源(命名空间选项， `MEMINI_NAMESPACE`（服务器的握手，或者git工作树的回退）， 如果没有env/option引脚，连接设置(the API密钥指纹化（从未打印），以及警告—全局 `MEMINI_NAMESPACE` pin，穿越明文HTTP的承载令牌。

没有 `/memini:status` 斜杠命令：opencode的插件契约寄存器 工具，而不是命令，并且这个插件不会发明它没有的API。

### 测试

```bash
cd integrations/opencode/plugin && node --test
```

## 可选：手动MCP线（工具，非自动）

而不是插件，你可以暴露memini的 `memory_*` 工具的模型和 让它随叫随到吧。opencode读取MCP服务器 `opencode.json` 下 `mcp`。这条线为模型提供了完整的工具集，包括 `memory_recall` (与 `tags` / `metadata` 过滤器), `memory_list` (无查询浏览按层/ 标签/元数据类别)，以及 `memory_remember`． 集 `metadata.category` 在 稍后按主题写入以浏览-请参阅 `docs/categories.md`.

**远程:** 合并 [`opencode.json`](https://npmcn.com/package/%40eleboucher/opencode-memini/opencode.json) 到你的配置中。

**本地(头):** 看到 [`opencode.local.json`](https://npmcn.com/package/%40eleboucher/opencode-memini/opencode.local.json) ——opencode 产生 `memini mcp`.

注意上下文预算：memini添加了一些工具，这是轻量级的，但是 禁用其他未使用的大型MCP服务器。使用相同的 `X-Memini-Namespace` 和你的其他特工共享记忆。 `my-project` 是一个 占位符-将其替换为您的实际项目名称，或删除标题并让 Memini从自己的工作目录自动解析。

## 常见问题

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

自动跨会话存储器的开放代码，通过记忆-回忆之前，每回合，捕获后。

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

在项目目录运行 npm install @eleboucher/opencode-memini，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

@eleboucher/opencode-memini 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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