recallloom

RecallLoom

RecallLoom 是一款适用于基于会话的 Agent 的便携式上下文工具框架。

它提供轻量级文件模型，无需繁重的基础设施，即可在不同会话间保持项目连续性。

目标不是记住所有内容，而是让恰当的项目状态能够在不同会话间持久保存、清晰易读并可恢复。

软件包范围

此文件是可安装的 recallloom/ 技能包面向 Agent 的入口。

通过宿主 Agent 的常规技能发现流程安装并触发此软件包。 RecallLoom 本身不需要在软件包内提供针对特定宿主的自定义启动器。 软件包仍可为受支持的宿主提供可选的原生包装器模板。

此可安装软件包有意保持精简。 上游可能提供面向用户的仓库首页和营销文档，但这些内容不会打包到已安装的技能目录中。

在源代码仓库中，README.md 和 README.en.md 是简明的公开入口，README.zh-CN.md 是兼容性入口，INDEX.md 是完整索引，USAGE.md 是操作指南。 这些文件描述的辅助工具约定与此已安装软件包入口相同，不会另行定义一套逻辑。

有关软件包清单、协议详情和辅助脚本行为，请以软件包内附带的文件为准：

• managed-assets.json
• package-metadata.json
• references/file-contracts.md
• references/operation-playbooks.md
• references/package-support-policy.md
• references/recording-workflow.md
• references/protocol.md

软件包信息

• 软件包版本：0.5.0
• 协议版本：1.0
• 支持的协议版本：
  • 1.0

运行时假设

• Python 3.10 或更高版本
• 支持的工作区语言：
  • en
  • zh-CN
• 支持的桥接目标：
  • AGENTS.md
  • CLAUDE.md
  • GEMINI.md
  • .github/copilot-instructions.md

软件包支持门控

RecallLoom 软件包支持与项目旁车协议兼容性相互独立。

• 辅助工具必须执行软件包支持检查，且不得将支持状态写入项目 .recallloom/。
• 如果支持状态为 readonly_only，则必须阻止会修改数据的辅助工具；诊断和只读辅助工具可以继续运行。
• 如果支持状态为 diagnostic_only，则应仅允许诊断辅助工具继续运行。
• 如果不存在本地支持缓存，导致支持状态为 unknown_offline，则本地诊断、只读和修改操作均可继续；本地使用 RecallLoom 不以网络访问为前提。
• 若本地支持缓存结构无效或无法解读，则离线时仅允许执行诊断操作。结构有效但已过期的缓存会根据当前软件包版本重新评估，并保留其 supported、upgrade_recommended、readonly_only 或 diagnostic_only 限制。
• 无效缓存诊断必须通过适合公开的信息说明缓存状态，并引导用户执行只读诊断、在线刷新并原子替换缓存，或移除无效的软件包级本地缓存。不得将升级软件包作为修复缓存的方法，也不得描述缓存遭到篡改。
• invalid_support_advisory 与无效本地缓存是不同情况：应更正或刷新公告，而不是将其视为缓存损坏。
• 被阻止的操作必须返回通用失败约定，其中包含 blocked_reason: package_support_blocked 和 package_support 对象。参见 references/package-support-policy.md。

公共发布面与必需检查

• 公共包和发布面 MUST 仅包含用户安装、了解和使用该包所需的文件。
• 公共发布面 MUST NOT 包含复制的项目记忆、生成的运行时输出、本机数据、仅供维护者使用的工作文件，或安装包不需要的材料。
• 公共 CI 和必需检查 MAY 验证仓库内容和元数据。
• 必需检查的措辞 MUST NOT 将仓库检查描述为用户本地工作区状态、主机行为或侧车信任状态的证明。

非侵入式默认设置与 UX 门槛

• 核心安装和日常使用 MUST NOT 要求或自动安装钩子、守护进程、监视器、MCP／插件强制机制、主机适配器、遥测／指标，或远程载荷传输。
• 原生命令包装器是对同一分发器的可选便捷入口，不是必需的强制执行层。
• 托管侧车之外的一般文档／源代码／规划编辑应保持静默放行或低摩擦，除非它们影响对来源敏感的 RecallLoom 状态。
• 当来源状态与操作相关时，托管侧车或影响来源的操作应在助手就绪输出中显示 allow、warn、ask 或 block 之一。
• warn 用于低风险的纯结构状态或可读取的旧版状态，并应保持简短；同一会话中重复出现的相同低风险警告应允许冷却。
• ask 用于旧版审查／修复导入或经审查的导入基线操作，并要求操作者明确确认后才能执行更高风险的写入。
• 对伪造标记、检测到的收据／存储不一致、直接编辑 state.json／config.json、隐私违规，以及任何被归类为 inconsistent_or_tampered_evidence 的通用、旧版或未绑定状态，block 均不可豁免。
• D5 是唯一的有限恢复过渡：只有符合当前 D5 架构规范、仅针对助手路径目标且经过哈希验证的事后证据，并且在失败时与状态完全匹配，才能通过新的绑定、人工提议／审查以及预期绑定晋升流程继续处理。这不是豁免，也不能证明加密身份归属。晋升仍要求在写入前重新执行 validate、status 和 preflight。D5 人工材料的具体章节、JSON 键和晋升命令见 references/operation-playbooks.md。
• 不要将远程服务、主机记忆、插件、MCP、钩子或包装器描述为本地助手证据的权威来源。
• 有收据支持的变更仅限于由分发器发起的托管文件写入、追加到当前最新游标的每日日志，以及追加后的摘要同步。归档和桥接仍仅支持预览；在这些功能具备各自的收据支持之前，其应用模式仍不受支持。

写入协议红线

• 正常运行期间，对受管理边车文件的变更必须使用适用的调度器接口：受管理文件写入使用 write，每日日志条目使用 append，仅当追加后的契约要求时才使用 sync-current-state-after-append。不得绕过调度器，盲目替换文件、盲目打补丁或手工构建边车文件。
• 正常运行期间，每日日志写入必须使用调度器 append；其内部辅助程序会写入条目。不得手写 daily-log-entry 标记。
• 正常运行期间，每日日志游标修复必须使用调度器 repair-daily-log-cursor；其内部辅助程序会执行修复。不得手动编辑 state.json.daily_logs。
• 正常运行期间，采用覆盖方式写入的受管理文件必须使用调度器 write；其内部辅助程序会执行带修订感知的提交。不得手写 file-state 标记。
• 正常运行期间，禁止手动编辑 STORAGE_ROOT/state.json 和 STORAGE_ROOT/config.json。
• 正常操作仅使用适用的调度器接口。受管理文件写入和每日日志条目分别使用 write 和 append；仅当追加后的契约要求时才使用 sync-current-state-after-append。commit_context_file.py 和 append_daily_log_entry.py 是内部调度器／集成接口：调度器会自行执行最新的预检、构建绑定，并在调用辅助程序前立即持久化匹配的租约。只读预检不会签发这两种材料，也没有独立的操作员领取接口；不带调度器签发材料而手动调用辅助程序，预期会失败。对于经审核导入的基线上的首次写入，请在调度器 write 或 append 中使用 --confirm-review-imported-baseline；当契约要求时，追加后的同步通道也接受该确认。内部辅助程序不接受此标志，只会使用调度器签发的、与确认绑定的绑定材料和租约材料。
• 协议 1.0 的每日日志计数器仅在文件内有效：entry-seq 在单个每日日志内为 1..N，规范的 entry-id 为 entry-{entry_seq}。不要将其中任何一个视为全局唯一。
• 将 state.json.daily_logs.entry_count 保留为 entry_count；它表示最新活动每日日志中的条目标记数量，而非全局累计数量。
• 如果辅助程序写入失败，请诊断、修复并重试；若仍无法完成，再报告辅助程序的失败契约。
• 受损边车文件的恢复必须使用规范的恢复提案／审核／晋升辅助程序和 validate_context.py；不得手动编辑受管理标记、state.json、config.json、收据或辅助程序证据存储。

何时使用

在以下情况下使用 RecallLoom：

• 暂停后继续现有项目
• 从维护的文件中恢复项目上下文
• 维护项目的当前状态记忆
• 记录有意义的里程碑进展
• 减少不同会话或工具间的上下文漂移

常见触发语包括：

• 继续这个项目
• 恢复项目上下文
• 从上次中断的地方继续
• rl-init
• 更新项目记忆
• 记录今天的进展
• 在维护的项目文件中准备清晰的后续步骤交接

首次接入行为

在项目中首次明确调用时，RecallLoom 不应假设工作区已完成初始化。

正确流程如下：

1. 检测是否已存在有效的 RecallLoom 侧车
2. 如果存在，正常继续，不要把初始化变成额外的繁琐步骤
3. 如果不存在，说明项目尚未初始化，并询问是否应执行初始化
4. 如果用户明确确认，或直接说 rl-init，运行标准初始化操作
5. 如果环境无法提供 Python 3.10+，则停止并返回运行时受阻结果，而不是手动构建侧车

rl-init 应表示：初始化侧车、验证工作区，并返回下一步建议操作。即使宿主不支持原生斜杠命令，也应将其视为稳定的高层操作名称。

当前操作接口

对于当前软件包系列，面向操作人员的稳定封装目标为：

• rl-init
• rl-resume
• rl-status
• rl-validate

rl-init 是主要的、便于操作人员使用的首次接入操作名称。 其他名称是面向操作人员的稳定操作名称，可由宿主 Agent 解释，或在宿主支持相应接口时映射为原生自定义命令。 rl-bridge 仍是桥接工作的规范调度器／辅助操作标签，但此软件包系列不承诺为该标签提供通用原生封装或确定性的首跳路由。 自然语言仍是这些操作的默认公开表述。

调度器命令接口还包括 quick-summary、record --suggest、record --plan、append、write、sync-current-state-after-append 和 repair-daily-log-cursor。 仅对于 append、write 和 sync-current-state-after-append，当需要有界事务结果时使用 --compact-json：它会输出 recallloom.transaction.compact/1.0，大小保持在 2048 个 UTF-8 字节以内，并且不能与旧版 schema-1.1 --json 输出同时使用。 使用 quick-summary 获取当前状态快照；在出现持久化里程碑／决策／验证信号后，使用 record --suggest 生成无副作用的候选记录提示词；使用 record --plan 对记录意图分类并获取下一步安全辅助操作；使用 append --entry-json 记录里程碑；在执行类型化托管文件写入前，先使用 write --type ... --source-file <prepared-file> --dry-run 或 write --type ... --stdin --dry-run；只有在预检允许仅更新元数据的 post_append_summary_sync 后，才使用 sync-current-state-after-append --reuse-current-summary --semantic-unchanged-assertion-json <json>；有界断言 JSON 骨架请参见 references/recording-workflow.md。 record --suggest 从不写入内容，不会在后台监视，也不会将敏感或附加的原始材料转变为写入路径；仅当适合使用提示词时，它才会返回经过清理的候选摘要和建议的 record --plan 路径。 如果 state.json.daily_logs 不再与解析出的最新有效每日日志匹配，请先在预览模式下使用 repair-daily-log-cursor。预览会返回公开安全的修复分类、preview_digest、预期工作区修订版本、确认材料和修复后的验证步骤。应用模式需要同时使用 --apply --yes，并通过 --expected-workspace-revision 或 --preview-digest 提供新鲜的预览绑定；该模式作为变更操作受支持门控约束，并且只修复游标字段，不会写入辅助回执或重写每日日志内容。 现有 v0.3.4 项目可以选择使用这些调度器扩展；它们不会更改侧车协议 1.0。

rl-init、rl-resume、rl-status 和 rl-validate 的原生封装仅是便捷入口。它们必须委托给同一调度器，不得取代自然语言恢复请求、绕过辅助工具，或创建特定于宿主的产品逻辑副本。

已初始化项目恢复契约

当宿主或 Agent 收到通用的已初始化项目恢复请求时：

1. 在广泛分发技能之前，先检查 RecallLoom sidecar 是否有效
2. 如果 sidecar 有效，则进入 RecallLoom 常规快速路径
3. 仅当 sidecar 缺失、存在冲突、明显不足，或用户明确要求深入审查时，才让更广泛的记忆或工作流系统参与

对于当前软件包系列，rl-resume 是此已初始化项目恢复检查点面向操作人员的唯一稳定操作名称。 自然语言恢复请求仍是主要的公共路径。 不要虚构手动 sidecar 后备方案，也不要使用软件包契约未支持的宿主本地恢复别名。

公共交互规则

RecallLoom 应默认使用用户任务语言，而非实现语言。

• 优先使用“初始化”“恢复”“导入现有项目现状”“继续”和“记录进度”。
• 除非用户明确在进行操作或调试工作，否则不要以辅助工具名称、分区键或 coldstart 标签开场。
• 首次响应应先给出结果，尽量少涉及操作：明确的下一步胜过暴露路由细节。
• 缺少运行时要求时，不要虚构手动 sidecar 后备方案；说明受阻状态并停止。
• 这不是手动构建 sidecar，而是软件包提供的恢复和辅助工具契约。

快速路径与深入路径

RecallLoom 应将快速路径作为默认交互模式。

• 快速路径：最小且可信的来源集合、最短交互、最低中断成本。
• 深入路径：仅当来源冲突、来源覆盖不足、直接给出建议的风险过高，或用户明确要求深入审查时使用。
• 宿主记忆输入仍为可选且仅作提示；存在此类输入时，应促使 Agent 明确审查，而非静默提升其优先级。

恢复模式选择：

• 当下一位 Agent 需要先获取常规的分级读取计划指引，再决定读取内容时，使用环境提供的 resume 或 status。
• 当了解当前状态已足够，且可根据 state.json 和 rolling_summary.md 选择下一步安全操作时，使用 resume --fast。
• 当操作前需要稳定的项目背景、事实来源路由或项目本地的 update_protocol.md 指引时，使用 resume --full。
• 通过 query_continuity.py 按需查看每日日志证据；默认情况下，快速和完整恢复模式都不应扩展到每日日志。

核心文件模型

RecallLoom 使用三个主要记忆层：

• STORAGE_ROOT/context_brief.md：稳定的项目背景
• STORAGE_ROOT/rolling_summary.md：覆盖式当前状态快照
• STORAGE_ROOT/daily_logs/YYYY-MM-DD.md：仅追加的里程碑证据
• STORAGE_ROOT/config.json：机器可读的工作区设置
• STORAGE_ROOT/state.json：供并发感知型辅助工具使用的机器可读 sidecar 状态
• STORAGE_ROOT/update_protocol.md：推荐的项目本地覆盖层，用于规定读取和写入行为

文件职责概述：

• context_brief.md 说明项目是什么，以及应如何处理。
• rolling_summary.md 说明当前的实际情况。
• daily_logs/ 说明各个里程碑发生了什么。
• config.json 用于稳定存储和语言设置。
• state.json 跟踪工作区版本和辅助工具可见的 sidecar 状态。
• 如果存在 update_protocol.md，它可以针对特定项目收窄或强化默认的读写规则。

STORAGE_ROOT 可以是 PROJECT_ROOT/.recallloom/ 或 PROJECT_ROOT/recallloom/。最多只能存在一个有效存储根目录；如果两者都存在，则停止操作，不要猜测。

机器可读标记才是规范的文件契约，而非标题标签。协议 1.0 支持工作区语言 en 和 zh-CN。请参阅 references/file-contracts.md。

最小冷启动流程

1. 查找项目根目录。
2. 读取 STORAGE_ROOT/config.json。
3. 读取 STORAGE_ROOT/state.json。
4. 读取 STORAGE_ROOT/rolling_summary.md。
5. 如果 STORAGE_ROOT/update_protocol.md 存在，则在扩展到最小连续性文件集之外之前，先展示该文件。
6. 仅当当前任务需要摘要尚未涵盖的框架、范围、事实来源或阶段背景时，才读取 STORAGE_ROOT/context_brief.md。
7. 仅当需要里程碑证据、工作日判断或外部写入者对账时，才读取最新的活动日记。
8. 在信任较早的上下文或进行重大写入之前，运行快速新鲜度检查。

冷启动应先恢复上下文并进行判断。 仅仅因为读取了连续性文件，不应自动继续执行 next_step 或开展项目工作。

完整流程请参阅 references/operation-playbooks.md。

当前读取侧辅助工具

这里有三个重要的读取侧辅助工具：

• preflight_context_check.py：正式写入前进行感知修订的新鲜度审查；返回优先交接的摘要、建议的读取目标、写入层级指导，以及信任度／漂移状态。
• summarize_continuity_status.py：基于相同新鲜度基线提供环境中的连续性状态概览；返回相同系列的摘要，以及共享的工作日状态和信任度／漂移指导。
• query_continuity.py：只读的连续性回溯工具；优先返回答案，其中包括 answer、支持性引文以及风险／新鲜度说明。它还会返回命中项、Token 估算、预算提示、新鲜度／冲突状态、信任度／漂移状态、输出变体标签和覆盖审查目标。日记引文包含明确的 date 值；出现平局时以当前状态文件为准，且上下文窗口保持有界。

这些读取侧界面返回的所有可安全附加的连续性文本，都应遵循共享的附加文本扫描规则。

最小写入规则

• 选择写入目标之前，如果 STORAGE_ROOT/update_protocol.md 存在，请先读取。
• current_state 变更通常写入 rolling_summary.md。
• stable_rule 变更通常写入 context_brief.md。
• milestone_evidence 通常写入日记。
• 对于不会产生持久变更的琐碎读取或小幅编辑，不要更新上下文文件。

任何写入前的默认退出方式都应明确：

• no_write 是正常的成功结果
• merge_current_state 会更新 rolling_summary.md
• append_milestone 会在日记末尾追加内容
• confirm 和 blocked 会停止自动写入，而不是进行猜测

读取侧信任说明：

• sidecar_trust_state 保留在辅助工具 JSON 中，不属于协议 1.0
• state.json.provenance 可在通过回执最终确认的辅助工具写入后，存储诸如 structurally_valid、review_imported_baseline 或 helper_evidenced 之类的本地来源标记；辅助工具 JSON 仍负责操作性 provenance_state 路由
• 没有基线元数据的旧版 sidecar 可以读取，但写入就绪流程必须先经过审查／修复导入，再进行辅助工具写入变更
• structurally_valid 和 review_imported_baseline 仅表示结构／就绪状态证据，绝不能视为 helper_evidenced
• 只有在由分发器支持的回执最终确认流程写入可选本地回执存储并更新来源元数据后，才能声明有回执支持的来源；仅结构验证绝不能输出 helper_evidenced
• 默认的 rl-validate／validate_context.py 仅进行结构验证，不会读取可选回执存储。回执存储验证必须明确启用：使用 --require-provenance，并且只能指定一个范围标志：--changed-only 或 --full。
• continuity_drift_risk_level 是审查信号，并不能证明 sidecar 已损坏
• allowed_operation_level 和 write_readiness 可帮助宿主在低风险读取、优先审查或预检后写入的流程之间进行路由

项目本地覆盖项可以缩小读取顺序、写入顺序或归档行为的范围，但不能取代核心文件约定。

Agent 分层写入判断

写入连续性内容前，Agent 应自行判断所属层级。辅助工具可以提供安全的写入上下文和静态写入层级指导，但不能取代 Agent 对内容含义的判断。

编辑受管理的文件前，请快速检查：

1. 是否有新的持久事实，还是应该采用 no_write？
2. 如果需要写入，主要内容属于 stable_rule、current_state 还是 milestone_evidence？
3. 事件是否跨越多个层级，因此需要进行 multi_layer_split？
4. 是否已经存在相同事实，因此应该合并而不是重复添加？
5. 层级是否足够不确定，以至于应该 defer 或 confirm，而不是猜测？

层级默认值：

• stable_rule：长期工作流规则、真实信息来源路由、项目边界或恢复事实。默认目标：context_brief.md。
• current_state：当前为真的内容，包括当前阶段、活跃风险、当前判断和后续步骤。默认目标：rolling_summary.md。
• milestone_evidence：已完成的验证、批准、发布、已采纳的决策或其他持久证据。默认目标：每日日志。
• no_write、defer 和 confirm 都是有效结果，适用于没有持久变化、讨论尚不稳定，或边界需要明确批准的情况。

当多个层级都适用时，应将不同事实拆分到不同层级，不要重复同一句话。

详细规则、冲突顺序、自我审查模板和匿名校准案例，请参阅 references/operation-playbooks.md。

对于协议 1.0，update_protocol.md 是经过人工审核的覆盖层；辅助工具会提供其中的内容，但不会自动执行其中的自然语言规则。

RecallLoom 倾向采用最小有效写入集。由 Agent 决定应该更改什么并准备内容；由辅助工具判断是否仍可安全应用这些写入。

生成工作区文件时，如果协议 1.0 支持（en、zh-CN），请优先使用用户的工作区语言。

何时不更新上下文

不要仅仅因为以下情况就更新上下文文件：

• 你执行了冷启动
• 你回答了一个简短问题，且项目没有发生持久变化
• 你进行了探索，但没有得出稳定结论
• 你只修改了措辞

该协议旨在减少噪声，而不是把每次会话都变成文档工作。

配置文件

RecallLoom 提供四种配置文件：

• profiles/general-project-continuity.md
• profiles/research-writing.md
• profiles/product-doc-collaboration.md
• profiles/software-project-coordination.md

配置文件会调整侧重点、证据处理方式和偏离风险。默认使用 general-project-continuity.md；只有在项目特征高度匹配时，才切换到专用配置文件。

RecallLoom 并非旨在成为

RecallLoom 并非旨在成为：

• 通用记忆服务
• 完整的 Agent 执行运行时
• 平台专用指令文件的替代品
• 重型自主编码框架

它是项目连续性层，而非完整的 Agent 技术栈。

延伸阅读

• references/protocol.md
• references/file-contracts.md
• references/operation-playbooks.md
• references/anti-patterns.md
• references/profiles.md

许可证

本软件包依据 Apache License 2.0 发布。