plexa

---

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.

Proof: NVIDIA Isaac Sim, Plexa vs no-memory baseline

Two Nova Carter robots, same arena, same Claude Haiku 4.5 brain, same obstacle course. One uses Plexa (VerticalMemory + recordOutcome). The other has bypass_cache: true and asks the model on every encounter.

	PLEXA (VerticalMemory)	NAIVE (bypass_cache=true)
Finish time	270.8 s	376.5 s
Brain calls	5	11
Memory hits	4	0
Collisions	0	2
Avg decision latency	0.22 ms	1338 ms

Plexa won by 105.7 seconds. Decision-layer speedup: 6,111x. Naive crashed twice on classes Plexa had already learned to handle, because Naive has no recordOutcome to remember the last failure.

The dashboard in the recording shows every VerticalMemory.searchAndEvaluate hit, every AnthropicBrain._rawCall, the stored reasoning per class, confidence decay, and the addGuardrail safety layer wired in. White box throughout.

Source for this demo: srk0102/SCP/tree/master/demo (uses @srk0102/plexa as the orchestration package, scp-protocol as the body-side cache).

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