JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 26
  • Score
    100M100P100Q62669F
  • License MIT

Orchestration framework above SCP. One brain, many bodies.

Package Exports

  • @srk0102/plexa
  • @srk0102/plexa/adapters/postgres
  • @srk0102/plexa/bridges/anthropic
  • @srk0102/plexa/bridges/bedrock
  • @srk0102/plexa/bridges/ollama
  • @srk0102/plexa/bridges/openai
  • @srk0102/plexa/bridges/together
  • @srk0102/plexa/core
  • @srk0102/plexa/core/aggregator
  • @srk0102/plexa/core/body-adapter
  • @srk0102/plexa/core/brain
  • @srk0102/plexa/core/network-body
  • @srk0102/plexa/core/space
  • @srk0102/plexa/core/translator
  • @srk0102/plexa/core/vertical-memory
  • @srk0102/plexa/introspection

Readme

Plexa

One brain. Many bodies. Orchestration for any continuously running system.

npm docs tests scp-protocol


The problem

Every LLM-controlled body today is welded to one environment. Change the body and you rebuild everything. There was no open protocol for it.

The insight

Let the body run at 60Hz. Push events up only when it cannot answer locally. The brain teaches. The muscle remembers.

Session Brain calls Cost (Nova Micro)
1 27 $0.0270
2 4 $0.0040
3 0 $0.0000

Familiar situations are handled locally. Novel situations wake the brain. Cost is proportional to novelty.

What's new in v2: the brain teaches reasoning, not answers

Old vertical memory cached answers: input -> "block". Every similar-but-different input needed the brain again.

New vertical memory caches reasoning: input -> { indicators, weights, threshold }. Each new input is evaluated individually using the learned reasoning. Different people get different decisions from the same pattern. The brain is called once.

// Brain teaches: "fraud looks like this"
await memory.store("guard", "check", worldState, "block", {
  indicators: [
    { variable: "account_age_hours", weight: 0.3, condition: "< 24" },
    { variable: "requests_per_hour", weight: 0.3, condition: "> 10", fuzzy: true },
    { variable: "is_vpn", weight: 0.2, condition: "true" },
  ],
  compounds: [
    { variables: ["account_age_hours", "is_vpn"], conditions: ["< 24", "true"], weight: 0.4 },
  ],
  threshold: 0.6,
});

// Now evaluate 4 different people. Zero brain calls. CPU math only.
memory.evaluate({ account_age_hours: 2, requests_per_hour: 50, is_vpn: true });   // score 1.4 -> BLOCK
memory.evaluate({ account_age_hours: 4320, requests_per_hour: 3, is_vpn: false }); // score 0.0 -> ALLOW
memory.evaluate({ account_age_hours: 12, requests_per_hour: 9, is_vpn: false });   // score 0.5 -> ALLOW
memory.evaluate({ account_age_hours: 8760, requests_per_hour: 2, is_vpn: true });  // score 0.2 -> ALLOW

Three types of indicators:

  • Simple: variable meets condition = full weight
  • Fuzzy: close to meeting condition = partial weight (catches boundary gamers)
  • Compound: multiple variables must ALL match = bonus weight (catches synergistic risk)

Three-tier safety

// Level 1: Immutable guardrails (code-level, cannot be overridden)
memory.addGuardrail((input, proposedDecision) => {
  if (input.account_age_hours > 8760 && proposedDecision === "block") return "allow";
  return null;
});

// Level 2: Schema validation (rejects hallucinated variables from LLM)
const memory = new VerticalMemory({
  allowedVariables: ["account_age_hours", "requests_per_hour", "has_2fa", "is_vpn"],
});
// LLM invents "days_since_creation"? SchemaValidationError. Rejected. Auto-retry.

// Level 3: Conflict resolution (when multiple heuristics fire)
// Highest confidence wins. Same confidence = most recent wins. Tie = fail-open (allow).

Install

npm install @srk0102/plexa

Quick start (5 minutes)

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

class Cart extends BodyAdapter {
  static bodyName = "cart"
  static tools = {
    apply_force: {
      description: "push",
      parameters: {
        direction: { type: "string", enum: ["left", "right"], required: true },
        magnitude: { type: "number", min: 0, max: 1, required: true },
      },
    },
  }
  async apply_force({ direction, magnitude }) {
    console.log(`push ${direction} @${magnitude}`)
  }
}

const space = new Space("balancer")
space.addBody(new Cart())
space.setBrain(new OllamaBrain({ model: "llama3.2" }))
space.setGoal("balance the pole upright")
await space.run()

Expected output (Ollama not required; stub brain takes over automatically):

push left @0.4
push right @0.5
push left @0.3

When to use what

You have Install
One body npm install scp-protocol
Several bodies, one brain npm install @srk0102/plexa

Five brain bridges (vendor-agnostic)

const { OllamaBrain }    = require("@srk0102/plexa/bridges/ollama")    // local, free
const { OpenAIBrain }    = require("@srk0102/plexa/bridges/openai")    // GPT-4o
const { AnthropicBrain } = require("@srk0102/plexa/bridges/anthropic") // Claude
const { BedrockBrain }   = require("@srk0102/plexa/bridges/bedrock")   // AWS Nova
const { TogetherBrain }  = require("@srk0102/plexa/bridges/together")  // Llama, Qwen

The brain writes the reasoning once. Vertical memory stores it. After that, the brain type doesn't matter - evaluate() runs on CPU math regardless of who taught it. Zero vendor lock-in.

Persistence

// SQLite (default, zero config)
const memory = new VerticalMemory({ dbPath: "./memory.db" });

// Postgres (production)
const { PostgresAdapter } = require("@srk0102/plexa/adapters/postgres");
const memory = new VerticalMemory({
  dbAdapter: new PostgresAdapter({ connectionString: "postgres://..." }),
});

Not just robotics

Plexa orchestrates any system that runs continuously and pushes events:

Robot vacuums   Game NPCs   Robot arms   Web servers   Fraud detectors   API gateways   Any loop

Ready-to-run examples in examples/:

node examples/fraud-detector/index.js   # API security with reasoning + guardrails
node examples/web-server/index.js
node examples/log-monitor/index.js
node examples/api-gateway/index.js

Adapters tested

Adapter Physics Cache rate
Missile Defense Canvas 2D ~100%
Self-Driving Car Canvas 2D ~90%
10-Lane Highway Canvas 2D ~90%
MuJoCo Cart-Pole Real 3D physics 89%
MuJoCo Ant Real 3D physics 85%

Five adapters, one orchestrator, one brain, same protocol.

Docs

Full documentation: https://srk-e37e8aa3.mintlify.app

Pages cover the Space reactor, memory layers (pattern store, adaptive memory, cross-session vertical memory), safety gate and approval hook, lateral body-to-body events, cost tracking and retry policy, and the full API.

License

MIT