# @cloudfrog/memory 中文文档

规范地址：https://npmcn.com/package/%40cloudfrog/memory/

版本：1\.7\.2
npm 元数据更新时间：2026-10-17T03:08:25.384Z
中文译文更新时间：2026-11-10T05:12:51.893Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudfrog/memory
原文对照：https://npmcn.com/package/%40cloudfrog/memory/?lang=original
项目主页：https://github.com/HoracioEspinosa/memory
源码仓库：https://github.com/HoracioEspinosa/memory

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

- 包体积（解压后）：735 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：pi-mcp-adapter \>=2\.5\.0，@earendil-works/pi-coding-agent \*
- 首次发布：2026-09-09T17:31:56.629Z
- 最新版本发布：2026-10-17T03:08:25.213Z
- 近 30 天下载量：2059（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

记忆:AI编码代理的持续记忆——一种本地第一的SQLite大脑,可选地复制到云中,它能活过会话和收缩并被共享于MCP上. 这个包把它插入了Pi.

## 安装

```sh
npm install @cloudfrog/memory
```

也可以使用：`pnpm add @cloudfrog/memory`、`yarn add @cloudfrog/memory`、`bun add @cloudfrog/memory`

## README

# Pi 的内存

[![npm](https://img.shields.io/npm/v/@cloudfrog/memory?color=blue)](https://www.npmjs.com/package/@cloudfrog/memory)

**给每个Pi会话一个相同的大脑——默认是局部的,需要时会有云,可以跨出代理搜索.**

皮很擅长在前面做活 问题在于工作周围的一切:代理昨天学到了什么,什么架构决定被接受,为什么一个错误被固定在一定的方式,用户喜欢什么,当上下文窗口收缩时应该有什么活下来.

内存是AI编码代理的持续内存. `@cloudfrog/memory` 将 Pi 连接到内存中, 这样您的代理可以保存一个会话的有用部分, 稍后再取回来 —— 不将原始工具输出输入到提示中 .

## 看着

| 你想这样 | 记忆赋予了皮 |
| --- | --- |
| 重复解释减少 | 可搜索往届会议的记忆 |
| 上下文废物减少 | 解禁保存而非原始工具调用垃圾堆 |
| 压缩后的连续性 | 所需会议摘要和回收协议 |
| 一个跨工具的内存 | 为 Pi 和其他代理共享 MCP 支持的内存 |
| 团队/项目内存 | 可选记忆云复制和仪表板 |

## 承诺

安装一次。 继续编码 皮记起.

-   **一个大脑给很多特工** ——Pi Claude Code,OpenCode,双子座CLI,Codex,VS Code/Copilot,Cursor,Windsurf,Antigravity,以及任何MCP相容的代理可以读取/写入相同的内存.
-   **本地第一记忆** ——一首"去"二进制单曲在你的机器上给SQLite + FTS5写作. 节点服务, Python 堆栈, 或核心路径所需的主机账户 .
-   **队伍需要时会云** ——"记忆云"在保留本地SQLite权威的同时,还增加了选入,项目范围复制,共享访问,以及浏览器仪表板.
-   **按设计效率计** ——"记忆"存储了被整理的概要,决定,提示,和会话交接等内容,而不是一个吵闹的原始工具调用. 特工先搜索,然后只取出相关的内存.
-   **接合生存** ——在上下文重排之前,"记忆协议"将摘要推入"记忆",以便下个会话能够恢复重要内容.
-   **简单 Pi 设置** ——安装Pi软件包,安装MCP适配器,运行 `pi-memory init`,重新启动 Pi.
-   **由"云蛙"兴建** ——"记忆"是从一个围绕真实工具而不是玩具演示而构建的亲手代理编码工作流程中成长而来.

## 为什么这与“更多背景”不同

上下文窗口为临时窗口 。 记忆就是记忆.

| 更多背景 | 内存 |
| --- | --- |
| 当前运行期间的帮助 | 跨会话、代理、机器和紧凑器 |
| 通常包括原始日志/工具输出 | 储存可搜索的知识 |
| 被总结掉 | SQLite + FTS5 中的持久性 |
| 通常绑在一个特工身上 | 通过MCP进行跨代理客户的工作 |

记忆并不试图让模型读出一切. 它给予模型一个有纪律的内存协议:保存重要知识,重复工作前进行搜索,只有在需要时才能获取全部细节.

## 看到记忆

![The Memory terminal workspace on its Home tab: a project card counting observations, open tasks, evidence and runbooks, above a list of recent tasks and the latest evidence files](https://cdn.jsdelivr.net/npm/@cloudfrog/memory@1.7.2/assets/tui-home.png) ![The project switcher open over the workspace, listing every project with its observation, open-task and evidence counts](https://cdn.jsdelivr.net/npm/@cloudfrog/memory@1.7.2/assets/tui-projects.png)

运行 `memory tui` 用于会话、观测、提示、项目、时间表和搜索结果的终端工作空间。 内存云为共享项目内存增加了浏览器能见度.

## 快开始

```bash
pi install npm:@cloudfrog/memory
pi install npm:pi-mcp-adapter
pi-memory init
```

安装后重新启动 Pi, 然后问 Pi 记得当前工程或调用什么 `mem_context`。 。 。 .

## 安装什么

`@cloudfrog/memory` 通过两个互补路径将 Pi 连接到内存 :

| 路径 | 目的 |
| --- | --- |
| Pi 扩展 | 抓取提示/会话事件,注入记忆协议,并曝光紧凑的 Pi-native `mem_*` 工具通过内存 HTTP 服务器. |
| MCP工具 | 保持内存的 MCP 表面通过 `pi-mcp-adapter` 直接使用 MCP 的客户和流量. |

```text
Pi events/tools -> @cloudfrog/memory extension -> MEMORY_URL / memory serve -> SQLite
Pi MCP tools   -> pi-mcp-adapter -> MEMORY_BIN / memory mcp -> SQLite
```

Pi-native紧凑工具使用与事件捕获相同的HTTP服务器路径,包括项目检测,诊断,被动捕获,生命周期审查,以及冲突判断工具等 `mem_current_project`, (中文(简体) ), `mem_doctor`, (中文(简体) ), `mem_capture_passive`, (中文(简体) ), `mem_review`, (中文(简体) ), `mem_judge`,以及 `mem_compare`. MCP 工具仍然是单独的 stdio 路径,因此,即使当 `MEMORY_URL` 在远程的 HTTP 服务器上点。 默认情况下, Pi 不启用内存 MCP 直接工具以避免重复原始 `memory_mem_*` 工具行.

## 压缩内存工具渲染

`@cloudfrog/memory` 通过注册紧凑的 Pi- 内存工具拥有 Pi 染色体 `mem_*` 工具在配套软件包中。 当工具如 `mem_search`, (中文(简体) ), `mem_context`, (中文(简体) ), `mem_save`, (中文(简体) ), `mem_session_summary`, (中文(简体) ), `mem_get_observation`, (中文(简体) ), `mem_review`, (中文(简体) ), `mem_judge`,以及 `mem_doctor` 在 Pi 中运行,默认已崩溃的视图将保持紧凑 :

```text
🧠 search “auth model” …
↳ ✓ 4 results
```

关于生命周期审查, `mem_review` 在不暴露原始工具有效载荷的情况下,保持倒闭输出清晰:

```text
🧠 review list “memory” limit 10 …
↳ ✓ 3 need review

🧠 review mark_reviewed #42 …
↳ ✓ reviewed #42
```

`action=list` 显示本地 `review_after` 时间戳到期. `action=mark_reviewed` 要求内存核心根据其内存类型重置该观测的本地审查时钟. 该审查的重置目前仅是局部的:它更新了本地的生命周期元数据,但在同步电线格式带有生命周期审查字段之前,它不被视为云/git同步突变.

普通内存活动也以短进度/结果文本更新状态栏, 如 `🧠 memory · search…` 财务报告和审定财务报表 `🧠 memory · ✓ 4 results`。扩展名不为正常内存操作使用通知.

当一个工具调用失败, 因为内存无法确定要使用哪个工程时, 状态栏会显示一个可操作的标签而不是通用的标签 `error`数字 :

| 状态栏标签 | 含义 |
| --- | --- |
| `🧠 repos · ambiguous project` | Pi是从包含多个 git repos 的目录开始的. 运行 Pi 从单回波内部运行, 或者添加 `.memory/config.json` 与 `project_name` 转到父目录. |
| `🧠 repos · error` | 发生了不同的工具或网络出错 。 为完整错误消息扩展 Pi 中的工具输出 . |

通过扩展 Pi 中的工具输出,完整工具细节仍然可用。如果 `@cloudfrog/memory` 或内存服务器没有安装/运行,紧凑工具报告错误而非内存可用.

## 小皮能记得的

-   结构决定和权衡
-   错误修正、 根源和错误
-   用户偏好和项目公约
-   会议目标、下一步步骤和交接摘要
-   快速上下文与有意义的已保存的观察绑定
-   一旦一个项目注册入"记忆云",则跨机/团队内存

## 私有块

`@cloudfrog/memory` 在向内存发送已捕获的提示、被动观察或压缩摘要之前, 编辑明确的私有块 :

```text
<private>
this should not be persisted verbatim
</private>
```

持续有效载荷保留了周围的文本,但以 `[REDACTED]`。Redaction 被递归应用到向外的 JSON 有效载荷中的字符串值和向内存 HTTP 请求中的查询值。 自动快速捕捉编辑器在将一个提示切换到2000个字符之前,所以一个横跨极限的块不能丢失其关闭标记并漏出.

这是一个轻量级的便利公约,而不是一个完整的秘密扫描系统。 不要依赖它自动检测证书.

## 收缩复原

当Pi释放出压缩寿命周期事件时, `@cloudfrog/memory` 从支持的事件字段提取压缩摘要并将其保存为 `session_summary` 带有主题密钥的观察 `session/compaction-recovery`。 。 。 .

不支持的事件形状优雅地失败. 该扩展仍会注入手动回收指令,其中包含 `FIRST ACTION REQUIRED`,所以下一个代理回合可以呼叫 `mem_session_summary` 如果内存 MCP 工具已安装并激活。 如果工具无法使用, 在内存再次可用后手动保存压缩摘要 .

## 本地、同步或云

记忆可以随工作流程而增长:

| 模式 | 用它当 |
| --- | --- |
| 本地 SQLite | 你想用一台机器快速的私人记忆. |
| Git 同步 | 您想要没有主机服务的便携式压缩内存块 . |
| 记忆云 | 您想要共享项目内存,浏览器的能见度,以及跨机器/代理复制. |

Cloud是选入和项目范围。 本地 SQLite 仍然是真理的来源;云复制并让内存在明确注册一个项目时可见.

## 所需资源

-   Npm 软件包支持的 Pi 编码代理 .
-   内存已安装为 `memory` 打开 `PATH`,或 `MEMORY_BIN` 指向二进制.
-   `pi-mcp-adapter` 只有您想要兼容/调试的可选 MCP 网关; Pi- 本地 `mem_*` 工具来自 `@cloudfrog/memory`。 。 。 .

如果您只想要针对已运行的内存服务器的 HTTP 会话抓取, 设置 `MEMORY_URL` 而扩展将不会自动启动本地 `memory serve` 进程.

## 配置

### 已存在的内存服务器

使用已运行的内存 HTTP 服务器 :

```bash
MEMORY_URL=http://127.0.0.1:6366 pi
```

何时 `MEMORY_URL` 设置,扩展将服务器视为外部管理,不自动启动 `memory serve`。没有它,扩展用途 `http://127.0.0.1:${MEMORY_PORT:-6366}`; 1.1.0 之前的版本默认为 7437,以及 `MEMORY_PORT=7437` 保持端口.

启动时进行扩展检查 `/health` 报告 `"service":"memory"`当没有答案时(和 `MEMORY_URL` 是未设置) 它开始 `memory serve <MEMORY_PORT>`;当另一个服务解答时,它发送的服务一无所有,甚至不发送工作目录,内存工具报告问题直到Pi重启.

每个请求都携带 `X-Memory-Client: pi/<package version>`,这是服务器的破坏性路径(`mem_delete` 他们中有需要的,并且派遣尸体作为JSON。 节点的 `fetch` 添加无 `Origin` 头, 本地服务器拒绝 。 A 类 `MEMORY_URL` 除回回路以外的主机必须在服务器上列出 `MEMORY_HTTP_ALLOWED_HOSTS`。 。 。 .

`mem_update` 财务报告和审定财务报表 `mem_delete` 选择 `expected_project`,转自 `expected_project` 查询参数只有在调用者发送了非空的;然后服务器运行变异,只有当它命名了观测器所存储的所有者。 适配器从未从活动项目中填入.

### 自定义内存二进制

为 MCP 工具和本地自动启动使用自定义内存二进制 :

```bash
MEMORY_BIN=/path/to/memory pi
```

如果缺少二进制, Pi 将不停地运行, 内存会退化而不是随同崩溃 `spawn memory ENOENT`。 。 。 .

## 安装命令细节

`pi-memory init` 在 Pi 代理目录中写入 Pi 拥有的配置 :

-   `settings.json`: 确保 `npm:pi-mcp-adapter` 财务报告和审定财务报表 `npm:@cloudfrog/memory` 已经宣布.
-   `mcp.json`: 添加一个 `memory` 发射的 MCP 服务器 `memory mcp --tools=agent` 通过安全节点包装 `directTools: false`,所以MCP仍然可以通过网关提供,而不重复 Pi-inative `mem_*` 工具.

`memory setup pi` 自动平板电脑 `npmCommand` 在皮语中 `settings.json` 何时 [爱](https://mise.jdx.dev/) 检测到在 `PATH`设定 `npmCommand` 改为 `["mise", "exec", "node@<version>", "--", "npm"]` 所以Pi总是使用错误管理的节点版本. 现有 `npmCommand` 值永远不会被覆盖;如果找不到 mise,则这个步骤是无操作的.

现有 `mcpServers.memory` 条目保存,除非您通过 `--force`数字 :

```bash
pi-memory init --force
```

命令尊重 `PI_CODING_AGENT_DIR`; 否则会写给 `~/.pi/agent`。 。 。 .

## 项目检测

HTTP事件-抓取路径反射出记忆正常的项目检测命令,就像Pi适配器可以:

1.  最接近 `.memory/config.json` 在当前 git repo 内
2.  gi `origin` 远程名称
3.  git 根目录名称
4.  单子 git repo 名称
5.  当前目录基名

MCP工具调用仍然在调用时间使用记忆核心的Canonic项目解析器. Pi- 本地工具呼叫询问内存 HTTP 服务器 `/project/current`; 如果旧运行的服务器缺少该路由, 适配器会回到最近的本地 `.memory/config.json` 并返回版本匹配的警告。 对于关键重置物或单置物,倾向于明确 `.memory/config.json`数字 :

```json
{
  "project_name": "my-project"
}
```

## 解决问题

| 症状 | 修补 |
| --- | --- |
| `mem_*` 缺少工具 | 安装/核查 `npm:@cloudfrog/memory`运行 `pi-memory init`,然后重新启动 Pi。保留 `npm:pi-mcp-adapter` 如果您使用诸如Notion或直接MCP流等MCP集成,则安装. |
| 皮无法找到 `memory` | 设定 `MEMORY_BIN=/absolute/path/to/memory`。 。 。 . |
| 会话抓取应该使用另一个服务器 | 设定 `MEMORY_URL=http://host:6366`。 。 。 . |
| Pi 显示 `error MCP: 0/N servers` 不过 `mem_*` 工作内容 | 这个状态是Pi的全球MCP网关,而不是证明Minery的Pi-native HTTP工具失败了. 检查 `~/.pi/agent/mcp.json` 用于远程 OAuth 服务等 stale/无法获取的服务器,并保留 `npm:pi-mcp-adapter` 如果您使用像Notion这样的 MCP 集成,则安装. |
| 未替换现有的 MCP 配置 | 运行 `pi-memory init --force`。 。 。 . |
| `mem_current_project` 报告 `/project/current` 不支持 | 重新启动或升级运行 `memory serve`; 检查 `MEMORY_URL`编号 :`MEMORY_BIN`如果 `.memory/config.json` 已存在, 皮用为临时倒置. |
| `mem_session_summary` 无法检测工程 | 询问用户应当收到摘要, 然后重试 `mem_session_summary` 与 `project: "name"`。 。 。 . |
| 状态栏显示 `🧠 repos · ambiguous project` | Pi起源于包含多个 git repos 的父目录. 运行 Pi 从单回波内部运行, 或者添加 `.memory/config.json` 与 `"project_name": "my-project"` 到模糊的目录. |

## 今后的步骤

-   运行 `memory tui` 检查存储的记忆.
-   使用 `mem_current_project` 在写入记忆前确认项目检测.
-   读取主内存设置指南 : [https://github.com/Horacio Espinosa/memory/blob/main/docs/AGENT-SETUP.md 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/HoracioEspinosa/memory/blob/main/docs/AGENT-SETUP.md)
-   探索记忆云: [https://github.com/Horacio Espinosa/memory/blob/main/docs/memory-cloud/README.md 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/HoracioEspinosa/memory/blob/main/docs/memory-cloud/README.md)

## 常见问题

### @cloudfrog/memory 是什么？

记忆:AI编码代理的持续记忆——一种本地第一的SQLite大脑,可选地复制到云中,它能活过会话和收缩并被共享于MCP上\. 这个包把它插入了Pi\.

### 如何安装 @cloudfrog/memory？

在项目目录运行 npm install @cloudfrog/memory，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@earendil-works/pi-coding-agent（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 pi-memory，可以用 npx pi-memory 直接运行。

### @cloudfrog/memory 支持 TypeScript 吗？

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

### @cloudfrog/memory 支持 ESM 还是 CommonJS？

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

### @cloudfrog/memory 可以商用吗？

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

### @cloudfrog/memory 的下载量有多少？

根据 npm 官方下载统计，@cloudfrog/memory 在 2026/10/10 – 2026/11/08 这 30 天内被下载 2,059 次，日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cloudfrog/memory 还在维护吗？

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