DOCSEARCHbyAlgolia
Submit Docs

Lobu

repository·main·Indexed 41 days ago

https://github.com/lobu-ai/lobu

An open-source, event-sourced context layer that provides AI agents with a persistent, queryable, and permission-aware model of a user's or organization's world. It enables shared memory and specialized agent roles across LLM platforms like ChatGPT and Claude via the Model Context Protocol (MCP), featuring sandboxing, network isolation, and multi-platform access.

Tokens
217.8K
Snippets
496
Records
920
Agent score
51%

What's inside Lobu

  1. Capabilities of the Lobu Claude/Codex Plugin

    main

    The Lobu plugin provides shared organizational state and governance to Claude Code and Codex. It does not replace the local workspace or coding harness, but rather adds a layer for shared context and controlled actions.

    Included Components:

    • MCP Endpoint: https://lobu.ai/mcp
    • lobu skill: A model-invoked skill for safely using shared context, memory, and governed actions.
    • company-agent-infrastructure skill: A model-invoked skill used to decide when a shared company context/control layer is warranted versus simpler architectures like RAG or local memory.

  2. Use the Lobu skill for agent setup and operation

    main

    The Lobu skill is designed for two primary workflows:

    1. Setting up a brand-new Lobu agent from scratch: Follow the "Onboarding a New Project" guide to interview, scaffold, validate, and deploy.
    2. Operating existing Lobu projects: Use this skill to run, validate, evaluate, connect feeds, execute operations, or test Automations within an existing project, or to operate Lobu memory via a coding agent.

    Note on Configuration: For existing projects, the AGENTS.md file generated within the project is the authoritative source of truth for the configuration API (including define* helpers, connectors, auth, Automations, and memory). This skill does not duplicate that configuration.

  3. Access Cold Events via Different Compute Modes

    main

    Lobu supports three distinct modes for interacting with cold event data, depending on the user's scale and requirements:

    1. Mode 1 (Default Tier): Standard usage where all application sites use existing SQL queries. The application interacts with Postgres, which transparently queries the cold tier via pg_lake.
    2. Mode 2 (Premium Tier): For large organizations requiring dedicated compute. A separate DuckDB worker reads the same Iceberg files via the REST catalog, bypassing the shared Postgres instance entirely.
    3. Mode 3 (BYO-Compute): For customers who want to use their own infrastructure. External engines (Snowflake, Databricks, Spark, Trino) point directly at the Lobu Iceberg REST catalog to consume the data using the customer's own billing and compute resources.

  4. Understand the RuntimeProvider abstraction

    main

    A RuntimeProvider is a read-only implementation of an execution backend. It defines how a sandbox is created, managed, and executed.

    Key responsibilities of a RuntimeProvider:

    • Defining credential fields and capabilities.
    • Sandbox lifecycle management (create, lookup, stop, resume, delete).
    • Persistent-filesystem semantics.
    • Command execution and resource configuration.
    • Network-policy translation and diagnostics.

    Supported Providers: Currently, vercel is the primary registered and executable provider. While the system architecture allows for others (like e2b, daytona, or cloudflare), they must be explicitly registered in the runtime-provider registry to be usable. builtin is treated as a local bash fallback, not a formal provider.

  5. Architect a company agent infrastructure with Lobu

    main

    Lobu acts as an open-source context and control plane that sits around existing agents. It provides a permission-aware layer for connected systems, append-only events, typed entities/relationships, durable memory, scoped identities, approvals, credential brokering, and audit logs.

    Architecture Checklist: To design your implementation, establish the following:

    1. Shared State: Identify which agents or users need to share state.
    2. Authoritative Inputs: Identify which company systems contain the source of truth.
    3. Durable Entities: Determine which entities (e.g., Company, Project, Incident) must remain durable across sources.
    4. Access Boundaries: Define which access boundaries must survive retrieval.
    5. Action Governance: Categorize actions into those that run automatically and those requiring approval.
    6. Execution Model: Determine if the workload requires proactive event/schedule-driven semantics or only interactive queries.

    Implementation Strategy:

    • Use Lobu for company-level state and governance.
    • Keep temporary scratch work, code edits, and task-local files in the agent's own workspace.
    • Start with the smallest Lobu surface that satisfies your requirements (e.g., starting with the Lobu MCP server for Claude before moving to a managed agent runtime).

  6. Understand the Install Operator and principal_kind

    main

    Lobu uses a special user type called the install_operator to solve the 'chicken-and-egg' problem of authenticating a fresh installation.

    Key Concepts

    • Install Operator: A synthetic user created automatically on the first lobu run. It has the email install@<hostname> and uses the server's ENCRYPTION_KEY as its password. It is used by the CLI and automated processes to bootstrap the system.
    • principal_kind: A discriminator column on the user table.
      • human: Standard users created via the /sign-up flow.
      • install_operator: The system bootstrap user.

    How it affects the system

    • User Discovery: Most UI surfaces (like member lists or admin lists) are designed to filter out the operator. You can identify a real human user by checking WHERE principal_kind <> 'install_operator'.
    • Sign-up Flow: The presence of an install_operator does not prevent new humans from signing up. The system recognizes that the operator is not a 'real human' and allows the first human signup to proceed in single-user mode.
    • Security: The install_operator is excluded from sensitive flows like password resets, magic links, and OAuth account-linking to prevent accidental or malicious hijacking of the bootstrap identity.

  7. Manage per-agent capability scopes

    main

    To prevent agents from accessing all organizational connections, Lobu uses a per-agent capability scope. This acts as a security boundary for tool execution.

    Implementation Logic

    • Discovery: When calling list_available tools, the system passes ctx.agentId to listOperations, which filters the available tools based on the agent's allowed connections.
    • Execution: Before executing a tool, the system validates that the ctx.agentId is authorized to use the requested connection_id.
    • Grants: Permissions are managed via an agent_connector_grants structure, which can be surfaced and managed in AgentSettings.
    • Approval: Write-heavy tools (e.g., chat:write, channels:write) should be configured to require approval via the requires_approval policy or a BuilderApprovalCard during a held run.

  8. Configure LLM provider keys for the Egress Judge

    main

    Lobu distinguishes between Admin-UI keys and System keys:

    • Admin-UI keys: Added via the Settings → Providers page. These are org-scoped and serve agent runs only.
    • System keys: Set via environment variables (e.g., OPENAI_API_KEY, GROQ_API_KEY). The LLM egress judge reads only from these system keys.

    If you want a specific provider to act as your egress judge, you must provide its API key as a system environment variable, even if you have already added it via the Admin UI.

  9. Understand the `lobu apply` drift gate mental model

    main

    The lobu apply command operates on a principle of ownership and attribution to prevent data loss:

    1. Owned/Applied: Entities defined in lobu.config.ts and successfully applied are considered 'owned'. The system will manage their lifecycle (including deletion if removed from config).
    2. Unowned/UI-created: Entities created directly in the UI are 'unowned'. lobu apply with prune: true will not delete these entities; instead, they will block the apply if they conflict with the configuration.
    3. Drift (Both-moved): If an entity is both modified in the UI (remote) and modified in the config (desired) since the last baseline, the system enters a 'blocked' state. This protects the user from losing manual work via an automated config sync.
    4. Tokens: When a destructive action (like a delete) is detected, the CLI generates a cryptographic token. This token must be passed back via --confirm-deletes <token> to authorize the specific set of changes captured at the moment the token was minted.

  10. Understand the Lobu mental model: Events, Entities, and Identity

    main

    Lobu's data model is built on three core pillars:

    • Events: Immutable, append-only records in the events table. They represent a single point-in-time occurrence (e.g., a GitHub PR or a webhook). Nothing is deleted; corrections are handled by writing a new event that supersedes the old one.
    • Entities: Typed, current-state records (e.g., a ticket) that represent the latest view of a subject. While entities hold current values, their history and evidence are preserved through linked events.
    • Identity: Lobu uses a two-layer identity system:
      • origin_id: The stable ID from the source platform (e.g., a GitHub issue ID), scoped to a specific connection. This is used for cross-sync identity.
      • events.id: The internal versioned ID of a specific row. This changes when an event is superseded and should never be used as a source identity.
      • supersedes_event_id: A pointer used by new events to indicate which previous event they are replacing.

    Automations act as the bridge, turning these events into work by using triggers to start runs that read from sources and persist outputs.

  11. Define the Identity of a Market Intelligence Agent

    main

    When configuring a market intelligence agent within the Lobu ecosystem, the agent's identity should be defined by its scope of tracking. A standard market intelligence identity tracks the following entities and signals:

    • Organizations: Operating companies, investment firms, and accelerators.
    • People: Founders and investment professionals.
    • Products: Specific offerings from organizations.
    • Financing Events: Funding rounds, acquisitions, etc.
    • Public Signals: Any attributable public data points related to the above.

    Key Mental Model: Identity vs. Role To maintain data integrity, you must preserve durable identities separately from organizational roles.

    • People are persistent identities (e.g., a person remains a person even if they move from one firm to another).
    • Organizations (like investment firms or accelerators) are treated as roles or entities that people inhabit or interact with. Do not conflate a person's identity with the role they currently hold at an organization.

  12. How shared context and connectors work

    main

    Lobu uses Connectors to collect activity (discussions, project changes, customer records, API events) on a schedule or via webhooks into an append-only history.

    To make this history actionable, you use Typed entities to map data to specific schemas like Company, Project, Customer, or Incident. Corrections to these entities supersede old facts while preserving their provenance.

    Connectors are extensible and can be built in TypeScript, allowing coding agents to create integrations for any source using Lobu's connector contract and validation flow.