# Memory 协议 本文档定义记忆系统的数据模型、API 协议以及 Agent 中的使用方式。 --- ## 概述 记忆系统为每个用户维护两类持久化记忆： | 类型 | 用途 | 使用者 | |------|------|--------| | `user` | 个人偏好、习惯、人际关系、常去地点等 | Router Agent | | `work` | 工作项目、团队成员、工作习惯、里程碑等 | Worker Agent | 每个用户拥有**恰好两条**记忆记录（user_type 和 work_type），存储为 JSONB。 注册初始化约定： - 用户首次注册成功后，后台会自动保证 `user` 与 `work` 两条 memory 记录存在。 - `content` 初始值分别使用 `UserMemoryContent()` 与 `WorkProfileContent()` 的默认结构。 --- ## 数据模型 ### MemoryType ```json { "USER": "user", "WORK": "work" } ``` ### MemoryStatus ```json { "ACTIVE": "active", "DISABLED": "disabled" } ``` --- ## Content 数据结构 ### UserMemoryContent ```json { "occupation": "string | null", "timezone": "string | null", "primary_language": "string | null", "people": [ { "name": "string", "relationship": "string | null", "role": "string | null", "preferred_contact_channel": "string | null", "notes": "string | null", "meta": { "source": "memory_source | null", "confidence": 0.0-1.0, "last_updated_at": "datetime | null" } } ], "places": [ { "name": "string", "category": "string | null", "address": "string | null", "timezone": "string | null", "commute_minutes": "int | null", "preference": "like | neutral | avoid | null", "notes": "string | null", "meta": { ... } } ], "preferences": { "communication_style": "string | null", "language_preference": ["string"], "location_preference": "string | null", "work_lifestyle": "string | null", "notification_preference": ["string"] }, "scheduling_preferences": { "productive_windows": [{ "weekdays": [], "start": "HH:MM", "end": "HH:MM" }], "preferred_meeting_windows": [], "no_meeting_windows": [], "deep_work_windows": [], "preferred_meeting_duration_minutes": [30, 60], "meeting_buffer_minutes": "int | null", "max_meetings_per_day": "int | null", "notes": "string | null" }, "interests": ["string"], "avoid_topics": ["string"], "custom_rules": ["string"], "recurring_routines": [ { "name": "string", "description": "string | null", "cadence": "string | null", "time_windows": [], "importance": "string | null", "meta": { ... } } ] } ``` ### WorkProfileContent ```json { "occupation": "string | null", "expertise": ["string"], "preferred_tools": ["string"], "current_projects": [ { "name": "string", "description": "string | null", "status": "planned | active | paused | completed | null", "priority": "string | null", "deadline": "date | null", "collaborators": ["string"], "key_milestones": [ { "name": "string", "due_date": "date | null", "status": "string | null", "notes": "string | null" } ], "notes": "string | null", "meta": { ... } } ], "work_habits": { "available_hours": [{ "weekdays": [], "start": "HH:MM", "end": "HH:MM" }], "deep_work_blocks": [], "preferred_meeting_windows": [], "no_meeting_windows": [], "preferred_meeting_duration_minutes": [30, 60], "notification_channel": "string | null", "notes": "string | null" }, "team_members": [ { "name": "string", "role": "string | null", "relationship": "string | null", "preferred_contact_channel": "string | null", "notes": "string | null", "meta": { ... } } ], "team_context": "string | null", "work_rules": ["string"] } ``` --- ## 数据库存储 ### memories 表 | 字段 | 类型 | 说明 | |------|------|------| | `id` | UUID | 主键 | | `owner_id` | UUID | 所有者用户 ID | | `memory_type` | VARCHAR(20) | 记忆类型枚举（当前含 `user`、`work`，可扩展） | | `content` | JSONB | UserMemoryContent 或 WorkProfileContent | | `status` | VARCHAR(20) | ACTIVE / DISABLED | | `created_at` | TIMESTAMP | 创建时间 | | `updated_at` | TIMESTAMP | 更新时间 | 说明： - `source` 列已移除，不再作为行级来源标记。 - `agent_id` 列不存在。 - 来源信息如果需要保留，使用 `content` 内各条目的 `meta.source`（字段级来源）。 - 唯一性约束：同一 `owner_id` 下 `memory_type` 不能重复（`UNIQUE(owner_id, memory_type)`）。 --- ## API 端点 Base URL: `/api/v1/memories` | 方法 | 路径 | 说明 | |------|------|------| | GET | `/` | 获取用户所有记忆 | | GET | `/user` | 获取用户记忆 (UserMemoryContent) | | GET | `/work` | 获取工作记忆 (WorkProfileContent) | | PUT | `/user` | 全量更新用户记忆 | | PUT | `/work` | 全量更新工作记忆 | | PATCH | `/user` | 部分更新用户记忆 | | PATCH | `/work` | 部分更新工作记忆 | ### GET `/` 获取用户所有记忆。 **Response:** ```json { "user_memory": { ...UserMemoryContent }, "work_memory": { ...WorkProfileContent } } ``` ### GET `/user` **Response:** `UserMemoryContent | null` ### GET `/work` **Response:** `WorkProfileContent | null` ### PUT `/user` 全量更新用户记忆。 **Request:** ```json { "content": { ...UserMemoryContent } } ``` **Response:** `UserMemoryContent` ### PATCH `/user` 部分更新用户记忆。 **Request:** ```json { "content": { ...Partial UserMemoryContent } } ``` **Response:** `UserMemoryContent` --- ## Agent 中的使用 ### 职责分离 | Agent | Memory 类型 | Prompt 标记 | |-------|-------------|-------------| | Router | UserMemoryContent | `...` | | Worker | WorkProfileContent | `...` | ### Prompt 组装流程 ``` MemoriesService.get_all_memories() │ ├── user_memory: UserMemoryContent | null │ └── build_user_memory_prompt(user_memory) │ └── 注入 Router system prompt │ └── work_memory: WorkProfileContent | null └── build_work_memory_prompt(work_memory) └── 注入 Worker system prompt ``` ### Router Agent Router 负责用户意图识别和任务规划，需要根据用户偏好、习惯、人际关系来更精确地理解用户需求。 ```python build_system_prompt( agent_type=AgentType.ROUTER, user_memory=user_memory, # 注入用户个人记忆 ... ) ``` ### Worker Agent Worker 负责执行具体任务，需要根据工作项目、团队成员、工作习惯来更好地完成任务。 ```python build_system_prompt( agent_type=AgentType.WORKER, work_memory=work_memory, # 注入工作记忆 ... ) ``` --- ## 实现文件 ### Backend | 文件 | 职责 | |------|------| | `src/schemas/domain/memory_content.py` | UserMemoryContent、WorkProfileContent 模型 | | `src/schemas/domain/memory.py` | MemoryModel 聚合模型 | | `src/schemas/enums.py` | MemoryType、MemoryStatus 枚举 | | `src/models/memories.py` | SQLAlchemy ORM 模型 | | `src/v1/memories/router.py` | API 端点 | | `src/v1/memories/service.py` | 业务逻辑层 | | `src/v1/memories/repository.py` | 数据访问层 | | `src/core/agentscope/prompts/memory_prompt.py` | Agent prompt 构建 | ### Flutter | 文件 | 职责 | |------|------| | `apps/lib/features/settings/data/services/memory_service.dart` | Memory API 服务 | | `apps/lib/features/settings/ui/screens/memory_screen.dart` | Memory 界面 |