recallloom

# 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.

## 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`

## Package Facts

<!-- RecallLoom metadata sync start: package-metadata -->
- package version: `0.4.5`
- protocol version: `1.0`
- supported protocol versions:
  - `1.0`
<!-- RecallLoom metadata sync end: package-metadata -->

## Runtime Assumptions

<!-- RecallLoom metadata sync start: 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`
<!-- RecallLoom metadata sync end: runtime-assumptions -->

## 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`.

## Public Surface And Required Checks

- Public package and release surfaces MUST stay limited to files a user needs to install, understand, and operate the package.
- Public surfaces MUST NOT include copied project memory, generated runtime output, machine-local data, maintainer-only working files, or material that is not required by the installable package.
- Public CI and required checks MAY validate repository contents and metadata.
- Required-check wording MUST NOT present repository checks as proof of a user's local workspace state, host behavior, or sidecar trust status.

## Non-Invasive Defaults And UX Gates

- Core install and daily use MUST NOT require or auto-install hooks, daemons, watchers, MCP/plugin enforcement, host adapters, telemetry/metrics, or remote payload transmission.
- Native command wrappers are opt-in convenience entrypoints over the same dispatcher, not a required enforcement layer.
- Ordinary docs/source/planning edits outside the managed sidecar stay silent allow or low-friction unless they affect provenance-sensitive RecallLoom state.
- Managed sidecar or provenance-impacting actions surface one of `allow`, `warn`, `ask`, or `block` in helper readiness output when provenance state is relevant.
- `warn` is for low-risk structural-only or readable legacy states and should stay brief; repeated same-session low-risk warnings should be cooldown-friendly.
- `ask` is for legacy review / repair import or reviewed imported baseline actions and requires explicit operator confirmation before higher-risk writes.
- `block` is non-waivable for forged markers, detected receipt/store inconsistency, direct `state.json` / `config.json` edits, privacy violations, and any state classified as `inconsistent_or_tampered_evidence`.
- Do not present remote services, host memory, plugins, MCP, hooks, or wrappers as authority for local helper evidence.
- Receipt-backed mutation is limited to dispatcher-issued managed-file writes, daily-log appends to the current latest cursor, and post-append summary sync. Archive apply and bridge apply remain preview-only until those surfaces gain their own receipt support.

## 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.
- Daily-log cursor repair MUST use `repair_daily_log_cursor.py` or dispatcher `repair-daily-log-cursor`. Do not hand-edit `state.json.daily_logs`.
- 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 he