memoweft

MemoWeft

MemoWeft 是一款面向 AI 应用、优先本地运行的记忆引擎。它将 Evidence、派生的 World 对象、来源信息、修订、纠正、撤回、权限状态和可移植数据分别记录，让宿主能够解释它记住了什么，以及原因。

简体中文

软件包入口

根 npm 软件包是 TypeScript 库。py/ 项目是 Python 版 MemoWeft 2.0 实现，包含生产级 Hermes provider、Trust 服务、Portable v4 和 DSH RPC v2。源代码树中还包含一个 Memory Experience 应用；该应用不会打包进根 npm 压缩包。

Python 发行包会在 hermes_agent.memory_providers 入口点组中公开 memoweft provider。软件包元数据、源清单和已安装后的行为属于不同的证据层，应分别验证。

安装 TypeScript 软件包

发布 npm 版本请使用 npm install memoweft。Node 24 内置 SQLite 支持；Node 20 和 Node 22 使用可选的 better-sqlite3 驱动程序。

仓库中的候选版本可能比最新发布的软件包更新。本地构建成功或压缩包哈希正确，并不能证明该版本已发布到软件包注册表。

记忆契约

MemoWeft 明确保持以下边界：

• 原始用户内容会作为原样证据保留，包括其来源信息和权限。
• 请求忘记已存储的记忆，并不等于否认被记住的事实；形成记忆时会排除该命令对应的条目，而独立的事实陈述仍符合纳入条件。在单独的授权遗忘流程完成前，原始证据会保持完整；真正的事实否认仍可支持撤回。
• 当一项绑定来源的更正满足以下条件时，后续的 no_change 才算完成该更正：其已应用回执、当前替代项、精确支持范围和已陈述的投影相互一致。同一消息中的其他更正、记忆请求和未覆盖的未知事实仍未完成；仅有共同来源不能证明已完成。共享账本也接受逐字保存的 MemoryLoop 证据记录；其中的文本或 JSON 内容绝不会作为记忆形成支持记录，也不能证明更正已完成。
• 按片段或引文选出的已陈述形成命题，源自逐字保存的证据，并保留姓名、称呼方式、数字和日期。形成载荷会在现有精细粒度的 segments 之外，提供完整的 sentences。支持项可以显式选择 sentence_id，用于完整的同主题主张；也可以选择 segment_id，用于独立分句。这些是互为替代的来源范围；Core 不会扩展未选中的范围，并会拒绝重叠的选择。与用户关系明确的具名人士会归类为关系记录，而不是仅命名记录或第三方属性。解释 JSON 或编译器字段无效时，系统会在任务结束且不写入之前，将具体编译器错误交给模型重写一次。持久化模型检查点会保留首次响应、错误和重写结果；恢复时绝不会重复已预留或已完成的重写。默认 DSH HTTP 路由会请求 response_format: {"type": "json_object"}；Core 仍会验证必需字段和证据依据。声明式来源之后若模型返回 no_change，也会触发同样的一次检查点式重新考虑，并保留首次结果。事件日历日期会根据选定来源中明确且无歧义的数字日期进行规范化；相对或有歧义的日期会保留原始时间表达，不会猜测 occurred_at 值。纯推理型模型输出绝不会用作解释，也不会包含在重写反馈中。
• 实体、关系、事件、认知和评估记录都是正式的 World 对象。
• 确认可以引用此前四个符合权限要求的对话轮次。编译器会针对持久化的消息 ID 验证确切的助手提议，并将用户确认保留为证据。提议引用会加入现有的支持／删除关系图；来源查询会同时公开两者的原始内容。用户明确重述的内容仍逐字保留，并可将此前同一人物的唯一提议作为上下文。助手文本绝不会成为用户证据。通过 confirmed 导入提议，需要所选范围和完整简短回复中都包含已知的肯定语，或肯定语加上该提议中的完整字面值。偶然的字符重叠，以及被截取出的肯定语前后带有否认内容，都不符合条件。其他明确的用户重述使用 stated；请参阅规则与审计。面向操作的赞同语，例如 Yes, do that. 或 好，要求所选主张本身是操作提议。相邻的提议不能确认事实猜测；确认说明只引用所选主张，而来源信息会保留完整的原始助手轮次。简短的中文先行操作指代可以出现在明确赞同之前；其中完整的字面主题和动作动词必须与所选提议一致。仍会检查整条回复是否包含否认；有限语法和限制详见确认规则。
• 当同一账户中的另一来源正在根据当前 World 进行解释时，World 条目遗忘会暂停，并返回 formation_in_progress。预览和执行都会进行相同检查，包括较早的确认。系统不会据此推断或擦除未经确认的更正来源。形成过程结束后，所有者需要获取新的预览；明确确认且涵盖正在进行的任务所有来源的批次，仍可原子地擦除这些来源并阻止延迟的工作进程。其他账户和无关的未启动任务不受影响。
• 主机通过现有的 model_context_dependencies 边界字段或 link_interaction_dependencies，将实际召回依赖项绑定到助手轮次。忘记某项事实时，会传递性地擦除依赖该事实的完整交互上下文副本，不影响原始应用聊天。对于缺少完整依赖项捕获的旧版副本，系统会在账户范围内，根据完整的原始／规范化事实进行匹配（并规范化呈现形式和所有者代词），且会在同一份遗忘预览中列出。匹配要求整个分句相同，并保留单词／值的边界（York 绝不会匹配 Yorkshire）。不含内容的上下文标识和保留的来源 ID 会阻止重放，并在 Portable v4 中保留；无论恢复顺序如何，已擦除的副本都优先于较早的有效副本。导出不会清理词语。这无法撤销恢复到从未接收过删除状态的数据库中的独立历史备份。
• 遗忘预览会返回 forget_scope。客户端必须将此值与已确认的计划一并保留，并在 delete_evidence／delete_world_item 的 payload.forget_scope 中原样发送。它会绑定账户、目标、World 修订版，以及受影响的上下文／承诺 ID 和内容。无关的新增内容不会使已确认的集合失效。在现有写锁下，快照发生变化时会以 forget_scope_changed 拒绝；若旧版调用会更改上下文但未提供令牌，则会以 forget_scope_required 回滚。遭拒后请重新预览、获取新的确认和命令 ID；执行时绝不能静默刷新令牌。forget_scope_fence: 1 表示支持此约定。forget_batch: 1 还会在 preview_forget 和现有删除命令载荷中支持 additional_targets（1–31 个精确的 {target_kind, target_id} 对象）。主目标和这些目标会共用一份预览、账户、修订版、范围令牌、事务和回执。预览会列出合并后的级联操作；令牌会绑定有序目标列表以及所有受影响的上下文副本。缺少范围令牌、目标／上下文发生变化或来源被拒绝，都会回滚整个批次。重叠的修订链只擦除一次。在进行任何级联写入之前，系统会收集每个显式目标的完整修订链和来源集合，因此不会因某个对象被较早的来源移除，而跳过其剩余来源或拒绝检查。较早的不完整批次预览凭据会被拒绝；请获取新的完整预览和确认。单目标凭据保持不变。请保留原始的已确认令牌；无需逐目标刷新，也无需主机端队列。现有单目标调用保持不变。同一范围也包括 evidence.preceding_ai_context 副本。预览条目会将这些副本标识为 object_kind=evidence_context、item_type=preceding_ai_context；成功回执的 affected_ids 会包含其证据 ID。仅清理上下文时会保留独立的原始证据，且不会将其加入预览的来源删除 evidence_ids 列表。可移植擦除标记会携带不含内容的原始上下文指纹；即使本地 ID 不同但复用了会话／情节名称，也必须与该指纹匹配，并且所有匹配 ID 都参与同一传递性级联。
• 对于相同的来源快照和就绪的检索索引，召回结果是确定性的，并且不会写入 World。当变更后的值没有重复旧的活动名词时，待处理的明确第一人称偏好引文也可以与第一人称偏好问题一同返回。它们仍是逐字保留的临时用户上下文，而不是合成的槽位、替代关系链接或正式 World 条目。这一有限回退不会提名第三人称陈述、引用的任务或问题；现有的账户、目标位置权限、年龄、大小和删除门控仍然适用。形成过程结束后，正式召回会通过现有路径替代待处理引文。即使较早的中性姓名仍为规范姓名，Python 也会将当前有来源的自我命名主张和已接受的别名关联到同一人物；只有当前且目标位置可读的别名来源信息才能建立此关联。完整的肯定式自我介绍也符合条件，例如 I am Martin Mark.、I'm Martin Mark. 和 我是林晓。；疑问、否认、引用的陈述，以及作为被提及者的朋友或同事，都不符合条件。召回时会将有直接来源的第一人称分句与相应人物关联；缺少目标、主题标签和所有者视角本身，绝不能证明事实指的是所有者。对其他人物的所有格描述和转述的第三方观点会保留原有归属。含糊的姓名仍保持未解析状态；姓名和召回事实的来源权限仍会分别应用。Python 召回会优先对已授权的本地 CPU 语义候选进行排序；编码器不可用时，仍会保留字面召回。系统还会单独追加最多五条带时间戳的精确用户来源摘录，总长度上限为 2600 个字符；来源权限、人物隔离和删除门控仍具有决定作用。主记忆上限仍为五项／600 个字符。所有者的问题还可以获得至多 18 项当前且有来源的个人资料条目／1800 个字符，并保留其原始归属和日期；所选依赖 ID 会包含这些条目和每条引用的来源（evidence 引用）。主机必须在助手上下文依赖项中保留这些引用，以便遗忘时也能擦除依赖它们的回复。形成过程会保留具体细节，并将新状态关联到其有来源的前序状态。遗忘会移除 Core 来源副本和派生上下文；已遗忘的记忆以及已撤回或删除的来源，不能通过主要召回、个人资料或原始来源窗口重新出现。请参阅配置和限制。 简短自然的更正可以通过其符合权限要求的前序内容的主题检索。系统只会呈现并选取当前后继项；过去的偏好值仅会出现在历史问题或对已保留人物身份的明确查询中，并会标记为过去的记忆。
• Python 形成过程会将明确的长期目标或计划视为有来源的意图（preference），保留其措辞、动机、条件和数量，但不会断言计划已发生。报告已完成、已放弃或状态已改变时，会通过 supersedes_cognition_id（或 supersedes_relationship_id）选择当前前序项；截止日期已过或保持沉默都不能证明进展。自然发生的变化会保留历史记录，而明确的错误会保留更正路径。在原子写入之前，如果替代目标缺失、不可读、属于其他账户、已被替代或不兼容，系统会拒绝替代。形成过程只会提供当前目标，并单独提供允许使用的旧措辞作为前序上下文。 返回过去的值会创建一个有来源的状态发生记录，保留线性的 A → B → A 历史，并将最新的一次发生记录设为当前状态。系统绝不会克隆旧证据。确定性检查会验证来源所有权、在没有其他肯定目标分句的情况下直接否定的目标动词，以及明确属于第三方的所有格目标主体。条件和开始日期不会使目标失效。其他语义资格由解释模型决定。对同一关系重新措辞时，会根据来源中的人物、目标人物和关系类型，支持其当前发生记录，并保留各自的引文。
• DSH 召回预览还会额外公开 recent_evidence：对未完成形成过程中的精确用户引文进行权限过滤，并与正式 World 条目分开。此只读衔接机制使用现有的证据和对话生命周期；它会从最近 24 小时和 32 个已接受轮次中，至多选取四条引文／800 个字符，并在成功形成后消失。它绝不会复制助手主张，也不会重新创建已删除的对话上下文。主机必须将这些引文标记为临时内容，并保留其与正式记忆的区别。简短的明确更正可以在四个已接受轮次和五分钟内跨对话携带其前一条用户引文。重复出现的数量或明确的数字／时间引用必须在维度上保持一致；如果存在多个候选项，系统会将它们一起返回，并设为 correction_status: "ambiguous"，绝不会将其分配给查询选定的主题。候选项唯一时使用 preceding_text／preceding_evidence_id；存在歧义的组使用 preceding_candidates。两者都会原子地纳入现有引文预算。轮次完成后会立即唤醒形成过程；主机队列负责容量和前台优先级。
• 偏好／状态后继实体标识的是主体，而不是变更后的值。若某个值意外被标记为主题，系统会根据此约定执行现有的一次持久化编译器重写；带围栏的 Apply 仍会强制执行原有的同账户、同主体和用户证据检查。
• 一项明确更正可以用一个确定性的后继项替换多个具名认知目标。只有相同、以编译器为依据且支持范围一致的更正条目，才能共享该后继项；普通的重复形式、重复目标和无关的主题标签仍会被拒绝。每个前序项都会保留自己的更正账本，以及通向共享后继项的转换。更正主题可以重复使用符合权限要求的前序项措辞。
• query_jobs 也会返回尚未解决的明确 formation_requests；更正被拒绝后，不会仅仅因为其工作进程状态为 no_change 就变为正常。retry_formation 会使用现有的来源重新处理操作，并附带请求 ID；它会保留已拒绝的终止状态，并唤醒配置的工作进程。召回预览会独立于近期引文的截止条件，公开经过权限过滤的 pending_corrections，以便主机将较早的事实标记为待更正。历史来源信息包含 successor_provenance，可从任一前序项解释更正来源；模型来源信息保持不变。
• 更正、撤回、遗忘、归档、静音和权限变更都会生成持久化回执。
• Python correct_world_item 接受可选的 payload.source 时会通过 correction_source: true 声明此功能：该来源包含 message_id、session_id、完整的逐字 content、唯一的逐字分句／句子 quote，以及可选的 timestamp／preceding_ai_context。主机提供真实的消息身份；模型只负责选择引文。更正和后续的 DSH 边界会复用相同的来源起点、证据和已陈述命题规范化流程。完整来源中的独立事实仍可供正常形成过程使用。不带 source 的调用保留现有的显式编辑约定；主机在发送原始消息来源信息前，必须先检查此功能是否可用。 更正请求正文不会复制到命令表中；完整的请求哈希仍用于重放／冲突检查，而实际措辞属于可擦除的证据。重复使用来源时，会采用现有／请求权限中更严格的一方。来源不可读或无法推断时，现有的正式 Apply 流程会拒绝该操作。 可选来源元数据可以省略或设为 null，而不会否定现有的已知值。在真实消息到达前已接受的更正，只会在现有支持账本载荷中保留待补元数据字段的名称；后续摄取会将真实时间／上下文与 World Job 原子绑定。记录时间的回退值并不是明确的消息时间主张。一旦提供了真实时间戳或助手上下文，若其与现有值冲突，仍会被拒绝；原始内容、消息身份、权限和命令重放仍受绑定约束。
• Python 遗忘 World 条目时，会在现有命令事务中沿完整的 corrects／supersedes 修订链擦除历史来源和派生副本。只读遗忘预览会使用相同的擦除路径，并在确认前列出完整的级联操作。默认情况下，主机会保留原始聊天消息。
• 共享的助手交互会保留原始历史记录和明确的记忆依赖项。模型投影会排除尚未解决或不再处于当前状态的依赖项，包括传递性复用；历史投影仍受来源权限约束。
• 可移植软件包会进行版本管理和验证，在应用前制定计划，并检查冲突。
• Hermes 主机事件和用户呈现会与 Core 业务终止状态保持区分。

Formation 重启恢复

默认的 Python World 工作线程在认领任务前会持有一个唯一的本地 OS 生命周期锁。启动时会立即撤销生命周期已结束的认领；持有锁的进程仍存活时（包括同一进程中的另一个工作线程），认领会保留可续期的五分钟租约。只有在能明确确认进程不存在时，才会回收旧版 PID 所有者；未知或自定义所有者仍通过租约进行恢复。仅对旧版所有者保守处理 PID 重用。新所有者不依赖 PID。

重启或有序关闭会在一个 SQLite 事务中归还原始任务、退还被中断认领的费用，并使其令牌/代次失效。已保存的模型检查点会继续使用。World Apply、来源信息、修订版本和终态记录会原子提交，因此中断的事务会回滚，已应用的任务绝不会被重新认领。关闭时会先归还认领，再等待缓慢的模型；DSH 最多等待其线程 250 ms，并等待恢复写锁 200 ms。如果数据库繁忙，宿主可以终止 Core，启动时会恢复认领。

只有 DSH 纯解读路由会选择重新执行响应丢失的推理（可能再次向提供方收费，但绝不会再次产生外部工具效果）。通用处理器仍采用现有的未知调度终态规则。对于待处理/处理中任务，恢复会将 restart_recovered / shutdown_recovered 保留在 worker.last_error_type 中，直到任务结算，以便宿主显示恢复仍在进行，而不将其视为失败尝试。不会迁移架构，也不会缩短租约。

已观察来源生命周期

DSH RPC v2 接受类型化的已观察证据修订、来源权限变更和真正撤回，这些操作独立于聊天摄取。回忆功能可以针对本地或云端目标，按来源及其衍生内容进行筛选。TypeScript Core 提供等效的已观察 DTO 和生命周期方法。有关版本、同意、有效性和删除语义，请参阅已观察 RPC 合约。

信任边界

本地优先并不意味着数据永远不会离开设备。宿主负责选择模型路由、存储路径、同意流程、身份验证、授权、加密、备份和日志记录策略。MemoWeft 权限字段约束其正式路径，但不会将任意宿主代码变成安全边界。

MemoWeft 根据 MIT License 授权。