记忆不是缓存，是智能体的长期认知架构：从需求拆解到Runnable动态配置，构建可演进的LLMOps记忆系统
在一次评审会上，前端抱怨记忆接口返回的分页结构不一致，后端发现数据库软删除字段未在ORM中同步，而测试发现调用长记忆接口时，系统竟在未开启记忆模式下也触发了向量检索——问题根因是记忆模块的边界从未被真正定义。
一、记忆功能的五层需求拆解：从会话到认知
那天评审会的火药味还没散尽。前端拿出来的接口返回结构，data字段里是嵌套的list和paginator，但paginator的字段名拼成了total_pages，和文档里写的total_page对不上。我翻了两遍日志，发现调用长记忆接口时，系统居然在memory_enabled: false的配置下还触发了向量检索——那条日志的trace_id像根刺，扎在代码里，提醒我：记忆模块的边界，从来没被真正定义过。
我重新梳理了记忆功能的本质。它不是缓存，不是临时堆栈，而是智能体的长期认知架构。缓存是为性能服务的临时存储，而记忆是带语义理解、可被智能体主动调用的持久化认知结构。我们得把记忆从“数据存储”升级为“认知行为”的组成部分。于是，我将记忆功能划分为三类，每类都有明确的生命周期与访问策略：
- 短期记忆：保存当前会话的完整对话流，以内存列表形式存在，生命周期与会话绑定，会话结束即清除。
- 中期记忆：在会话结束时生成摘要，记录对话核心意图与关键事实，生命周期为单次会话的延续。
- 长期记忆：将中期记忆进一步提炼为向量嵌入，存入向量数据库，支持跨会话检索，用于历史知识的模糊匹配与上下文补充。
这三类记忆，构成了记忆系统的三层认知结构，分别对应“感知-理解-回忆”的认知过程。
五项核心需求，锚定系统边界
基于这三层结构，我提炼出记忆模块的五项核心需求，作为所有设计的基准：
- 多轮上下文保持：系统必须能维持多轮对话状态，支持
n轮上下文传递，且不因模型输入长度限制而丢失关键信息。 - 动态轮数控制：允许运行时调整传递给模型的最近对话轮数，通过配置实现，避免固定轮数带来的性能与完整性矛盾。
- 分页加载与软删除：支持分页获取历史记录，查询接口必须返回统一的分页结构，且采用软删除机制，通过
deleted_at IS NULL过滤，确保数据可追溯。 - 支持手动编辑与自动总结：用户可编辑记忆内容，系统也需支持在会话结束时自动触发摘要生成。
- 配置可实时更新：记忆功能的开关、轮数配置、模型参数等，必须支持草稿保存与实时生效，无需重启服务。
这些需求，不是功能清单，而是判断“是否属于记忆模块”的标准。我把它写成一组判断题，挂在开发看板上：
- 是否影响智能体的行为决策？ → 是，属于记忆。
- 是否可被外部系统感知？ → 是，如前端展示历史对话，属于记忆。
- 是否需要跨会话持久化？ → 是，长期记忆必须。
记忆与缓存的本质差异
我把缓存和记忆的对比列在一张表格里，贴在工位上：
| 特性 | 缓存 | 记忆 |
|---|---|---|
| 存储目的 | 提升性能 | 支持认知决策 |
| 生命周期 | 临时、可淘汰 | 持久、可引用 |
| 访问方式 | 键值对查询 | 语义匹配、向量检索 |
| 是否带语义 | 否 | 是 |
| 是否影响智能体行为 | 否 | 是 |
这张表让我清醒：当我说“记忆”时，我是在说“可被智能体理解与调用的长期知识结构”，而不是“存数据的工具”。
代码实现：定义记忆配置与接口契约
我用代码定义了记忆模块的配置接口和核心字段，确保需求与实现对齐。
{"app_id":"app_123","memory_enabled":true,"context_rounds":8,"summary_enabled":true,"pagination":{"page_size":10,"max_page":50},"memory_mode":"auto"// auto | manual | none}配置结构明确了记忆的开关、上下文轮数、摘要启用状态、分页参数。memory_mode的三种取值，分别对应自动总结、手动编辑、不启用记忆。
记忆接口的统一契约
我定义了记忆接口的返回结构，强制前后端对齐。
{"code":200,"message":"success","data":{"list":[{"id":"msg_abc","query":"你好，我想查一下订单状态","answer":"请提供订单号。","answer_tokens":5,"created_at":"2025-04-05T10:00:00Z","status":"active"}],"paginator":{"current_page":1,"page_size":10,"total_page":3,"total_record":25}}}所有记忆接口返回必须遵循此结构。status字段用于软删除标识，前端只需检查status是否为active，避免因物理删除导致数据丢失。
拦截器：未启用记忆时禁止长记忆调用
我写了一个前置校验逻辑，确保在memory_enabled: false时，长记忆接口直接返回空结果，避免无效调用。
defvalidate_memory_enabled(config):ifnotconfig.get("memory_enabled"):raiseHTTPException
