# @agent-assistant/memory 中文文档

规范地址：https://npmcn.com/package/%40agent-assistant/memory/

版本：0\.4\.37
npm 元数据更新时间：2026-10-04T06:47:47.520Z
中文译文更新时间：2026-11-05T19:26:09.654Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：96.8 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-14T18:49:45.086Z
- 最新版本发布：2026-10-04T06:47:47.169Z
- 近 30 天下载量：38940（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 64 个）

## 中文简介

带有内相和超相容器的辅助范围内存组成层

## 安装

```sh
npm install @agent-assistant/memory
```

也可以使用：`pnpm add @agent-assistant/memory`、`yarn add @agent-assistant/memory`、`bun add @agent-assistant/memory`

## README

# `@agent-assistant/memory`

`@agent-assistant/memory` 是其所运载的继电器内存适配器上的v1辅助成份层(`InMemoryAdapter`, (中文(简体) ), `SupermemoryAdapter`, (中文(简体) ), `createMemoryAdapter`; 最初来自 `@agent-relay/memory`) (中文(简体) ).

它直接使用这些适配器进行持久性和CRUD,然后只添加经批准的v1行为:

-   助理内存范围 : `session`, (中文(简体) ), `user`, (中文(简体) ), `workspace`, (中文(简体) ), `org`, (中文(简体) ), `object`
-   按范围、标记和必要性分列的结构检索
-   可选用户范围扩展为明确的会话范围
-   推广到更广泛的范围
-   通过呼叫器提供的回调进行收缩
-   通过助理管理的元数据过滤 TTL

它不执行新的内存引擎,语义搜索,政策控制,只云行为,或交叉代理合并.

## 安装

```bash
npm install @agent-assistant/memory
```

## 出口

```typescript
import {
  createRelayBackedMemoryStore,
  createMemoryStore,
  InMemoryMemoryStoreAdapter,
  RelayMemoryStoreAdapter,
  retrieveTurnMemoryContext,
  promoteLatestSessionMemory,
} from '@agent-assistant/memory';
```

套件出口公众 `MemoryEntry`, (中文(简体) ), `MemoryScope`, (中文(简体) ), `MemoryStore`,输入/清空类型,以及错误类别 `MemoryEntryNotFoundError`, (中文(简体) ), `InvalidScopePromotionError`,以及 `CompactionError`。 。 。 .

## 快速启动

```typescript
import { createMemoryStore, InMemoryMemoryStoreAdapter } from '@agent-assistant/memory';

const memory = createMemoryStore({
  adapter: new InMemoryMemoryStoreAdapter(),
});

const sessionEntry = await memory.write({
  scope: { kind: 'session', sessionId: 'sess-123' },
  content: 'User prefers concise responses.',
  tags: ['preference', 'style'],
  metadata: {
    agentId: 'assistant-1',
    source: 'capability:intake',
  },
});

const results = await memory.retrieve({
  scope: { kind: 'session', sessionId: 'sess-123' },
  tags: ['preference'],
});

const promoted = await memory.promote({
  sourceEntryId: sessionEntry.id,
  targetScope: { kind: 'user', userId: 'user-456' },
  deleteOriginal: true,
});

const compacted = await memory.compact({
  sourceEntryIds: [promoted.id],
  targetScope: { kind: 'user', userId: 'user-456' },
  compactionCallback: (entries) => entries.map((entry) => entry.content).join('\n'),
  tags: ['summary'],
});
```

## 中继重用

V1 重用中继内存适配器(从 `@agent-relay/memory` 7.1.1 项下 `src/relay-memory/`:

-   `InMemoryAdapter` 权限 `InMemoryMemoryStoreAdapter`
-   任何兼容的中继器 `MemoryAdapter` 能够用 `RelayMemoryStoreAdapter`
-   中继 `add()`, (中文(简体) ), `get()`, (中文(简体) ), `update()`, (中文(简体) ), `delete()`,以及 `list()` 仍然是基本的储存业务

V1 故意不使用继电器 `MemoryService` 或者说 `search()`数字 :

-   `MemoryService` 不显示助手软件包需要的完整更新/get/逐一删除
-   语义搜索被推迟; v1 检索是结构化的, 并带有惯性偏差

## 范围绘图

助理范围被编码到中继字段和元数据上:

| 助理范围 | 中继绘图 |
| --- | --- |
| `session` | `sessionId` + 键 `metadata._scopeKind = 'session'` |
| `user` | `metadata.userId` + 键 `metadata._scopeKind = 'user'` |
| `workspace` | `projectId` + 键 `metadata._scopeKind = 'workspace'` |
| `org` | `metadata.orgId` + 键 `metadata._scopeKind = 'org'` |
| `object` | `metadata.objectId` + 键 `metadata.objectType` + 键 `metadata._scopeKind = 'object'` |

软件包也存储 `metadata._updatedAt` 因为中继条目曝光 `createdAt` 但没有本地人 `updatedAt`。 。 。 .

## 检索规则

`retrieve()` 过滤器来自:

-   精确范围匹配
-   所有请求的标签
-   `since` 时间戳
-   过期

`includeNarrower: true` 在v1中故意缩小:

-   (单位:千美元) `user` 范围查询,存储中还包括 `session` 仅当 `context.sessionId` 提供
-   没有隐含的会话发现
-   v1 未执行工作空间/ org 扇出

检索使用继电器 `list()` 和助手侧过滤。 因为接力 `list()` 是一个最近的项目原始的,v1的检索具有递归性,而不是保证对所有存储条目的详尽扫描.

## 促进和紧凑

晋升仅向上:

-   `session -> user | workspace | org | object`
-   `user -> workspace | org`
-   `workspace -> org`
-   `object -> user | workspace | org`

缩合为 v1 :

-   所有源条目必须存在
-   所有来源必须共享一个范围
-   `targetScope` 必须匹配源范围
-   呼叫者提供收缩回调
-   软件包从不调用模型

## 过期和举证

`expiresAt` 被存储在中继元数据中并由 `get()` 财务报告和审定财务报表 `retrieve()`。过期记录保留在基本适配器中,直至明确删除.

该软件包通过写作,更新,推广和收缩来保存助理出处元数据. 计划领域是:

-   `agentId`
-   `source`
-   `confidence`
-   `createdInSessionId`
-   `promotedFromId`
-   `compactedFromIds`

## 生产用途

```typescript
import {
  createMemoryAdapter,
  createMemoryStore,
  RelayMemoryStoreAdapter,
} from '@agent-assistant/memory';

const relayAdapter = await createMemoryAdapter({
  type: 'supermemory',
  apiKey: process.env.SUPERMEMORY_API_KEY,
});

const memory = createMemoryStore({
  adapter: new RelayMemoryStoreAdapter(relayAdapter),
});
```

包裹的中继适配器必须执行 `list()` 财务报告和审定财务报表 `update()`。构造器拒绝不提供两种方法的适配器.

## 转换内存帮助器

建立自己快速格式的消费者可以使用原始转弯帮助器,而不是重新实施范围检索和推广:

```typescript
import {
  createRelayBackedMemoryStore,
  retrieveTurnMemoryContext,
  promoteLatestSessionMemory,
} from '@agent-assistant/memory';

const { store, close } = await createRelayBackedMemoryStore({
  config: {
    type: 'supermemory',
    apiKey: process.env.SUPERMEMORY_API_KEY,
    defaultAgentId: 'sage',
    defaultProjectId: 'workspace-123',
  },
});

const context = await retrieveTurnMemoryContext({
  store,
  sessionId: 'thread-1',
  userId: 'user-1',
  workspaceId: 'workspace-123',
  tags: ['conversation'],
  limit: 5,
});

await promoteLatestSessionMemory({
  store,
  sessionId: 'thread-1',
  userId: 'user-1',
  tags: ['promotable'],
});

await close();
```

`retrieveTurnMemoryContext()` 返回会话中的条目,用户,然后默认的工作空间顺序,由条目 id去除. `promoteLatestSessionMemory()` 向用户或呼叫者提供的目标范围促进最新的匹配会话条目.

## 隔离

`packages/memory` 可自行管理 :

-   `npm install`
-   `npm run build`
-   `npm test`

该包没有云要求. `InMemoryMemoryStoreAdapter` 是默认本地/测试后端.

## 未在 V1 中

-   语义或嵌入搜索
-   自动内存写入时速
-   会话存档工作流程
-   政策性出入控制
-   助理层加密
-   交叉代理合并、矛盾处理或共享团队出版物

记忆 包接 模拟

## 常见问题

### @agent-assistant/memory 是什么？

带有内相和超相容器的辅助范围内存组成层

### 如何安装 @agent-assistant/memory？

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

### @agent-assistant/memory 支持 TypeScript 吗？

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

### @agent-assistant/memory 支持 ESM 还是 CommonJS？

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

### @agent-assistant/memory 可以商用吗？

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

### @agent-assistant/memory 的下载量有多少？

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

### @agent-assistant/memory 还在维护吗？

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