Skip to content

Frappucc1no/recall-loom / skills/recallloom

recallloom

Flagged

Use when a task involves continuing a project, restoring project context, maintaining file-based project memory, updating current-state summaries, or recording meaningful progress across sessions. Works best for long-horizon, file-based projects and supports research writing, product document collaboration, software project coordination, and broader cross-functional project continuity.

FileKindSize
LICENSEother10.0 KB
NOTICEother190 B
SKILL.mdskill md24.5 KB
managed-assets.jsonconfig1.1 KB
native_commands/README.mdmarkdown1.2 KB
native_commands/claude-code/rl-init.md.tmplother323 B
native_commands/claude-code/rl-resume.md.tmplother290 B
native_commands/claude-code/rl-status.md.tmplother299 B
native_commands/claude-code/rl-validate.md.tmplother277 B
native_commands/gemini-cli/rl-init.toml.tmplother295 B
native_commands/gemini-cli/rl-resume.toml.tmplother262 B
native_commands/gemini-cli/rl-status.toml.tmplother271 B
native_commands/gemini-cli/rl-validate.toml.tmplother249 B
native_commands/opencode/rl-init.md.tmplother286 B
native_commands/opencode/rl-resume.md.tmplother253 B
native_commands/opencode/rl-status.md.tmplother262 B
native_commands/opencode/rl-validate.md.tmplother240 B
package-metadata.jsonconfig1.0 KB
profiles/general-project-continuity.mdmarkdown2.4 KB
profiles/product-doc-collaboration.mdmarkdown2.2 KB
profiles/research-writing.mdmarkdown2.1 KB
profiles/software-project-coordination.mdmarkdown2.8 KB
references/anti-patterns.mdmarkdown2.5 KB
references/contract-registry.jsonconfig7.7 KB
references/contract-schema.jsonconfig7.7 KB
references/file-contracts.mdmarkdown23.4 KB
references/operation-playbooks.mdmarkdown26.5 KB
references/package-support-policy.mdmarkdown9.4 KB
references/profiles.mdmarkdown2.0 KB
references/protocol.mdmarkdown20.5 KB
references/recording-workflow.mdmarkdown9.9 KB
scripts/_common.pyscript87.8 KB
scripts/append_daily_log_entry.pyscript40.4 KB
scripts/archive_logs.pyscript17.6 KB
scripts/commit_context_file.pyscript31.6 KB
scripts/core/__init__.pyscript39 B
scripts/core/bridge/__init__.pyscript30 B
scripts/core/bridge/blocks.pyscript6.9 KB
scripts/core/coldstart/__init__.pyscript26 B
scripts/core/coldstart/sources.pyscript22.4 KB
scripts/core/coldstart/structured.pyscript5.4 KB
scripts/core/continuity/__init__.pyscript34 B
scripts/core/continuity/daily_log.pyscript16.1 KB
scripts/core/continuity/freshness.pyscript15.3 KB
scripts/core/continuity/preflight.pyscript41.0 KB
scripts/core/continuity/quick_summary.pyscript10.9 KB
scripts/core/continuity/workday.pyscript12.3 KB
scripts/core/errors.pyscript838 B
scripts/core/failure/__init__.pyscript47 B
scripts/core/failure/context.pyscript5.6 KB
scripts/core/failure/contracts.pyscript108.6 KB
scripts/core/output/__init__.pyscript35 B
scripts/core/output/confirmation_material.pyscript15.0 KB
scripts/core/output/privacy.pyscript10.5 KB
scripts/core/output/user_status.pyscript5.8 KB
scripts/core/protocol/__init__.pyscript60 B
scripts/core/protocol/contracts.pyscript8.3 KB
scripts/core/protocol/markers.pyscript4.9 KB
scripts/core/protocol/sections.pyscript3.4 KB
scripts/core/protocol/templates.pyscript6.5 KB
scripts/core/provenance/__init__.pyscript67 B
scripts/core/provenance/bindings.pyscript13.2 KB
scripts/core/provenance/evidence.pyscript58.2 KB
scripts/core/provenance/inconsistent_review.pyscript85.6 KB
scripts/core/provenance/receipts.pyscript20.2 KB
scripts/core/provenance/state.pyscript38.0 KB
scripts/core/provenance/store.pyscript43.8 KB
scripts/core/recording/__init__.pyscript1.6 KB
scripts/core/recording/contracts.pyscript31.7 KB
scripts/core/recording/daily_log_append.pyscript30.2 KB
scripts/core/recording/managed_write.pyscript52.8 KB
scripts/core/recording/planner.pyscript20.6 KB
scripts/core/recording/privacy.pyscript1.7 KB
scripts/core/recording/suggestions.pyscript8.6 KB
scripts/core/recording/transaction.pyscript93.3 KB
scripts/core/registry/__init__.pyscript58 B
scripts/core/registry/loader.pyscript18.8 KB
scripts/core/safety/__init__.pyscript30 B
scripts/core/safety/attached_text.pyscript6.9 KB
scripts/core/safety/input_transport.pyscript61.0 KB
scripts/core/safety/prepared_input.pyscript24.4 KB
scripts/core/safety/scratch_residue.pyscript18.8 KB
scripts/core/support/__init__.pyscript53 B
scripts/core/support/cache.pyscript19.4 KB
scripts/core/support/policy.pyscript8.8 KB
scripts/core/trust/__init__.pyscript42 B
scripts/core/trust/state.pyscript4.1 KB
scripts/core/workspace/__init__.pyscript33 B
scripts/core/workspace/atomic_io.pyscript12.2 KB
scripts/core/workspace/runtime.pyscript54.7 KB
scripts/detect_project_root.pyscript3.4 KB
scripts/generate_coldstart_proposal.pyscript7.5 KB
scripts/init_context.pyscript37.8 KB
scripts/install_native_commands.pyscript31.5 KB
scripts/manage_entry_bridge.pyscript20.8 KB
scripts/preflight_context_check.pyscript10.1 KB
scripts/prepare_recovery_promotion.pyscript22.1 KB
scripts/query_continuity.pyscript84.1 KB
scripts/recallloom.pyscript233.7 KB
scripts/recommend_workday.pyscript17.6 KB
scripts/record_recovery_review.pyscript50.9 KB
scripts/remove_context.pyscript13.9 KB
scripts/repair_daily_log_cursor.pyscript33.7 KB
scripts/stage_recovery_proposal.pyscript17.5 KB
scripts/summarize_continuity_status.pyscript43.7 KB
scripts/sync_contract_docs.pyscript11.3 KB
scripts/unlock_write_lock.pyscript8.1 KB
scripts/validate_context.pyscript54.9 KB

scripts/core/continuity/freshness.py

View on GitHub
#!/usr/bin/env python3
"""Freshness and digest helpers for RecallLoom continuity reads."""

from __future__ import annotations

from pathlib import Path

from core.output.privacy import redact_public_text
from core.protocol.sections import extract_section_text

DEFAULT_WORKSPACE_ARTIFACT_EXCLUDED_DIRS = {
    ".git",
    ".hg",
    ".svn",
    ".idea",
    ".vscode",
    ".venv",
    "venv",
    "__pycache__",
    "node_modules",
    "dist",
    "build",
    "coverage",
    ".mypy_cache",
    ".pytest_cache",
    ".ruff_cache",
}

DEFAULT_WORKSPACE_ARTIFACT_EXCLUDED_FILES = {
    ".DS_Store",
    ".recallloom.write.lock",
}

ROLLING_SUMMARY_EMPTY_SHELL_TEMPLATES = (
    {
        "current_state": (
            "Write the validated handoff-first state here:",
            "Active state",
            "Relevant files",
            "Critical context",
        ),
        "active_judgments": (
            "Record the coordination judgments that matter right now:",
            "Key decisions",
            "Active assumptions",
            "Tradeoffs in force",
        ),
        "risks_open_questions": (
            "Make blocker visibility explicit:",
            "Blocked items",
            "Open questions",
            "External dependencies",
        ),
        "next_step": (
            "Describe the handoff-first next move:",
            "Active task",
            "Owner or role when known",
            "Immediate next action",
        ),
    },
    {
        "current_state": (
            "这里优先写 handoff-first 的已确认当前状态:",
            "当前活跃状态",
            "相关文件",
            "关键上下文",
        ),
        "active_judgments": (
            "这里记录当前真正影响推进的判断:",
            "关键决策",
            "当前假设",
            "仍在生效的取舍",
        ),
        "risks_open_questions": (
            "把阻塞与未决问题写清楚:",
            "当前阻塞",
            "未决问题",
            "外部依赖",
        ),
        "next_step": (
            "这里写 handoff-first 的下一步:",
            "当前任务",
            "已知负责人或角色",
            "立刻要做的动作",
        ),
    },
)

EMPTY_NEXT_STEP_MARKERS = {
    "none",
    "n/a",
    "na",
    "no next step",
    "no next action",
    "无",
    "暂无",
    "无下一步",
    "暂无下一步",
    "无后续动作",
}


def _structural_cursor_repair_revision_only(
    *,
    state: dict,
    summary_base_workspace_revision: int,
    workspace_revision: int,
) -> bool:
    if workspace_revision != summary_base_workspace_revision + 1:
        return False
    provenance = state.get("provenance")
    if not isinstance(provenance, dict):
        return False
    repair = provenance.get("last_structural_repair")
    if not isinstance(repair, dict):
        return False
    if repair.get("repair_kind") != "daily_log_cursor_repair":
        return False
    if repair.get("receipt_backed") is not False:
        return False
    if repair.get("finalizes_mutating_receipt") is not False:
        return False
    files_state = state.get("files")
    if not isinstance(files_state, dict):
        return True
    for file_state in files_state.values():
        if not isinstance(file_state, dict):
            continue
        base_revision = file_state.get("base_workspace_revision")
        if isinstance(base_revision, int) and base_revision > summary_base_workspace_revision:
            return False
    return True


def latest_file(paths: list[Path]) -> Path | None:
    if not paths:
        return None
    return max(paths, key=lambda path: path.stat().st_mtime)


def normalized_section_lines(section_text: str) -> list[str]:
    lines: list[str] = []
    for raw in section_text.splitlines():
        stripped = raw.strip()
        if not stripped:
            continue
        if stripped.startswith("<!--"):
            continue
        if stripped.startswith("#"):
            continue
        stripped = stripped.lstrip("-* ").strip()
        if not stripped:
            continue
        lines.append(stripped.casefold())
    return lines


def summary_matches_empty_shell_template(summary_text: str) -> bool:
    for template in ROLLING_SUMMARY_EMPTY_SHELL_TEMPLATES:
        if all(
            normalized_section_lines(extract_section_text(summary_text, section_key))
            == [line.casefold() for line in expected_lines]
            for section_key, expected_lines in template.items()
        ):
            return True
    return False


def continuity_state_for_workspace(
    *,
    state: dict,
    summary_text: str,
    latest_daily_log_exists: bool,
) -> tuple[str, bool]:
    daily_logs_state = state.get("daily_logs")
    entry_count = daily_logs_state.get("entry_count") if isinstance(daily_logs_state, dict) else None

    empty_shell = (
        not latest_daily_log_exists
        and isinstance(entry_count, int)
        and entry_count == 0
        and summary_matches_empty_shell_template(summary_text)
    )
    continuity_state = "initialized_empty_shell" if empty_shell else "initialized_seeded"
    return continuity_state, (not empty_shell)


def is_effectively_empty_summary_next_step(text: str) -> bool:
    cleaned = normalized_section_lines(text)
    if not cleaned:
        return True
    lowered = " ".join(cleaned).strip().strip(" .。!!")
    return lowered in EMPTY_NEXT_STEP_MARKERS


def continuity_confidence_level(
    *,
    workspace_valid: bool,
    summary_revision_is_stale: bool,
    workspace_artifact_is_newer: bool | None,
    latest_daily_log_exists: bool,
    workspace_artifact_scan_mode: str,
) -> str:
    if not workspace_valid:
        return "broken"
    artifact_newer = bool(workspace_artifact_is_newer)
    if (summary_revision_is_stale and not latest_daily_log_exists) or (
        artifact_newer and not latest_daily_log_exists
    ):
        return "low"
    if summary_revision_is_stale or artifact_newer or not latest_daily_log_exists:
        return "medium"
    if workspace_artifact_scan_mode != "full":
        return "medium"
    return "high"


def freshness_risk_summary(
    *,
    workspace_artifact_scan_mode: str,
    workspace_artifact_scan_performed: bool,
    workspace_artifact_newer_than_summary: bool | None,
    summary_revision_stale: bool,
    continuity_confidence: str,
) -> dict:
    if continuity_confidence == "broken":
        return {
            "level": "high",
            "note": "Continuity state is broken. Validate the workspace before trusting recall or writing.",
        }
    if workspace_artifact_newer_than_summary:
        return {
            "level": "high",
            "note": "Workspace artifacts are newer than rolling_summary.md. Review current workspace state before trusting recall or writing.",
        }
    if summary_revision_stale:
        return {
            "level": "medium",
            "note": "workspace_revision is ahead of the rolling summary base revision. Review rolling_summary.md before trusting recall or writing.",
        }
    if not workspace_artifact_scan_performed or workspace_artifact_scan_mode != "full":
        return {
            "level": "medium",
            "note": "Only the quick freshness path was used. Run a full scan before high-confidence writes.",
        }
    return {
        "level": "low",
        "note": None,
    }


def read_freshness_semantics(
    *,
    workspace_artifact_scan_mode: str,
    workspace_artifact_scan_performed: bool,
    workspace_artifact_newer_than_summary: bool | None,
    summary_revision_stale: bool,
    workspace_newer_than_summary: bool,
    continuity_confidence: str,
) -> dict:
    freshness_risk = freshness_risk_summary(
        workspace_artifact_scan_mode=workspace_artifact_scan_mode,
        workspace_artifact_scan_performed=workspace_artifact_scan_performed,
        workspace_artifact_newer_than_summary=workspace_artifact_newer_than_summary,
        summary_revision_stale=summary_revision_stale,
        continuity_confidence=continuity_confidence,
    )
    if continuity_confidence == "high" and freshness_risk["level"] == "low":
        read_confidence = "current"
    elif workspace_artifact_newer_than_summary:
        read_confidence = "workspace_newer_than_summary"
    elif summary_revision_stale or workspace_newer_than_summary:
        read_confidence = "stale_summary_review_recommended"
    elif continuity_confidence == "broken":
        read_confidence = "broken"
    else:
        read_confidence = "bounded"

    return {
        "legacy_path": "protocol_1_0_sidecar_compatible",
        "legacy_path_compatible": True,
        "stale_summary": summary_revision_stale,
        "workspace_newer_than_summary": workspace_newer_than_summary,
        "read_confidence": read_confidence,
        "freshness_risk_level": freshness_risk["level"],
        "freshness_risk_note": freshness_risk["note"],
    }


def digest_excerpt(
    text: str,
    *,
    max_lines: int = 4,
    project_root: str | Path | None = None,
) -> str | None:
    lines: list[str] = []
    for raw in text.splitlines():
        stripped = raw.strip()
        if not stripped:
            continue
        if stripped.startswith("<!--"):
            continue
        stripped = stripped.lstrip("-* ").strip()
        if not stripped:
            continue
        stripped = redact_public_text(stripped, project_root=project_root) or "redacted"
        lines.append(stripped)
        if len(lines) >= max_lines:
            break
    if not lines:
        return None
    return " | ".join(lines)


def _digest_excerpt(
    text: str,
    *,
    max_lines: int = 4,
    project_root: str | Path | None = None,
) -> str | None:
    return digest_excerpt(text, max_lines=max_lines, project_root=project_root)


def continuity_digest_bundle(
    *,
    summary_text: str,
    latest_daily_log_text: str | None = None,
    project_root: str | Path | None = None,
) -> dict:
    summary_is_empty_shell_template = summary_matches_empty_shell_template(summary_text)
    if summary_is_empty_shell_template:
        active_task_digest = None
        blocked_digest = None
    else:
        next_step_text = extract_section_text(summary_text, "next_step")
        risks_text = extract_section_text(summary_text, "risks_open_questions")
        active_task_digest = (
            None
            if is_effectively_empty_summary_next_step(next_step_text)
            else digest_excerpt(next_step_text, project_root=project_root)
        )
        blocked_digest = digest_excerpt(risks_text, project_root=project_root)

    latest_relevant_log_digest = None
    if latest_daily_log_text:
        log_sections = [
            extract_section_text(latest_daily_log_text, "work_completed"),
            extract_section_text(latest_daily_log_text, "key_decisions"),
            extract_section_text(latest_daily_log_text, "recommended_next_step"),
        ]
        latest_relevant_log_digest = digest_excerpt(
            "\n".join(section for section in log_sections if section.strip()),
            project_root=project_root,
        )

    suggested_handoff_sections: list[str] = []
    if active_task_digest:
        suggested_handoff_sections.append("next_step")
    if blocked_digest:
        suggested_handoff_sections.append("risks_open_questions")
    if latest_relevant_log_digest:
        suggested_handoff_sections.append("latest_daily_log")

    return {
        "active_task_digest": active_task_digest,
        "blocked_digest": blocked_digest,
        "latest_relevant_log_digest": latest_relevant_log_digest,
        "suggested_handoff_sections": suggested_handoff_sections,
    }


def iter_workspace_artifacts(
    project_root: Path,
    storage_root: Path,
    *,
    excluded_dirs: set[str] | None = None,
    excluded_files: set[str] | None = None,
) -> list[Path]:
    excluded_dirs = excluded_dirs or DEFAULT_WORKSPACE_ARTIFACT_EXCLUDED_DIRS
    excluded_files = excluded_files or DEFAULT_WORKSPACE_ARTIFACT_EXCLUDED_FILES
    artifacts: list[Path] = []
    for path in project_root.rglob("*"):
        if not path.is_file():
            continue
        try:
            path.relative_to(storage_root)
            continue
        except ValueError:
            pass
        if path.name in excluded_files:
            continue
        rel_path = path.relative_to(project_root)
        if any(part in excluded_dirs for part in rel_path.parent.parts):
            continue
        artifacts.append(path)
    return artifacts


def evaluate_continuity_freshness(
    *,
    project_root: Path,
    storage_root: Path,
    summary_path: Path,
    workspace_revision: int,
    summary_base_workspace_revision: int,
    latest_daily_log_exists: bool,
    scan_mode: str = "quick",
    state: dict | None = None,
) -> dict:
    if scan_mode not in {"quick", "full"}:
        raise ValueError(f"Unsupported scan_mode: {scan_mode}")

    workspace_artifact_scan_performed = scan_mode == "full"
    latest_workspace_artifact = None
    workspace_artifact_is_newer = None
    summary_mtime = summary_path.stat().st_mtime

    if workspace_artifact_scan_performed:
        latest_workspace_artifact = latest_file(
            iter_workspace_artifacts(project_root, storage_root)
        )
        workspace_artifact_is_newer = (
            latest_workspace_artifact is not None
            and latest_workspace_artifact.stat().st_mtime > summary_mtime
        )

    raw_summary_revision_is_stale = workspace_revision > summary_base_workspace_revision
    structural_cursor_repair_revision_only = (
        raw_summary_revision_is_stale
        and isinstance(state, dict)
        and _structural_cursor_repair_revision_only(
            state=state,
            summary_base_workspace_revision=summary_base_workspace_revision,
            workspace_revision=workspace_revision,
        )
    )
    summary_revision_is_stale = (
        raw_summary_revision_is_stale and not structural_cursor_repair_revision_only
    )
    workspace_is_newer = (
        (workspace_artifact_is_newer if workspace_artifact_is_newer is not None else False)
        or summary_revision_is_stale
    )
    continuity_confidence = continuity_confidence_level(
        workspace_valid=True,
        summary_revision_is_stale=summary_revision_is_stale,
        workspace_artifact_is_newer=workspace_artifact_is_newer,
        latest_daily_log_exists=latest_daily_log_exists,
        workspace_artifact_scan_mode=scan_mode,
    )

    return {
        "workspace_artifact_scan_mode": scan_mode,
        "workspace_artifact_scan_performed": workspace_artifact_scan_performed,
        "latest_workspace_artifact": latest_workspace_artifact,
        "workspace_artifact_newer_than_summary": workspace_artifact_is_newer,
        "summary_revision_stale": summary_revision_is_stale,
        "raw_summary_revision_stale": raw_summary_revision_is_stale,
        "structural_cursor_repair_revision_only": structural_cursor_repair_revision_only,
        "workspace_newer_than_summary": workspace_is_newer,
        "summary_stale": workspace_is_newer,
        "continuity_confidence": continuity_confidence,
        "read_freshness": read_freshness_semantics(
            workspace_artifact_scan_mode=scan_mode,
            workspace_artifact_scan_performed=workspace_artifact_scan_performed,
            workspace_artifact_newer_than_summary=workspace_artifact_is_newer,
            summary_revision_stale=summary_revision_is_stale,
            workspace_newer_than_summary=workspace_is_newer,
            continuity_confidence=continuity_confidence,
        ),
    }
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall