Core Concepts

Matrix is built around a small set of load-bearing components. Each has a clear responsibility. Understanding how they fit together makes the rest of the docs click into place.

Neo: the conversational agent

Neo is the default agent entry point. It runs a recursive LLM tool-calling loop where the conversation transcript is the state. The model emits text and tool-call intents; the harness dispatches tools and feeds results back.

Neo is fully permissive on reversible work: shell commands, code execution, web search, file operations. When it encounters a request that is monetary, on-chain, or irreversible, it delegates to the MCL rail through the core_execute tool.

Key properties of the Neo loop:

• Per-turn step budget. Each turn has a bounded number of tool-call steps. The loop detects stalls (no progress) and produces honest partial results on exhaustion, never fabricated success.
• Paged memory via Cortex. Neo reads from and writes to Cortex. A background Consolidator promotes durable learnings from the conversation into long-term memory out-of-band.
• Conversational recall. A relevance-based read lane surfaces the most relevant past turns beyond the live transcript, keeping long threads coherent without growing the context window.
• Tool transparency. Every tool call is surfaced as a ToolEvent with its name, arguments, and result. Users see the real evidence behind an answer, not just a synthesized paragraph.

Cortex: persistent memory

Cortex is the per-actor typed memory graph. Each actor (user, agent, or service) gets its own Pebble database on disk. Every mutation is recorded in an append-only journal using canonical CBOR encoding with monotonic, gap-free sequence numbers.

Cortex stores nine memory types:

Each memory gets an auto-generated short and medium rendering form, ranked by a salience score that weighs recency, access frequency, citation count, declared importance, and vector similarity.

Cortex also provides:

• Semantic search via an async embedding pipeline and a pure-Go HNSW vector index (Find Near)
• Graph traversal via typed edges (14 edge types) and bounded BFS (Find From / Find Follow)
• Merkle-anchored snapshots with an OverallRoot that enables byte-deterministic replay

The defining correctness property: derived state can always be rebuilt byte-identically from the journal. This is the replay invariant, enforced on every PR.

MCL: the typed intent pipeline

MCL (Matrix Communication Layer) converts natural language into typed, signed artifacts. No free-form side channels. Every user input produces a typed artifact.

The pipeline:

1. Draft. User types natural language, producing an intent.draft.
2. Compile. A seedable, grammar-constrained LLM converts the prose into a typed Intent IR. The compiler is written in MatrixScript (.mtx), a Matrix-native declarative DSL. Compilation is deterministic: the seed is sha256(intent_id || actor || snapshot_hash || mtx_digest).
3. Accept. The user reviews the typed Frame (verb, objects, constraints, success criteria, unknowns, confidence) and signs it. This is intent.accept.
4. Execute. The Executor walks the plan.
5. Attest. On completion, a signed intent.attest envelope records the outcome, optionally chain-anchored.

The Frame is the source of truth, not the original prose. It carries:

• Verb from a closed vocabulary of 10: find, acquire, build, modify, deliver, analyze, negotiate, schedule, monitor, delegate. Extension verbs use an x: prefix.
• Objects from 8 typed kinds: service, model, agent, knowledge, intent, asset, plan, capability.
• Constraints (budget, allow/deny, policy, schema)
• Success criteria (typed predicates)
• Preferences (ranked soft preferences)
• Unknowns (structured gaps with severity)

Executor: the plan walker

The Executor owns everything downstream of intent.accept: the lifecycle state machine, the plan-tree walker, tool dispatch, materiality classification, and the closing intent.attest or intent.fail envelope.

Plan walking is depth-first with support for parallel branches and gates. Each step dispatches tool calls through MCP (Model Context Protocol) servers. The default agent manifest pins filesystem-mcp, fetch-mcp, and git-mcp.

Key design decisions:

• MCP-native tool dispatch. Tools are exposed via MCP servers over stdio or streamable HTTP. The Executor verifies that tools/list matches the manifest at startup.
• Materiality classification. Plan modifications during execution are classified as material or non-material. Material changes halt execution and require re-accept.
• Replay determinism. Tool outputs are captured as Cortex Fact memories at the moment of execution. Replays read from Cortex, never re-run tools.

LayerX: settlement fabric

LayerX is the settlement and custody spine for agent balances. It provides escrow-backed, USD-denominated agent money (USDX) that agents use to pay for services, settle transactions, and transfer value.

How it works:

1. Deposit. Agents fund their USDX balance by depositing USDL (or swapping other tokens) into the LayerX vault. The depositing EVM address becomes the agent's payout address.
2. Pay. Agents pay other agents by DID (did:matrix:<label>:<keyfp>) instantly and gaslessly. The sequencer signs receipts with Merkle inclusion proofs.
3. Settle. Micropayments net-batch on a settlement window. The batch Merkle root anchors to Paxeer on settlement. Material amounts force-settle immediately.
4. Withdraw. Agents burn USDX to release real USDL to their payout address, optionally swapping to another asset.

Every layerx_pay returns a sequencer-signed receipt. Inclusion proofs and batch roots are independently verifiable via layerx_receipt.

Deus: service marketplace

Deus is the agent-service marketplace. Service providers register listings; agents discover, quote, and invoke them.

The flow:

1. Discover. deus_discover searches service listings by plain language or filters.
2. Quote. deus_quote returns a signed EIP-712 price quote for a specific operation.
3. Invoke. deus_invoke calls the service. Payments ride LayerX: a priced call returns 402 with USDX terms, the bridge auto-signs and retries under the agent's spend leash.

Agents have per-call and rolling daily USDX spend limits (LAYERX_MAX_SPEND_USDX, LAYERX_MAX_DAILY_USDX). Calls that exceed the leash surface the terms without signing.

Chronos: scheduler

Chronos gives agents durable scheduling: one-shot alarms and recurring cron jobs that wake the agent with a contextful message.

When an alarm fires, Chronos delivers the wake_message as a new agent turn, optionally resuming a specific conversation. The message is written to the agent's future self with enough context to act without re-deriving state.

Tachyon: smart contract engine

Tachyon is the agent-native Solidity/EVM engine. It gives agents the ability to compile, test, simulate, and deploy smart contracts, all through the tool surface.

Deployments are tracked in a registry. Agents can look up prior deployments by idempotency key and chain ID. Chain profiles are configurable; Paxeer mainnet (chain 125) is preconfigured.

Tools: the MCP ecosystem

Matrix tools are MCP (Model Context Protocol) servers. Each tool module exposes a set of capabilities over stdio or streamable HTTP. The agent manifest declares which servers to spawn and which tools to register.

Core tool modules:

Tools are policy-gated. On-chain write operations go through the embedded wallet at connect.paxportwallet.com, where key material, signing, spend limits, and allow-lists are enforced network-side, not trusted to agent code.

Hosting model

In production, each user gets a dedicated daemon on a Fly Machine that auto-suspends when idle. A router service handles JWT verification, machine wake, and reverse-proxying. LLM calls flow through a metered gateway that debits a per-user PAX credit ledger against a versioned rate card.

Where to go next