Guarantees vs. Best-Effort

Recalletta aims to be reliable, but its behavior depends on third-party AI clients and operating system state. This page clarifies what is a hard guarantee and what is a "best-effort" convenience.

Session Capture

Contract (in current implementation)

  • Claude Code: If hooks are enabled and the CLI can read the transcript, Recalletta will attempt to spawn a background uploader on SessionEnd.
  • Background Uploads: Uploads are spawned as a detached process so your terminal session can exit immediately.

Best-Effort

  • Codex: Codex integrates via a notify hook installed by recalletta init. If the notify hook fails to fire or the transcript location is non-standard, session capture falls back to process monitoring, which may miss short-lived agent processes.
  • Gemini (fallback path): Gemini integrates via a native hook installed by recalletta init, but it can also be captured via the background monitor as a fallback. The monitor path has the same best-effort limitations as Codex.
  • Resume Chains: Matching resumed sessions to their root ID depends on the client providing a session reference in its transcript. If the client changes its transcript format, resume chains might break until Recalletta is updated.

Context Injection

Contract (in current implementation)

  • Content Delivery: If the API is reachable and the hook fires, Recalletta writes context to stdout for the agent to consume.
  • Important Entries: Entries marked as important are included in the context injection payload when project detection/pinning succeeds.

Best-Effort

  • Project Detection: While project detection has a clear precedence (pin file > git remote > path prefix), it can fail if your environment is missing git metadata or if a pin file is unreadable.
  • Relevance Ranking: Session summaries returned during injection are ranked using BM25. Like all search systems, relevance is "best-effort"—it might include a session that is technically similar but not helpful, or miss a helpful one with no keyword overlap.

Crew and Attractor

Contract (in current implementation)

  • Deterministic Merge: Attractor parallel fan-in merges sort branches by ID and namespace context keys to avoid collisions.

Best-Effort

  • Agent Compliance: We cannot guarantee that an AI agent will follow the communication protocol (writing to the mail-board, using recalletta crew message). Personas include instructions for these behaviors, but the agent’s actual compliance depends on the underlying model’s capabilities.
  • Observability Persistence: The .crew/history.md and mail-board files are written locally. If an agent fails so catastrophically that it cannot run CLI commands, the history record for that event might be incomplete.
  • Message Delivery: crew message relies on a live tmux session and successful tmux message delivery. If the session does not exist, tmux is unhealthy, or message delivery fails, delivery is not guaranteed.

Network and Security

Contract (in current implementation)

  • Marker Files: Recalletta skips context detection and session uploads in any directory tree where a .norecalletta file is present (unless overridden by a closer .yesrecalletta).

Best-Effort

  • Compaction: Compaction is a "best-effort" size reduction to ensure uploads succeed. It is not a security feature and does not guarantee the removal of sensitive information.