Lobu architecture and concepts

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

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

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.

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.

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

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.

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:

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.