Agent-engine-sdk-memory

目录

• 内存是如何工作的

  • 它解决的问题

  • 两层

  • 写入如何成为内存

  • 提取失败时

  • 阅读是如何进行的

  • 内存的范围

  • user_id and visibility 回答不同问题 <#user_id-and-visibility-answer- different-questions>`__

• 安装

• 正在连接

  • 托管平台

  • 本地开发

  • 平台代理内部（应用程序绑定）

  • 环境变量是一种备用

  • 路由的工作原理

  • 高级：经过身份验证的直接后端

  • 每个连接支持什么

• 使用它

• 配置内存服务器

  • 以后无法更改的设置

• 如何解析身份

  • 设置写入可见性

  • 确定读取范围

• Errors

• 模型

  • 读回您自己的元数据

• 内部

  • 封装布局

  • 依赖拒绝列表

  • 谁使用它

内存是如何工作的

record_turn(...)          you write turns as the conversation happens
      │
      ▼   turns accumulate into a session
   snapshot                a contiguous run of turns, summarised
      │
      ▼   an LLM reads the snapshot and extracts what is durable
  semantic · episodic · procedural · taxonomic

安装

pip install agent-engine-sdk-memory

from agent_engine_sdk_memory import Memory, MemoryRequestContext

正在连接

代理的运行位置决定了它的连接方式，区别主要在于谁提供身份。

这三个版本的API是相同的。针对外部部署的代理编写的代码在移动到平台上时运行不变 — 您删除构造函数调用，运行时会提供对象。

平台部署的代理免费获得身份，这是本质上的区别。运行时已经知道它正在处理的调用的“组织”、 “项目”、“用户”和“会话”，因此它会为您绑定这些内容。外部代理只知道其服务帐户令牌意味着什么（项目），因此它必须告诉内存每个调用属于哪个用户和会话。如果错误，您将以另一个用户的身份写入一个用户的内存，这就是为什么外部路径要求您是显式的。

agentengine service-account create my-agent --project-id <your-project-id> --role AGENT_DEVELOPER

ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error      --user <client-id>      --data grant_type=client_credentials      https://agentengine.mongodb.com/api/v1/oauth/token | jq -er .access_token)

memory = Memory(service_account_token="<your-access-token>", project_id="<your-project-id>")

memory = Memory(base_url="http://localhost:8080")

# `memory` is supplied by the platform runtime — do not construct it.
memory.record_turn(role="user", content="I'm allergic to penicillin.")
context = memory.build_context(query="What medications should I avoid?")
# bind(...) is still available to scope a call chain to a specific identity.

使用它

完整的往返：构建内存、绑定会话身份、记录回合和检索上下文。

from agent_engine_sdk_memory import Memory, MemoryRequestContext
memory = Memory(service_account_token="<your-access-token>", project_id="<your-project-id>")
# Scope every call to a user and conversation.
session = memory.bind(MemoryRequestContext(user_id="user_1", session_id="thread_123"))
# Record what happened.
session.record_turn(role="user", content="I'm allergic to penicillin.")
session.record_turn(role="assistant", content="Noted — I'll avoid it.")
# Later, pull back the relevant context for a new prompt. Include "stm"
# to surface the turns just recorded (the default is episodic, semantic).
# max_tokens is an optional gross context-construction budget.
context = session.build_context(
    query="What medications should I avoid?",
    enabled_sources={"stm", "episodic", "semantic"},
    max_tokens=2048,
)
# context is a ContextResponse — inject its content into the next prompt.

bind(ctx) 返回范围为 ctx 的新处理，而不改变原始句柄，因此一个 Memory 可以同时为许多用户和会话提供服务。

``build_context``默认源。省略的 enabled_sources 默认为 episodic 和 semantic； stm、taxonomic 和 procedural 需要显式设立。

``max_tokens``。可选的正上下文构建总预算。它不是获取费用或承诺的输出大小：在检索和排名后，服务器减去 500-token 格式保留，然后贪心地选择适合余数的整个内存块。等于或低于 500 的正值不会留下内存预算。当没有适合的数据块时，高于 500 的值仍可能产生空上下文。 metadata.token_count 仅报告格式化输出，不包括保留。省略 max_tokens 以保持先前的行为。

``format_style`` 和 ``include_memories``。 build_context 和 build_context_from_sources 接受两个响应调整选项。 format_style（"openai"、"claude" 或 "jinja2"；为类型注解导出 FormatStyle枚举）选择 formatted_context 的格式，无效值会在本地引发 ValueError。省略，服务器从其配置的模型中推断格式。需要注意的是：当前，当显式值与其默认模型类型匹配时，服务器会重新推断，因此仅在配置了 OpenAI 系列模型的服务器上才会逐字遵循显式 "openai"； "claude" 和 "jinja2" 始终受到尊重。 include_memories=True 使用预算后 MemoryChunk 列表填充响应的 selected_memories，因此您可以准确检查选择了哪些内存。两者都需要托管或直接HTTP连接；当设立其中之一时，应用程序绑定模式会引发 MemoryNotSupportedError。

每个源上下文 — ``build_context_from_sources``。在 build_context 对每个源应用一个过滤和语义检索的情况下，该方法允许每个源通过以下方式声明自己的检索 mode（text、semantic 或 hybrid）、metadata_filter 和 top_k：一个 SourceSpec。跨源对结果进行合并和去重，可以选择按相关性 rerank 重新排序，然后像 build_context 一样进行格式化和预算。 metadata.ranking_strategy 和 metadata.source_outcomes 报告最终订单是如何生成的以及每个来源的表现。 sources 必须为非空，且每个源最多可列出一次，且每个源的 top_k 必须介于 1 和 200 之间；仅当包含 stm 源时才需要 session_id。

对于带有文本的来源，混合通常是正确的默认：单独的向量搜索会错过确切的标识符和稀有单词，单独的文本搜索会错过释义。当规范省略时，mode 默认为 semantic。

声明可筛选元元数据。 metadata_filter 只能命名项目已声明的元数据，因为过滤将应用于搜索索引内部，而不是其结果。在 project-config.yaml 中声明这些属性以及必须为这些属性提供服务的索引腿：

metadata_partition_key:            # Filterable metadata attributes (max 10)
  - name: tier
    type: string                   # string | number | boolean | date
  - name: confidence
    type: number
metadata_partition_index:
  semantic: [both]                 # both legs, so a hybrid source can filter
  short_term: [both]               # stm is searchable only once listed here
short_term:
  embed_on_write: true             # required to give stm a vector leg

agentengine memory apply --upgrade

在写入过滤之前，有四个值得了解的结果：

• 过滤键是限定的索引路径，而不是声明的名称。声明为 tier 的属性在 metadata.tier 建立索引，这是过滤必须说的 — 没有任何前缀。

• 键只能针对您列出的边进行筛选。 metadata_partition_index 将源映射到 [vector]、[text] 或 [both]，并且 hybrid 源需要 [both]：如果其文本支路无法提供服务，则在运行查询之前拒绝过滤，而不是静默返回较少值。

• 错误的密钥会导致很大的失败。与 build_context 的单个顶级 metadata_filter 不同，每个源的密钥会根据声明的设立进行验证。未声明或拼写错误的路径会引发 MemoryBadRequestError ，其消息会列出已接受的路径，因此拼写错误会导致调用失败，而不是默默地返回缩小的结果设立。

• 短期记忆没有自己的索引。只有当项目在 metadata_partition_index 中列出 short_term 时，才可以对其进行筛选，并且完全可以通过此方法进行搜索。在此之前，stm 源会失败而不是返回任何内容：搜索错误，并且会在 metadata.source_outcomes 中使用 error 报告源。如果 stm 是唯一请求的源，则每个源都失败，调用返回 503 而不是空上下文，因为空结果与对空语料库的健康搜索无法区分。为其提供向量分支（[vector] 或 [both]）还需要 short_term.embed_on_write: true，没有它，配置将被拒绝，因为从未嵌入的向量索引将是自重。文本腿不需要嵌入。

声明的 type 设置匹配语义。 string 键作为词元进行索引，因此匹配为整数值且区分大小写："gold" 既不匹配 Gold，也不匹配 gold-tier。范围操作符需要 number 或 date 键。

支持的子句：相等； $gt / $gte / $lt / $lte，合并边界融合到一个范围中； $in / $nin 用于集合； $ne； $exists； $and / $or / $nor 用于组合。

agent_id 无需声明即可过滤。租户字段 org_id、user_id、project_id、session_id、visibility、deleted、is_latest 和 has_embedding 保留用于访问权限控制，并且不能由调用者过滤。

将它们放在一起。使用上述配置：

from agent_engine_sdk_memory import SourceSpec
context = session.build_context_from_sources(
    query="what did we decide about the refund policy?",
    sources=[
        # Exact match on a string key, and a range on a numeric one.
        SourceSpec(
            source=MemorySource.SEMANTIC,
            mode=RetrievalMode.HYBRID,
            metadata_filter={
                "metadata.tier": "gold",
                "metadata.confidence": {"$gt": 0.8},
            },
            top_k=20,
        ),
        # Sources without a filter are unrestricted.
        SourceSpec(source=MemorySource.EPISODIC, mode=RetrievalMode.HYBRID, top_k=5),
        SourceSpec(source=MemorySource.STM, mode=RetrievalMode.TEXT, top_k=10),
    ],
    rerank=True,
)

此方法可在所有三种连接模式下到达后端。在托管项目路由 (project_id 设立) 上，网关代理相同的每源处理程序，从经过身份验证的会话中为组织/项目打上标记；在直接路由（project_id 空）上，OE 代理会转发该路由；在平台内（应用程序绑定）运行时，平台会标记租户并通过持久性执行传回完整响应。

除了 record_turn 和 build_context 之外，Memory对象还公开：

• 搜索 — search(query, sources=[...]) 在内存类型之间展开，并返回排名靠前的 list[MemoryChunk]； search_semantic、search_episodes、search_taxonomic 和 discover_procedures 以单一类型为目标。

• 特定类型的写入和读取（其中连接支持增删改查） — save_semantic / get_semantic、save_episode / list_episodes、save_taxonomic / get_taxonomic_term / list_domains 和 save_procedure / get_procedure 。

• 自定义内存类型 — save(memory_type, content, tags=...) 和 retrieve(memory_type, query, tags=..., top_k=...) 对项目内存配置中声明的类型进行操作。内置类型名称将被拒绝 — 请使用上述专用方法。这些调用不包含身份字段；平台会为请求中的 org、 项目和 user 标记 org、project 和 user。在不提供服务自定义类型路由的平台上，或者禁用了该功能的平台上，调用会引发 `MemoryNotSupportedError <#errors>`__。

使用上述绑定 session 的简短示例—写入事实，按标签读回，然后跨类型搜索：

# Save a semantic fact (user_id is inherited from the bound session).
session.save_semantic(text="Prefers window seats on flights.", label="seat-preference")
# Read it straight back by label.
fact = session.get_semantic("seat-preference")
# Search across memory types; returns one ranked list[MemoryChunk].
hits = session.search("travel preferences", sources=["semantic", "episodic"], top_k=5)

Memory 也是上下文管理器； with Memory(service_account_token=...) as memory: 在退出时释放根本的传输。

配置内存服务器

SDK 读写内存；它不会配置服务器。设置 — 嵌入、提取 LLM、提取哪些内存类型、可筛选元元数据— 位于项目 project-config.yaml 的 memory:区块中，并与CLI一起应用。仅上传该子文档；文件的其余部分将被忽略。

agentengine memory configure      # store the memory: block for this project
agentengine memory apply --wait   # roll the memory server so it takes effect

存储不是应用。 configure 保存配置，平台自行将其传递到项目的内存服务器，但服务器仅在初创企业时读取其配置。在 Pod 重新启动之前，新设置会以未读取状态保存在磁盘上。 agentengine memory apply 执行重启 — 并首先预配内存运行时（如果项目还没有内存运行时）。

agentengine memory apply --upgrade 此外，还将运行时移动到环境当前固定的内存服务器映像，这就是您选择较新服务器的方式。如果没有 --upgrade，该图像将保持不变。 agentengine memory status 随时报告运行时状态； apply 区块上的 --wait，直到准备就绪。

如何解析身份

内存操作的范围由 user_id、agent_id 和 session_id 限定，并在 MemoryRequestContext 中承载。对于每次调用，每个字段都通过三个层级进行解析，优先级最高：

1. 调用参数 — 直接传递给方法的值（例如 search_semantic(query, user_id="user_2")）。

2. 绑定上下文 — 传递给 bind(...) 的 MemoryRequestContext。

3. 运行时上下文 — 运行时提供的环境标识，由应用程序绑定路径使用。

Blank or whitespace-only values count as unset at every tier; agent_id is always optional. Identity is validated client-side only for the type-specific writes: save_semantic, save_taxonomic, and save_procedure require a user_id, and save_episode requires both user_id and session_id — each raises MemoryIdentityError when the field cannot be resolved. The workflow operations (record_turn, build_context, the searches) and the get_* / list_* reads do not enforce identity locally; they forward whatever resolves to the backend, which may reject the request as a transport error.

``session_id`` is scoped by operation. It identifies a conversation, so it is inherited (from bind/runtime) only for conversation I/O: record_turn and the short-term-memory leg of build_context. Episodic and semantic search do not inherit it — search_episodes, list_episodes, and the episodic leg of search() resolve session_id from the call argument only. Episodic memory is stored session-unscoped (consolidated episodes carry session_id: null), so a bound session would otherwise silently filter out every durable memory and return an empty list with no error. Pass session_id= explicitly on the search call when you do want a session-scoped episodic read. (This brings the SDK in line with the platform agent-engine-sdk-langgraph / TenantRuntime path, which already requires an explicit session_id on episodic search.) user_id and agent_id are unaffected and still inherit from bind/runtime on reads.

# Private to user_1 — the default.
session.save_semantic(text="Prefers window seats.", label="seat-preference")
# Readable across the whole organization.
session.save_semantic(
    text="Refunds over $500 need manager approval.",
    label="refund-policy",
    visibility="org",
)

session = memory.bind(MemoryRequestContext(user_id="user_1", session_id="thread_123"))
session.search_semantic("refund policy", visibility="org")   # user_1 AND org

# The original handle is unbound, so it carries no user_id.
memory.search_semantic("refund policy", visibility="org")
# Or bind only the parts you want.
thread = memory.bind(MemoryRequestContext(session_id="thread_123"))
thread.search_semantic("refund policy", visibility="org")

personal = session.search_semantic(query, top_k=5)                       # user_1, any visibility
shared = memory.search_semantic(query, visibility="org", top_k=5)        # org-wide, any owner

Errors

错误分为两类。客户端错误是 ValueError 的子类，通常在任何网络调用之前引发：

• MemoryClientError — 使用错误的基础。

• MemoryIdentityError — 无法解析必填身份字段。直接对 ValueError 进行子类化（MemoryClientError 的同级，因此不会被 except MemoryClientError 捕获）。

• MemoryNotSupportedError — 该操作不适用于活动连接（请参阅连接）。该消息会列出操作名称和原因。对于自定义类型方法 (save / retrieve)，当响应显示平台缺乏此功能时，也可在HTTP调用后引发此问题：裸露的 404/405（平台太旧，无法提供服务路由）或网关的结构化 400报告部署中禁用的自定义内存类型。结构化未知类型 404 是请求错误，而不是功能差距，会引发MemoryBadRequestError。

传输错误派生自 MemoryAPIError 并携带HTTP status 和响应正文：

• MemoryAuthError —身份验证或授权失败 (401/403)。

• MemoryBadRequestError —请求被拒绝（除 auth 或 not-provisioned 之外的 4xx）。

• MemoryRouteNotFoundError — 核心循环请求404，因此路由结构可能与后端不匹配。该消息提供设立或取消设置 project_id 的定向提示。 MemoryBadRequestError 的子类。

• MemoryNotProvisionedError — 尚无法访问项目的内存运行时间。

• MemoryServerError —后端出错 (5xx) 或返回无法解析或意外的正文。

• MemoryConnectionError — 无法访问后端。

模型

请求和响应类型从包根目录导出并从 agent_engine_sdk_memory.models 重新导出。检索返回 MemoryChunk 和 ContextResponse；写入会返回类型化结果，例如 WriteTurnResult、CreateSemanticResult 和 CreateEpisodicResult。 SearchSource 枚举可搜索类型。上下文构建是使用 Memory.build_context（示例enabled_sources 和 max_tokens）上的 kwargs 配置的，而不是单独的配置模型。从 agent_engine_sdk_memory（而不是 agent_engine_sdk）导入这些模型 — 模型曾经住在那里，现在已经搬到了这里。

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
    MemorySource,
    RetrievalMode,
    SourceSpec,
)
session_id = "session-42"
memory = Memory(base_url="http://localhost:8080").bind(
    MemoryRequestContext(user_id="user-1", session_id=session_id)
)
memory.record_turn(
    role="user",
    content="The engagement is green and the rollout continues.",
    metadata={"engagement_id": "eng-alpha", "tier": 2},
)
context = memory.build_context_from_sources(
    query="what is the engagement status?",
    sources=[
        SourceSpec(
            source=MemorySource.STM,
            mode=RetrievalMode.HYBRID,
            metadata_filter={"metadata.engagement_id": "eng-alpha"},
        )
    ],
    session_id=session_id,
    include_memories=True,
)
for chunk in context.selected_memories or []:
    print(chunk.metadata["metadata"]["engagement_id"])

内部

以下部分描述了如何构建该包。他们不需要使用它。

agent_engine_sdk_memory/
├── memory.py        # Memory — the public, transport-free facade
├── protocol.py      # MemoryRequestContext, MemoryRuntime + MemoryCrudClient seams
├── identity.py      # resolve_identity — call arg > bind ctx > runtime ctx
├── errors.py        # MemoryIdentityError + the typed transport-error family
├── models.py        # Pydantic models for memory requests/responses
├── validation.py    # require_positive_max_tokens — public build_context guard
├── _transport.py    # _HttpTransport — shared retry / error-mapping / lifecycle
├── _http_runtime.py # _HttpMemoryRuntime — the workflow ops + per-backend profiles
├── _direct_crud.py  # empty-tenancy MemoryCrudClient over the shared transport
├── _wire.py         # custom-type request-body builders shared by the CRUD clients
├── _tag_syntax.py   # client-side custom-type name + tag-syntax checks
├── _client.py       # MemoryClient — internal HTTP client for the Memory Server API
└── _denylist.py     # do-not-add dependency denylist (see below)