# Lobu architecture and concepts

> The Lobu model, from connectors and event-sourced memory to agents, workers, watchers, and self-improvement.

Lobu is the operating layer between company systems and organizational agents. It gives agents an authorization-filtered history of what happened, isolated workspaces to operate in, and governed ways to act.

## System boundaries

```text
Entrypoints
Slack · Telegram · WhatsApp · Discord · Teams · Google Chat · REST · MCP
    ↓
Gateway / control plane
Auth · routing · agent config · ACLs · approvals · secret resolution · queues
    ↓
Conversation worker + workspace
Model loop · bash · files · skills · MCP tools · network proxy
```

The gateway is the trusted boundary. Workers execute agent turns against a per-user, DM, channel, or task workspace. Some deployments run workers as ordinary child processes with the gateway egress proxy as the network boundary; hardened hosts may use `systemd-run`; provider-backed environments may execute in a remote sandbox.

Use **workspace** for per-conversation files. Reserve **sandbox provider** for runtime-provider execution such as a remote or device-backed sandbox.

## The data and action loop

```text
Definition time
Connector code ──▶ Connector definition
                    auth · feeds · event kinds · operations

Ingestion time
Connection ──▶ Feed ──▶ Run ──▶ Event log ──▶ Entities + projections
account/app     collected   status     append-only   current state
or webhook      streaming   inputs     evidence      with evidence
                virtual     outputs

Agent time
Authorized events + entities ──▶ Agent or watcher ──▶ Action / reaction
                                      │                    │
                                      │                    ▼
                                      └──────────── External outcome
                                                     reply · completion
                                                     rejection · metric
                                                              │
                                                              ▼
                                                          More events
```

This loop is the central architecture: ingestion, memory, agent work, feedback, and action history are not separate disconnected systems.

## Connector definitions, connections, and feeds

| Concept | Meaning |
| --- | --- |
| **Connector definition** | Reusable integration contract. Declares authentication methods, feed schemas, event kinds, actions, runtime requirements, and optional MCP/OpenAPI bridges. |
| **Connection** | One configured installation inside an organization. `github` is a definition; “Acme production GitHub organization” is a connection. |
| **Feed** | One stream or query surface exposed by a connection. A connection can expose several feeds. |
| **Operation** | A connector, MCP, or OpenAPI action that can mutate or query the source. |
| **Auth profile** | A reusable user- or organization-scoped credential used by a connection or provider. |

Connection capabilities are composed rather than stored as rigid classes: feeds provide data, channel bindings provide chat, operations provide actions, and synchronized ACL state defines the audience.

### Feed kinds

- **Collected** — Lobu calls `sync()`, resumes from a checkpoint, and appends new events.
- **Streaming** — a webhook, platform adapter, or device pushes events as they happen; Lobu never polls it.
- **Virtual** — the connector performs a live search or query; results are not normally synchronized into the log unless an agent or watcher saves them.

Connector source files are explicitly referenced with `connectorFromFile(...)`. `lobu apply` type-checks and bundles only referenced code, registers the definition, and makes its feeds available for configured connections.

## Project, agent, and watcher ownership

`lobu.config.ts` is project-level desired state. The top-level project owns organization-wide wiring; agents own their behavior and chat bindings.

```text
Project
├── agents
├── organization inference providers
├── connections and auth profiles
├── entity and relationship types
├── connector source files
└── watchers

Agent
├── IDENTITY.md / SOUL.md / USER.md
├── skills
├── model provider preferences
├── tool policy
├── guardrails
├── network policy
├── Nix packages
└── platform bindings

Watcher
├── owning agent
├── schedule and sources
├── prompt and keying
├── optional reaction script
└── notification / cooldown / tags
```

A watcher belongs to exactly one agent, but it is declared at the project level. A connection is also project-level. A chat platform binding is agent-level.

## Runs, events, and entity memory

A **run** records one execution boundary: connector sync, agent turn, watcher window, scheduled behavior, reaction, or operation.

An **event** is the durable fact produced or observed by that execution. Events can carry source identity, semantic type, occurrence time, engagement score, typed metadata, connection/feed/run provenance, entity links, and supersession lineage.

The event log is append-only. Current-state projections select the latest non-superseded representation without destroying older evidence.

| Layer | Scope | Use |
| --- | --- | --- |
| **Workspace filesystem** | One user, DM, channel, or task | Drafts, scripts, downloads, generated files, and intermediate work |
| **Event log** | Organization, filtered by ACL | Durable evidence of observations, actions, corrections, and outcomes |
| **Entity memory** | Shared typed objects | Current and historical knowledge about companies, projects, people, incidents, and other domain objects |
| **Relationships** | Shared graph | Explicit typed links between entities |
| **Watch surfaces / projections** | Derived current views | Status pages, summaries, dashboards, and other maintained representations |

An event can attach to several entities. A single support email can update a company, a contact, and a renewal project while keeping one source event as evidence.

### Compensation instead of fictional rollback

Real-world effects cannot always be reversed. An email cannot be unsent and a customer may already have seen a wrong update.

```text
run 100 sends the wrong email
    ↓
recipient reply arrives
    ↓
human correction is appended
    ↓
run 101 sends a clarification
    ↓
later reply records whether recovery worked
```

Agents can backtrace authorized history and perform compensating actions. The original mistake, correction, compensation, and residual outcome remain available for audit and learning.

## Agent runtime

```text
User or channel event
    ↓
Gateway
authenticate · resolve ACL · load agent version
    ↓
Context
prompt files · skills · memory · thread · model/provider choice
    ↓
Conversation worker
model loop · commands · files · MCP tools
    ↓
Guardrails · approval · egress proxy
    ↓
Reply and events
```

An agent definition combines prompt files, local and registry skills, inference provider preferences, tool policy, guardrails, network policy, Nix packages, and chat platform bindings. Project-level config adds connections, entity schemas, relationship schemas, watchers, connector source files, and organization inference providers.

Inference and execution are independent. A model may come from OpenAI, Anthropic, OpenRouter, Gemini, or an organization-defined compatible endpoint while commands run in the builtin worker runtime, an authorized device, or a provider-backed sandbox environment.

### MCP, connectors, and memory have different jobs

- **Connectors** continuously ingest or query systems and define source actions.
- **Memory** stores durable organizational knowledge and evidence.
- **MCP tools** let an active agent perform live work.
- **Skills** teach the agent procedures and may request Nix packages.
- **Guardrails and tool policy** determine what is allowed.
- **Reactions** run typed code after watcher extraction.

A useful rule is: the graph is for knowing; MCP and connector operations are for doing.

## Behaviors

Lobu exposes three behavior kinds:

- **Listen** — react to live chat or platform events.
- **Watch** — process new source windows incrementally and skip empty windows.
- **Schedule** — run because of the clock even when no new source data exists.

A watcher can read events, entities, metrics, previous reactions, and human corrections. It can save memory, maintain a surface, notify someone, call a tool, request approval, or remain silent. Watchers are versioned, and runs stay tied to the exact version that produced them.

## Self-improvement

Self-improvement is an architecture pattern built from existing Lobu primitives: events, runs, watchers, versions, evals, and approvals.

```text
Production trajectories
runs · actions · feedback · metrics
    ↓
System watchers
harvest evals · write lessons · propose changes
    ↓
Candidate version
prompt · skill · model · retrieval · routing · guardrail
    ↓
Replay / held-out evals
    ↓
Approval-bound promotion
    ↓
Later outcomes become more events
```

Useful signals already arrive as events: votes, replies, engagement scores, approvals, rejections, corrections, action failures, compensating actions, metrics, and eval results. A system watcher can turn those trajectories into regression cases, evidence-backed lessons, and proposed prompt, skill, model, retrieval, routing, or guardrail versions.

**Status:** observation, lessons, eval harvesting, and proposal generation fit the current model. A single first-class workflow for automatic replay, approval binding, and organization-wide promotion is still a product boundary. Background watchers should not receive general builder-admin access; promotion should be bound to the exact reviewed version and pass through approval or a builder-authorized path.

## How project code reaches Lobu

`lobu.config.ts` is the desired-state entrypoint. Files are included only through explicit references:

```ts
connectorFromFile("./github.connector.ts");
reactionFromFile("./notify.reaction.ts");
skillFromFile("./agents/support/skills/internal-api");
defineAgent({ id: "support", dir: "./agents/support" });
```

There is no directory auto-discovery.

- `lobu run` imports the config, starts the local stack, and applies it.
- `lobu validate` checks the config and referenced sources.
- `lobu apply` bundles referenced connector and reaction code and synchronizes the declared organization state.

## Read next

- [Getting Started](/getting-started/)
- [Agent workspace](/guides/agent-prompts/)
- [Memory](/getting-started/memory/)
- [Connectors](/sdks/connectors/)
- [Reactions](/sdks/reactions/)
- [Tool policy](/guides/tool-policy/)
- [Guardrails](/guides/guardrails/)
- [Providers](/reference/providers/)
- [Related systems and research](/getting-started/related-work/)
- [Docker deployment](/deployment/docker/)
- [Kubernetes deployment](/deployment/kubernetes/)