RecallLoom
RecallLoom 是一个为基于会话的智能体设计的便携式上下文工具。
它提供了一个轻量级的文件模型,用于在会话之间实现项目连续性,而无需依赖繁重的基础设施。
目标不是记住一切,而是在会话之间保持正确的项目状态持久、可读且可恢复。
包范围
此文件是 recallloom/ 技能包中面向智能体的入口点。
通过宿主智能体正常的技能发现流程安装和触发此包。 RecallLoom 本身不需要在包内部提供自定义的宿主特定启动器。 该包仍可为支持的宿主提供可选的本地包装器模板。
此可安装包有意保持精简。 面向人类的仓库登录页面和营销文档可能存在上游,但它们不会捆绑到已安装的技能目录中。
在源代码仓库中,README.md 和 README.en.md 是简洁的公共入口,README.zh-CN.md 是兼容性入口,INDEX.md 是完整地图,USAGE.md 是操作指南。
这些文件描述的帮助契约与此已安装包的入口点相同,而不是定义第二套逻辑。
有关包清单、协议细节和帮助脚本行为,请依赖包内部自带的文件:
managed-assets.jsonpackage-metadata.jsonreferences/file-contracts.mdreferences/operation-playbooks.mdreferences/package-support-policy.mdreferences/recording-workflow.mdreferences/protocol.md
包信息
- 包版本:
0.4.6.1 - 协议版本:
1.0 - 支持的协议版本:
1.0
运行时假设
- Python 3.10 或更新版本
- 支持的工作区语言:
enzh-CN
- 支持的桥接目标:
AGENTS.mdCLAUDE.mdGEMINI.md.github/copilot-instructions.md
包支持门控
RecallLoom 包支持与项目侧车协议兼容性是分开的。
- 帮助脚本必须执行包支持检查,并且不得将支持状态写入项目
.recallloom/中。 - 如果支持状态为
readonly_only,变异的帮助脚本必须阻止,而诊断和只读帮助脚本可以继续。 - 如果支持状态为
diagnostic_only,则只有诊断帮助脚本应继续。 - 如果支持状态为
unknown_offline,诊断和只读操作可以继续,但变异操作必须阻止,直到支持状态可验证。 - 被阻止的操作必须返回共享的失败契约,其中包含
blocked_reason: package_support_blocked和一个package_support对象。请参阅references/package-support-policy.md。
公共表面和必要检查
- 公共包和发布表面必须仅限于用户需要安装、理解和操作包的文件。
- 公共表面不得包含复制的项目内存、生成的运行时输出、机器本地数据、仅维护者使用的工作文件,或非可安装包必需的材料。
- 公共 CI 和必要检查可以验证仓库内容和元数据。
- 必要检查的措辞不得将仓库检查呈现为用户本地工作区状态、宿主行为或侧车信任状态的证明。
非侵入式默认值和用户体验门控
- 核心安装和日常使用不得要求或自动安装钩子、守护进程、监视器、MCP/插件强制、宿主适配器、遥测/指标或远程负载传输。
- 本地命令包装器是同一调度程序之上的可选便利入口点,而不是必需的强制层。
- 在管理的侧车之外,普通的 docs/source/planning 编辑保持静默允许或低摩擦,除非它们影响对来源敏感的 RecallLoom 状态。
- 当来源状态相关时,管理的侧车或影响来源的操作会在帮助脚本就绪输出中显示
allow、warn、ask或block之一。 warn适用于低风险的仅结构或可读的遗留状态,应保持简短;重复的同一会话低风险警告应具有冷却友好机制。ask适用于遗留审查/修复导入或审查导入的基线操作,在更高风险写入之前需要明确的操作员确认。block对于伪造标记、检测到的收据/存储不一致、直接编辑state.json/config.json、隐私违规以及任何归类为inconsistent_or_tampered_evidence的状态是不可放弃的。- 不要将远程服务、宿主机内存、插件、MCP、钩子或包装器作为本地帮助证据的权威来源。
- 收据支持的变异仅限于调度程序发出的管理文件写入、追加到当前最新游标的每日日志,以及追加后的摘要同步。存档应用和桥接应用仍然保持预览状态,直到这些表面获得自己的收据支持。
写入协议红线
- 管理的侧车写入必须使用帮助脚本。不要使用盲目的文件替换、盲目的补丁或手工构建的侧车文件来绕过它们。
- 每日日志写入必须使用
append_daily_log_entry.py或调度程序的append。不要手工编写daily-log-entry标记。 - 每日日志游标修复必须使用
repair_daily_log_cursor.py或调度程序的repair-daily-log-cursor。不要手工编辑state.json.daily_logs。 - 覆盖类型的管理文件必须使用知晓修订版本的帮助提交。不要手工编写
file-state标记。 STORAGE_ROOT/state.json和STORAGE_ROOT/config.json在正常操作期间不得手工编辑。- 协议
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 不应假设工作区已经初始化。
正确的流程是:
- 检测是否已存在有效的 RecallLoom 侧车
- 如果存在,则正常继续,不要将初始化变成额外的仪式
- 如果不存在,则解释项目尚未初始化,并询问是否应执行初始化
- 如果用户明确确认,或直接说
rl-init,则运行标准初始化操作 - 如果环境无法提供 Python
3.10+,则停止并返回被阻止的运行时结果,而不是手工构建侧车
rl-init 应该意味着:初始化侧车,验证工作区,并返回下一个推荐操作。即使宿主不暴露原生斜杠命令,也应将其视为稳定的高级操作名称。
当前操作表面
对于当前包线,稳定的面向操作员的包装器目标是:
rl-initrl-resumerl-statusrl-validate
rl-init 是主要的面向操作员的首次附加操作名称。
其他的都是面向操作员的稳定操作名称,可以由宿主智能体解释,或者在宿主支持该表面时映射到原生自定义命令中。
rl-bridge 仍然是桥接工作的规范调度程序/帮助脚本操作标签,但此包线不保证为该标签提供通用的原生包装器或确定性的第一跳路由。
自然语言仍然是这些操作的默认公开表达方式。
调度程序命令表面还包括 quick-summary、record --plan、append、write、sync-current-state-after-append 和 repair-daily-log-cursor。
使用 quick-summary 获取当前状态快照,record --plan 对记录意图进行分类并获取下一个安全的帮助步骤,append --entry-json 进行里程碑日志记录,write --type ... --source-file <prepared-file> --dry-run 或 write --type ... --stdin --dry-run 在类型化管理文件写入之前进行预检,以及 sync-current-state-after-append --reuse-current-summary --semantic-unchanged-assertion-json <json> 仅在预检允许仅元数据的 post_append_summary_sync 后使用;有关绑定断言 JSON 骨架,请参阅 references/recording-workflow.md。
当 state.json.daily_logs 不再与解析的最新活动每日日志匹配时,首先以预览模式使用 repair-daily-log-cursor。应用模式需要 --apply --yes,在新鲜的预览/状态检查后应包括 --expected-workspace-revision,作为变异操作受支持门控,并修复游标字段而不写入帮助程序收据或重写每日日志内容。
这些调度程序新增功能对于现有的 v0.3.4 项目是可选的,并且不会更改侧车协议 1.0。
rl-init、rl-resume、rl-status 和 rl-validate 的原生包装器
只是便利入口点。它们必须委托给同一个调度程序,并且
不得替换自然语言恢复请求、绕过帮助脚本或创建
特定于宿主的产物逻辑副本。
已初始化项目恢复契约
当宿主或智能体看到通用的已初始化项目恢复请求时:
- 在广泛的技能扇出之前检查有效的 RecallLoom 侧车
- 如果侧车有效,则路由到正常的 RecallLoom 快速路径
- 仅当侧车缺失、冲突、明显不足或用户明确要求更深入的审查时,才让更广泛的内存或工作流系统参与
对于当前包线,rl-resume 是该已初始化项目恢复检查点的单个稳定面向操作员的操作名称。
自然语言恢复请求仍然是主要的公开路径。
不要发明手动侧车回退或未经包契约支持的宿本地恢复别名。
公共交互规则
RecallLoom 应默认使用用户任务语言,而不是实现语言。
- 优先使用“初始化”、“恢复”、“导入现有项目现实”、“继续”和“记录进展”。
- 不要以帮助脚本名称、章节键或
coldstart标签开头,除非用户明确在进行操作员/调试工作。 - 保持第一个响应结果优先和轻操作:一个清晰的下一步比暴露路由细节要好。
- 在缺少运行时需求时,不要发明手动侧车回退;呈现阻塞状态并停止。
- 这不是手工构建侧车;而是打包的恢复和帮助契约。
快速和深度路径
RecallLoom 应将快速路径视为默认交互模式。
- 快速路径:最小的可信源集,最短的交互,最低的中断成本。
- 深度路径:仅当源冲突、源覆盖不足、直接推荐风险过高或用户明确要求更深入的审查时。
- 宿主内存输入仍然是可选的和仅提示性的;它们的存在应使智能体倾向于显式审查而不是静默提升。
恢复模式选择:
- 当下一个智能体在决定读取什么之前需要正常的分层阅读计划指导时,使用正常的
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:机器可读的侧车状态,用于并发感知的帮助脚本STORAGE_ROOT/update_protocol.md:推荐的针对特定项目的读写行为覆盖层
一句话描述各文件职责:
context_brief.md解释这个项目是什么以及应该如何对待它。rolling_summary.md解释当前正确的状态。daily_logs/解释在里程碑级别发生了什么。config.json保持存储和语言设置稳定。state.json跟踪工作区修订和帮助脚本可见的侧车状态。update_protocol.md(如果存在)可以缩小或加强此特定项目的默认读/写规则。
STORAGE_ROOT 是 PROJECT_ROOT/.recallloom/ 或 PROJECT_ROOT/recallloom/ 之一。可能只存在一个有效的存储根;如果两者都存在,则停止而不是猜测。
机器可读的标记,而不是标题标签,是规范的文件契约。协议 1.0 支持工作区语言 en 和 zh-CN。请参阅 references/file-contracts.md。
最小冷启动流程
- 找到项目根目录。
- 读取
STORAGE_ROOT/config.json。 - 读取
STORAGE_ROOT/state.json。 - 读取
STORAGE_ROOT/rolling_summary.md。 - 如果
STORAGE_ROOT/update_protocol.md存在,则读取它。 - 如果可应用,读取
context_brief.md以获取稳定的框架。 - 如果在恢复上下文中,请查阅
state.json中的最新每日日志游标以了解日志存在性(不读取内容)。 - 在正常操作中按需读取每日日志内容;不要自动扩展它们。
…
[为翻译而截断]