# @agentskit/memory 中文文档

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

版本：0\.12\.1
npm 元数据更新时间：2026-10-24T15:08:28.630Z
中文译文更新时间：2026-11-05T21:10:41.029Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/memory
原文对照：https://npmcn.com/package/%40agentskit/memory/?lang=original
项目主页：https://www.agentskit.io/docs/reference/packages/memory
源码仓库：https://github.com/AgentsKit-io/agentskit

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

- 包体积（解压后）：713 kB，32 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：2 个
- peer 依赖：pg ^8\.23\.1，vectra ^0\.15\.0，drizzle-orm ^0\.44\.0 \|\| ^0\.45\.3
- 首次发布：2026-04-06T11:30:39.300Z
- 最新版本发布：2026-10-24T15:08:28.035Z
- 近 30 天下载量：20347（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：44（近 12 个月 44 个）

## 中文简介

AgentsKit 的持久和向量内存后端.

## 安装

```sh
npm install @agentskit/memory
```

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

## README

# @ agentskit/ 记忆

简介 : `major-package`

![AgentsKit](https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg)

坚持对话,并在您的代理中添加向量搜索——互换后端而无需更改代理代码.

[![npm version](https://img.shields.io/npm/v/@agentskit/memory?color=blue)](https://www.npmjs.com/package/@agentskit/memory) [![npm downloads](https://img.shields.io/npm/dm/@agentskit/memory)](https://www.npmjs.com/package/@agentskit/memory) [![bundle size](https://img.shields.io/bundlejs/size/@agentskit/memory?label=bundle)](https://bundlejs.com/?q=@agentskit/memory) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/LICENSE) [![stability](https://img.shields.io/badge/stability-beta-yellow)](https://npmcn.com/package/docs/STABILITY.md) [![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)

**标记 :** `ai` • 妇女 `agents` • 妇女 `llm` • 妇女 `agentskit` • 妇女 `ai-agents` • 妇女 `memory` • 妇女 `vector-db` • 妇女 `embeddings` • 妇女 `rag` • 妇女 `sqlite` • 妇女 `redis` • 妇女 `vector-search`

## 已核实的证据

-   软件包元数据和测试在 `packages/memory/`。 。 。 .
-   软件包指南 : [https://www.agentskit.io/docs/reference/packages/memory (中文(简体) )](https://www.agentskit.io/docs/reference/packages/memory)
-   稳定地图: [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)

## 如何适应生态系统

@ agentskit/memory 给出代理的连续性:聊天历史,向量内存,图表内存,加密存储,以及本地或托管后端.

-   **探员Kit**:与本回购中的其他包一起作曲,从可互换的小零件来构建代理.
-   **书记官处**: 查找已使用此图层的即时代理和模板 [登记. agentskit.io](https://registry.agentskit.io/)。 。 。 .
-   **游戏本**: 学习本层背后的生产模式 [游戏本. agentskit.io](https://playbook.agentskit.io/)。 。 。 .

文档 : [软件包指南](https://www.agentskit.io/docs/reference/packages/memory) • 妇女 [代理交接](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt)

## 为什么记忆

-   **在重启中幸存的对话** – SQLite 用于本地开发, Redis 用于生产; 您的代理在零代码更改的会话中记得上下文
-   **RAG 已准备好的向量搜索** ——储存并取回嵌入物 `fileVectorMemory` (纯JS,无原生道口)或 Redis 矢量搜索尺度
-   **插入任何后端** - 那个 `VectorStore` 接口是 3 个方法; 将 LanceDB 、 Pinecone 或任何自定义商店带入分钟内
-   **一个接口,每个部署目标** - 互换自 `inMemory` 改为 `sqlite` 改为 `redis` 没有触摸代理代码

## 安装

```bash
npm install @agentskit/memory better-sqlite3
# For production:  npm install redis
# For vectors:     npm install vectra
```

## 快速实例

```ts
import { createRuntime } from '@agentskit/runtime'
import { anthropic } from '@agentskit/adapters'
import { sqliteChatMemory } from '@agentskit/memory'

const runtime = createRuntime({
  adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-sonnet-4-6' }),
  memory: sqliteChatMemory({ path: './chat.db' }),
})

// Agent now remembers previous conversations across process restarts
const result = await runtime.run('What did we discuss yesterday?')
console.log(result.content)
```

## 带RAG

使用一个 **向量** 后端为 [`@agentskit/rag`](https://www.npmjs.com/package/@agentskit/rag) `createRAG({ embed, store })` —— 说 `fileVectorMemory` 财务报告和审定财务报表 `redisVectorMemory` 执行 `VectorMemory` 用于块存储和搜索.

## 特征

### 聊天记忆(4)

-   `fileChatMemory({ path })` - JSON在磁盘上.
-   `sqliteChatMemory({ path })` ——WAL-mode SQLite;按会话索引.
-   `redisChatMemory({ client, keyPrefix })` ——分布相通,无服务器友好.
-   `tursoChatMemory({ url, authToken? })` ——主办或当地libSQL/Turso.

全部在顶上 `createInMemoryMemory` 编号 : `createLocalStorageMemory` 从 `@agentskit/core`。 。 。 .

### 浏览器网络存储

当主机需要验证、 绑定存储或 `sessionStorage` 而不是遗产 核心 `localStorage` 帮助者 :

```ts
import { createWebStorageMemory } from '@agentskit/memory/web-storage'

const memory = createWebStorageMemory({
  key: 'app:chat',
  getStorage: () => typeof sessionStorage === 'undefined' ? undefined : sessionStorage,
  maxMessages: 20,
  maxRecordBytes: 1_048_576,
})
```

Canonical记录被运行时间验证. 超大小保存拒绝 `AK_MEMORY_SAVE_FAILED` 在更改存储之前. `migration` 可能提供遗产 密钥和主机拥有的解析器; 遗留的密钥仅在犬科之后被删除 持久性成功.

### 病媒记忆(11)

-   `fileVectorMemory` ——纯-JS,文件已存在(好到~10k向量).
-   `redisVectorMemory` —— Redis Stack / Redis 8+ HNSW.
-   `pgvector` - BYO SQL跑车手(`postgres.js`, (中文(简体) ), `pg`德瑞兹 普里斯玛 尼昂.
-   `pinecone` 管理;命名空间+元数据过滤器.
-   `qdrant` ——通过HTTP自行托管或云.
-   `chroma` ——Chroma v2 HTTP客户端,拥有租户,数据库,和象征性支持.
-   `upstashVector` ——无服务器的HTTP.
-   `supabaseVectorStore` - Supabase公司主办Pgvector RPC.
-   `weaviateVectorStore` ——织出"云"或自办HTTP.
-   `milvusVectorStore` ——米尔武斯/齐利兹·雷斯特API.
-   `mongoAtlasVectorStore` ——蒙戈DB 阿特拉斯矢量搜索并有被注入的集合.

矢量适配器跟随 ADR 0003 : 只有在得分为 绝对大于 `threshold`。远程 HTTP 适配器接受 `timeoutMs` 财务报告和审定财务报表 `maxResponseBytes`,默认为15秒和2米B;两者都需要正数 安全整数。 喷出 `fetch` 和呼叫者 `signal` 也得到支持。 超时 和响应限制失败的使用 `AK_MEMORY_REMOTE_HTTP`。文件 KV 写入为 原子和序列化 在一个过程中。 他们不是 多进程协调原始; 使用 SQLite、 Redis 或其他外部 当多个进程写入相同文件时存储.

同样的三相方法 `VectorStore` 合同——互换不触摸代理代码.

### 高档包装纸(6)

-   `createHierarchicalMemory` ——MemGPT风格分级:工作/召回/存档. [食谱](https://www.agentskit.io/docs/reference/recipes/hierarchical-memory)。 。 。 .
-   `createVirtualizedMemory` ——热窗+冷取器作长会. [食谱](https://www.agentskit.io/docs/reference/recipes/virtualized-memory)。 。 。 .
-   `createAutoSummarizingMemory` _(通过) `@agentskit/core/auto-summarize`(中文(简体) )_ 折叠最古老的 变成运行中的摘要. [食谱](https://www.agentskit.io/docs/reference/recipes/auto-summarize)。 。 。 .
-   `createEncryptedMemory` - AES-GCM-256 信封上的任何 `ChatMemory`钥匙从不离开呼叫者. [食谱](https://www.agentskit.io/docs/reference/recipes/encrypted-memory)。 。 。 .
-   `createInMemoryGraph` ——知识图(节点+边缘+BFS). [食谱](https://www.agentskit.io/docs/reference/recipes/graph-memory)。 。 。 .
-   `createInMemoryPersonalization` + 键 `renderProfileContext` ——每个用户特质简介. [食谱](https://www.agentskit.io/docs/reference/recipes/personalization)。 。 。 .

内存合同v1(ADR0003)——跨域可替换 `runtime`, (中文(简体) ), `useChat`,每个框架都具有约束力.

## 生态系统

| 软件包 | 作用 |
| --- | --- |
| [@ agentskit/ 核心](https://www.npmjs.com/package/@agentskit/core) | `Memory`, (中文(简体) ), `VectorMemory` 类型 |
| [@ agentskit/ 擦伤](https://www.npmjs.com/package/@agentskit/rag) | 向量内存上方的弹簧+取回 |
| [@ agentskit/ 运行时间](https://www.npmjs.com/package/@agentskit/runtime) | `memory` 编号 : `retriever` 选项 |
| [@ agentskit/ 适应器](https://www.npmjs.com/package/@agentskit/adapters) | RAG 嵌入 |

## 贡献者

[![AgentsKit contributors](https://contrib.rocks/image?repo=AgentsKit-io/agentskit)](https://github.com/AgentsKit-io/agentskit/graphs/contributors)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 文档

[完整文档](https://www.agentskit.io/) • 妇女 [GitHub 图像](https://github.com/AgentsKit-io/agentskit)

## 成熟性和相容性

-   稳定性: **β 语录** 看到了吗 [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)
-   **节点.js 20+** 财务报告和审定财务报表 **类型脚本** 严格模式
-   发表于 `@agentskit/memory`

## 捐款

见 [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 单曲 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

### PostgreSQL 聊天内存( 节点和工人)

安装 `drizzle-orm` 财务报告和审定财务报表 `pg` 与这个包裹。 可选 `@agentskit/memory/postgres` 子路径导出 `postgresChatMemory`, (中文(简体) ), `postgresChatTable` (Drizzle schema),和 (中文(简体) ) `postgresChatMigrationSql`。 。 。 . 主条目不导入对等点 .

```ts
import { Pool } from 'pg'
import { drizzle } from 'drizzle-orm/node-postgres'
import { sql } from 'drizzle-orm'
import { postgresChatMemory, postgresChatMigrationSql } from '@agentskit/memory/postgres'

const pool = new Pool() // host owns connection configuration and shutdown
const db = drizzle(pool)
// Run once in your migration tooling, not on every request:
await db.execute(sql.raw(postgresChatMigrationSql))
const memory = postgresChatMemory({ db, tenantId: 'tenant-a', sessionId: 'session-a' })
await memory.save([])
await pool.end()
```

在工人中,启用 `nodejs_compat`; 创建和连接一个 `pg.Client` 每一个里面 请求,通过 `drizzle(client)`,并用 `ctx.waitUntil(client.end())` 在所有内存操作(以及任何使用它们的流)完成后. 这个 软件包从不连接、迁移或关闭客户端。 节点 `Pool` 可能会是 (b) 各项请求共享。 无需依赖霓虹、超驱动或Cloudflare; ,主机可以酌情提供它们的连接配置.

每个查询都同时使用租户和会话,这构成了主键. 衍生 这些识别资料来自信任的授权范围: 提供电话的租户 姓名本身不是授权。 从解剖角度保存替换版本的 JSONB 抓取,保存部件,工具,元数据,日期,以及消息顺序. 同时 保存使用上一个写入- wins; 此 ChatMemory 不执行会话 CAS 或 转租。 Schema 迁移是明确的; SQL/连接错误被传播和 无效的记录失败,而不是默默地抛弃历史.

默认情况下不进行截取(CM1-CM6)。 选择到 `maxMessages: N` 改为 按原始顺序保存每个保存中最新的 N 信息 . 只保留在用户转弯边界上切:保留窗口总是从一个开始 `user` 消息,所以用户问题从不脱离其助手的回答 并且一个工具呼叫 永远不会与它的结果分开。 当N -最新截断 掉入最近的一圈(可能是在进行中), 整个一圈被保持,所以 结果可能超过 N `system` 信件总是保留。 历史 没有用户信件的存储不改变而不是被清空。 永远 删除更古老的转折并计数信件,而不是符号或字节. 对于语义 总结,整理主机的历史 换句话说 需要一个正的安全整数; 空保存仍然存在 `[]`。 。 。 .

支持的 Drizzle 同行范围是 `^0.44.0 || ^0.45.3`。两个下限 通过了真正的 PostgreSQL 合同套件和包类型检查.

`signal` 在任何 SQL 发布前拒绝已经放弃的操作 。 装入 还在 SQL 返回后检查 。 Drizzle/pg 在此不取消飞行中 SQL : 已提交的保存/ 清除程序可在中止后执行,并将报告 实际SQL结果。 在主机连接上配置查询/声明超时 .

可选的防御深度 RLS(作为迁移所有人运行,通过 无BYPASSRLS的非所有者角色; 将租户设置在主机管理的交易内 :

```sql
ALTER TABLE agentskit_chat_memory ENABLE ROW LEVEL SECURITY;
ALTER TABLE agentskit_chat_memory FORCE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON agentskit_chat_memory
  USING (tenant_id = current_setting('app.tenant_id', true))
  WITH CHECK (tenant_id = current_setting('app.tenant_id', true));
```

在交易外的共享池连接上不要设置租户. 东道主 必须执行角色权限,并将其信任的租户设定为本地交易 `set_config('app.tenant_id', tenant, true)`。 。 。 .

真正的验收(本地可支配的PostgreSQL 16,对回回路的信任认证); 没有生产账户:

```sh
docker run -d --name ak-memory-test -p 127.0.0.1:55439:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:16
AK_POSTGRES_TEST_PORT=55439 pnpm --filter @agentskit/memory test:postgres
AK_POSTGRES_TEST_PORT=55439 pnpm --filter @agentskit/memory test:workerd
docker rm -f ak-memory-test
```

CI 运行 `test:postgres` 针对具有信任认证的 PostgreSQL 16 服务 和一个明确的测试端口;不需要任何秘密。 本地跳过 没有明确的测试端口. `test:workerd` 运行 `wrangler dev --local`,每个请求使用客户端 `waitUntil` 关闭, 并进行与节点池测试相同的合成合同套件.

## 常见问题

### @agentskit/memory 是什么？

AgentsKit 的持久和向量内存后端\.

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

在项目目录运行 npm install @agentskit/memory，或使用 pnpm add / yarn add / bun add。

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

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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

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

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

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

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