recallloom

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RecallLoom

RecallLoom is a portable context harness for session-based agents.

It provides a lightweight file model for project continuity across sessions without requiring heavy infrastructure.

The goal is not to remember everything. The goal is to keep the right project state durable, readable, and recoverable across sessions.

RecallLoom 是一款面向会话式Agent的可移植上下文管理工具。

它提供轻量级文件模型，无需复杂基础设施即可实现跨会话的项目连续性。

它的目标并非记住所有内容，而是让正确的项目状态在跨会话过程中保持持久、可读且可恢复。

Package Scope

包范围

This file is the agent-facing entrypoint for the installable

recallloom/

skill package.

Install and trigger this package through your host agent's normal skill discovery flow. RecallLoom itself does not require a custom host-specific launcher inside the package. The package may still ship optional native wrapper templates for supported hosts.

This installable package is intentionally kept lean. Human-facing repository landing pages and marketing docs may exist upstream, but they are not bundled into the installed skill directory.

In the source repository,

README.md

and

README.en.md

are concise public front doors,

README.zh-CN.md

is the compatibility entry,

INDEX.md

is the full map, and

USAGE.md

is the operator guide. Those files describe the same helper contract as this installed package entrypoint rather than defining a second logic set.

For package inventory, protocol details, and helper-script behavior, rely on the files that ship inside the package itself:

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

本文件是可安装

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/protocol.md
```

Package Facts

包信息

package version:
```
0.4.0
```
protocol version:
```
1.0
```
supported protocol versions:
- ```
1.0
```

包版本：
```
0.4.0
```
协议版本：
```
1.0
```
支持的协议版本：
- ```
1.0
```

Runtime Assumptions

运行时假设

Python 3.10 or newer
supported workspace languages:
- ```
en
```
- ```
zh-CN
```

supported bridge targets:

```
AGENTS.md
```
```
CLAUDE.md
```
```
GEMINI.md
```
```
.github/copilot-instructions.md
```

Python 3.10 或更高版本
支持的工作区语言：
- ```
en
```
- ```
zh-CN
```

支持的桥接目标：

```
AGENTS.md
```
```
CLAUDE.md
```
```
GEMINI.md
```
```
.github/copilot-instructions.md
```

Package Support Gate

包支持规则

RecallLoom package support is separate from project sidecar protocol compatibility.

Helpers MUST perform the package-support check and MUST NOT write support state into project
```
.recallloom/
```
.
If support is
```
readonly_only
```
, mutating helpers MUST block while diagnostic and read-only helpers MAY continue.
If support is
```
diagnostic_only
```
, only diagnostic helpers SHOULD continue.
If support is
```
unknown_offline
```
, diagnostic and read-only actions MAY continue, but mutating actions MUST block until support can be verified.

Blocked actions MUST return the shared failure contract with

blocked_reason: package_support_blocked

and a

package_support

object. See

references/package-support-policy.md

RecallLoom 包支持与项目边车协议兼容性是相互独立的。

辅助工具必须执行包支持检查，且不得将支持状态写入项目
```
.recallloom/
```
目录。
如果支持状态为
```
readonly_only
```
，则修改类辅助工具必须停止运行，而诊断类和只读类辅助工具可继续运行。
如果支持状态为
```
diagnostic_only
```
，则仅诊断类辅助工具可继续运行。
如果支持状态为
```
unknown_offline
```
，则诊断类和只读类操作可继续运行，但修改类操作必须停止，直到支持状态可被验证。

被阻止的操作必须返回包含

blocked_reason: package_support_blocked

和

package_support

对象的通用失败契约。详情请见

references/package-support-policy.md

。

Write Protocol Red Lines

写入协议红线

Managed sidecar writes MUST use helper scripts. Do not bypass them with blind file replacement, blind patching, or hand-built sidecar files.
Daily-log writes MUST use
```
append_daily_log_entry.py
```
or dispatcher
```
append
```
. Do not handwrite
```
daily-log-entry
```
markers.
Overwrite-style managed files MUST use revision-aware helper commits. Do not handwrite
```
file-state
```
markers.
```
STORAGE_ROOT/state.json
```
and
```
STORAGE_ROOT/config.json
```
MUST NOT be hand-edited during normal operation.
Protocol
```
1.0
```
daily-log counters are file-local:
```
entry-seq
```
is
```
1..N
```
within one daily log and canonical
```
entry-id
```
is
```
entry-{entry_seq}
```
. Do not treat either as globally unique.
Keep
```
state.json.daily_logs.entry_count
```
as
```
entry_count
```
; it means the entry marker count in the latest active daily log, not a global cumulative count.
If a helper write fails, diagnose, fix, retry, then surface the helper failure contract if it still cannot complete.
Manual repair is allowed only for explicit damaged-sidecar repair; repair marker and state cursor fields as one consistency set, then rerun
```
validate_context.py
```
.

托管边车文件的写入必须使用辅助脚本。不得通过盲文件替换、盲补丁或手动构建边车文件绕过脚本。
每日日志写入必须使用
```
append_daily_log_entry.py
```
或调度器的
```
append
```
命令。不得手动编写
```
daily-log-entry
```
标记。
覆盖式托管文件必须使用支持版本感知的辅助提交。不得手动编写
```
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
```
。

When To Use It

使用场景

Use RecallLoom when you need to:

continue an existing project after a pause
restore project context from maintained files
maintain current-state project memory
record meaningful milestone progress
reduce context drift across sessions or tools

Typical triggers include:

continue this project
restore project context
pick up where we left off
rl-init
update the project memory
record today’s progress
prepare a clean next-step handoff inside the maintained project files

当你需要以下功能时，可使用 RecallLoom：

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

典型触发指令包括：

continue this project
restore project context
pick up where we left off
rl-init
update the project memory
record today’s progress
prepare a clean next-step handoff inside the maintained project files

First Attach Behavior

首次关联行为

On first explicit invocation in a project, RecallLoom should not assume the workspace is already initialized.

The correct flow is:

detect whether a valid RecallLoom sidecar already exists
if it exists, continue normally without making initialization into extra ceremony
if it does not exist, explain that the project is not initialized yet and ask whether initialization should be performed
if the user explicitly confirms, or directly says
```
rl-init
```
, run the standard initialization action
if the environment cannot provide Python
```
3.10+
```
, stop with a blocked runtime result instead of hand-building a sidecar

rl-init

SHOULD mean: initialize the sidecar, validate the workspace, and return next recommended actions. Treat it as a stable high-level action name even when the host does not expose native slash commands.

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

正确流程如下：

检测是否已存在有效的 RecallLoom 边车
若存在，则正常继续，无需额外的初始化仪式
若不存在，则说明项目尚未初始化，并询问是否需要执行初始化
若用户明确确认，或直接输入
```
rl-init
```
，则运行标准初始化操作
若环境无法提供 Python
```
3.10+
```
，则返回运行时阻止结果，而非手动构建边车

rl-init

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

Current Action Surface

当前操作接口

For the current package line, the stable operator-facing wrapper targets are:

```
rl-init
```
```
rl-resume
```
```
rl-status
```
```
rl-validate
```

rl-init

is the primary operator-friendly first-attach action name. The others are operator-facing stable action names that can be interpreted by the host agent or mapped into native custom commands when the host supports that surface.

rl-bridge

remains the canonical dispatcher/helper action label for bridge work, but this package line does not promise a universal native wrapper or deterministic first-hop routing for that label. Natural language remains the default public phrasing for these actions.

The dispatcher command surface also includes

quick-summary

append

write

, and

sync-current-state-after-append

. Use

quick-summary

for current-state snapshots,

append --entry-json

for milestone logging,

write --type ... --source-file <prepared-file> --dry-run

write --type ... --stdin --dry-run

before typed managed-file writes, and

sync-current-state-after-append --stdin --input-format json

only after preflight allows

post_append_summary_sync

. These dispatcher additions are optional for existing

v0.3.4

projects and do not change sidecar protocol

1.0

Native wrappers for

rl-init

rl-resume

rl-status

, and

rl-validate

are convenience entrypoints only. They must delegate to the same dispatcher and must not replace natural-language restore requests, bypass helpers, or create a host-specific product logic copy.

对于当前包版本，面向操作员的稳定包装器目标包括：

```
rl-init
```
```
rl-resume
```
```
rl-status
```
```
rl-validate
```

rl-init

是面向操作员的主要首次关联操作名称。其他是面向操作员的稳定操作名称，可由宿主Agent解释，或在宿主支持时映射为原生自定义命令。

rl-bridge

仍是桥接工作的标准调度器/辅助操作标签，但此包版本不承诺通用原生包装器或该标签的确定性首次路由。自然语言仍是这些操作的默认公共表述方式。

调度器命令接口还包括

quick-summary

、

append

、

write

和

sync-current-state-after-append

。使用

quick-summary

获取当前状态快照，使用

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 --stdin --input-format json

。这些调度器新增功能对现有

v0.3.4

项目是可选的，且不会改变边车协议

1.0

。

rl-init

、

rl-resume

、

rl-status

和

rl-validate

的原生包装器仅为便捷入口。它们必须委托给同一调度器，不得替代自然语言恢复请求、绕过辅助工具或创建宿主特定的产品逻辑副本。

Initialized-Project Restore Contract

已初始化项目恢复契约

When a host or agent sees a generic initialized-project restore request:

check for a valid RecallLoom sidecar before broad skill fan-out
if the sidecar is valid, route into the normal RecallLoom fast path
let broader memory or workflow systems participate only when the sidecar is missing, conflicting, clearly insufficient, or the user explicitly asks for deeper review

For the current package line,

rl-resume

is the single stable operator-facing action name for that initialized-project restore checkpoint. Natural-language restore requests are still the primary public path. Do not invent a manual sidecar fallback or a host-local restore alias that is not backed by the package contract.

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

在广泛调用技能前，先检查是否存在有效的 RecallLoom 边车
若边车有效，则进入 RecallLoom 的常规快速路径
仅当边车缺失、冲突、明显不足或用户明确要求深度审查时，才让更广泛的记忆或工作流系统参与

对于当前包版本，

rl-resume

是面向操作员的已初始化项目恢复检查点的唯一稳定操作名称。自然语言恢复请求仍是主要的公共路径。不得发明未被包契约支持的手动边车回退或宿主本地恢复别名。

Public Interaction Rules

公共交互规则

RecallLoom should default to user task language, not implementation language.

Prefer “initialize”, “restore”, “import existing project reality”, “continue”, and “record progress”.
Do not lead with helper names, section keys, or the
```
coldstart
```
label unless the user is explicitly doing operator/debug work.
Keep the first response result-first and action-light: one clear next move is better than exposing routing details.
Do not invent a manual sidecar fallback when runtime requirements are missing; surface the blocked state and stop.
This is not hand-building a sidecar; it is the packaged restore and helper contract.

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

优先使用“初始化”、“恢复”、“导入现有项目状态”、“继续”和“记录进展”等表述。
除非用户明确进行操作员/调试工作，否则不要以辅助工具名称、章节键或
```
coldstart
```
标签开头。
首次响应应优先展示结果、简化操作：一个清晰的下一步比暴露路由细节更好。
当缺失运行时要求时，不得发明手动边车回退；应展示阻止状态并停止。
这不是手动构建边车，而是打包的恢复和辅助契约。

Fast And Deep Paths

快速路径与深度路径

RecallLoom should treat fast path as the default interaction mode.

Fast path: smallest trustworthy source set, shortest interaction, lowest interruption cost.
Deep path: only when sources conflict, source coverage is insufficient, risk is too high for a direct recommendation, or the user explicitly asks for deeper review.
Host-memory inputs remain opt-in and hint-only; their presence should bias the agent toward explicit review instead of silent promotion.

Resume mode selection:

Use ambient
```
resume
```
or
```
status
```
when the next agent needs the normal tiered read-plan guidance before deciding what to read.
Use
```
resume --fast
```
when current-state orientation is enough and the next safe move can be chosen from
```
state.json
```
plus
```
rolling_summary.md
```
.
Use
```
resume --full
```
when stable framing, source-of-truth routing, or project-local
```
update_protocol.md
```
guidance is needed before action.
Keep daily-log evidence on demand through
```
query_continuity.py
```
; fast and full resume modes should not expand into daily logs by default.

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

快速路径：最小的可信源集合、最短的交互、最低的中断成本。
深度路径：仅当源冲突、源覆盖不足、直接推荐风险过高或用户明确要求深度审查时使用。
宿主内存输入仍为可选且仅作为提示；其存在应引导Agent进行显式审查，而非静默提升。

恢复模式选择：

当下一个Agent在决定读取内容前需要常规分层读取计划指导时，使用环境
```
resume
```
或
```
status
```
。
当仅需当前状态定位，且可从
```
state.json
```
加
```
rolling_summary.md
```
中选择安全下一步时，使用
```
resume --fast
```
。
当需要稳定框架、可信源路由或项目本地
```
update_protocol.md
```
指导后再执行操作时，使用
```
resume --full
```
。
通过
```
query_continuity.py
```
按需获取每日日志证据；快速和完整恢复模式默认不应展开到每日日志。

Core File Model

核心文件模型

RecallLoom uses three primary memory layers:

```
STORAGE_ROOT/context_brief.md
```
: stable project framing
```
STORAGE_ROOT/rolling_summary.md
```
: overwrite-style current-state snapshot
```
STORAGE_ROOT/daily_logs/YYYY-MM-DD.md
```
: append-only milestone evidence
```
STORAGE_ROOT/config.json
```
: machine-readable workspace settings
```
STORAGE_ROOT/state.json
```
: machine-readable sidecar state for concurrency-aware helpers
```
STORAGE_ROOT/update_protocol.md
```
: recommended project-local override layer for read and write behavior

File responsibilities in one sentence:

```
context_brief.md
```
explains what this project is and how it should be approached.
```
rolling_summary.md
```
explains what is true right now.
```
daily_logs/
```
explain what happened at milestone level.
```
config.json
```
keeps storage and language settings stable.
```
state.json
```
tracks workspace revision and helper-visible sidecar state.
```
update_protocol.md
```
, when present, can narrow or strengthen the default read/write rules for this specific project.

STORAGE_ROOT

is either

PROJECT_ROOT/.recallloom/

PROJECT_ROOT/recallloom/

. Exactly one valid storage root MAY exist; if both exist, stop instead of guessing.

Machine-readable markers, not heading labels, are the normative file contract. Protocol

1.0

supports workspace languages

en

and

zh-CN

. See

references/file-contracts.md

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

。

Minimum Cold-Start Flow

最小冷启动流程

Find the project root.
Read
```
STORAGE_ROOT/config.json
```
.
Read
```
STORAGE_ROOT/state.json
```
.
Read
```
STORAGE_ROOT/rolling_summary.md
```
.
If
```
STORAGE_ROOT/update_protocol.md
```
exists, surface it before expanding beyond the minimum continuity set.
Read
```
STORAGE_ROOT/context_brief.md
```
only when the current task needs framing, scope, source-of-truth, or phase context that the summary does not already cover.
Read the latest active daily log only when milestone evidence, workday judgment, or external-writer reconciliation requires it.
Run a quick freshness check before trusting older context or before a major write.

Cold start should restore and judge first. It should not automatically continue

next_step

or execute project work just because continuity files were read.

See

references/operation-playbooks.md

for the full flow.

找到项目根目录。
读取
```
STORAGE_ROOT/config.json
```
。
读取
```
STORAGE_ROOT/state.json
```
。
读取
```
STORAGE_ROOT/rolling_summary.md
```
。
若
```
STORAGE_ROOT/update_protocol.md
```
存在，则在扩展到最小连续性集合之前展示它。
仅当当前任务需要框架、范围、可信源或阶段上下文，且摘要未涵盖这些内容时，才读取
```
STORAGE_ROOT/context_brief.md
```
。
仅当需要里程碑证据、工作日判断或外部作者协调时，才读取最新的活跃每日日志。
在信任旧上下文或进行重大写入前，运行快速新鲜度检查。

冷启动应先恢复并判断。不应仅仅因为读取了连续性文件就自动继续

next_step

或执行项目工作。

完整流程请见

references/operation-playbooks.md

。

Current Read-Side Helpers

当前读取侧辅助工具

Three read-side helpers matter here:

```
preflight_context_check.py
```
: revision-aware freshness review before formal writes; returns handoff-first digests, suggested read targets, write-tier guidance, and trust/drift state.
```
summarize_continuity_status.py
```
: ambient continuity status surface on the same freshness baseline; returns the same digest family plus shared workday-state and trust/drift guidance.
```
query_continuity.py
```
: read-only continuity recall surface; returns answer-first recall with
```
answer
```
, supporting citations, and a risk/freshness note. It also returns hits, token estimate, budget hint, freshness/conflict state, trust/drift state, an output variant label, and override review targets. Daily-log citations include explicit
```
date
```
values, current-state files win ties, and the context window stays bounded.

All attach-safe continuity text returned through these read-side surfaces is expected to respect the shared attached-text scan rules.

以下三个读取侧辅助工具至关重要：

```
preflight_context_check.py
```
：正式写入前的版本感知新鲜度审查；返回优先展示交接的摘要、建议读取目标、写入层级指导以及信任/漂移状态。
```
summarize_continuity_status.py
```
：基于相同新鲜度基线的环境连续性状态展示；返回相同系列的摘要以及共享工作日状态和信任/漂移指导。
```
query_continuity.py
```
：只读连续性召回展示；返回优先展示答案的结果，包含
```
answer
```
、支持性引用以及风险/新鲜度说明。它还返回命中结果、令牌估算、预算提示、新鲜度/冲突状态、信任/漂移状态、输出变体标签和覆盖审查目标。每日日志引用包含明确的
```
date
```
值，当前状态文件在冲突时优先，且上下文窗口保持受限。

通过这些读取侧接口返回的所有关联安全连续性文本，均需遵守共享的关联文本扫描规则。

Minimum Write Rules

最小写入规则

Before choosing a write target, read
```
STORAGE_ROOT/update_protocol.md
```
if it exists.
```
current_state
```
changes usually target
```
rolling_summary.md
```
.
```
stable_rule
```
changes usually target
```
context_brief.md
```
.
```
milestone_evidence
```
usually targets the daily log.
Do not update context files for trivial reads or minor edits with no durable change.

Default exits before any write should stay explicit:

```
no_write
```
is a normal successful result
```
merge_current_state
```
updates
```
rolling_summary.md
```
```
append_milestone
```
appends to the daily log
```
confirm
```
and
```
blocked
```
stop automatic writes rather than guessing

Read-side trust notes:

```
sidecar_trust_state
```
stays in helper JSON, not in protocol
```
1.0
```
```
continuity_drift_risk_level
```
is a review signal, not proof that the sidecar is damaged
```
allowed_operation_level
```
helps hosts route low-risk read vs review-first vs write-after-preflight flows

Project-local overrides MAY narrow read order, write order, or archive behavior, but they do not replace the core file contract.

在选择写入目标前，若存在
```
STORAGE_ROOT/update_protocol.md
```
则先读取它。
```
current_state
```
变更通常目标为
```
rolling_summary.md
```
。
```
stable_rule
```
变更通常目标为
```
context_brief.md
```
。
```
milestone_evidence
```
通常目标为每日日志。
不得为无持久变更的 trivial 读取或 minor 编辑更新上下文文件。

任何写入前的默认退出应保持明确：

```
no_write
```
是正常的成功结果
```
merge_current_state
```
更新
```
rolling_summary.md
```
```
append_milestone
```
追加到每日日志
```
confirm
```
和
```
blocked
```
停止自动写入而非猜测

读取侧信任说明：

```
sidecar_trust_state
```
保留在辅助工具JSON中，而非协议
```
1.0
```
```
continuity_drift_risk_level
```
是审查信号，而非边车已损坏的证明
```
allowed_operation_level
```
帮助宿主路由低风险读取、优先审查或预检后写入的流程

项目本地覆盖可缩小读取顺序、写入顺序或归档行为，但不得替代核心文件契约。

Agent Layered Write Judgment

Agent分层写入判断

Before writing continuity content, the agent should make the layer decision itself. Helpers can provide safe write context and static write-tier guidance, but they must not replace agent judgment about what the content means.

Use this quick check before editing managed files:

Is there a new durable fact, or is
```
no_write
```
the right result?
If writing is needed, is the main content
```
stable_rule
```
,
```
current_state
```
, or
```
milestone_evidence
```
?
Does the event span multiple layers, so it needs a
```
multi_layer_split
```
?
Is the same fact already present, so the right action is merge instead of duplicate?
Is the layer uncertain enough to
```
defer
```
or
```
confirm
```
rather than guess?

Layer defaults:

```
stable_rule
```
: long-lived workflow rules, source-of-truth routing, project boundaries, or recovery facts. Default target:
```
context_brief.md
```
.
```
current_state
```
: what is true now, including current phase, active risks, active judgments, and next steps. Default target:
```
rolling_summary.md
```
.
```
milestone_evidence
```
: completed validations, approvals, releases, accepted decisions, or other durable evidence. Default target: daily log.
```
no_write
```
,
```
defer
```
, and
```
confirm
```
are valid outcomes when nothing durable changed, the discussion is unstable, or the boundary needs explicit approval.

When more than one layer is valid, split different facts across layers and do not duplicate the same sentence.

For the detailed rules, conflict order, self-review template, and anonymized calibration cases, see

references/operation-playbooks.md

For protocol

1.0

update_protocol.md

is a human-reviewed override layer; helpers surface it but do not automatically execute its natural-language rules.

RecallLoom prefers the smallest valid write set. The agent decides what should change and prepares content; helpers decide whether the write is still safe to apply.

When generating workspace files, prefer the user's workspace language when it is supported by protocol

1.0

(

en

zh-CN

在写入连续性内容前，Agent应自行决定分层。辅助工具可提供安全写入上下文和静态写入层级指导，但不得替代Agent对内容含义的判断。

在编辑托管文件前使用以下快速检查：

是否有新的持久事实，还是
```
no_write
```
是正确结果？
若需要写入，主要内容是
```
stable_rule
```
、
```
current_state
```
还是
```
milestone_evidence
```
？
事件是否跨越多个层，因此需要
```
multi_layer_split
```
？
相同事实是否已存在，因此正确操作是合并而非重复？
层是否足够不确定，需要
```
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

），则优先使用该语言。

When Not To Update Context

无需更新上下文的场景

Do not update context files just because:

you performed a cold start
you answered a short question with no durable project change
you explored without reaching a stable conclusion
you made wording-only edits

The protocol is designed to reduce noise, not to turn every session into documentation work.

请勿仅因以下情况更新上下文文件：

执行了冷启动
回答了无持久项目变更的简短问题
进行了探索但未得出稳定结论
仅进行了措辞修改

本协议旨在减少噪音，而非将每个会话都变成文档工作。

Profiles

配置文件

RecallLoom provides four profiles:

```
profiles/general-project-continuity.md
```
```
profiles/research-writing.md
```
```
profiles/product-doc-collaboration.md
```

profiles/software-project-coordination.md

Profiles refine emphasis, evidence handling, and drift risk. Use

general-project-continuity.md

by default; switch to a specialized profile only when the project shape is a high-confidence match.

RecallLoom 提供四个配置文件：

```
profiles/general-project-continuity.md
```
```
profiles/research-writing.md
```
```
profiles/product-doc-collaboration.md
```

profiles/software-project-coordination.md

配置文件可调整侧重点、证据处理方式和漂移风险。默认使用

general-project-continuity.md

；仅当项目类型高度匹配时才切换到专门的配置文件。

What RecallLoom Does Not Try To Be

RecallLoom 不追求的定位

RecallLoom does not try to be:

a general-purpose memory server
a full agent execution runtime
a replacement for platform-specific instruction files
a heavy autonomous coding framework

It is the project continuity layer, not the whole agent stack.

RecallLoom 不追求成为：

通用内存服务器
完整的Agent执行运行时
平台特定指令文件的替代品
重型自主编码框架

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

Where To Read More

License

许可证

This package is released under Apache License 2.0.

本包基于 Apache License 2.0 发布。

recallloom

Original

Translation

RecallLoom

RecallLoom

Package Scope

包范围

Package Facts

包信息

Runtime Assumptions

运行时假设

Package Support Gate

包支持规则

Write Protocol Red Lines

写入协议红线

When To Use It

使用场景

First Attach Behavior

首次关联行为

Current Action Surface

当前操作接口

Initialized-Project Restore Contract

已初始化项目恢复契约

Public Interaction Rules

公共交互规则

Fast And Deep Paths

快速路径与深度路径

Core File Model

核心文件模型

Minimum Cold-Start Flow

最小冷启动流程

Current Read-Side Helpers

当前读取侧辅助工具

Minimum Write Rules

最小写入规则

Agent Layered Write Judgment

Agent分层写入判断

When Not To Update Context

无需更新上下文的场景

Profiles

配置文件

What RecallLoom Does Not Try To Be

RecallLoom 不追求的定位

Where To Read More

更多阅读资源

License

许可证