Omega Lisp

Motivation

Omega Lisp is a small, persistent-session Lisp that exists for two kinds of reader. The first is a language user who wants a REPL with first-class LLM oracles, deterministic session replay, and a CESK runtime they can pause, fork, and inspect. The second is a Matrix integrator who wants to script live actor pipelines without writing a TypeScript package — calling actors through $eval, embedding the narrow @omega/core facade, and sharing the same inference driver registry that system.inference uses. The two seams are deliberate and narrow. Omega is not Matrix and Matrix does not require Omega; you can run either alone, and these docs are for whichever side you are arriving from.

What this is and why

Omega Lisp (npm package omega-lisp, sometimes called "OmegaLLM" in older notes) is a Lisp dialect built around three ideas you don't usually see together:

1. A CESK abstract machine — (Control · Environment · Store · Kontinuation) — where the interpreter state is a first-class value, so time-travel debugging, parallel forks, and breakpoints fall out for free.
2. A first-class oracle protocol — LLM calls return Meaning values (text + denotation + obligations + provenance), and the LLM can call back into the Lisp runtime through a co-recursive tower (effect callback.eval_lisp).
3. A persistent REPL with session replay — sessions serialize to disk, rehydrate on next launch, and double as a deterministic event log.

It is its own product family. It runs standalone (as a CLI / npm package / embeddable library). It also serves as the in-loop scripting language for Matrix agents — when a Matrix AgentActor needs to compute something with intermediate state, the natural surface is $eval against an embedded Omega REPL session, not a bus tool call.

Where this fits

Omega is substrate-side language tooling. It is not the Matrix protocol (that is docs-matrix), not the Matrix SDK (docs-sdk), and not a Matrix vertical. It meets the Matrix substrate at three documented seams (covered in Matrix integration):

Seam	What flows
$eval on system.agents	Matrix actor invokes Lisp; result returns through the activity-frame stream and session_state(key='repl_state').
@omega/core narrow facade	A Matrix actor can evaluate Lisp without dragging in the REPL or the driver registry.
Shared inference driver registry (@open-matrix/inference)	Matrix system.inference and Omega (effect infer.op …) go through the same InferenceDriver interface; provider credentials managed by Factotum apply to both.

You can use Omega without Matrix. You can use Matrix without ever calling $eval. The seams are explicit.

Five-minute quickstart

Run Omega standalone and exercise the oracle protocol against a configured inference driver:

# From the repo root
pnpm --filter omega-lisp build
pnpm --filter omega-lisp omega-fast

# In the REPL:
;; > (define greet (lambda (name) (string-append "Hello, " name)))
;; greet
;; > (greet "world")
;; "Hello, world"
;; > (effect infer.op "Summarize the last commit message in one sentence." "claude")
;; <Meaning ...>

Sessions persist by default to ~/.omega-sessions/. Reopen the REPL with the same session name and (define x 42) is still bound. The full session log is a deterministic replay log; see REPL for session, snapshot, and replay primitives.

To embed Omega from a Matrix actor without the full REPL, depend on @omega/core (the narrow facade at projects/omega-lisp/packages/core/) and call compileTextToExpr + runToCompletion. See overview/matrix-integration.md.

Conceptual map

Section	What you'll find
Overview	What Omega Lisp is, language goals, runtime model, REPL, Matrix integration. Start here.
Language Guide	Syntax, values, functions, macros, evaluation rules, modules. The reader and core forms.
Runtime	Runtime architecture, standard library, the package layout, drivers, testing. The CESK evaluator and oracle wiring.
Integration	Matrix actor integration, agent integration, package lifecycle, embedding patterns.
Reference	Forms, built-ins, libraries, CLI/REPL commands, error codes.

What Omega is NOT

• Not the Matrix Agent Platform. Different package, different mounts, different storage. Some Matrix actors embed an Omega REPL for $eval, but the substrates are independent.
• Not a strict ECMAScript variant. The s-expression reader, evaluation rules, and value model are Lisp-shaped.
• Not a JIT or native compiler. The CESK evaluator interprets compiled Expr ASTs.
• Not a substitute for the Matrix bus. (effect ...) is how Omega reaches into Matrix actors and external services; the bus is still the substrate.

Source-code map

projects/omega-lisp/
├── package.json                              ← npm package "omega-lisp"
├── src/index.ts                              ← full library API
├── src/runtime.ts                            ← OmegaRuntime + OmegaConfig
├── bin/omega.mjs                             ← CLI entry (omega, omega-lisp)
└── packages/
    ├── core/                                 ← narrow facade for membrane consumers
    ├── repl/                                 ← REPL, sessions, snapshots
    ├── agents/                               ← agent loop
    ├── oracle/                               ← oracle protocol primitives
    ├── solve/                                ← solver primitives
    └── …                                     ← additional sibling packages

projects/omega-drivers/packages/
├── inference/                                ← @open-matrix/inference (driver registry)
├── driver-anthropic/
├── driver-openai/
├── driver-ollama/
└── …

Sister docs

• docs-matrix — the substrate Omega meets through $eval and the shared inference driver registry.
• docs-sdk — building Matrix actors that embed Omega.
• docs-agents — the Matrix agent platform that invokes Omega through $eval.

Source: Package metadata at projects/omega-lisp/package.json. Public API surface at projects/omega-lisp/src/index.ts. Build pipeline node build.mjs per package; CLI entry omega (projects/omega-lisp/bin/omega.mjs). Matrix $eval integration in projects/matrix-3/packages/agents/src/AgentsRoot.ts.