Installation

Lambo ships as a single lambo binary that carries both runtime surfaces: the MCP server (lambo serve) and the command line verbs. You deploy it in two steps. Install the binary, then write a lambo.toml that says which store and which embedder to use.

That is the whole deployment model. The released binary carries every adapter. You move between the in-memory store, SQLite, and CockroachDB by editing config, never by downloading a different build.

Install the binary

Each release carries one lambo binary per platform plus a SHA-256 checksum file. Releases are published for Linux x86_64, Linux arm64, macOS arm64, and Windows x86_64, with the full adapter feature set compiled in.

1. Run the install script

   curl -fsSL https://github.com/nrynss/lambo/releases/latest/download/install.sh | sh

   The script detects your OS and architecture, downloads the matching binary, verifies its SHA-256 against the published checksum, and installs it to ~/.local/bin.

2. Confirm the install

   lambo --version

To pin a version or choose the install directory:

LAMBO_VERSION=0.2.0 LAMBO_INSTALL_DIR=/usr/local/bin \
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/nrynss/lambo/main/scripts/install.sh)"

On Windows, download lambo-<version>-windows-x86_64.exe and its .sha256 file from the releases page and verify the checksum yourself.

Write a lambo.toml

The config file picks the store and the embedder at runtime. This one needs no external services at all, because the in-memory store and the fixture embedder are both self-contained.

[store]
kind = "sqlite"
path = "./lambo.db"

[embedder]
kind = "fixture"
dim = 1024

SQLite is a local file, so this still needs no external service, and it survives a restart. Create the schema once with lambo --config lambo.toml provision.

Caution

The in-memory store lives inside one process. It is ideal for a single lambo serve that many agents connect to, because they all share that one process’s graph. It does not survive that process exiting, and a separate command line process cannot read it. Choose sqlite or cockroach whenever more than one process is involved.

Every key has an environment variable override. See Configuration for the full set.

Caution

An adapter is compiled into the binary, but its backing service still has to be reachable at runtime. The bge_m3 embedder needs a llama-server, and the cockroach store needs a cluster.

Run it the first time

Start a server in one terminal and read from it in another.

1. Start a session server

   lambo serve --config lambo.toml --session demo --agent agent-a

2. Write a concept from another terminal

   lambo --config lambo.toml derive --session other --agent agent-b \
     --content "user schema" --kind entity

   Use a second session name, because the server already holds the writer lease on demo.

3. Read it back

   lambo --config lambo.toml recall --session other --query "user schema"

   Recall is a read, so it works whether or not a server holds the session.

Your agent can now connect over MCP. See MCP tools for the tool surface, and End to end for a full walkthrough.

Connect an MCP client

Most MCP clients, such as Claude Code and Cursor, read an mcpServers configuration. Add Lambo as a server and let the client start it over stdio. Point command at your lambo binary and pass the serve arguments.

{
  "mcpServers": {
    "lambo": {
      "command": "/path/to/lambo",
      "args": [
        "--config", "/path/to/lambo.toml",
        "serve",
        "--session", "demo",
        "--agent", "agent-a",
        "--transport", "stdio"
      ]
    }
  }
}

The --config flag comes before serve, because it is a global flag. The serve flags come after. The client launches this process and talks to it over stdio, so you do not start lambo serve yourself when you use a client this way.

Real clients drive this, not only unit tests. Claude Code and the Cursor Agent CLI each complete the handshake and list all seven tools over stdio. OMP, the Oh My Pi harness, is an MCP client out of the box. Two models have driven the tools autonomously: DeepSeek Flash under OMP called derive, recall, and stats against a live CockroachDB session, and Cursor’s model ran derive, record_action, recall, and stats in sequence. Pi needs its MCP adapter installed first, after which it drives all seven tools. See MCP tools for the per-client breakdown.

To connect over HTTP instead, start the server yourself with --transport http and point your client at http://127.0.0.1:7700.

Caution

The HTTP endpoint is a session writer, so treat it accordingly. On loopback it is unauthenticated by default. Binding anywhere else fails closed and requires a bearer token (--auth-token or LAMBO_AUTH_TOKEN), which every request must then send as Authorization: Bearer <token>. See Configuration.

Set up real embeddings

To use BGE-M3 embeddings, run a local llama-server with an embedding model and point Lambo at it.

llama-server -m path/to/bge-m3.gguf --embedding --port 8080

Then set the embedder in lambo.toml.

[embedder]
kind = "bge_m3"
dim = 1024
url = "http://127.0.0.1:8080"

Caution

Do not switch embedder models in the middle of a session without re-embedding, because vectors from different models are not comparable.

Set up durable storage

For a durable store, apply the schema before you serve. The repository’s scripts/provision.sh does this for CockroachDB. Then select the store in lambo.toml and keep the connection string in the environment, so the secret stays out of the file.

[store]
kind = "cockroach"

export LAMBO_COCKROACH_DSN="postgresql://USER@HOST:26257/lambo?sslmode=verify-full"

For a local file instead, set kind = "sqlite" and path = "./lambo.db". See Configuration for the store keys and the provisioning details.

Build from source

You do not need this to run Lambo. Build from source when you want an unreleased change, a smaller binary, or to work on Lambo itself. You need a stable Rust toolchain from rustup.rs.

git clone https://github.com/nrynss/lambo.git
cd lambo
cargo build --release --features ship

Cargo writes the binary to target/release/lambo. The ship profile is what releases are built with, so the result matches a downloaded binary. You can also install straight from git, which compiles the default branch and may be newer than the latest tag:

cargo install --git https://github.com/nrynss/lambo.git

Cargo features select which adapters are compiled in. List fewer to get a smaller binary.

Feature	What it adds
store-memory	In-memory store. This is the default and needs no external service.
store-sqlite	SQLite store, backed by a local file.
store-cockroach	CockroachDB store, for a hosted cluster.
embed-fixture	Deterministic fixture embedder for tests and quick starts.
embed-bge	BGE-M3 embeddings served by llama-server.
embed-bedrock	Reserved for Amazon Titan embeddings through Bedrock. Not implemented, so it fails at startup if selected.

Choosing features only changes what the binary can do. Which store and embedder it does use is still a lambo.toml decision.