记忆系统 - PAI 文档

概述

PAI 为每位用户维护独立的长期记忆库，实现跨会话持久化。当前实现采用 PostgreSQL 保存业务真值，Milvus 保存向量索引；写入时先落真值，再由独立 memory_index_worker 异步同步索引，读取时优先做相关记忆召回，再回 PostgreSQL 取真值内容。

真值与索引解耦

PostgreSQL 保存正式记忆，Milvus 只负责召回，不承担业务真值职责。

双通道写入

Agent 显式工具调用 + 对话后异步提取，最终统一写入长期记忆表。

异步索引同步

记忆写入后先标记为 DIRTY，再由 memory_index_worker 批量生成 embedding 并写入 Milvus。

检索模式可切换

支持 full_inject 和 dense 两种模式，可按环境配置切换。

记忆类型

系统支持以下 5 种长期记忆类型：

类型	说明	示例
`preference`	稳定偏好与习惯	喜欢川菜、偏好简洁回复风格
`fact`	持久事实信息	常住武汉、喜欢乌龙茶
`goal`	长期目标与计划	年底前考过 N1
`project`	长期项目上下文	正在开发 PAI 项目
`constraint`	长期规则约束	回复尽量中文、输出不超过 200 字

profile 类型用于用户档案字段，不进入长期记忆表，避免昵称、AI 名称、emoji 等身份信息与记忆系统混用。

数据模型

长期记忆保存在 long_term_memories 表：

CREATE TABLE long_term_memories (
    id                SERIAL PRIMARY KEY,
    user_id           INTEGER NOT NULL REFERENCES users(id),
    conversation_id   INTEGER REFERENCES conversations(id),
    source_message_id INTEGER REFERENCES messages(id),

    memory_key        VARCHAR(160) NOT NULL,
    memory_type       VARCHAR(40) DEFAULT 'fact',
    content           VARCHAR(1000),
    importance        INTEGER DEFAULT 3,
    confidence        FLOAT DEFAULT 0.8,

    is_active         BOOLEAN DEFAULT TRUE,
    last_accessed_at  TIMESTAMPTZ,
    expires_at        TIMESTAMPTZ,

    vector_status     VARCHAR(20) DEFAULT 'DIRTY',
    vector_synced_at  TIMESTAMPTZ,
    vector_error      TEXT,
    vector_model      VARCHAR(120),
    vector_version    INTEGER,
    vector_text_hash  VARCHAR(64),

    created_at        TIMESTAMPTZ NOT NULL,
    updated_at        TIMESTAMPTZ NOT NULL,

    UNIQUE(user_id, memory_key)
);

消息表同时追踪每条用户消息的记忆处理状态：

PENDING -> PROCESSED
        -> FAILED
        -> SKIPPED

双通道写入

通道一：Agent 显式工具

Agent 在对话过程中可直接调用以下工具：

工具	功能
`memory_save`	创建或覆盖一条记忆
`memory_append`	追加内容到已有记忆
`memory_delete`	删除指定记忆
`memory_list`	查询用户当前记忆

这条路径直接写 PostgreSQL 真值，并同步标记向量状态。

通道二：异步提取管道

每轮对话结束后，系统会调度长期记忆提取管道；独立 memory_worker 也会补扫 PENDING / FAILED 的用户消息，确保最终一致性。

三阶段提取流程

候选提取 (extract_memory_candidates)

LLM 以当前用户消息为触发源，结合会话摘要与完整上下文提取结构化候选记忆。助手回复仅作上下文，不作为事实来源。候选包含 op、memory_type、key、content、importance、confidence、ttl_days 等字段。

精炼去重 (_llm_refine_memory_candidates)

第二轮 LLM 调用结合用户已有记忆，对候选逐条裁决：保留、合并到已有记忆、复用既有 key，或直接丢弃。

持久化写入 (upsert_long_term_memories)

最终将候选写入 long_term_memories，并根据 key 匹配或语义重复阈值执行覆盖、合并、删除和去重。

提取边界

会被保留为长期记忆的内容：

稳定偏好和习惯
30 天后仍有价值的事实信息
长期目标、长期项目、长期约束
用户明确要求“以后都按这个来”的长期规则

不会进入长期记忆的内容：

短期提醒、待办和执行步骤
今晚、明天、这周、本月这类明确时间窗要求
仅在短期窗口内成立的条件规则
天气快照、日/周/月汇总、短期财务统计
可用工具清单、系统状态、技术实现细节、流式开关等内部信息
昵称、AI 名称、emoji 等身份档案字段
明显错误的档案槽位值，例如把纯数字写进城市、国家、省份等字段

例如“下雨时提醒我带伞”可视为长期约束；“明后天有雨时提醒我带伞”属于短期规则，不会写入长期记忆。

事实来源与硬过滤

提取由 user 消息驱动；完整上下文和会话摘要只用于判断这条信息是否稳定、是否覆盖旧记忆
assistant 回复不会被当作新的事实来源，不会单独生成长期记忆
当前实现会对一批已知噪声 key 做硬过滤，例如 weather-date_*、tool-*、system-*、reminder-last_*、finance-monthly_* / weekly_* / daily_*
对工具清单、天气快照、流式输出设置、系统格式说明等内容，即使误进入候选，也会在写入和读取阶段被再次过滤

这意味着即便历史库里遗留了旧的脏记忆，memory_list、召回注入和后台清洗也会优先把它们排除在外。

向量同步

长期记忆写入 PostgreSQL 后，会统一标记为 vector_status = DIRTY。独立 memory_index_worker 定时扫描 DIRTY / FAILED 记录并执行：

构造索引文本：[{memory_type}] {memory_key}: {content}
调用 embedding 模型生成向量
upsert 到 Milvus collection
成功后将对应行更新为 SYNCED

删除或失效记忆时，也会同步删除或刷新 Milvus 中的索引项。

检索流程

系统支持两种读取模式，由 LONG_TERM_MEMORY_RETRIEVE_MODE 控制：

模式	行为
`full_inject`	直接注入当前用户全部有效长期记忆
`dense`	先向量召回，再回 PostgreSQL 取真值并重排

`dense` 模式流程

将 query = 用户当前问题 + 会话摘要
调用 embedding 模型生成 query vector
去 Milvus 搜索 top-N memory_id
回 PostgreSQL 取这些 memory_id 的真值内容
应用层按 retrieval_score / importance / confidence / recency / exact_key_bonus 重排
返回 top-k 注入 prompt

这意味着：

PostgreSQL 决定“这条记忆真实是什么”
Milvus 决定“当前最该召回哪几条记忆”

如果向量检索不可用，系统会自动回退到词法扫描，不会中断主对话链路。

生命周期管理

TTL 过期

默认 TTL：730 天
支持按条目设置 ttl_days
检索时自动过滤已过期记忆

语义去重

阈值	用途
`0.82`	判定为语义重复，优先复用已有记忆
`0.90`	写入后强制合并高相似度冗余副本

后台清洗

系统提供 consolidate 能力，可按用户批量审查长期记忆，执行保留、删除、合并和规范化更新。

后台进程

`memory_worker`

扫描 PENDING / FAILED 消息并重新执行提取管道，保证消息侧最终一致性。

`memory_index_worker`

扫描 DIRTY / FAILED 记忆并同步 Milvus，保证向量索引最终一致性。

配置参数

参数	默认值	说明
`LONG_TERM_MEMORY_ENABLED`	`true`	总开关
`LONG_TERM_MEMORY_RETRIEVE_MODE`	`full_inject`	记忆读取模式，支持 `full_inject` / `dense`
`LONG_TERM_MEMORY_MIN_CONFIDENCE`	`0.75`	写入最低置信度
`LONG_TERM_MEMORY_MAX_WRITE_ITEMS`	`6`	单轮最多写入条数
`LONG_TERM_MEMORY_RETRIEVE_LIMIT`	`6`	注入 prompt 的记忆条数上限
`LONG_TERM_MEMORY_RETRIEVE_SCAN_LIMIT`	`80`	检索候选扫描上限
`LONG_TERM_MEMORY_DEFAULT_TTL_DAYS`	`180`	默认过期天数
`LONG_TERM_MEMORY_DEBOUNCE_SEC`	`12`	异步提取延迟
`LONG_TERM_MEMORY_EXTRACT_TIMEOUT_SEC`	`90`	提取超时
`LONG_TERM_MEMORY_UPSERT_TIMEOUT_SEC`	`90`	写入超时
`LONG_TERM_MEMORY_EXTRACT_CONTEXT_MAX_CHARS`	`8000`	提取上下文窗口
`LONG_TERM_MEMORY_SCAN_ENABLED`	`true`	`memory_worker` 开关
`LONG_TERM_MEMORY_SCAN_INTERVAL_SEC`	`120`	后台扫描间隔
`MEMORY_INDEX_WORKER_ENABLED`	`false`	`memory_index_worker` 开关
`MEMORY_INDEX_WORKER_INTERVAL_SEC`	`30`	向量同步轮询间隔
`MEMORY_INDEX_WORKER_BATCH_SIZE`	`32`	每轮同步批量大小
`MEMORY_EMBEDDING_MODEL`	`text-embedding-3-small`	记忆 embedding 模型
`MEMORY_EMBEDDING_DIM`	`1536`	向量维度
`MEMORY_MILVUS_ENABLED`	`false`	是否启用 Milvus 检索
`MEMORY_MILVUS_URI`	-	Milvus 连接地址
`MEMORY_MILVUS_COLLECTION`	`memory_text_v1`	记忆向量 collection

关键文件

文件	职责
`backend/app/models/memory.py`	记忆真值模型与向量状态字段
`backend/app/services/memory.py`	提取、精炼、写入、检索、去重、清洗
`backend/app/services/memory_embeddings.py`	embedding 调用封装
`backend/app/services/memory_vector_store.py`	Milvus collection / upsert / search
`backend/app/services/message_handler.py`	记忆注入与异步提取调度
`backend/app/services/tool_executor.py`	`memory_save` / `memory_append` / `memory_delete` / `memory_list`
`backend/app/memory_worker.py`	后台消息补扫
`backend/app/memory_index_worker.py`	后台索引同步
`backend/app/core/config.py`	记忆与 Milvus 配置参数

Documentation Index

​概述

真值与索引解耦

双通道写入

异步索引同步

检索模式可切换

​记忆类型

​数据模型

​双通道写入

​通道一：Agent 显式工具

​通道二：异步提取管道

​三阶段提取流程

​提取边界

​事实来源与硬过滤

​向量同步

​检索流程

​dense 模式流程

​生命周期管理

​TTL 过期

​语义去重

​后台清洗

​后台进程

​memory_worker

​memory_index_worker

​配置参数

​关键文件

概述

记忆类型

数据模型

双通道写入

通道一：Agent 显式工具

通道二：异步提取管道

三阶段提取流程

提取边界

事实来源与硬过滤

向量同步

检索流程

`dense` 模式流程

生命周期管理

TTL 过期

语义去重

后台清洗

后台进程

`memory_worker`

`memory_index_worker`

配置参数

关键文件