Build on the Matrix Stack.

Matrix Stack Deep Dive

Build custom agents, extend tool capabilities, and integrate with the Matrix execution pipeline. The stack exposes typed APIs for every layer: cognition, memory, tool dispatch, and on-chain settlement.

Custom Tool Definitions

Register custom MCP tools that Neo and MCL agents can invoke. Tools are defined as JSON schemas and executed in sandboxed environments with full lifecycle management.

// Register a custom MCP tool
POST /v1/tools/register
{
  "name": "github_create_pr",
  "description": "Create a pull request on GitHub",
  "input_schema": {
    "type": "object",
    "properties": {
      "repo": { "type": "string", "description": "owner/repo" },
      "title": { "type": "string" },
      "body": { "type": "string" },
      "head": { "type": "string", "description": "Source branch" },
      "base": { "type": "string", "default": "main" }
    },
    "required": ["repo", "title", "head"]
  },
  "handler": "https://your-worker.example.com/tools/github-pr",
  "timeout_ms": 30000,
  "requires_approval": false
}

// Tool handler receives typed input
// POST https://your-worker.example.com/tools/github-pr
// Body: { "repo": "paxlabs-inc/matrix-core", "title": "...", ... }
// Response: { "result": { "pr_number": 42, "url": "..." } }

Cortex Memory API

Read and write to the per-actor memory graph. Cortex stores typed observations, entity relationships, and conversation summaries with Merkle-anchored integrity proofs.

// Write observations to cortex
POST /v1/cortex/write
{
  "actor_id": "neo-prod-01",
  "observations": [
    {
      "type": "note",
      "namespace": "matrix://knowledge/neo",
      "content": "User prefers TypeScript over Python for backend services",
      "tags": ["preference", "language"]
    },
    {
      "type": "entity",
      "namespace": "matrix://entities/users",
      "content": {
        "name": "Andrew",
        "role": "core-team",
        "org": "PaxLabs"
      }
    }
  ]
}

// Query cortex with structured search
GET /v1/cortex/query?actor_id=neo-prod-01&namespace=matrix://knowledge/neo&limit=50

// Response includes Merkle proof for integrity verification
{
  "observations": [...],
  "proof": {
    "root": "0x7a3f...",
    "path": ["0xb2c1...", "0x9d4e..."],
    "snapshot_seq": 1847
  }
}

Agent Orchestration

Spawn and coordinate sub-agents for parallel task execution. The orchestrator manages lifecycle, resource limits, and result aggregation across agent fleets.

// Spawn sub-agents for parallel work
POST /v1/agents/spawn
{
  "parent_id": "neo-prod-01",
  "agents": [
    {
      "id": "researcher-1",
      "role": "web-researcher",
      "task": "Find recent papers on agent memory architectures",
      "tools": ["web-search", "fetch"],
      "max_turns": 10,
      "timeout_seconds": 120
    },
    {
      "id": "coder-1",
      "role": "code-analyst",
      "task": "Review the Pebble storage layer in matrix-core",
      "tools": ["exec", "fs"],
      "max_turns": 20,
      "timeout_seconds": 300
    }
  ],
  "aggregation": "merge_summaries",
  "on_failure": "continue_others"
}

// Poll for completion
GET /v1/agents/orchestration/{orchestration_id}/status

// Results aggregated into parent cortex
{
  "status": "completed",
  "results": {
    "researcher-1": { "status": "done", "summary": "..." },
    "coder-1": { "status": "done", "summary": "..." }
  }
}

Execution Pipeline & Webhooks

The Executor manages the full lifecycle from plan creation through tool dispatch to result aggregation. Configure webhooks to receive execution events in your own infrastructure.

// Submit an execution plan
POST /v1/executor/plans
{
  "actor_id": "neo-prod-01",
  "steps": [
    {
      "tool": "exec__shell",
      "input": { "command": "git clone https://github.com/paxlabs-inc/matrix-core" }
    },
    {
      "tool": "fs__read_file",
      "input": { "path": "/workspace/matrix-core/README.md" },
      "depends_on": [0]
    },
    {
      "tool": "web-search__web_search",
      "input": { "query": "Matrix agent framework documentation" },
      "depends_on": []
    }
  ],
  "strategy": "parallel_where_possible",
  "max_concurrent": 3
}

// Webhook receives step-level events
// POST https://your-app.com/executor-events
// {
//   "event": "step_completed",
//   "plan_id": "plan_abc123",
//   "step_index": 0,
//   "result": { "exit_code": 0, "stdout": "..." },
//   "timestamp": "2026-01-15T14:23:11Z"
// }