JSPM

One brain. Many bodies.
Orchestration framework for embodied AI systems. Built on scp-protocol.

SCP gives AI one body. Plexa gives AI a whole body.

Relationship to SCP

Use SCP when you have one embodied agent. Use Plexa when you have several and want one LLM coordinating all of them.

What it does

Plexa is an orchestration layer that sits above SCP. It coordinates multiple SCP adapters under a single LLM brain.

LLM (Brain)
    |
Plexa (Orchestrator)
    |
Multiple SCP adapters (Body parts)
    |
Environment

Four jobs only

No reasoning. No safety logic. No pattern matching. Four jobs only.

Decision authority

LLM decides:           WHAT (intent, goals)
Plexa decides:     WHEN and HOW (sequencing, timing)
SCP adapters decide:   WHETHER (safety veto, hardware limits)

These three layers never overlap. Plexa is not a brain. It is a sequencer.

Transport truth

Zero HTTP between JS bodies and Plexa. HTTP only where physically necessary.

A body is a class. Tools are its async methods. By default transport = "inprocess", no port, no network. Plexa calls body.invokeTool(name, params) directly. To run a body in another process, mark it explicitly:

class MuJoCoCartpole extends BodyAdapter {
  static transport = "http"
  static port = 8002
}

Hello world

git clone https://github.com/srk0102/plexa.git
cd plexa
npm install
node examples/hello-world/index.js

No AWS. No API key. Just Node.js.

Ollama optional: install from ollama.ai and run ollama pull llama3.2 for a real local brain. Otherwise the example uses a stub brain.

API

const { Space, BodyAdapter, OllamaBrain } = require("@srk0102/plexa")

class CartpoleBody extends BodyAdapter {
  static bodyName = "cartpole"
  static tools = {
    apply_force: {
      description: "push the cart",
      parameters: {
        direction: { type: "string", enum: ["left","right"], required: true },
        magnitude: { type: "number", min: 0, max: 1, required: true },
      },
    },
  }
  async apply_force({ direction, magnitude }) {
    // physics here
  }
  async tick() {
    // sensor loop called by Plexa at tickHz
  }
}

const space = new Space("my_robot")
space.addBody(new CartpoleBody())
space.setBrain(new OllamaBrain({ model: "llama3.2" }))
space.run()

Tools are methods. No ports. No transport configuration. Plexa calls body.invokeTool(...) as a direct async call.

Managed mode

Connected bodies flip to managed mode automatically. Managed does NOT mean dumb.

In managed mode:

• The body keeps using its local pattern store to decide at muscle speed.
• Every local decision fires space.onBodyDecision(name, entity, decision, meta) so Plexa can build vertical memory and stay aware.
• Only the LLM path is routed through Plexa.

Managed = coordinated, not lobotomized.

Architecture

Read sensors in SCP muscle
  |
Reflex check (always local, fastest)
  |
Emit event UP via HTTP to Plexa
  |
Space aggregator compresses state from all bodies
  |
Space calls LLM brain (fire-and-forget, async)
  |
Brain returns intent
  |
Translator validates intent against body capabilities
  |
Space dispatches command DOWN to body
  |
Body forwards command to SCP muscle via HTTP
  |
SCP muscle executes command

Single-threaded reactor at 120Hz. No locks. No polling. Deterministic tick budget.

Package structure

plexa/
  packages/
    core/
      space.js          Space orchestrator
      body-adapter.js   BodyAdapter base class
      brain.js          Brain base class
      translator.js     Intent -> command validation
      aggregator.js     State compression with token budget
    bridges/
      ollama.js         OllamaBrain (local, free)
  adapters/
    template/           Minimal SCP adapter for testing
  examples/
    hello-world/        End-to-end demo
  tests/
    plexa.test.js       43 tests, 0 failures

CLI

npx @srk0102/plexa version   # ✦ starfish + version
npx @srk0102/plexa status    # running space + body health
npx @srk0102/plexa bodies    # connected bodies with tools
npx @srk0102/plexa logs      # live tail of events + tool calls
npx @srk0102/plexa start ./space.js

Opt into the introspection server in your app:

const { Space, attachIntrospection } = require("@srk0102/plexa")
const space = new Space("my_robot", { tickHz: 60 })
// ... addBody, setBrain ...
attachIntrospection(space)   // exposes localhost:4747 for the CLI
await space.run()

Tests

npm test

43 tests. Zero external deps beyond scp-protocol. node:test built-in.

Roadmap

Links

• SCP: https://github.com/srk0102/SCP
• SCP npm: https://npmjs.com/package/scp-protocol
• SCP docs: https://srk-e37e8aa3.mintlify.app

License

MIT -- srk0102