qzl/social-app

Fork 0

Files

T

qzl d22ded21f8 refactor: 重构 schemas 结构，统一枚举定义

2026-03-25 12:36:31 +08:00

7.6 KiB

Raw Blame History

Memory 协议

本文档定义记忆系统的数据模型、API 协议以及 Agent 中的使用方式。

概述

记忆系统为每个用户维护两类持久化记忆：

类型	用途	使用者
`user`	个人偏好、习惯、人际关系、常去地点等	Router Agent
`work`	工作项目、团队成员、工作习惯、里程碑等	Worker Agent

每个用户拥有恰好两条记忆记录（user_type 和 work_type），存储为 JSONB。

注册初始化约定：

用户首次注册成功后，后台会自动保证 user 与 work 两条 memory 记录存在。
content 初始值分别使用 UserMemoryContent() 与 WorkProfileContent() 的默认结构。

数据模型

MemoryType

{
  "USER": "user",
  "WORK": "work"
}

MemoryStatus

{
  "ACTIVE": "active",
  "DISABLED": "disabled"
}

Content 数据结构

UserMemoryContent

{
  "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

{
  "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:

{
  "user_memory": { ...UserMemoryContent },
  "work_memory": { ...WorkProfileContent }
}

GET `/user`

Response: UserMemoryContent | null

GET `/work`

Response: WorkProfileContent | null

PUT `/user`

全量更新用户记忆。

Request:

{
  "content": { ...UserMemoryContent }
}

Response: UserMemoryContent

PATCH `/user`

部分更新用户记忆。

Request:

{
  "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 负责用户意图识别和任务规划，需要根据用户偏好、习惯、人际关系来更精确地理解用户需求。

build_system_prompt(
    agent_type=AgentType.ROUTER,
    user_memory=user_memory,  # 注入用户个人记忆
    ...
)

Worker Agent

Worker 负责执行具体任务，需要根据工作项目、团队成员、工作习惯来更好地完成任务。

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 界面

7.6 KiB Raw Blame History