Quickstart

This guide takes you from a fresh clone to a running Matrix agent. The monorepo contains independently buildable Go modules and MCP tool servers.

Prerequisites

Docker and buildx are only needed if you plan to build the per-user daemon container image.

1. Clone and build

git clone https://github.com/paxlabs-inc/matrix-core.git
cd matrix-core

make build      # compile all Go modules
make install    # place CLIs in ./bin
make test       # run tests across all modules

The build produces the following CLIs in ./bin:

2. Configure

cp .env.example .env

Edit .env and set the required keys:

# LLM provider key (required for compilation and plan walking)
FIREWORKS_API_KEY=your_key_here

# Wallet auth (required for on-chain writes; reads work without it)
PAXEER_WALLET_EMAIL=you@example.com
PAXEER_WALLET_PASSWORD=your_password

# Optional: per-user daemon auth token
MATRIX_DAEMON_TOKEN=your_token

The .env file is gitignored. See .env.example for the full list of variables and their defaults.

3. Compile your first intent

./bin/mclc compile \
  -skill skills/writing-plans/SKILL.mtx \
  -prose "Build a deployment pipeline for my Node.js app" \
  -verb build

With a valid FIREWORKS_API_KEY, the compiler emits a typed Intent Frame containing the verb, typed object slots, blocking unknowns, confidence score, and compilation metadata. Without an API key, it falls back to dry-run mode and prints the interpolated prompt structure.

4. Walk a plan end-to-end

./bin/mcl-execute walk \
  -prose       "Summarise the README and write it to /tmp/summary.md" \
  -manifest    agents/default.json \
  -cortex-root ./runs/dev-cortex \
  -skills-root ./skills

This command:

1. Loads the agent manifest (which MCP servers and tools to spawn)
2. Compiles the prose into an Intent and PlanTree
3. Walks the plan step-by-step, dispatching tool calls through MCP
4. Journals every step as a Cortex Event memory
5. Writes a signed KindAttest and KindLearnWeights on completion

5. Run the per-user daemon

./bin/mcl-execute daemon \
  -addr        :8080 \
  -cortex-root ./runs/dev-cortex \
  -manifest    agents/default.json \
  -skills-root ./skills

The daemon exposes an HTTP and SSE surface:

The full route reference, request/response shapes, and per-service APIs are in the API Reference.

6. Explore Cortex interactively

Use the cortex shell to read and write memories directly:

# Write an identity memory
./bin/cortex-shell -root ./runs/dev-cortex -actor dev \
  write Identity '{"name":"Developer","did":"did:pax:dev"}'

# Write a preference
./bin/cortex-shell -root ./runs/dev-cortex -actor dev \
  write Preference '{"topic":"code_style","polarity":"prefer","strengthval":0.9,"rationale":"terse"}'

# List all memories of a type
./bin/cortex-shell -root ./runs/dev-cortex -actor dev \
  list Preference

# Dump the full journal
./bin/cortex-shell -root ./runs/dev-cortex -actor dev \
  dump

What's next