Maka 记忆子系统威胁模型PR-MEMORY-1 契约、九道隐私闸门与准记忆隔离设计【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka本文基于仓库中的 memory-threat-model-pr-memory-1.md 展开。该文档记录了 MakaApache MakaIncubating记忆Memory子系统的契约层威胁模型PR-MEMORY-1 是一个仅契约contract-only包它用类型系统、统一校验入口和九道隐私闸门从设计源头禁止准记忆观察结果被悄悄升级为持久记忆条目。读者读完本文将掌握Maka 记忆契约的源类型划分、五大边界、九道闸门G1–G9的具体强制机制、反向参考清单哪些参考实现特性被明确禁止、准记忆排除清单、最小测试矩阵以及 PR 审阅阶段的源码红线。说明该文档已归档Archived on 2026-07-13归档声明明确指出本文档记录的是契约边界而非当前产品实现活跃契约以源码与聚焦测试为准。因此本文所有涉及当前仓库的论述均以仓库内现有源码与测试为事实依据。PR-MEMORY-1 的本质只定义契约不实现任何功能PR-MEMORY-1 的第一个、也是最重要的约束是它的范围边界它是一个 contract-only 包禁止包含以下任何实现禁止新增 IPC handler如ipcMain.handle禁止新增存储仓库storage repository禁止接入 embedding provider禁止实现 Recall 工具运行时禁止新增渲染进程rendererUI禁止新增设置settings开关。后续实现包PR-MEMORY-2 及以后全部位于该契约的下游任何实现包都不得绕过validateMemoryWriteRequest校验入口。这条单点咽喉设计意味着即使下游实现写错了只要所有写路径都强制经过同一个校验函数契约层的九道闸门就不会被静默突破。该文档还记录了三处锚点anchors用于追溯契约的来历notes/reference implementation-memory-reverse-2026-05-25.mdkenji 消息66fd3eab——参考实现事实清单 Maka 准记忆quasi-memory盘存notes/pr-memory-0-audit-plan.md——预审计计划骨架#my-ai:2f91befb线程其中22209a1bxuan 的闸门评审与范围调整、fb95a158kenji 的不变量要求、68a1bcb5xuan 的评审优先级。这些笔记是团队内部锚点未随当前公开仓库分发本文以该文档记载为准。源类型分离gate #8 类型系统准记忆无法靠类型冒充持久记忆契约设计的第一个关键洞见是记忆不是单一表面。MemorySource与MemoryCandidateSource是两个不相交disjoint的枚举类型系统在运行时校验之前就把两类数据隔离开。可持续化源MemorySource源类型说明允许的持久化状态user_authored用户亲自撰写提供confirmedAt时间戳且请求非渲染进程发起时可产生active条目chat_extracted从对话中提取同上必须显式确认非持续化候选源MemoryCandidateSource源类型说明允许的持久化状态voice_transcript语音转写只能产生draft或review_requiredactivity_observation活动观察同上cu_observation计算机使用Computer Use观察同上search_recall搜索召回同上daily_review每日回顾候选同上契约保证DurableMemoryEntry的source字段类型是MemorySource而DraftMemoryEntry的source字段类型是MemoryCandidateSource。因此一段语音转写文本在类型层面就无法构造出DurableMemoryEntry——即使它绕过校验器也过不了 TypeScript 编译。这是类型系统闸门gate #8 的组成部分的意义所在。此外归一化器normalizer会对候选源请求做二次拦截任何候选源请求若携带persistenceState: active一律以MemoryBlockReasoncandidate_source_no_active拒绝。资产清单契约要保护的七类资产威胁模型首先明确要保护什么这份资产清单定义了记忆子系统的信任边界记忆条目content——写入前必须经过 NFC 归一化并剥离控制字符 / 零宽字符防止隐藏注入内容记忆条目source及其衍生出的用户可见溯源provenance记忆条目scope——workspace工作区级或session会话级记忆条目confirmedAt——这是对用户已确认这一动作的声明CLAIMgate #9 禁止渲染进程设置该字段待处理 / 待评审队列内容未来 embedding 向量——v1 契约明确不涉及embeddingProvider: disabled被硬编码消费记忆时的引用索引 / 提示注入防护引用gate #4 相关导出包export bundles——对应 gate #6 的可逆性要求。注意第 4 条的关键措辞confirmedAt不是用户点了某个按钮这个事实本身而是关于用户动作的一份声明。契约要求确认事件记录是主进程main侧责任渲染进程只能提议写入propose永远不能自称已确认。五条边界谁可以写、写到哪、谁能读文档定义了五条进程/模块边界每条边界都有明确的契约义务#边界契约约束1渲染进程 → 主进程渲染进程可提议记忆写入但不得提供confirmedAt确认事件记录是主进程侧职责2主进程 → 存储每次写入都必须经过validateMemoryWriteRequest存储边界拒绝任何未通过校验的请求3存储 → embedding/providerv1 未实现MemoryCapabilitySnapshot中硬编码字面量embeddingProvider: disabled从配置上杜绝误接 provider4存储 → 提示词构建只有active的持久条目可注入提示词且必须带可见引用表面MemoryUsePolicycited_only契约中不存在silent策略5准记忆表面 → 记忆禁止作为直接写路径准记忆进入记忆的唯一途径是先生成 draft 条目再由用户显式提升promote第 4 条值得展开即便一条记忆完全合规地进入了active状态当它被用于提示词构建时也必须向用户展示引用来源。契约故意不提供静默注入策略——这是对提示注入攻击和看不见的记忆影响模型行为这类问题的结构性强约束。九道隐私闸门由 xuan22209a1b锁定这是整份威胁模型的核心。九道闸门G1–G9每道都有明确的契约层强制手段#闸门契约层强制手段1默认关闭default-offMEMORY_MODES包含off全新安装的快照必须为off校验器第 1 步即以MemoryBlockReasonmode_off拒绝2持久化写入前需人工确认持久active路径要求confirmedAt缺失或非法时校验器以MemoryBlockReasonmanual_confirm_required拒绝3删除 / 导出可逆契约文档要求在引入任何自动写入能力之前可逆操作必须已存在v1 契约无自动写入下游包在添加任何写驱动前必须先添加deleteexport形态4隐身模式读写双禁用MemoryWriteRequestContext.incognitoActive在校验器第 2 步短路返回MemoryBlockReasonincognito_active读路径属于未来契约同一标志必须同时门控读路径5禁止自动睡眠整合自动整合源既不在MemorySource也不在MemoryCandidateSource中——不存在任何自动整合源类型要新增必须走契约变更并显式评审6可见引用MemoryUsePolicy只允许never或cited_only不存在silent策略新增即枚举扩展需显式评审7禁止隐藏活动晋升activity_observation/cu_observation只能是MemoryCandidateSource校验器对persistenceStateactive经candidate_source_no_active闸门拒绝8provider embedding 泄漏边界MemoryCapabilitySnapshot.embeddingProvider是字面量disabledv1 条目上无 provider 字段任何下游 provider 接线都需扩展此快照类型9渲染进程不得伪造溯源/就绪MemoryWriteRequestContext.originatedFromRenderertrue阻断任何持久active写入——即使confirmedAt合法——返回MemoryBlockReasonrenderer_provenance_forged闸门间的配合逻辑G1 G2覆盖默认什么都不写写了也先要人点头G4 G9覆盖隐身时/渲染进程提议时可信度归零G5 G7覆盖没有任何后台机制能悄悄把观察变成记忆G6 G8覆盖即便记忆成立用的时候必须可见、且不给云端 embedding 留口子。这套闸门设计的特点是每条隐私承诺都对应一个可以在校验器里精确判定的布尔条件因此都能被测试断言锁定见下文测试矩阵。反向参考清单从参考实现中不要复制的八件事文档基于notes/reference implementation-memory-reverse-2026-05-25.md的反向工程结论明确列出八条禁止复制项——这是威胁模型中最具实战意义的部分因为它直接告诉你哪些看似先进的记忆功能在 Maka 里是违禁的睡眠周期 / 4 层整合参考实现的22-embeddings.md——Maka 没有睡眠阶段不存在任何自动聚合、摘要、合并记忆条目的代码路径从聊天自动提取——每次chat_extracted写入都要求显式确认即使助手给出了建议用户也必须点击确认不允许静默插入自动检索 / Recall 工具运行时——超出 v1 契约范围若要添加需要单独的检索侧契约和独立的威胁模型LLM 中介的遗忘/删除——只允许用户主动发起的删除不存在模型认为这个不再相关就删掉的路径活动派生的记忆——Activity recorder 只能通过activity_observation候选源进入 Maka 记忆永远不是持久源且活动审计独立通道必须先于任何活动→记忆管线运行未认证的本地路由参考实现的05-express-api.md通过本地 HTTP 暴露记忆——Maka 记忆禁止本地 HTTP 端点若未来 Local Gateway 通道落地必须经过能力范围白名单 审计日志且绝不能默认开启云端 embedding 回退——embeddingProvider: disabled是硬锁接入 provider 必须显式扩展契约不允许静默的 OpenAI / Cohere / 本地混合方案Soul tree / 全局长期文件参考实现的~/.config长期记忆文件——超出 v1 范围若持久化落地PR-MEMORY-2必须位于现有工作区存储内而不是独立的全局目录树。这八条负面对照构成了 Maka 记忆功能设计的不可逾越的红线也是评审者最常引用的依据。准记忆排除清单哪些现有表面禁止被当作记忆源Maka 中已经存在大量包含用户关联持久数据的表面但它们必须被排除在MemorySource之外、且禁止自动晋升准记忆表面内容处理方式settings.json个性化字段、入门里程碑仅作为设置不进入记忆skills/用户安装的技能内容仅按需加载usage_logtelemetryRepo历史查询 / 延迟 / 错误遥测专用sessions/*/session.jsonl会话历史会话专用workspace/指令文件仅提示词注入提示词时使用Capability 快照 运行时探针历史健康中心数据运行状态专用Visual-smoke 测试夹具视觉冒烟数据测试专用Daily Review 候选每日回顾后置通道候选源搜索索引命中搜索结果经search_recall候选源桥接非持久语音转写语音输入voice_transcript候选源CU / 活动观察计算机使用 / 活动数据候选源契约能拦住什么unknown_source按 xuan0c9c68f9的闸门任何把准记忆表面字面名当作source的请求都会被直接拒绝例如source: usage_log、source: health_probe、source: session_summary等无论其他字段如何validateMemoryWriteRequest都以MemoryBlockReasonunknown_source拒绝——因为该字符串不在MEMORY_SOURCES或MEMORY_CANDIDATE_SOURCES中。契约拦不住什么源洗白source-laundering文档毫不讳言契约的盲区如果下游某个 IPC handler 或存储边界读取了一条 usage-log 条目把其正文复制进一个全新的{ source: chat_extracted, confirmedAt: ..., content: ... }载荷再提交给校验器——校验器会接受它。因为从校验器视角看这就是一条格式良好的持久chat_extracted写入它无从得知正文其实来自准记忆表面。因此源洗白防御是每个 IPC handler / 每个存储边界的责任在输入层做 provenance 锁定而不是契约层的责任。文档进一步规定任何未来引入将 draft 提升为 active或把准记忆表面摘要为 chat_extracted路径的实现包必须在该边界额外增设独立的 provenance 闸门。最小测试矩阵用断言锁死九道闸门契约文档要求配套测试文件packages/core/src/__tests__/memory.test.ts至少包含以下断言每条标注其锁定的闸门 G#N标签断言G1modeoff→mode_off拦截任意 source、任意状态G2持久user_authoredpersistenceStateactive但无confirmedAt→manual_confirm_requiredG2b持久chat_extractedpersistenceStateactive但无confirmedAt→manual_confirm_requiredG3契约中不存在delete/export绕过形态必须由下游包新增G4incognitoActivetrue 任意合法写入 →incognito_activeG5MEMORY_SOURCES与MEMORY_CANDIDATE_SOURCES中不存在自动整合源G6MEMORY_USE_POLICIES仅包含never与cited_onlyG7候选源 persistenceStateactive→candidate_source_no_active每种候选源各一条断言G8MemoryCapabilitySnapshot.embeddingProvider是字面量disabledG9持久 active originatedFromRenderertrue→renderer_provenance_forged归一化器测试矩阵除闸门断言外归一化器还需覆盖normalizeMemoryContenttypeof 拒绝、NFC 归一化、控制/零宽字符剥离、trim、空内容拒绝、容量上限拒绝normalizeMemorySource已知持久源、已知候选源、未知源拒绝normalizeMemoryMode/normalizeMemoryPersistenceState/normalizeMemoryScope非枚举成员关闭式拒绝validateMemoryWriteRequest成功时返回规范化的DurableMemoryEntry或DraftMemoryEntry而非原始输入validateMemoryWriteRequest拒绝mode_only 候选源组合mode_disallows_candidate。最后一条很有意思它表明契约连仅模式变更这类无害请求与候选源组合的情况都做了显式拒绝避免模式变更被当作候选条目的隐式背书。PR 审阅红线源码 grep 禁止出现的表面为了让契约未实现任何功能可被机械验证文档给评审者列出了一份源码 grep 黑名单——PR-MEMORY-1 的 diff 中不得出现ipcMain.handle——不得接线任何 IPC handlerBrowserWindow/ 渲染进程 import——不得有任何渲染进程代码路径触碰记忆fetch(/XMLHttpRequest——不得有 provider / 网络调用embedding/vector——不得有任何 embedding 逻辑契约字段只能是字面量disabledRecall/recall_tool——不得有 Recall 工具运行时存储仓库名telemetryRepo、connectionStore、sessionStore等——不得有任何持久化路径记忆相关的设置字段新增——契约在 PR-MEMORY-2 之前与设置形态解耦。这份红线让contract-only从口号变成了可执行的门禁审阅者不需要阅读全部 diff只需 grep 上述关键词即可确认范围合规。仓库中的源码呼应契约思想已在现有代码中落地虽然 PR-MEMORY-1 的契约实现尚未合入该文档已归档活跃契约以源码为准但当前仓库中已能看到同一套防御思想的实践痕迹可作为理解本威胁模型的对照1.validateMemoryWriteRequest被作为防御范式的命名锚点在 packages/core/src/thread-search.ts 的共享 API 文档注释中明确写着Acceptsunknownbecause the IPC payload crosses a process boundary... malformed input must fail closed with an error envelope. Dependency adapters project ordinary I/O failures before calling this function.Same defense pattern as PR-MEMORY-1validateMemoryWriteRequestand PR-UI-IPC-1 baseUrl normalize (xuan msg2f1aba55fixup).这段注释本身就是一份跨契约证据跨进程边界的载荷一律按不可信处理、统一归一化、失败关闭fail closed。runThreadSearch的实际代码也体现了这种分层L1 运行时形状守卫 → L2 源枚举闸门只处理sourcethread→ L3 查询/限额归一化与威胁模型中校验器统一入口 源枚举闸门的分层如出一辙。2. 记忆相关的既有实现与测试仓库中已存在的记忆实现与测试文件是理解当前活跃记忆能力的第一手资料packages/core/src/local-memory.ts 与配套测试 packages/core/src/tests/local-memory.test.ts本地透明文件式记忆V0.1 双开关模型enabled/agentReadEnabledagentReadEnabled默认 OFF、隐身上下文 fail closedpackages/core/src/long-term-memory.ts 与配套测试 packages/core/src/tests/long-term-memory.test.ts长期记忆条目存储含MemoryItemStoreConflictError冲突错误类型记忆相关测试还分布在 runtime 与 runtime-host 包中例如memory-extraction*.test.ts、memory-protocol.test.ts、memory-two-client-uds.test.ts等覆盖记忆提取协调、协议与多客户端场景。3. 白盒契约锚点docs/archive/maka-memory-whitebox-contract.md 记录了更早期的本地记忆契约锚点V0.1 的设置形态、磁盘格式Markdown H2 HTML 注释元数据行、状态枚举不变量disabled/incognito_blocked/safe_mode/error/ok、以及 V0.2 对extracted来源的要求——未来的extract_memory工具必须是permissionRequired: true且门控在agentReadEnabled与!incognitoActive之上。这与 PR-MEMORY-1 威胁模型中的 G2人工确认、G4隐身禁用、G7候选源不可自动晋升一脉相承。需要特别指出的是威胁模型文档明确要求配套测试文件packages/core/src/__tests__/memory.test.ts包含 G1–G9 断言该文件属于 PR-MEMORY-1 交付物当前仓库中记忆相关测试为上述local-memory.test.ts与long-term-memory.test.ts二者共同构成现阶段记忆能力的测试证据。总结一份以不做为设计的威胁模型PR-MEMORY-1 威胁模型最鲜明的特征是它把**禁止清单当作一等公民**来设计九道闸门里至少五道G1、G3、G5、G6、G8本质上是默认不存在的声明并通过类型枚举、字面量硬编码和源码 grep 红线将其固化。这种做法把隐私承诺从开发纪律升级为编译期 测试期 评审期三重可验证的契约。对读者而言这份文档的实际价值在于三处可直接复用的方法论源类型分离——用不相交枚举在类型层阻断观察数据→持久记忆的自动升级比纯运行时校验更早、更硬单点咽喉校验——所有写路径强制经过validateMemoryWriteRequest让安全策略集中在可测试的一点显式承认契约盲区——源洗白无法在契约层拦截因此把 provenance 锁定责任明确下放到 IPC handler 与存储边界并在后续实现包中强制增设独立闸门。这份威胁模型同样适用于任何计划为 AI 工作区添加记忆能力的系统先定义什么必须永远不发生再谈什么可以做。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考