Yao 提供四个记忆命名空间，各有不同的生命周期。所有命名空间均通过任意 Hook 中的 `ctx.memory.*` 访问。
## 四个命名空间
| 命名空间 | 作用域 | 何时清除 |
|----------|--------|---------|
| `ctx.memory.context` | 当前请求 | 上下文释放时（默认 TTL：30 分钟） |
| `ctx.memory.chat` | 当前会话 | 会话结束或 TTL 到期时（默认：24 小时） |
| `ctx.memory.user` | 每个用户 | 永不清除（持久化） |
| `ctx.memory.team` | 每个团队 | 永不清除（持久化） |
**`context`** —— 临时暂存区，用于在单次请求中从 `Create` 向 `Next` 传递数据。
**`chat`** —— 随对话推进积累状态（如当前话题、任务进度）。
**`user`** —— 用户级长期偏好、计数器和历史记录。
**`team`** —— 团队内所有用户共享的状态（共享上下文、配额等）。
## 基本操作
所有命名空间共用相同的 API：
```typescript
// 写入
ctx.memory.chat.Set("topic", "machine learning");
// 读取
const topic = ctx.memory.chat.Get("topic") as string;
// 判断 / 删除
if (ctx.memory.chat.Has("topic")) {
ctx.memory.chat.Del("topic");
}
// 原子读取并删除
const token = ctx.memory.context.GetDel("one_time_token");
// 所有键 / 数量
const keys = ctx.memory.user.Keys();
const count = ctx.memory.chat.Len();
// 清空全部
ctx.memory.context.Clear();
// 带 TTL 设置（毫秒）
ctx.memory.context.Set("temp_data", value, 300_000); // 300 000 ms = 5 分钟
```
## 计数器
```typescript
const views = ctx.memory.user.Incr("page_views"); // +1，返回新值
const visits = ctx.memory.user.Incr("visits", 5); // +5
const credits = ctx.memory.user.Decr("credits", 10); // -10
```
## 常见模式
### 从 Create 向 Next 传递数据
```typescript
// Create Hook
export function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
ctx.memory.context.Set("start_time", Date.now());
ctx.memory.context.Set("mode", detectMode(ctx));
return { messages };
}
// Next Hook
export function Next(ctx: agent.Context, payload: agent.Payload): agent.Next | null {
const startTime = ctx.memory.context.Get("start_time") as number;
const mode = ctx.memory.context.Get("mode") as string;
const duration = Date.now() - startTime;
ctx.Send(`完成，耗时 ${duration}ms（模式：${mode}）`);
return null;
}
```
### 累积会话状态
```typescript
// Create Hook —— 加载会话上下文
export function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
const taskCount = ctx.memory.chat.Get("task_count") as number || 0;
const topic = ctx.memory.chat.Get("current_topic") as string;
const enriched = [
{
role: "system" as const,
content: `本次会话已完成任务：${taskCount} 个。当前话题：${topic || "未设置"}。`,
},
...messages,
];
return { messages: enriched };
}
// Next Hook —— 更新状态
export function Next(ctx: agent.Context, payload: agent.Payload): agent.Next | null {
const taskCount = ctx.memory.chat.Get("task_count") as number || 0;
ctx.memory.chat.Set("task_count", taskCount + 1);
return null;
}
```
### 追踪用户偏好
```typescript
// Next Hook —— 从 LLM 响应中检测语言偏好
export function Next(ctx: agent.Context, payload: agent.Payload): agent.Next | null {
const content = payload.completion?.content;
const text = typeof content === "string" ? content : "";
if (text.startsWith("以") || text.startsWith("您")) {
ctx.memory.user.Set("preferred_language", "zh");
}
return null;
}
// Create Hook —— 应用偏好
export function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
const lang = ctx.memory.user.Get("preferred_language") as string;
if (lang === "zh") {
return { messages, locale: "zh-cn" };
}
return { messages };
}
```
### 限流
使用无提示词的 Assistant（不配置 `prompts.yml`），只运行 Create Hook，LLM 不会被调用。
```typescript
export function Create(ctx: agent.Context, messages: agent.Message[]): agent.Create {
const calls = ctx.memory.user.Incr("api_calls_today") as number;
if (calls > 100) {
ctx.Send("今日调用次数已达上限，请明天再试。");
return { messages };
}
return { messages };
}
```
## 下一步
状态管理介绍完毕，接下来学习多 Agent 协作。
→ **[多 Agent 协作](./multi-agent)**
