backend-python/docs/AGNO-memory-integration.md

# AGNO 长期记忆集成说明

## 目标

- 终结当前自建的长期记忆逻辑，改用 AGNO 官方 memory 路径（参考 https://docs.agno.com/context/memory/overview 和 https://docs.agno.com/context/memory/working-with-memories/overview）。
- UX 端保留“长期记忆”开关，控制 `enableLongTermMemory` 参数，后台只有在这个标记及 `enable_long_term_memory` 为 true 时才读写记忆。
- 目前仅使用 Supabase 作为数据源，但保留 provider 等级的结构以便未来扩展。
- 后端位于 `backend-python`，由它调用 AGNO memory manager 与 Supabase 同步。

## 现行逻辑概要

1. 设置页的开关同步到 `chatStore.memoryEnabled`，并在 `/api/stream-chat` 请求中附带 `enableLongTermMemory`；后端只有这个字段为 true（与 `enable_long_term_memory` 相等）且请求包含合法 `userId` 时才会启动记忆读写。
2. 记忆写入/读取走 AGNO memory manager，所有流量都到 `backend-python` 的 agent（主 agent 或 lite agent）；前端只负责传 Supabase 配置与开关状态。
3. Supabase 参数由前端通过 `databaseProvider`/`databaseConfig` 传递，后端在 `agent_registry._build_memory_kwargs` 中识别 provider 为 `supabase` 才创建 `PostgresDb` 连接并设置 `update_memory_on_run=True`。
4. 多 agent 共用同一 Supabase 数据库且启用 `update_memory_on_run`，任何一个 agent 写入的记忆都对其他 agent 可见。

## 数据库/表结构说明

- AGNO memory 会在 Supabase 内部自动建表（通过 `postgresql://postgres:<service-role>@db.<project>.supabase.co:5432/postgres?sslmode=require`），无需手动创建。
- 未来新增 provider 只需在 UI/配置里增加选项，并在 `agent_registry.build_memory_agent` 中传入 provider/model 即可。

## 需要注意

- Supabase 变更时同步前端的 database 配置与 `backend-python/.env`（比如 `DATABASE_PROVIDER`）。
- “长期记忆”开关与 `enable_long_term_memory` 必须一致：开关决定前端是否传参，后端才有开关值可读。
- 记忆数据不再存到 local storage 或临时会话，只存在 AGNO + Supabase。

## 记忆优化与多 agent 共享

- 记忆优化通过 `agent.memory_manager.optimize_memories(..., strategy=MemoryOptimizationStrategyType.SUMMARIZE)` 压缩 token，默认以当前 agent 的 lite 模型为标准。
- 多 agent 共享只要统一指向 Supabase 并打开 `update_memory_on_run`，任何一个 agent 写入的记忆都对其它 agent 可见。
- `memory_service.optimize_user_memories` 允许传 `provider/model/base_url/api_key`，方便手动调度时传 agent lite metadata。

## 自动优化策略

- `StreamChatService` 完成 run 后检查 `request.enable_long_term_memory`、`user_id` 与 lite agent memory_manager；满足条件才继续。
- 若记忆数 ≥ 50 且距上次优化 ≥ 12 小时，后台自动执行 `memory_manager.optimize_memories(..., strategy=SUMMARIZE, apply=True)`，以 `asyncio.to_thread` 在后台运行，避免每次会话都跑。
- 这个流程遵循 AGNO “batch memories should auto-summarize” 最佳实践，并只在 `enable_long_term_memory` 为 true 时有效。

## 常见 WARN：Supabase credentials missing

- 看到 `Supabase credentials are missing; cannot initialize AGNO memory store.` 或 `Memory requested but Supabase memory store is unavailable.` 时说明 ENV 里缺 `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY`（service-role key，必须在 Supabase 控制台拿）。
- 只有在 `enable_long_term_memory`（即开关）为 true 的情况下才会触发该逻辑；关闭开关或让前端传 `enableLongTermMemory: false` 就不会触发 WARN。
- 准备好 credentials 后再打开放记忆功能，AGNO 会自动在 Supabase 建表，警告也会消失。

## 备选 Agent 与 lite 模型兜底

- 记忆 API 使用当前上下文的 lite 配置：前端在 `/api/stream-chat` 中附加 `memoryProvider/memoryModel/memoryBaseUrl/memoryApiKey`（优先取当前 agent 的 lite 设置，否则 fallback 到默认 agent）。
- 主 agent 即便用高质量模型，记忆读写/优化也始终沿用 lite 配置，既避免高 token 成本，又保留未来切 provider 的弹性。
- 无论主 agent 还是 lite fallback，只要 `enable_long_term_memory` 关闭、请求少了 `userId` 或 memory_manager 无效，就不会做记忆操作。