# @cerefox/memory 中文文档

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

版本：1\.23\.0
npm 元数据更新时间：2026-11-07T17:52:59.581Z
中文译文更新时间：2026-11-09T11:07:24.225Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：20.2 MB，129 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：13 个
- 首次发布：2026-05-27T02:35:51.774Z
- 最新版本发布：2026-11-07T17:52:59.209Z
- 近 30 天下载量：2812（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：122（近 12 个月 122 个）

## 中文简介

Cerefox-用户拥有的AI代理共享内存. CLI + stdio MCP服务器 + web UI + 摄取在您自己的Supabase项目(或与 Cerefox Local 完全自办)上的知识库.

## 安装

```sh
npm install @cerefox/memory
```

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

## README

# @ cerefox/ 记忆

**用户拥有的AI代理共享内存.** 本地类型脚本运行时间 [仙乐花](https://github.com/fstamatelopoulos/cerefox) - 坚持不懈, 由多个AI工具可以读取和书写而来的知识层.

> **Cerefox是BYO的储存.** 这个包是 _客户端_ ——CLI+当地 MCP服务器+本地网络UI. 知识库本身生活在 **你们自己 Supabase项目** (postgres + pgvector;免费分级工作). 安装此选项 npm 软件包 **没有** 给您一个工作 KB; 您还需要一个 Supabase 项目 + 嵌入式 API 密钥, 以及一次性服务器侧部署 (单位:千美元)`cerefox server deploy` ——不需要再现克隆). **见下文"在你安装之前".**
> 
> 偏偏无相云? 还有 **本地目录**: 同一堆叠在一个 机器上的单个 Docker 容器( 此 npm 包不需要用于 ) (中文(简体) ). 见 [当地设置-md](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/setup-local.md)。 。 。 .

**云后为甚么?** Cerefox被设计为一种 _云背书_ 内存层如此 同样的知识可以从你运行的每一个特工处获得—— Claude Code on 你的笔记本电脑, Codex 或 Cursor 在第二台机器上, Claude 在你的手机上, 在CI里的脚本. Postgres + pgvector 发送混合(语义+全文)搜索 共享内存 ; Supabase 提供了“ 相同 ” 的终点 记忆,任何设备,任何代理"的工作。 您拥有数据和终点; 此 软件包包 **你在当地经营的一切** ——CLI,MCP服务器,网络UI, 和过程内摄取+取回管道——即与之交谈.

这个软件包包含一个单一的二进制, **`cerefox`**数字 :

| 子命令 | 它会做什么 |
| --- | --- |
| `cerefox <command>` | CLI——搜索,摄入,列表,版本-历史,审计-记录,生命周期(C`init`, (中文(简体) ), `doctor`, (中文(简体) ), `configure-agent`, (中文(简体) ), `self-update`) (中文(简体) ). 从任意目录调用 . |
| `cerefox mcp` | 本地 stdio MCP 服务器. Drop-in for Claude Code, Cursor, Claude Desktop, Codex CLI, 双子座 CLI. 展示与远程相同的15个MCP核心工具 `cerefox-mcp` Edge函数,加上4个文档关系工具,在启用前一直隐藏. |
| `cerefox web` | 本地网络应用 `http://localhost:8000` ——回放UI用于浏览,搜索,编辑和摄取文档. 由显示同样内容的Hono服务器支持 `/api/v1/*` REST 表面为捆绑的边缘函数 . |

> **这个包裹不是:** cerefox建筑的真相来源 或者医生。 他们住在 [GitHub 重传](https://github.com/fstamatelopoulos/cerefox)。 。 。 . 这个README是npm起落架卡.

* * *

## 在安装前

Cerefox是一个自我托管的内存层,有两个你独立设置的一半:

**服务器侧** (生活在你的Supabase项目中,运行~24/7):

-   Postgres schema + RPC (搜索,摄入,审计日志,版本历史)
-   边缘函数(服务器侧嵌入,远程) `cerefox-mcp` MCP 服务器, 自定义- GPT 动作)

**客户端** (这个npm包,运行在你的机器上):

-   `cerefox` CLI + 化学反应 `cerefox mcp` (当地stdio MCP) + `cerefox web` (当地UI: `http://localhost:8000`(中文(简体) )

你用这个软件包的CLI部署服务器侧—— `cerefox server deploy` 从捆绑的资产(没有repo克隆)中起立 schema, RPC, 以及所有 9 边函数 。 工作安装需要两半.

### 你需要的东西

| 先决条件 | 为什么 | 怎么样 |
| --- | --- | --- |
| A 类 **Supabase项目** | 主机 Postgres + pgvector + 边缘函数. 免费等级足以供大多数个人使用. | [supabase.com (英语)](https://supabase.com/) • 新项目 |
| 一个 **嵌入 API 密钥** | 开放AI `text-embedding-3-small` (云后端的嵌入器; Cerefox Local 可以运行一个全离线本地模型). 典型个人使用的硬币/月(见 [业务费用](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/operational-cost.md)) (中文(简体) ). | 拿一个 [OpenAI API 密钥](https://platform.openai.com/api-keys)。 。 。 . |
| **节点 24** 或者说 **Bun ^ 1.0 (韩语)** | 运行时间 `cerefox` bin (和捆绑的 `cerefox mcp` 服务器). | [节点js.org](https://nodejs.org/) • 妇女 [包子. 嘘](https://bun.sh/)。靴子下方的一行安装器 如果两个都不在场,就用Bun. |

### 一次性服务器侧设置( ~10分钟- 不需要克隆)

CLI 站起整个服务器侧面 —— schema, RPCs, 以及所有 9 Edge 函数——来自捆绑的资产:

```bash
cerefox init             # enter your Supabase URL/keys + embedding key
cerefox server deploy    # schema + RPCs + Edge Functions
```

详细信息(Supabase登录/链接、连接-集线突起、API-键口味、, 清除出故障, 贡献者克隆和部署路径) [快速启动](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/quickstart.md) 财务报告和审定财务报表 [设置-基地.md](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/setup-supabase.md)。 。 。 .

如果您还没有 Supabase + 一个 OpenAI 键,则 [仙乐花 快速启动](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/quickstart.md) 在一个地方走遍整个设置.

* * *

## 安装

一旦您具备上述先决条件:

```bash
# One-line install (recommended on a fresh machine; bootstraps Bun if needed):
curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh

# Or direct (any of these):
bun install -g @cerefox/memory
npm install -g @cerefox/memory
pnpm add -g @cerefox/memory
yarn global add @cerefox/memory
```

* * *

## 第一跑步设置

```bash
cerefox init        # 5-step interactive bootstrap (asks for Supabase URL,
                    # Supabase key, OpenAI key, optional Postgres URL, identity)
cerefox doctor      # end-to-end health check against the live services
```

`cerefox init` 上面收集的证书的提示, 验证它们 他们反对现场服务 `~/.cerefox/.env` (chmod 0600),以及 (中文(简体) ) 可选择连接 MCP 客户端. **它不创建 Supabase 项目 给你的** - 你会被问到 URL + 键,所以确保这些是 已经提供( 参见“ 在您安装之前 ” ).

> **已经运行了上面的服务器端设置 ?** 然后,你的计划就位 `cerefox init` 只需要 URL + 键。 如果你跳过那一步, `cerefox doctor` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}会标出它并指示你 `cerefox server deploy`。 。 。 .

> **来一个 `.env` 从更早的安装(例如repo clone)中?** `cerefox init` 检测出来,并愿意复制到 `~/.cerefox/.env` - 黑瓦尔的名字是 完全一样,不需要重写。 (Python的实施工作在 v1.0.0; 见 [移徙指南](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/migration-1.0.md). ) (中文(简体) )

* * *

## 连接一个 AI 代理

```bash
# Run the configure-agent commands that apply to your setup:
cerefox configure-agent --tool claude-code          # ~/.claude.json via `claude mcp add`
cerefox configure-agent --tool claude-desktop       # Claude Desktop config
cerefox configure-agent --tool cursor               # ~/.cursor/mcp.json
cerefox configure-agent --tool codex                # ~/.codex/config.toml
cerefox configure-agent --tool gemini               # ~/.gemini/settings.json
```

对于手动配置(任何其他MCP客户端),犬科条目为:

```json
{
  "mcpServers": {
    "cerefox": {
      "command": "npx",
      "args": ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
    }
  }
}
```

配置后,其中任何客户端都可以通过 Cerefox KB 搜索 + 写入您的 Cerefox KB 15个核心多边协商进程工具`cerefox_search`, (中文(简体) ), `cerefox_ingest`, (中文(简体) ), `cerefox_insert`, (中文(简体) ), `cerefox_edit`, (中文(简体) ), `cerefox_delete_document`, (中文(简体) ), `cerefox_restore_document`, (中文(简体) ), `cerefox_get_document`, (中文(简体) ), `cerefox_list_versions`, (中文(简体) ), `cerefox_list_projects`, (中文(简体) ), `cerefox_list_metadata_keys`, (中文(简体) ), `cerefox_metadata_search`, (中文(简体) ), `cerefox_set_document_projects`, (中文(简体) ), `cerefox_set_document_metadata`, (中文(简体) ), `cerefox_get_audit_log`, (中文(简体) ), `cerefox_get_help`) (中文(简体) ).

`cerefox_insert` 财务报告和审定财务报表 `cerefox_edit` 更改文档的一部分而无需再发送 它——代理发送改变的东西,服务器组装结果.

4个工具(`cerefox_set_relation`, (中文(简体) ), `cerefox_delete_relation`, (中文(简体) ), `cerefox_get_relations`, (中文(简体) ), `cerefox_get_neighbors`)在 文档。 他们飞来 **休眠状态**: 隐藏在每一个代理中,直到选择使用 `cerefox config set relations_enabled true`. 仅仅改变能见度, 从来没有你的数据.

* * *

## 常见命令

```bash
cerefox search "second brain"                          # hybrid (FTS + semantic)
cerefox document ingest notes.md --project "Personal"  # add a doc
cerefox document get <id> --section "## Heading"       # read one section
cerefox document set-metadata <id> --set-meta k='"v"'  # metadata-only write
cerefox document delete <id>                           # soft-delete (restore undoes it)
cerefox document dead-links                            # sweep for dead document links
cerefox project list                                   # discover projects
cerefox metadata search --metadata-filter '{"type":"decision-log"}'
cerefox audit list --since 2026-05-01                  # immutable history
cerefox doctor                                         # diagnose your install
cerefox upgrade                                        # alias for self-update
```

运行 `cerefox --help` 用于完整命令表面——资源动词形状 (单位:千美元)`document …`, (中文(简体) ), `project …`, (中文(简体) ), `metadata …`, (中文(简体) ), `server …`)加平面命令 喜欢 `search` 和生命周期动词.

* * *

## 为什么要安装CLI呢?

你不必这样. `cerefox mcp` (启动为 stdio 子进程,由任意 MCP客户端)让你的AI代理能够完全进入知识库 自己来的 其余部分 `cerefox` CLI用于:

-   **一次性壳体操作**:搜索,摄入,列表,审计-日志.
-   **电力用户工作流程**数字 : `cerefox document ingest-dir ./meeting-notes`, (中文(简体) ), `cerefox metadata search --metadata-filter …`, (中文(简体) ), `cerefox backup create`。 。 。 .
-   **设置+诊断**数字 : `cerefox init`, (中文(简体) ), `cerefox doctor`, (中文(简体) ), `cerefox configure-agent`, (中文(简体) ), `cerefox self-update`。 。 。 .
-   **通过本地巴什工具进行代理**: 一些编码代理更喜欢运行 `cerefox <subcommand>` 从外壳而不是配置 MCP.

* * *

## 建筑、设计、文件

-   **项目README+路线图**数字 : [https://github.com/fstamatelopoulos/cerefox (中文(简体) )](https://github.com/fstamatelopoulos/cerefox)
-   **结构概览**数字 : [`CLAUDE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/CLAUDE.md)
-   **设置指南**数字 : [`docs/guides/`](https://github.com/fstamatelopoulos/cerefox/tree/main/docs/guides)
-   **升级**数字 : [`docs/guides/upgrading.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/docs/guides/upgrading.md)
-   **对于使用 Cerefox 的AI 代理**数字 : [`AGENT_GUIDE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/AGENT_GUIDE.md), (中文(简体) ), [`AGENT_QUICK_REFERENCE.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/AGENT_QUICK_REFERENCE.md),或运行 `cerefox guides list`。 。 。 .
-   **更改日志**数字 : [`CHANGELOG.md`](https://github.com/fstamatelopoulos/cerefox/blob/main/CHANGELOG.md)

* * *

## 许可证

阿帕奇-2.0 — 见 [`LICENSE`](https://github.com/fstamatelopoulos/cerefox/blob/main/LICENSE) 在回购.

Cerefox是一个单一维护者开源项目. 错误报告和公关 欢迎光临 [github.com/fstamatelopoulos/cerefox/问题](https://github.com/fstamatelopoulos/cerefox/issues)。 。 。 .

## 常见问题

### @cerefox/memory 是什么？

Cerefox-用户拥有的AI代理共享内存\. CLI \+ stdio MCP服务器 \+ web UI \+ 摄取在您自己的Supabase项目\(或与 Cerefox Local 完全自办\)上的知识库\.

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

在项目目录运行 npm install @cerefox/memory，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cerefox，可以用 npx cerefox 直接运行。

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

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

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

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

### @cerefox/memory 需要什么版本的 Node\.js？

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

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

@cerefox/memory 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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