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/recording-workflow.md
• references/protocol.md

Package Facts

<!-- RecallLoom metadata sync start: package-metadata -->

• package version: 0.5.0
• 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 because no local support cache exists, local diagnostic, read-only, and mutating actions MAY continue; network access is not a prerequisite for local RecallLoom use.
• A structurally invalid or uninterpretable local support cache permits diagnostic actions only while offline. A structurally valid stale cache is re-evaluated against the current package version and keeps its supported, upgrade_recommended, readonly_only, or diagnostic_only restriction.
• Invalid-cache diagnostics MUST identify the cache condition with a public-safe reason and direct recovery toward read-only diagnosis, online refresh and atomic cache replacement, or removal of the invalid package-scoped local cache. They MUST NOT present a package upgrade as the cache repair or describe the cache as tampered.
• invalid_support_advisory remains distinct from an invalid local cache: correct or refresh the advisory rather than treating it as cache damage.
• 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 general, legacy, or unbound state classified as inconsistent_or_tampered_evidence.
• D5 is the sole narrow recovery transition: only helper-path target-only post-hash evidence that is contract-valid for the current D5 schema and has an exact failure-time state match may proceed through a fresh binding, human proposal/review, and expected-binding promotion. It is not a waiver and does not prove cryptographic authorship. Promotion still requires fresh validate, status, and preflight before a write. The exact D5 human-material sections, JSON keys, and promotion commands are in references/operation-playbooks.md.
• 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 and bridge remain preview-only; their apply modes remain unsupported until those surfaces gain their own receipt support.

Write Protocol Red Lines

• Managed sidecar mutations in normal operation MUST use the applicable dispatcher surface: use write for managed-file writes, append for daily-log entries, and sync-current-state-after-append only when its post-append contract requires that lane. Do not bypass the dispatcher with blind file replacement, blind patching, or hand-built sidecar files.
• Daily-log writes in normal operation MUST use dispatcher append; its internal helper writes the entry. Do not handwrite daily-log-entry markers.
• Daily-log cursor repair in normal operation MUST use dispatcher repair-daily-log-cursor; its internal helper performs the repair. Do not hand-edit state.json.daily_logs.
• Overwrite-style managed files in normal operation MUST use dispatcher write; its internal helper performs the revision-aware commit. Do not handwrite file-state markers.
• STORAGE_ROOT/state.json and STORAGE_ROOT/config.json MUST NOT be hand-edited during normal operation.
• Normal operations use only the applicable dispatcher surface. Managed-file writes and daily-log entries use write and append; sync-current-state-after-append is used only when its post-append contract requires that lane. commit_context_file.py and append_daily_log_entry.py are internal dispatcher/integration surfaces: the dispatcher performs its own fresh preflight, constructs the binding, and persists the matching lease immediately before calling a helper. A read-only preflight does not issue either material, there is no independent operator pickup interface, and a hand-invoked helper without dispatcher-issued material is expected to fail. For the first write from a reviewed imported baseline, use dispatcher write or append with --confirm-review-imported-baseline; the post-append sync lane also accepts that confirmation when its contract requires it. The internal helpers do not accept the flag and only consume dispatcher-issued confirmation-bound binding and lease material.
• 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.
• Damaged-sidecar recovery MUST use the canonical recovery proposal/review/promotion helpers and validate_context.py; do not hand-edit managed markers, state.json, config.json, receipts, or helper-evidence stores.

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

First Attach Behavior

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

The correct flow is:

1. detect whether a valid RecallLoom sidecar already exists
2. if it exists, continue normally without making initialization into extra ceremony
3. if it does not exist, explain that the project is not initialized yet and ask whether initialization should be performed
4. if the user explicitly confirms, or directly says rl-init, run the standard initialization action
5. 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.

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, record --suggest, record --plan, append, write, sync-current-state-after-append, and repair-daily-log-cursor. For append, write, and sync-current-state-after-append only, use --compact-json when a bounded transaction result is needed: it emits recallloom.transaction.compact/1.0, remains below 2048 UTF-8 bytes, and is mutually exclusive with the legacy schema-1.1 --json output. Use quick-summary for current-state snapshots, record --suggest to produce a side-effect-free candidate recording prompt after a durable milestone/decision/validation signal, record --plan to classify a recording intent and get the next safe helper step, append --entry-json for milestone logging, write --type ... --source-file <prepared-file> --dry-run or write --type ... --stdin --dry-run before typed managed-file writes, and sync-current-state-after-append --reuse-current-summary --semantic-unchanged-assertion-json <json> only after preflight allows metadata-only post_append_summary_sync; see references/recording-workflow.md for the bound assertion JSON skeleton. record --suggest never writes, never watches in the background, and never turns sensitive or attached raw material into a write path; it only returns a sanitized candidate summary and suggested record --plan path when a prompt is appropriate. Use repair-daily-log-cursor in preview mode first when state.json.daily_logs no longer matches the parsed latest active daily log. Preview returns a public-safe repair classification, preview_digest, expected workspace revision, confirmation material, and post-repair validation step. Apply mode requires --apply --yes plus a fresh preview binding through --expected-workspace-revision or --preview-digest, is support-gated as mutating, and repairs cursor fields without writing helper receipts or rewriting daily-log content. 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.

Initialized-Project Restore Contract

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

1. check for a valid RecallLoom sidecar before broad skill fan-out
2. if the sidecar is valid, route into the normal RecallLoom fast path
3. 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.

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.