/ /

@mongodb-js/agent-engine-sdk-memory

Atlas Agent Engine (TypeScript) 的统一内存门面。 Python agent-engine-sdk-memory包的对应项：TypeScript 代理通过相同的路由读取和写入内存服务器，并且内存在轮次和会话中持续存在。

安装

npm install @mongodb-js/agent-engine-sdk-memory

`Memory` 门面

Memory 公开一个与传输无关的表面后面的每种内存类型：

类型	写入	读取
会话轮次 (STM)	`recordTurn`	（供稿 `buildContext`）
语义（事实）	`saveSemantic`	`searchSemantic`, `getSemantic`
情景（对话）	`saveEpisode`	`searchEpisodes`, `listEpisodes`
分类（知识库）	`saveTaxonomic`	`searchTaxonomic`, `getTaxonomicTerm` , `listDomains`
程序化（操作方法）	`saveProcedure`	`discoverProcedures`, `getProcedure`
自定义类型（按项目声明）	`save`	`retrieve`
统一	—	`buildContext`, `search`

所有方法都是异步的。每次调用时都会解析身份 (userId / sessionId) — 从参数、绑定上下文和运行时的环境上下文中解析。自定义类型的操作是个例外：它们不带有身份字段 — 平台会为请求中的 org、项目和 user 打上标记 — 因此它们不会解析客户端身份，并且需要一个可以为其打上标记的后端（project-作用域的网关路由或执行作用域的运行时）。

两种模式

两者的门面相同；只是提供URL、身份验证和身份的方式有所不同。

HTTP-direct（独立运行/平台外）

一个独立的客户端，用于在平台外运行的脚本、测试和代码。通过构造函数参数或 AGENTIC_MEMORY_* 环境变量进行配置。

import { Memory } from "@mongodb-js/agent-engine-sdk-memory";
const memory = new Memory({
  serviceAccountToken: process.env.AGENTIC_MEMORY_SERVICE_ACCOUNT_TOKEN, // service-account access token
  projectId: "my-project",                    // set => project-scoped Gateway routes
});                                            // unset => flat OE routes
await memory.saveSemantic({
  text: "favorite color is teal",
  label: "favorite_color",
  userId: "u1",
  metadata: { channel: "web", priority: "high" }, // optional caller-supplied metadata
});
const hits = await memory.searchSemantic({ query: "color", userId: "u1" });
await memory.close();

Env var	用途
`AGENTIC_MEMORY_SERVICE_ACCOUNT_TOKEN`	服务帐户访问权限令牌（设立为时，回退到托管网关URL ）。 `AGENTIC_MEMORY_API_KEY` 是已弃用的别名：它仍然有效，打印 `DeprecationWarning`，并与新变量冲突（设置两个异常）。使用 `agentengine service-account create` 加上Python SDK 自述文件中所示的 OAuth 令牌交换来创建令牌。
`AGENTIC_MEMORY_BASE_URL`	后端解决。
`AGENTIC_MEMORY_PROJECT_ID`	设置 =>项目范围的网关路由； empty =>扁平 OE 路由。

应用程序绑定（在已部署的代理内部）

代理代码使用 app.memory（来自 @mongodb-js/agent-engine-sdk-langgraph）。身份来自环境请求上下文，并通过编排引擎的内存代理路由调用 — 无需管理令牌，也无需 userId 线程：

// inside a tool or entrypoint
await app.memory.saveSemantic({ text: "prefers email over SMS", label: "contact_pref" });
const context = await app.memory.buildContext({ query: "how does the user like to be contacted?" });

仅在处理平台请求时才能访问应用程序绑定的内存（它需要执行上下文的 OE_URL）。

上下文词元预算

buildContext({ maxTokens }) 设置可选的上下文构建总预算（而不是获取费用）。在检索和排名后，服务器减去 500-token 格式保留，然后贪心地选择适合余数的整个内存块。等于或低于 500 的正值不会留下内存预算。当没有适合的数据块时，高于 500 的值仍可能产生空上下文。 metadata.token_count 仅报告格式化输出，不包括保留。省略 maxTokens 以保留服务器默认。

Errors

Typed errors let callers branch on failure mode: MemoryAuthError (401/403), MemoryRouteNotFoundError (404 with a route-shape hint), MemoryBadRequestError, MemoryServerError (5xx / bad body), MemoryConnectionError, MemoryNotSupportedError (capability gap), and MemoryIdentityError (a required identity field could not be resolved). MemoryNotSupportedError covers both client-side gaps and, on the custom-type routes, capability gaps only the platform can report: a bare 404/405 (platform too old to serve the route) or the gateway’s structured 400 reporting custom memory types disabled on the deployment. A structured unknown-type 404 raises MemoryBadRequestError. Transport retries 502/503/504 up to three times.

开发中

npm install
npm test      # vitest
npm run build # tsc

后退

API 参考

来年