feat: 重构 memory 系统，支持 user memory 和 work memory 分离
This commit is contained in:
qzl
@@ -0,0 +1,322 @@
|
||||
# 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 |
|
||||
| `agent_id` | UUID | 关联 Agent ID（可选） |
|
||||
| `memory_type` | VARCHAR(20) | 记忆类型枚举（当前含 `user`、`work`，可扩展） |
|
||||
| `content` | JSONB | UserMemoryContent 或 WorkProfileContent |
|
||||
| `status` | VARCHAR(20) | ACTIVE / DISABLED |
|
||||
| `created_at` | TIMESTAMP | 创建时间 |
|
||||
| `updated_at` | TIMESTAMP | 更新时间 |
|
||||
|
||||
说明：
|
||||
- `source` 列已移除，不再作为行级来源标记。
|
||||
- 来源信息如果需要保留，使用 `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 | `<!-- USER_MEMORY_START -->...<!-- USER_MEMORY_END -->` |
|
||||
| Worker | WorkProfileContent | `<!-- WORK_MEMORY_START -->...<!-- WORK_MEMORY_END -->` |
|
||||
|
||||
### 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/memories/memory_content.py` | UserMemoryContent、WorkProfileContent 模型 |
|
||||
| `src/schemas/memories/__init__.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 界面 |
|
||||
Reference in New Issue
Block a user