Omi 产品原则与通用记忆生命周期Capture→Act 闭环、INV-MEM 不变式与工程治理实战指南【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本文以仓库根目录的 PRODUCT.md 为骨架系统解读 Omi 的北极星产品原则、面向所有认证账号的通用记忆生命周期以及如何通过product/invariants/不变式注册表把产品规则变成可机器校验的工程纪律。读完本文你将掌握 Capture → Understand → Remember → Retrieve → Act 核心闭环的落地形态、INV-MEM-4/INV-MEM-5 的禁止性条款与守卫测试以及产品规则如何被 PR 检查强制引用的整套治理机制。一、Omi 的产品原则一份给人和 Agent 的北极星PRODUCT.md 开篇即说明自身定位Short north star for humans and agents—— 它同时面向人类工程师与 AI Agent是任何提议新功能或提交改变产品行为的 PR 之前的必读文档。工程规范在 AGENTS.md已锁定的产品规则在 product/invariants/。这一分层非常关键原则Principles给出方向不变式Invariants给出可执行禁令工程规范给出编码标准。1. Memory-first保护核心闭环第一条原则直接定义了产品存在的理由Capture → Understand → Remember → Retrieve → Act如果 Omi 未能捕获或保存记忆其他一切都无关紧要。这一闭环贯穿整个记忆子系统捕获Capture是所有新记忆的入口理解Understand与维护Maintenance决定每条待处理记忆的去向记住Remember依赖规范化存储与原子台账检索Retrieve按规范谱系折叠去重行动Act则由任务智能Task Intelligence承接。2. Trust over cleverness可靠优先于炫技优先保证捕获、同步、检索的可靠性而不是堆砌花哨功能。文档给出了两条可判定的产品缺陷判据静默数据丢失silent data loss和双重事实来源dual sources of truth。这正是后文通用记忆生命周期要消灭的两种状态——历史扁平文档与规范文档并存时必须只有一个变更权威。3. One product mind一个产品心智所有界面Chat、Agent、MCP、桌面端、移动端都只是同一个共享产品体验的输入/输出而非各自拥有独立历史的多个产品。这条原则在 INV-MEM-5 中被固化为每个认证账号只有一套记忆策略与一套任务智能策略。4. Harness over heuristics马具优于启发式在整合我们不拥有的界面时投资于持久化的马具harnesses与契约contracts而不是脆弱的临时自动化。仓库中可见的对应物是backend/database/下的 read boundary、outbox 等持久化抽象以及 product/invariants/integrations.mdINV-INT-1集成行为必须由契约与马具背书。5. Taste floor品味下限保持品牌一致性优先删除重复路径而不是用 feature flag 永久保留它们。这条原则直接指导了收敛 Epic 中删除旧路径而非让新旧并存的工程决策。二、通用记忆生命周期唯一准入、唯一变更权威PRODUCT.md 的核心章节定义了一套面向每个认证账号的通用记忆生命周期配套的可执行设计说明是 INV-MEM-4Canonical promotion is the sole Long-term authority与 INV-MEM-5Universal memory and task authority。PRODUCT.md 声明二者处于 seven-day 观察期但从当前仓库可见两则不变式文档的状态均已标记为locked详见本文第四节关于注册表机制的讨论。2.1 短期记忆是唯一入口所有新的记忆摄取conversation、显式用户输入、import、API、plugin、integration一律先进入短期记忆Short-term不存在任何直达长期记忆Long-term的通道。这一点在 memory_service.py 中体现为CanonicalMemoryBackend与HistoricalMemoryAdapter的边界设计历史适配器deliberately has no create/update/delete methods物理上只读。2.2 维护阶段每条待处理记忆恰好一条合并路径维护Maintenance给每条待处理记忆恰好一个终结路由consolidation route四选一路由含义promote晋升唯一的长期记忆准入通道archive归档保留但不再参与默认检索review复核进入人工/规则复核reject拒绝作为负面样本不再保留禁止对同一待处理项施加多条路径也禁止把短期记忆的 TTL 过期本身当作终结路由——过期项在规范 apply 记录其处置之前不得被静默隐藏。对应守卫测试可见 backend/tests/unit/test_canonical_consolidation.pypending work 获得精确的一路由划分且拒绝的源与近重复负面样本不可晋升。2.3 晋升的原子性receipt graph assertionPromote 是唯一进入长期记忆的通道且只有在一笔原子台账ledger交易同时记录以下内容时才会被受理服务端签发的晋升受理回执server-authored promotion admission receipt该记忆的结构化图谱断言structured graph assertion按版本栅栏version-fenced逐记忆写入。这排除了三类捷径通用generic晋升、批量/每日batch/daily晋升、调用点或用户自行断言的 fast-track 晋升。代码级佐证在 backend/tests/unit/test_atomic_apply.py 与 backend/tests/unit/test_memory_apply_store.py晋升必须原子写入 item、graph assertion、ledger 状态、操作结果与 outbox 事件源替换与隐私墓碑复用同一 journal 边界。2.4 默认检索按规范谱系折叠默认检索同时覆盖合格的短期与长期记忆并按规范谱系canonical lineage折叠使同一条逻辑记忆只出现一次。一个短期别名与其长期规范幸存者不得同时出现在默认列表或搜索结果中守卫测试 backend/tests/unit/test_ws_m_atom_keyword_index.py。同时受限restricted记忆内容禁止发送给任何搜索、嵌入或向量提供商backend/tests/unit/test_canonical_memory_vectors.py。2.5 派生视图可重试而非权威关键词、向量、兼容性与共享图谱投影projections都是派生视图它们的更新先提交到 outbox带规范状态再从权威记忆源重试。它们自身永远不被当作记忆权威。对应的 outbox 收敛语义由 backend/tests/unit/test_memory_outbox_worker.py 守卫投影投递必须重载权威状态、修复被回收的投递、重试并且只有收敛成功后才会确认ack。三、INV-MEM-4 与 INV-MEM-5把生命周期固化为禁令3.1 INV-MEM-4规范晋升是长期记忆的唯一权威INV-MEM-42026-07-27 提出当前状态 locked的核心 Statement所有新的规范摄取都从短期记忆开始一次合并决策给每条待处理项恰好一个终结路由只有原子回执化、图谱背书的晋升才能将项准入长期记忆。默认访问折叠规范谱系而关键词、向量、兼容性与共享图谱投影仍是可重试的派生视图。其 MUST NOT 条款完整列出如下择要保留原文语义不得将新捕获的 conversation、显式用户、import、API、plugin、integration 输入直接准入 Long-term 或 Archive历史迁移/回填不是新摄取由显式迁移策略管辖不得让待处理短期项没有合并路由或对同一项施加多于一个 promote/archive/review/reject不得把短期 TTL 当作终结路由也不得在规范 apply 记录处置前隐藏过期项不得在合并路由之外叠加 generic、batch/daily、调用点或用户断言的 fast-track 晋升通道提交新的短期→长期转换时必须验证服务端签发的晋升回执并原子地写入版本栅栏化的逐记忆图谱断言、item、ledger head/commit、操作结果与 outbox 事件默认列表或搜索结果中不得同时返回短期别名及其长期规范幸存者不得把关键词/向量/兼容性/共享图谱投影当作权威状态不得把受限记忆内容发送给搜索、嵌入或向量提供商outbox 背书的投影事件在其幂等写入成功、post-write 权威栅栏协调完成前不得确认。文档中值得注意的真实性细节其 Guard tests 一节明确记录了一处覆盖率缺口——test_ws_i_write_convergence.py1398 行被提交5724a10084converge universal memory and task authority 删除且列表未更新因此该文件已从守卫清单移除以让其余守卫可被持续验证。这说明不变式文档的守卫清单不是装饰而是会被脚本逐一核实的见第四节。3.2 INV-MEM-5通用记忆与任务权威INV-MEM-52026-08-11 提出当前状态 locked解决的是权威唯一性问题每个认证账号使用同一套规范记忆策略与同一套任务智能策略。历史记忆与 staged-task 文档可通过受限兼容适配器保持物理可读但 UID allowlist、store origin、客户端与 rollout 元数据永远不得选择不同的产品权威。其 MUST NOT 关键条款不得通过固定 UID 列表授予/拒绝记忆、任务智能、目标、工作流、推荐或 Chat-first不得因为账号 enrolled/dogfood/canonical/legacy/在某个 cohort 中而路由到不同的记忆或任务业务逻辑通用规范写入启用后不得创建或修改历史users/{uid}/memories行幂等的、由 lazy materialization 或账号删除拥有的 redaction/deletion 除外不得把历史适配器当作 mutation、lifecycle、privacy、graph、vector 或 task 权威规范状态/墓碑/代际/就绪校验失败时不得回退到旧写入器或无栅栏的历史读取不得因规范与历史物理记录并存而把同一逻辑记录暴露两次不得用文本相似度推断记录身份、变更归属或删除优先级现有用户使用通用记忆/任务功能前不得要求批量历史回填、LLM 重处理或重新嵌入删除 cohort 逻辑时不得移除账号代际、所有权、幂等性、设备、隐私、主动用户选择或全局事故/成本栅栏export、delete-all、账号删除、源删除、搜索、图谱、MCP、开发者工具或已发布客户端 API 都不得绕过通用权威。代码级证据非常直观backend/config/memory_rollout.py 中的universal_memory_capabilities(uid, *, account_generation0)返回的是与 uid 无关的常量策略——legacy_onlyFalse、memory_writes_enabledTrue、memory_reads_enabledTrue、legacy_reads_authoritativeFalse。文件头注释明确写道Memory and task product authority is universal for authenticated accounts. 遗留字段保留在内部 DTO 中仅为兼容旧调用方且是常量绝不从 UID 注册或持久化 rollout 状态机推导。唯一的用户可见产品开关是环境变量MEMORY_ENABLEDon|off未设置时代码 fail-closed 到offMEMORY_MODE与MEMORY_V3_GET_ENABLED仅作为旧版本的单次部署别名保留。INV-MEM-5 的核心守卫测试包括测试验证点test_universal_memory_task_authority.py任意认证 UID 共享同一记忆/任务决策静态生产导入与旧写入器所有权受约束test_memory_service_parity.py规范与历史记录共享同一发布的 service contracttest_memory_mutation_contract.py历史变更通过规范权威物化或墓碑化且不可复活test_backend_candidate_capture.py通用 Candidate 捕获具有显式 no-drop/no-duplicate 行为test_account_deletion_projection_fence.py删除栅栏同时覆盖两个来源与派生提供商check_app_client_openapi_compatibility.py已发布客户端保持方向兼容四、不变式注册表产品规则如何被机器校验product/invariants/README.md 定义了整套治理机制这是 PRODUCT.md A product rule without a guard surface is taste advice, not a locked invariant 一句的落地点。4.1 locked 与 proposed 的真实语义状态含义locked机器可校验的声明文档点名的每个 guard 都存在命名的 guard 脚本已接入 checks manifestPR 触碰其 path globs 时必须引用其 ID除非显式 opt outproposed设计说明design note对判断有约束力但对 CI 无约束力是一个稳定的驻留状态而非队列状态不控制执行静态 guard 之所以运行是因为它接入了 .github/checks-manifest.yaml与文档状态无关。locked 只控制一件事——PR body 是否必须引用该 ID。值得注意的演进事实注册表 README 明确指出旧的七天浸泡期已被废除——历史上从未有任何不变式完成过proposed → locked晋升而有两条不变式在浸泡规则写就六天后直接born locked。取而代之的是 .github/scripts/check_product_invariants.py 在每个 PR 上连续审计而非只在晋升时检查一次。这与 PRODUCT.md 中保持 proposed 七天不变才可锁定的表述存在仓库内部演进时差——以当前注册表 README 与 invariant 文档的实际状态两则均 locked为准。4.2 连续审计在做什么从 check_product_invariants.py 的源码可以确认审计的三类检查Guard tests 存在性locked 不变式文档Guard tests一节点名的每个仓库路径必须存在被点名的.github/scripts/check_*.py必须被 checks-manifest 中的某个条目运行。若某天一个 guard 测试被删除当日 PR 就会失败——这就是 PRODUCT.md 所说规则必须有守卫表面的机器化。注册表自洽每个不变式 ID 必须出现在 README 索引表中且索引行指向的文档必须真实存在path-glob 条目必须用反引号包裹否则视为静默忽略并报错fail-closed格式漂移不得静默关闭执行。Whole-tree globs 检查若不变式的 glob 覆盖整个应用树如backend/**、desktop/macos/Desktop/Sources/**强制每个 PR 引用就会让引用变成仪式。此类不变式必须让 guard 承担底线并 opt out 引用INV-UI-1 模式。INV-MEM-5 正是如此——其 PR rule 写明Donotrequire naming因为其 globs 覆盖两个桌面应用树。4.3 PR 引用规则与失败输出当 PR 修改的文件命中某个 locked 不变式的 path globs 时引用是廉价的脚本提供--suggest参数直接打印 paste-ready 的## Product invariants affected块引用的持久价值不是注意力而是上下文路由失败输出会附带命中不变式的 Statement 与 MUST NOT 条款把规则送到正在编辑这些文件的人/Agent 面前对于皇冠级不变式README 建议 PR rule 要求声明claim而非令牌token例如说明本次变更是否保持既有权威或属于显式迁移例外——声明可能错误并可被评审令牌则不能。4.4 与 Failure-class 注册表的呼应产品规则的守卫表面要求与 product/failure-classes.md 的 guard-artifact ratchet 一脉相承90 天窗口内同一 failure class 被声明 ≥3 次却没有canonical_prevention_artifact可复用的守卫表面即失败。两者的共同哲学是意图不是守卫只有落地的可复用检查才算数。五、历史数据兼容只读适配、惰性迁移、无批量回填PRODUCT.md 承诺历史扁平记忆文档通过一个只读兼容适配器保持可读用户无需批量回填即可保留既有数据并指出完整的收敛与移除台账在 backend/docs/epics/universal_memory_task_convergence.md。该 Epic 给出了落地细节。5.1 目标架构authenticated surface | v Universal MemoryService -------------------- Universal Task Intelligence | | | one policy/state machine | Candidate - action_items | | goals/workstreams/recommendations -------------------------------------------- | ------------------------------- | | canonical memory repository historical storage adapter users/{uid}/memory_items users/{uid}/memories read write authority read-only physical compatibility ledger/evidence/graph/outbox no new writes or business policy图源universal_memory_task_convergence.md历史读适配的关键决策与 PRODUCT.md 的不是第二个变更权威严格对应起源定位符(uid, legacy, legacy_id)稳定公共 ID沿用既有 legacy ID生命周期准入grandfathered_long_term——一个显式的历史例外标记而非伪造的晋升回执缺失可见性/设备身份由统一的已批准兼容策略处理而非各调用方自行处理畸形/加密行复用既有受保护 legacy reader 与共享畸形行策略读取时不伪造任何图谱断言或规范证据。5.2 惰性变更Lazy mutation编辑、复核、重分类、改可见性等对历史记录的变更执行有界的逐项转换顺序为通过受保护适配器读取并校验拥有的 legacy 文档向规范 apply 提交一个确定性的历史物化操作尽量保留稳定公共 ID 与原始时间戳/来源原子地建立规范覆盖/抑制记录带规范状态用规范变更逻辑应用所请求的变更通过规范 outbox 入队 provider/图谱清理仅作为幂等清理删除/脱敏物理 legacy 文档——清理失败不得让它重新可见。删除历史记录遵循同一顺序但提交的是规范隐私墓碑。delete-all 与账号删除重复执行有界、代际栅栏化的扫描直到两个来源逻辑上均为空。5.3 统一读取与显式拒绝旧游标List/read/search 调用方使用同一个仓库混合账号被读为两条有界索引流并按一个确定性公共顺序合并。关键约束旧的签名游标signed cursor只服务于 cutover 投影无法表示通用混合视图因此游标请求显式失败直到设计并证明双源复合游标为止——这正符合不得让工具选择第二权威的原则。六、工程流程Before you build 与 Maintainer operating rulePRODUCT.md 的Before you build清单整理为可执行流程大型或模糊的功能先从 GitHub issue 开始贡献指南见 docs/doc/developer/Contribution.mdx先查不变式注册表product/invariants/确认是否存在适用于你的变更的已锁定规则没有守卫表面的产品规则只是品味建议不是锁定不变式——任何新规则必须自带守卫测试与路径 globs新规则以 proposed 设计说明驻留行为与守卫保持七天不变后按注册表现行机制为连续机器审计方可锁定。Maintainer operating rule则约束维护者本身当因方向或品味拒绝一个 PR 时要么引用一个既有不变式 ID要么在同一周内在 product/invariants/ 打开一条 proposed 不变式。部落式的 Notribal no变成成文法律——拒绝的理由必须可追溯、可复核而非口头惯例。七、收敛 Epic 的验证门与移除证明universal_memory_task_convergence.md 给出了十项验证门可作为理解 PRODUCT.md 生命周期设计的验收参考跨面等价old-only、new-only、混合用户在所有面/v3、chat、agent、MCP、tools、developer API、Flutter、macOS返回相同逻辑 ID/顺序/策略状态机性质create、source replace、edit、review、visibility、archive、supersede、delete、账号重建均保持合法状态与规范优先级对抗分页上千行、相同时间戳、非法/加密文档、冲突、交错写入产生有界读取无重复无遗漏隐私测试删除立即从所有读/搜/图表面消失outbox/provider 清理在崩溃、重试、租约回收后仍存活导出预言机每条存活逻辑记忆导出一次墓碑内容缺席任务派生记录遵循已批准导出策略任务 no-drop/no-duplicate非 cohort 账号完整走通 extraction → Candidate → acceptance → action item/workstream → recommendation → feedback/outcome → Chat-first全程不查询记忆 cohort 或图谱循环交接规范合并的循环信号可创建 workstream Candidate但其缺失绝不禁用任务兼容性方向性 OpenAPI 检查与已发布 Flutter/macOS 解码 fixture 通过成本/延迟每条返回项的 Firestore 读取、p95/p99 延迟、游标大小、vector/LLM 调用、outbox 延迟与死信保持在预 cutover 预算内回滚排练携带通用双格式读取器的发布可以全局停止新的规范写入而不隐藏任何历史或新规范数据。回滚纪律同样明确第一个通用读取器发布是回滚底线——规范写入全局化后回滚到只读旧版会隐藏新数据被明令禁止安全回滚是全局停止新规范摄取但保留通用读取器与历史适配器。代码收敛也不授权物理数据销毁旧集合的删除需要另行测量证据与显式授权。八、关键文件索引主题路径产品北极星原则PRODUCT.md工程规范AGENTS.md不变式注册表说明product/invariants/README.md记忆晋升唯一权威INV-MEM-4product/invariants/memory-promotion-authority.md通用记忆与任务权威INV-MEM-5product/invariants/universal-memory-task-authority.md通用收敛 Epic 与实施台账backend/docs/epics/universal_memory_task_convergence.md记忆域模型backend/docs/memory/domain_model.md通用能力实现MEMORY_ENABLED 开关backend/config/memory_rollout.py规范/历史/适配后端实现backend/utils/memory/memory_service.py不变式连续审计脚本.github/scripts/check_product_invariants.pyFailure-class 守卫表面制度product/failure-classes.md理解 Omi 的产品与工程体系从这套原则 — 不变式 — 守卫 — 审计的四层治理开始原则给方向不变式给禁令守卫给证据审计给持续强制力。任何新功能提案或 PR都应当在这四层中找到自己的位置。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考