Security and Privacy

What It Is

This page describes Recalletta's trust boundaries as an interface contract: what data is persisted locally, what data can be sent to the hosted API, what controls exist, and what Recalletta does not protect against.

Threat Model (What This Covers)

Recalletta is a persistent memory system for AI coding agents. Its security posture depends heavily on the security of:

  • the local machine and OS account
  • the repos and directories agents run in
  • the Recalletta account and API key
  • any network used for cross-host features (crew bridge)

This page assumes the goal is to avoid:

  • accidental leakage (committing artifacts to git, sharing logs, copying mail-board files)
  • surprise uploads (not realizing what gets sent to the hosted API)
  • cross-host messaging security (encrypted, but network topology matters)

This page does not promise protection against:

  • a compromised machine or account (malware, stolen SSH keys, hostile browser extensions)
  • an attacker with access to the home directory or repo checkout
  • an attacker who can read the hosted Recalletta account data (account takeover)

Data Flows (Explicit)

Local Persistence (On the Filesystem)

These are durable by default, and should be treated as sensitive if sessions contain sensitive data:

  • Project-root artifacts:
    • .crew/history.md (crew timeline / audit-like history)
    • .crew/mail-board/ (reports and long-form messages)
    • .attractor/runs/ (pipeline run outputs, stage status JSON, artifacts)
  • Home directory state:
    • ~/.recalletta/config.json (includes the API key; treat it like a password)
    • ~/.recalletta/crew.db (crew operational state and messages; SQLite)
    • ~/.recalletta/log/unified.log (CLI/hook/monitor events)
    • ~/.recalletta/repos/<repo-hash>.db (local code search index databases)

Note: artifacts under the project root can be accidentally committed if no action is taken. If the content is sensitive, keep .crew/ and .attractor/ out of git (for example via .gitignore) and avoid sharing them in bug reports.

Provider Transcript Storage (Still Exists)

Recalletta reads session transcripts from the AI client's local storage. Using Recalletta does not erase those transcripts.

Network Flows (What Is Sent to the Hosted API)

Recalletta is local-first, not local-only.

  • SessionStart (context injection):
    • Recalletta calls the hosted API to format the additional context that will be injected into the new agent session.
    • The request includes repo/context metadata such as working directory and git metadata (for example git remote, branch, status summary, recent commits), plus KB context when a project is pinned.
    • This is not "upload the repo," but it is not offline.
  • SessionEnd (session ingestion):
    • Recalletta converts the transcript to markdown and uploads the session body to the hosted API for storage and search.
    • Compaction is size reduction, not redaction. If a secret appears in the transcript, do not assume compaction will remove it.

Available Controls

Opt Out For Sensitive Directories

Use marker files to disable Recalletta in a directory tree:

  • Create .norecalletta in a directory to disable hooks/uploads for that directory and its children.
  • Create .yesrecalletta in a subdirectory to re-enable under that subtree.

Example:

cd /path/to/sensitive-repo
touch .norecalletta

Keep Artifacts Out of Git When Needed

If crew work and pipeline outputs can contain sensitive data, treat .crew/ and .attractor/ like build outputs: keep them uncommitted, or only store them in private repos with appropriate access controls.

API Key Hygiene

The API key enables reading and writing data in the Recalletta account.

  • Store it only where intended (for example ~/.recalletta/config.json).
  • Do not paste it into chat transcripts, KB entries, or issue trackers.
  • Rotate it if exposure is suspected.

Bridge (Cross-Host Messaging) Hygiene

For cross-host crew messaging:

  • Treat the bridge as an internal tool.
  • recalletta crew message (cross-machine delivery) encrypts all traffic: TLS for API relay transport, ChaCha20-Poly1305 (Noise IK pattern) for direct P2P connections.
  • P2P keys are generated per-machine and exchanged during peer discovery.

Operational Guidance (How Not To Get Burned)

  • Do not paste secrets (API keys, credentials, private keys, customer data) into agent sessions. If it enters the transcript, it can be persisted locally and uploaded.
  • Avoid embedding credentials in git remote URLs. Those remote URLs can show up in metadata sent during SessionStart.
  • Treat injected context as untrusted input. If a stored session or KB entry contains malicious instructions, it can steer the agent before any prompt is entered.
    • Mitigate procedurally: restrict who can write shared KB entries, review "important" entries, and keep high-risk projects opted out by default.

Guarantees vs Best-Effort

  • Recalletta can create local files/databases and can upload transcripts/metadata when hooks are enabled. OS permissions and account controls are the main enforcement mechanism.
  • Marker files (.norecalletta / .yesrecalletta) are intended to provide a clear opt-out boundary, but behavior should be verified in the target environment before relying on it for high-stakes policy enforcement.
  • Compaction reduces size to fit upload limits; it is not designed as a security feature.