开发AI智能体记忆服务，不让各用户的记忆混在一起

## 区分记忆类型，不在记忆库之间混用数据 保持不同存储知识类型之间的区别，因为摄取、检索和推理会以不同方式使用它们。 ### 对记忆进行显式建模 - 世界事实表示一般知识。 - 经历事实表示归属于某个用户或智能体的个人事件。 - 心智模型整合从多项事实中归纳出的模式。 - 允许每个记忆库携带背景上下文，以及怀疑倾向、字面主义和同理心等按1–5分衡量的倾向特征。 - 只将倾向特征应用于反思性推理；不得让它们改变事实回忆。 ### 隔离各记忆库 - 将每个记忆库视为面向单个用户或智能体的独立记忆存储。 - 防止存储、检索、推理和测试中的跨库泄漏。 - 每个API请求只操作1个记忆库。 - 任何多记忆库工作流都应由客户端编排，不得因此削弱服务器边界。 ## 分开摄取、检索和推理，并合并多种检索方法 将三项主要操作分开，同时共享模型、嵌入、实体和排序所需的稳定抽象。 ### 保持操作语义 - Retain负责摄取内容并提取事实、实体和关系。 - Recall负责检索现有记忆，不应用倾向特征。 - Reflect基于记忆和已整合的心智模型，进行将倾向特征纳入考量的推理。 - 将编排与事实提取、实体规范化、链接管理和提供商适配器分离。 ### 将检索构建为流水线 - 并行运行4种互补的检索策略：语义检索、词法BM25检索、图检索和时间检索。 - 在使用交叉编码器重新排序之前，先通过倒数排名融合合并各项排序结果。 - 将图扩展置于检索接口之后，使替代策略仍可互换。 - 通过职责单一的封装器支持本地和远程模型、嵌入及重新排序提供商。 ### 同步API契约 - 更改端点后，重新生成OpenAPI规范。 - 规范更改后，重新生成所有受支持的客户端SDK，包括Python、TypeScript和Rust。 - 更改API参数时，同时更新代理路由、请求值提取、SDK调用、客户端类型和所有使用该参数的接口。 ## 编写在PostgreSQL和Oracle上都能运行的迁移 让所有受支持的数据库共用同一套迁移历史，同时明确处理方言差异。 ### 定义修订版本 - 为每项迁移赋予唯一的12个字符十六进制修订标识符，并让`down_revision`指向其前一个修订版本。 - 使升级和降级行为保持配对。 - 通过单一的方言路由器进行分派，由它根据当前连接选择相应实现。 - 缺少分派器时，应让迁移结构测试失败。 ### 实现每种方言 - 分别为PostgreSQL和Oracle兼容数据库提供独立的升级函数和降级函数。 - 配置了租户架构时，应在原始PostgreSQL SQL中使用该架构进行限定。 - 只有迁移框架无法建模的数据库操作形式，例如特殊的向量、文本或分区操作，才使用驱动程序级执行。 - 如果某项迁移确实只适用于1种方言，应有意省略另一个槽位；绝不能因疏忽而将其留空。 - 评审时考虑不同方言之间的架构漂移。 ### 验证执行 - 对基础架构和所有租户架构运行迁移。 - 同时支持只对1个具名租户架构进行定向运行，以便集中验证。 - 如果服务启动时会自动运行迁移，应针对所有受支持的方言和租户范围测试启动过程。 ## push之前，先通过必需的检查和代码审查 每次实现变更后都使用标准工具链，并区分阻断性缺陷与建议性清理项。 ### 运行必需检查 - 更改Python或TypeScript后，运行格式化、代码检查和类型检查。 - 将未使用的导入和变量、孤立的客户端文件以及未列入清单的软件包依赖项视为阻断性失败。 - 完整但未使用的函数和有意保持宽泛的组件库导出应视为建议项，除非项目政策将其提升为阻断项。 - 通过代码库的标准命令运行单元测试、API集成测试和相关基准测试。 - 按需重新生成API规范和客户端，然后确认没有未提交的生成文件差异残留。 ### 发布前进行评审 - 实现完成后进行结构化代码评审。 - 修复所有涉及测试缺失、死代码、类型安全、数据隔离或生成文件漂移的必改问题。 - 在所有必改问题解决之前，不得推送代码或创建变更请求。 - 不要手动添加未发布的变更日志条目；由发布流程创建带版本号的条目。 ## 确定性逻辑直接测试，模型回答交给另一个模型判定 根据行为是由机制确定，还是依赖模型解释来选择断言。 ### 直接测试确定性机制 - 对数量、必填字段、提示词组装、抑制逻辑和注入的子字符串使用直接断言。 - 使用模拟模型或纯函数，让大多数测试保持快速。 - 为模型行为测试配套编写单元测试，覆盖其周边的确定性准备过程。 ### 评判模型的语义行为 1. 为单提供商核心模型作业标记语义测试；将提供商矩阵标记保留给跨提供商验收。 2. 调用实际配置的流水线，而不是模拟对象。 3. 使用评估所需的语义标签概括响应。 4. 让独立的评判模型判断响应是否满足所提供上下文中的明确标准。 5. 绝不能使用与被测调用相同的模型调用进行评判。 - 对分类、归属、维度保持和指令遵循使用评判模型断言。 - 对于在不同模型和运行之间可以合理变化的行为，不要硬编码完全匹配的字符串或枚举值。 ## 把API变更同步到所有客户端，并为新的集成添加CI 只有当运行时行为、测试、持续集成、发布注册和客户端接口保持一致时，集成才算完成。 ### 更新API使用方 - 添加请求字段时，在代理路由中提取它并传给SDK调用。 - 更新客户端方法类型，以及所有提供或读取该字段的接口。 - 将每个请求限定于1个记忆库，并为多记忆库用例保留客户端编排。 ### 完成集成 - 添加模拟或实际调用外部框架接口的测试，并验证该集成能正确调用记忆服务。 - 不要将仅测试辅助函数的单元测试视为充分的集成覆盖。 - 添加一项按变更范围触发的持续集成作业，用于构建、安装依赖项和运行集成测试。 - 在标准发布工作流中注册该集成。 - 对结构化数据使用类型化结构而不是原始字典，并避免返回包含多个元素的元组。 - 在测试、CI变更检测或发布注册缺失时，不得合并或发布。 ## 先决定新设置能否按租户或记忆库调整，再添加 实现前对每项设置进行分类，使覆盖范围和文档保持一致。 ### 选择配置级别 - 按全局环境值、租户覆盖值、记忆库级数据库覆盖值的层级顺序解析配置。 - 对模型提供商、模型名称、API密钥、操作专用选项和客户专用功能标志使用分层配置。 - 数据库地址、主机、端口、全局并发限制和系统级标志应在服务器级保持静态。 - 不得将静态字段加入可远程配置字段集合。 ### 完整添加字段 1. 定义环境变量名称和默认值。 2. 向中央配置对象添加类型化字段。 3. 只有当租户或记忆库覆盖有效时，才将其加入可配置字段允许列表。 4. 从环境中初始化该字段。 5. 只有需要命令行覆盖时，才添加命令行选项。 6. 通过逐库解析器读取分层值，通过全局访问器读取静态值。 7. 更新配置参考和环境模板，写明说明、默认值和层级状态。 8. 同步所有随附的环境模板副本，并使模板同步测试持续通过。 - 绝不能在文档、模板、日志或测试中暴露真实凭据值。