本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用命名空间指定长期内存组织
<a name="specify-long-term-memory-organization"></a>

[创建](memory-create-a-memory-store.md) AgentCore 内存时，请使用命名空间来指定[内存策略的[长期内存](memory-types.md#memory-long-term-memory)](memory-strategies.md)的逻辑分组位置。每次使用内存策略提取新的长期内存时，都会将其保存在您设置的命名空间下。这意味着所有长期记忆都限于其特定的命名空间，从而使它们井井有条，并防止与其他用户或会话混淆。应使用由正斜杠分隔的分层格式`/`，以斜杠开头和结尾（例如，`/actors/alice/`）。这有助于使记忆井井有条。根据需要，您可以根据应用程序的组织需求选择在命名空间的大括号内使用以下预定义变量：
+  **ActorID** — 识别长期记忆属于谁。

  行为者是指诸如最终用户或 agent/user 组合之类的实体。例如，在编码支持聊天机器人中，参与者通常是开发者在提问。使用操作者 ID 可以帮助系统知道内存属于哪个用户，从而使每个用户的数据保持独立和井井有条。
+  **StrategyID** — 显示正在使用哪种内存策略。此策略标识符是在您创建 AgentCore 内存时自动生成的。
+  **sessionID** — 标识内存来自哪个会话或会话。

  会话通常是用户与 AI 代理之间的单次对话或互动时段。它对对话期间发生的所有相关消息和事件进行分组。

例如，如果您在创建 AgentCore 内存时将以下命名空间定义为策略的输入：

```
/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/
```

创建内存后，此命名空间可能如下所示：

```
/strategy/summarization-93483043/actor/actor-9830m2w3/session/session-9330sds8/
```

命名空间可以有不同的粒度级别。以下示例仅使用内置变量：

 **会话级别的精细化** 

 `/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}/` 

 **跨会话的演员层面精细化** 

 `/strategy/{memoryStrategyId}/actor/{actorId}/` 

 **各参与者在策略层面上精细化** 

 `/strategy/{memoryStrategyId}/` 

 **所有策略均覆盖全球** 

 `/` 

对于更精细的组织，您可以添加[自定义命名空间变量](#specify-custom-namespace-variables)来表示其他维度，例如租户、团队或环境。

有关示例代码，请参阅[启用长期内存](long-term-enabling-long-term-memory.md)。

## 命名空间格式
<a name="memory-namespace-format"></a>

AgentCore Memory 以标准化形式存储每个命名空间，前导有一个斜杠`/`和一个尾部斜杠`/`（例如，）。`/actors/alice/`我们建议您在指定命名空间的任何地方都使用这种格式：
+  **内存策略**-`CreateMemory` 和中的命名空间模板`UpdateMemory`。
+  **写入记忆记录**-`BatchCreateMemoryRecords` 和`BatchUpdateMemoryRecords`、中每条记录`sourceNamespaces`的`BatchUpdateMemoryRecords`。`namespaces`
+  **读取记忆记录** — `namespace` 和 `namespacePath` in `ListMemoryRecords` 和`RetrieveMemoryRecords`。
+  **IAM 策略** — 条件键的值，例如`bedrock-agentcore:namespace`和`bedrock-agentcore:namespacePath`。例如，使用与应用程序发送的相同标准化值`/summaries/agent1/`，或者`/summaries/agent1/*`用于层次结构。

**注意**  
如果 IAM 策略中的命名空间值省略了前导或尾部的斜杠（例如，`summaries/agent1`或`/summaries/agent1`），则该策略将与 M AgentCore emory 操作的命名空间不匹配。

## 自定义命名空间变量
<a name="specify-custom-namespace-variables"></a>

除了内置变量 (`actorId`、`sessionId`、`memoryStrategyId`) 之外，您还可以定义自定义命名空间变量来表示应用程序的独特组织维度，例如公司、组织、团队或环境。使用自定义变量，您可以沿任意层次结构确定长期记忆的范围，而无需创建重复的策略或使内置变量过载。

例如，多租户应用程序可能需要按组织划分的内存：

```
/org/{orgname}/team/{teamname}/actor/{actorId}/session/{sessionId}/
```

在使用`namespaceKeys`参数创建或更新现有内存资源时，您可以定义自定义变量，并在运行时通过[CreateEvent](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_CreateEvent.html)操作中的`extractionConfig.namespaceVariables`字段提供其值。

**重要**  
所有自定义命名空间变量键和值都必须为小写。

### 定义命名空间密钥
<a name="specify-define-namespace-keys"></a>

创建或更新内存资源时，使用`namespaceKeys`参数声明您的自定义变量键和可选的验证规则。每个密钥必须：
+ 仅包含小写字母数字字符。
+ 不是内置变量名（`actorId``sessionId`、或`memoryStrategyId`）。
+ 长度不超过 32 个字符。

每个内存资源最多可以定义 5 个命名空间密钥，每个内存资源最多可以定义 5 个自定义变量`namespaceTemplate`。

定义命名空间键时，请记住以下几点：
+ 您可以定义任何策略都未引用的命名空间密钥来预注册密钥以备将来使用。
+ 单个命名空间密钥可以由多种策略引用。例如，`{companyname}`可以同时出现在语义策略和摘要策略中。`namespaceTemplate`
+ 策略当前引用的命名空间密钥`namespaceTemplate`无法删除。您必须先从策略中移除该引用（取消引用密钥），然后将其删除。

对于每个密钥，您可以选择指定验证规则，以限制运行时接受的值：
+  **allow** edValues-最多包含 10 个允许值的列表（区分大小写）。值必须以小写字母数字字符开头，并且仅包含小写字母数字字符、连字符和下划线。
+  **RegExpattern** — 值必须匹配的正则表达式模式（最多 64 个字符）。

同时指定`allowedValues`和时`regexPattern`，服务会强制执行这两个规则（逻辑`AND`）。

以下示例说明如何使用自定义命名空间变量和验证创建内存资源：

```
aws bedrock-agentcore-control create-memory \
    --name "MultiTenantAgentMemory" \
    --description "Memory for a multi-tenant AI agent" \
    --event-expiry-duration 10 \
    --memory-strategies '[
        {
            "semanticMemoryStrategy": {
                "name": "TenantScopedStrategy",
                "namespaceTemplates": ["/org/{orgname}/team/{teamname}/actor/{actorId}/session/{sessionId}/"]
            }
        }
    ]' \
    --namespace-keys '[
        {"key": "orgname", "validation": {"allowedValues": ["acme", "globex", "initech"]}},
        {"key": "teamname", "validation": {"regexPattern": "^[a-z][a-z0-9-]*$"}}
    ]'
```

### 在运行时提供命名空间值
<a name="specify-supply-namespace-values-at-runtime"></a>

使用[CreateEvent](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_CreateEvent.html)操作创建事件时，请在`extractionConfig.namespaceVariables`字段中传递自定义命名空间变量值：

```
aws bedrock-agentcore create-event \
    --memory-id "MultiTenantAgentMemory-n29sh5ka8r" \
    --actor-id "user123" \
    --session-id "session67" \
    --event-timestamp "$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")" \
    --payload '[
        {
            "conversational": {
                "content": {"text": "I need help debugging my application."},
                "role": "USER"
            }
        }
    ]' \
    --extraction-config '{
        "namespaceVariables": {
            "orgname": "acme",
            "teamname": "engineering"
        }
    }'
```

在长期内存提取期间，该服务会将这些值替换到命名空间模板中。

**注意**  
如果`CreateEvent`请求中未提供策略所引用的自定义命名空间变量，`namespaceTemplate`则不会对该策略进行命名空间解析。因此，该策略不会启动长期内存提取。`CreateEvent`操作仍然成功，并且该事件在短期记忆中持续存在。  
要检测这些故障，请设置销售日志并监控`NamespaceResolutionFailure`指标，该指标的报告维度为：`Operation`、`Resource``StrategyType`、，以及跳过提取`StrategyId`的维度。

### 更新命名空间密钥
<a name="specify-update-namespace-keys"></a>

使用[UpdateMemory](https://docs.amazonaws.cn/bedrock-agentcore-control/latest/APIReference/API_UpdateMemory.html)操作更新命名空间密钥时，该`namespaceKeys`值将完全替换现有的命名空间密钥。要安全更新，请使用检索当前密钥`GetMemory`，应用您的更改，然后提交完整列表。

请记住以下限制：
+ 如果您省略了仍由策略引用的密钥`namespaceTemplate`，则该服务会抛出。`ValidationException`您必须先从策略中移除密钥，`namespaceTemplate`然后才能将其从中移除`namespaceKeys`。
+ 要添加新密钥，请将其与请求中的所有现有密钥一起添加。

```
# Get the current memory configuration
current = control_client.get_memory(memoryId="MultiTenantAgentMemory-n29sh5ka8r")
existing_keys = current['memory'].get('namespaceKeys', [])

# Add a new key while preserving existing ones
existing_keys.append({
    'key': 'category',
    'validation': {
        'allowedValues': ['backend', 'frontend', 'data']
    }
})

# Update with the full set
control_client.update_memory(
    memoryId="MultiTenantAgentMemory-n29sh5ka8r",
    namespaceKeys=existing_keys
)
```