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

  ┌──────────────────┐  events   ┌──────────────────┐  reads   ┌──────────────────┐
  │ Connectors       │ ────────▸ │ Memory            │ ───────▸ │ Agents           │
  │                  │           │                   │          │                  │
  │ built-in feeds   │           │ events (append)   │          │ chat bots        │
  │ webhooks         │           │ ↓ cron · LLM      │          │ CLI / API / MCP  │
  │ device connectors│           │ entities (typed)  │          │ automations      │
  │ agent-written    │           │ relationships     │          │ reactions        │
  └──────────────────┘           └──────────────────┘          └──────────────────┘
         ▲                                                        │
         └──────── replies & actions become new events ────────────┘

The data and action loop

  Connector code → Connector definition → Connection → Feed → Run
  TypeScript SDK     auth · feeds ·       one installed   collected ·
  MCP · OpenAPI      event kinds ·        account/app/    streaming ·
                     operations           channel/webhook virtual
        │
        ▼
  ┌─────────────────────────────┐
  │ Event log (append-only)     │
  └─────────────────────────────┘
        │
        ▼
  Entities + projections
  (current state with evidence)

  Agents and automations
  read authorized events, entities, metrics, feedback
        │
        ▼
  Action / reaction → External outcome → More events
  notify · create ·   reply · completion · rejection · metric
  update · query ·
  request approval

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 automation 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 automation ownership

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

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

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

Automation
├── owning agent
├── connector- or workspace-sourced event, schedule, or manual activation
├── prompt, pinned skills, and read-only sources
├── declared entity and event outputs
├── optional reaction script
└── notification / cooldown / tags

An automation 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, automation window, scheduled run, 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, automations, 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 automation extraction.

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

Automations

Lobu uses one Automation model with four activation modes:

Connector event — react to a declared live chat or platform delivery.
Workspace-sourced event — react to a newly persisted declared event output from another automation.
Schedule — process a source window because of the clock.
Manual — run explicitly through Lobu, API, SDK, CLI, or MCP.

An automation can read events, entities, metrics, previous reactions, and human corrections. It can save memory, maintain a surface, notify someone, call a tool, request approval, emit a durable result for another automation, or remain silent. Automations are versioned, and runs stay tied to the exact version that produced them. Triggers decide when a run starts; read-only sources decide what additional durable context it receives.

Self-improvement

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

  Production trajectories
  runs · actions · feedback · metrics
        │
        ▼
  System automations
  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 automation 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 automations 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" });

Only explicitly referenced files are included.

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.