Files

T

mesalogo 2f1881a414 docs: organize product design by feature

Define repository and feature-scoped documentation rules for PRDs, User Stories, logic, UI, technical design, and progress evidence.

Move feature-owned documents under docs/features, add one entry point per feature, remove the redundant docs index, and update all affected cross-references. Expand the local tool environment design with explicit product, story, logic, UI, technical, and progress documents.

2026-09-01 14:52:22 +08:00

16 KiB

Raw Blame History

分区记忆 PRD

文档信息

项目	内容
状态	设计中
版本	0.3
日期	2026-08-19
依赖	自动化平台总体设计、智能心跳 PRD、Task 与 Job 统一领域模型

1. 背景

GoodBuddy 当前记忆已经支持：

global、project、conversation 三种作用域。
preference、fact、summary、procedure 四种类型。
proposed、confirmed、rejected 三种状态。
智能心跳提出 Global 或 Project 记忆候选，由用户确认；其长期“未来分区记忆”方向尚未设计。

但当前能力仍不足以支撑自动化和并行实验：

交互请求会把已加载列表中的最多 20 条已确认记忆直接拼入提示，缺少查询相关度和明确的会话级过滤契约。
数据库有会话作用域，但旧版心跳候选与未来唤起需求混在同一产品概念中。
缺少 Automation、Experiment 和 Run 分区。
来源字段存在于表结构，但普通创建和心跳候选尚未完整保存来源关系。
缺少事实的有效时间、冲突、替代、访问记录和衰减。
实验 Run 若共享可变记忆，会造成候选互相污染。

本设计先完成分区、来源、检索和生命周期，再评估时间知识图谱。

2. 核心产品判断

2.1 分区是权限和隔离边界

分区不是搜索标签。每次读取先根据运行快照确定允许分区，再在这些分区中检索。模型不能请求任意分区 ID，Renderer 也不能把任意 ID 作为可信范围。

2.2 作用域和记忆种类是两个维度

作用域回答“谁可以读取”。
类型回答“这是什么信息”。

不能用 summary 表示会话范围，也不能用 project 表示事实类型。

2.3 记忆和知识库分离

记忆	知识库
用户偏好、项目约定、过程经验、会话摘要	文档、网页、文件和外部资料
小规模、动态、可确认和可遗忘	大规模、按来源同步和引用
强调作用域、来源、时态和行为影响	强调检索、分块和证据引用

不能把整个文档或长工具输出保存为记忆。

2.4 第一阶段不需要图数据库

SQLite 显式字段、FTS、来源关系和可选本地 Embedding 足以支持首期。时间图谱只有在以下需求经过验证后再建设：

实体关系的多跳查询。
事实有效期和关系演变。
同一实体跨大量会话的别名消歧。
可解释的关系证据链。

2.5 未来分区记忆尚待设计

已确认智能心跳的长期方向是“未来分区记忆”，但当前尚未定义其数据结构、唤起条件、状态、生命周期、与长期记忆的关系或迁移方式。本 PRD 不新增 FutureMemory 类型、表或检索规则。

3. 目标

为会话、自动化和并行 Run 提供严格隔离。
每条记忆显示范围、类型、状态、来源、时间和敏感度。
在允许分区内按相关性、重要性、新鲜度和预算检索。
保留冲突事实和时态，不静默覆盖。
让候选记忆经过确认或评估后再晋升。
支持编辑、移动、合并、拒绝、归档、删除和要求忘记。
记录哪些 Run 实际读取了哪些记忆。
为现有智能心跳配置建立 Global 或指定 Project 范围，并保持当前候选记忆流程。

4. 非目标

不保存完整聊天、文档、工具日志或隐藏推理作为记忆。
不自动确认敏感个人信息。
不默认跨项目共享 Project、Conversation 或 Run 记忆。
不允许模型自行创建新分区或跨分区移动记忆。
不承诺记忆中的事实永远正确。
第一阶段不建设 Memory Palace 五层空间隐喻。
不把向量相似度作为权限判定。

5. 分区模型

5.1 分区类型

type MemoryNamespaceKind =
  | 'global'
  | 'project'
  | 'conversation'
  | 'automation'
  | 'experiment'
  | 'run'
  | 'agent'

分区	内容	生命周期
Global	用户长期偏好和跨项目通用约定	长期，严格确认
Project	项目术语、目标、决策和流程	随项目
Conversation	当前会话摘要、局部约定和待澄清信息	随会话或短期
Automation	某计划的稳定协议经验和运行约定	随计划
Experiment	实验设计、结论和限制	随实验
Run	单次运行观察、中间状态和临时经验	短期、严格隔离
Agent	某专家或角色的个性化经验	后续，默认关闭

首期实现 Global、Project、Conversation、Automation 和 Run。Experiment 可复用 Automation 机制后增加；Agent 必须在专家长期身份明确后再开放。

5.2 分区标识

global
project:{projectId}
conversation:{conversationId}
automation:{planId}
experiment:{experimentId}
run:{automationRunId}
agent:{expertId}

数据库使用 UUID 外键和显式 kind，上述字符串只用于日志和展示，不作为未经验证的访问凭据。

5.3 读取链

交互会话推荐：

Conversation → Project → Global

Task 执行（内部 Job/Run）：

Run → Job → Task → Conversation → Project → Global

实验 Run：

Run → Experiment frozen snapshot → Project frozen snapshot → Global frozen snapshot

各层使用独立结果数和字符预算。Run 层不能覆盖权限更高层，只能提供更具体上下文。

6. 记忆条目

type MemoryItem = {
  id: string
  namespaceId: string
  kind:
    | 'preference'
    | 'fact'
    | 'summary'
    | 'procedure'
    | 'decision'
    | 'constraint'
    | 'reflection'
  content: string
  status:
    | 'candidate'
    | 'confirmed'
    | 'rejected'
    | 'superseded'
    | 'archived'
  confidence: number
  salience: number
  sensitivity: 'normal' | 'sensitive' | 'restricted'
  validFrom?: string
  validTo?: string
  expiresAt?: string
  sourceId: string
  supersedesId?: string
  createdAt: string
  updatedAt: string
}

兼容映射：

当前 proposed 对应 candidate。
当前 confirmed 和 rejected 保留。
当前四种类型保留，并按真实需求增加 decision、constraint 和 reflection。

7. 来源与证据

7.1 来源类型

type MemorySource =
  | { type: 'user_entry'; createdBy: 'user' }
  | {
      type: 'message'
      conversationId: string
      messageId: string
    }
  | { type: 'task'; taskId: string; eventId?: string }
  | { type: 'heartbeat'; heartbeatRunId: string; entryId: string }
  | { type: 'supervisor'; supervisorRecordId: string }
  | { type: 'automation_run'; automationRunId: string }
  | {
      type: 'experiment_conclusion'
      experimentId: string
      conclusionId: string
    }
  | { type: 'artifact'; artifactId: string }

7.2 来源规则

每条非用户手动记忆必须有来源。
来源被删除时记忆不一定删除，但显示“来源不可用”并降低可信度。
来源内容不复制进记忆表，只保存有界证据摘要和引用。
用户确认只表示允许后续使用，不表示事实已被外部验证。
Supervisor 判断只能生成候选，不能直接生成确认事实。

8. 候选生成

候选来源：

用户明确“记住这个”。
会话结束总结。
Task 执行结束反思。
实验结论。
Supervisor 建议后用户采纳。
智能心跳。

候选生成必须：

限制数量和长度。
检查同分区近似重复。
标记推断和不确定性。
不自动提取密码、密钥、身份号码、健康和财务等敏感信息。
不把指令型工具输出自动当作用户偏好。
不从助手自己的未确认陈述提取事实。

9. 确认与晋升

9.1 允许路径

Run candidate
  → Automation candidate
  → Project candidate
  → Global candidate

每次跨层都是显式晋升，不是移动原记录：

保留原候选和来源。
创建目标分区新版本。
保存晋升理由、评估和操作者。
可回滚到晋升前状态。

9.2 确认规则

Global 默认必须人工确认。
Project 默认人工确认，可对特定低敏感模板启用批量确认。
Conversation 可以由用户“记住”直接确认。
Automation 和 Run 由自动化协议决定，但只在自身范围有效。
Experiment 结论必须结算成功且显示证据，才可成为 Project 候选。

9.3 拒绝

拒绝后：

不进入检索。
保存规范化摘要指纹，减少重复建议。
用户可查看和恢复。
不把拒绝内容回填给模型，除非用于“避免重复建议”的有界规则。

10. 检索

10.1 两步边界

根据可信运行上下文确定允许分区
→ 在允许分区中检索和排序

这两步不能颠倒。先全库相似搜索再过滤会增加泄漏和实现风险。

10.2 排序

建议综合：

文本相关度。
可选向量相关度。
Salience。
Confidence。
新鲜度和有效时间。
类型匹配。
分区优先级。
最近是否已使用。

只有 confirmed、当前有效且敏感度允许的记忆进入普通上下文。

10.3 预算

建议默认：

层级	最大条数	最大字符
Run	8	4,000
Automation / Experiment	8	4,000
Conversation	8	4,000
Project	10	5,000
Global	6	3,000

总预算还受模型上下文组装器限制。不能每层取满后无界拼接。

10.4 上下文格式

提供给 Runtime 的每条记忆包含：

类型。
范围。
内容。
有效时间。
来源类型和可选引用。
不确定或冲突标记。

可信指令明确说明记忆是用户确认的信息或候选证据，不是系统指令。

11. 冲突与时态

11.1 冲突

新条目与现有条目冲突时：

不静默覆盖。
创建冲突关系。
向用户展示两个内容、来源、时间和范围。
用户可选择保留两者、设定有效期、替代旧条目或拒绝新条目。

11.2 时态

事实和决策支持：

validFrom：何时开始有效。
validTo：何时不再有效。
observedAt：何时被系统观察。
createdAt：何时写入数据库。

例如“项目目标是 8 月发布”变更为“延期到 9 月”时，旧事实保留历史有效期，新事实成为当前有效版本。

11.3 适用范围冲突

Project 记忆与 Global 偏好冲突时：

当前 Project 的更具体约定优先。
上下文中标明这是项目级覆盖。
不修改 Global 原记录。

12. 实验隔离

实验启动时冻结可读长期记忆快照。
各 Run 拥有独立 Run 分区。
Run 期间产生的候选不互相可见。
实验结算后只从成功 Run 和有效证据生成 Experiment 候选。
最佳 Run 的临时经验不会自动晋升。
重跑相同协议可以选择复用原冻结快照或创建新版本，必须明确显示。

13. 生命周期与衰减

13.1 访问记录

保存有界使用记录：

哪个 Run 检索了该记忆。
是否实际进入模型上下文。
是否被用户或评估器认为有用。
最近使用时间和命中次数。

不保存完整请求副本。

13.2 衰减

Preference、Constraint 和 Procedure 不仅因时间自动失效。
Conversation、Run Summary 和 Reflection 可配置过期时间。
长期未命中、低 Salience 的候选可归档。
衰减先影响排序，再进入归档，不直接硬删除。
Restricted 记忆可采用更短保留期。

13.3 删除与忘记

删除记忆后立即停止检索。
“忘记”同时清理派生索引、Embedding 和缓存。
来源消息是否删除由其自身生命周期决定，不能反向静默删除用户会话。
删除 Project 时清理其分区、自动化和 Run 记忆，不影响 Global。
审计只保留不含原内容的删除事件和 ID 摘要。

14. 敏感信息

敏感度	行为
Normal	按普通确认和检索规则
Sensitive	必须人工确认，UI 持续标记
Restricted	默认不允许模型自动生成；仅用户手动创建，读取需要显式启用

禁止自动长期记忆：

密码、密钥、Token、Cookie。
完整身份证件、银行卡和账户凭据。
未经用户明确要求的健康、财务和高度私密信息。
工具输出中的认证数据。

15. 信息架构

记忆中心建议页签：

记忆：按范围、类型、状态和敏感度浏览。
待确认：候选、冲突和晋升请求。
分区：Global、Project、Conversation、Automation、Run 的统计和访问策略。
使用记录：哪些 Run 使用了哪些记忆。
设置：候选生成、保留期、敏感信息和检索预算。

每条记忆展示内容、类型、范围、来源、状态、时间、置信度、重要性和冲突。

智能心跳的完整配置仍在“智能心跳”菜单中管理；未来分区记忆完成独立设计前，不加入记忆中心信息架构。

16. 数据模型建议

建议表：

memory_namespaces
memory_items
memory_sources
memory_relations
memory_access_events
memory_promotion_events
memory_embeddings，可选

现有 memory_items 可渐进迁移：

增加 Namespace 并回填现有 Scope。
回填来源为空的旧记录为 legacy_unknown。
增加状态和类型兼容映射。
上线新检索器后再停止旧的列表拼接方式。

17. 安全与隐私

分区解析只在 Main 进行。
所有 ID 重新验证对象归属和项目范围。
Renderer 无法指定任意分区进行搜索。
Runtime 只能获得有界记忆文本和来源摘要。
Embedding 只能发送用户已配置允许的记忆，Restricted 默认不发送外部服务。
记忆内容和来源不出现在普通日志与通知。
跨分区晋升需要明确操作和审计。
Ask 和 Execute 使用同一只读记忆检索边界。
记忆不能绕过系统指令、工具审批和工作区权限。

18. 实施顺序

修正当前交互请求的范围过滤，确保只读 Global、当前 Project 和当前 Conversation。
增加来源记录和“实际进入上下文”的诊断。
为现有智能心跳配置增加 Global 或指定 Project 范围，保持候选记忆行为不变。
建立 Automation 和 Run Namespace。
上线有界相关检索，替换简单列表前 20 条拼接。
增加冲突、时态、替代和归档。
增加实验冻结快照与 Run 隔离。
增加可选本地 Embedding 和混合排序。
未来分区记忆和时间知识图谱都必须在明确需求与独立设计后再实施。

19. 验收标准

普通会话只读取 Global、当前 Project 和当前 Conversation 的允许记忆。
智能心跳配置只能属于 Global 或 Main 已验证的一个、多个 Project。
未来分区记忆完成独立设计前，不新增相关表、状态或检索行为。
Task 执行只读取内部 Run 快照绑定的分区。
实验 Run 不能读取其他 Run 的消息或记忆。
每条非手动记忆都有可追溯来源。
候选和被拒绝记忆不进入普通上下文。
Global 和 Project 晋升需要明确确认或评估。
冲突事实不被静默覆盖。
当前有效事实可通过有效时间正确选择。
上下文组装遵守各层和总字符预算。
UI 能在 Task 执行记录中显示实际使用的记忆，不把 Run 暴露为独立导航对象。
删除或忘记后，文本、索引和缓存不再可检索。
Restricted 记忆不会自动生成或发送给外部 Embedding 服务。

16 KiB Raw Blame History Unescape Escape