Concepts

This page explains how Recalletta works. Understanding these concepts makes everything else — the CLI commands, the dashboard (https://recalletta.ai), the configuration — make sense.

The Mental Model

Recalletta has five moving parts:

  1. Session capture — every AI coding session is saved automatically when it ends.
  2. Context injection — when a new session starts, relevant history and knowledge are injected before the agent begins work.
  3. Knowledge base — a structured, versioned store of knowledge that agents receive automatically in every future session.
  4. Crew — multiple AI agents working on the same project, sharing memory.
  5. Attractor — multi-stage pipelines defined as graphs, executed by crews.

Each part works independently, but they reinforce each other. Sessions feed context injection. The knowledge base augments context injection. Crews produce sessions that feed future crews. The feedback loop is the point.

Session Lifecycle

A session has three phases: start, work, end.

SessionStart

When an agent client (Claude Code, Gemini CLI, or Codex CLI) starts in a directory where Recalletta is enabled, the SessionStart hook fires. It does three things:

  1. Collects local context — working directory, git branch, recent commits, git status, and (if present) a .recalletta.json project pin.
  2. Calls the API with the local context and (optionally) the first prompt.
  3. Injects the response — the API returns formatted summaries of relevant past sessions and important KB entries. The hook injects this as additional context into the agent session.

The agent starts warm. It has context about the project before any work begins.

What gets sent to the API: working directory, hostname, OS, CLI version, agent type, git metadata (repo root, branch, remote, recent commits, status), and KB context if a project is pinned.

What comes back: a single formatted string containing session summaries, KB entries marked as important, and a KB structure index (compartment and entry names without content for non-important entries).

During the Session

Nothing special happens. The agent works normally. The client writes the conversation to a transcript file.

SessionEnd

When the agent session ends, the SessionEnd hook fires. It spawns a detached background process and exits immediately — there is no wait for the upload to finish.

The background process:

  1. Reads the transcript from the client's storage.
  2. Converts to markdown — a significant size reduction. The markdown captures the conversation structure (user messages, assistant responses, tool calls) without the raw overhead.
  3. Applies compaction if needed — if the markdown exceeds 10 MB, it reduces size by removing less important messages. Compaction is size-reduction, not redaction. Secrets are not removed.
  4. Detects resume chains — if this session resumed a previous one, the upload uses the original session's ID. This ensures continued sessions merge into a single record.
  5. Uploads the markdown body, session ID, and minimal context. The API upserts: new sessions are created, resumed sessions are updated.

Resume Chains

When an agent resumes a session, the client creates a new transcript file linked to the parent session. Recalletta follows this chain to find the root session ID, so all continuations of the same conversation are stored under one record.

Gemini CLI

Gemini CLI integrates via a native extension installed by recalletta init. This provides both context injection and session capture through the extension mechanism.

Codex CLI

Codex CLI integrates via a notify hook installed by recalletta init. A background monitor also captures Codex sessions:

  • Polls for agent processes.
  • Opens a time window while they are running.
  • Scans for transcript files modified during that window.
  • Uploads them in the background.

This is best-effort. It depends on process markers and transcript file discovery.

Context Injection

Context injection is what makes session 1,764 better than session 1. It is the mechanism that turns stored sessions and knowledge into useful context for the current session.

What Gets Injected

The API returns a formatted string containing:

  • Important KB entries — full content of entries marked as important, and all entries in compartments marked as important. These appear first.
  • KB structure index — compartment and entry names (without content) for non-important entries. This lets the agent know what knowledge exists and request it with recalletta kb <path> if needed.
  • Relevant session summaries — sessions matching the current context (same project, same directory, relevant to the first prompt).

Project Detection

The system needs to know which project the agent is working in to inject the right KB entries. Detection uses this precedence:

  1. Explicit pin — a .recalletta.json file in the directory tree with a project_id and slug. Created with recalletta pin <slug>. Overrides everything.
  2. Git remote match — the repo's git remote URL matched against registered projects. Exact match required.
  3. Directory prefix match — is the working directory a subdirectory of a registered project path? Longest match wins.
  4. Single project fallback — if there is exactly one project, it is used automatically.
  5. No match — no KB injected, only session search results.

Ignored Paths

Recalletta skips context detection and uploads for certain paths: node_modules, .git, vendor, venv, target, dist, build, __pycache__, and similar. This prevents supply-chain context injection from malicious packages and avoids noise.

Knowledge Base

The KB is a hierarchical content store designed to be machine-read, not just human-read.

Hierarchy

Personal Workspace
└── Projects (e.g., "recalletta")
    └── Compartments (e.g., "gotchas", "onboarding")
        └── Entries (e.g., "commits", "start")
            └── Versions (immutable history)

Path Addressing

Entries are addressed by path: project/compartment/entry. With a single project, agents can use the 2-part shorthand: compartment/entry.

Important Entries

Entries and compartments can be marked as important. Important entries are automatically included in the context injection for their project. This is the mechanism that turns documentation into active knowledge — write it once, mark it important, and every future agent session starts knowing it.

Keep important entries compact. Every important entry consumes agent context window. Over-marking entries as important degrades agent performance.

Versioning

Every edit creates a new version. Versions are immutable. History can be viewed, versions diffed, and any previous version restored with rollback. The KB evolves with the project without losing history.

CLI Reference

See Knowledge Base CLI for commands.

Crew

A crew is a group of AI agents working on the same project, sharing memory through the same session and KB systems.

How It Works

Each agent runs in its own tmux session. When an agent is summoned with recalletta crew summon <persona> <task>, the system:

  1. Fetches the persona's profile, communication instructions, and workflow from the KB.
  2. Writes a CLAUDE.md (or equivalent instruction file) for the agent.
  3. Launches a new tmux session with the appropriate AI client (Claude Code, Codex, or Gemini).
  4. Delivers the task message via tmux send-keys.

The agent works autonomously in its tmux session. Its session is saved by the same hooks as any other session. Its output is available to future agents through session search and context injection.

Communication

Agents communicate through two channels:

  • Messages (recalletta crew message <name> <msg>) — short messages delivered directly to the agent's tmux session. Good for quick coordination.
  • Mail-board reports (.crew/mail-board/) — markdown files for anything longer than a few sentences. Architecture proposals, implementation reports, code review feedback. Agents write reports and notify recipients with a contact message pointing to the file.

Observability

  • recalletta crew attach <name> — see exactly what any agent is doing in real time. Prompts, tool calls, output.
  • .crew/history.md — human-readable log of summons, releases, and messages.
  • Mail-board reports — durable artifacts of agent work.
  • Attractor status.json — per-stage status, notes, and failure reasons.

Not yet available: stable correlation IDs across runs, captured stdout/stderr per stage, structured timings, failure histograms. Planned: JSONL event logs per run, a diagnostics subcommand.

Multi-Machine Support

The bridge server (recalletta crew bridge start) enables cross-machine crew coordination. Messages are relayed via the bridge when recalletta crew message targets a remote host. All communication is encrypted — TLS for API relay, ChaCha20-Poly1305 (Noise IK pattern) for direct P2P connections.

Personas

Personas are available, each with a default AI client, a role, and a personality stored in the KB. Personas shape how agents approach problems — for example, one persona may optimize for performance while another writes systematic tests or reviews for correctness.

CLI Reference

See Crew CLI for commands.

Attractor

Attractor is a pipeline engine that executes multi-stage workflows defined as Graphviz DOT graphs.

How It Works

Agents write DOT files with nodes (stages) and edges (dependencies) using the pipeline specification. Each node can have custom attributes:

  • persona — which persona runs this stage.
  • client — which AI client to use (claude, codex, gemini).
  • prompt — the task instructions.
  • timeout — maximum time for the stage.
  • goal_gate — if true, the stage's outcome determines which edge to follow.
  • retry_target — which node to retry on failure.

Special node shapes define behavior:

  • component — parallel fan-out point.
  • tripleoctagon — fan-in merge point.
  • hexagon — human review gate.

Execution

Attractor walks the graph, summoning agents for each stage, waiting for completion, and passing context to the next stage. Parallel branches run concurrently. Fan-in merges are deterministic — branches sorted by ID, context namespaced as branch.<branch_id>.<key>.

Validation

recalletta attractor validate <file.dot> checks the graph for structural issues before execution: missing start/exit nodes, unreachable nodes, goal gates without retry targets, etc.

CLI Reference

See Attractor CLI for commands.

Data Flow Summary

Agent client starts (Claude Code, Gemini CLI, or Codex CLI)
    │
    ▼
SessionStart hook fires
    │ collects: working directory, git metadata, KB context
    │ calls the API for context
    │ receives: formatted context (session summaries + important KB entries)
    │ injects: additional context into agent session
    ▼
Agent works normally
    │ client writes transcript
    ▼
Agent session ends
    │
    ▼
SessionEnd hook fires
    │ spawns detached background process
    │ exits immediately (no wait)
    ▼
Background process
    │ reads transcript, converts to markdown
    │ detects resume chains
    │ compacts if > 10MB
    │ uploads to API
    ▼
Session stored in API
    │ available for future context injection
    │ searchable via recalletta "<query>"
    ▼
Next session starts → cycle repeats