Quick Start

Quick Start

Get AgentCTX running and execute your first CTX operations in under 5 minutes.

Prerequisites

• Node.js ≥ 20 — Download
• Docker (optional) — required for SurrealDB persistence and NATS messaging

1. Install

npm install @agentctx/core

This installs the core library and the actx CLI.

2. Initialize a Project

npx actx init

This creates a .context/ directory in your project with:

.context/
├── actx.yaml           # Gateway configuration
├── objects/             # Content-addressed object store
├── refs/                # Reference pointers
├── translations/        # Signed sidecar translations
├── logs/                # Operation logs
└── .keys/
    ├── ed25519.key      # Agent signing keypair
    └── project.salt     # Scoped convergent encryption salt

3. Add an MCP Backend

Register a backend server that your agent can call tools from:

npx actx add github --command "npx -y @modelcontextprotocol/server-github" --roles "code,issues"

This updates .context/actx.yaml with the backend configuration. AgentCTX will lazy-spawn the backend when an agent first queries its tools.

4. Start the Gateway

# SSE mode (for HTTP clients)
npx actx start --transport sse --port 3100

# stdio mode (for IDE extensions and agent frameworks)
npx actx start

5. Run Your First Queries

Open a second terminal and try these operations:

# Discover available tools
npx actx query '?t github'

# Call a tool
npx actx query '>t github.issues.list state="open" ^5'

# Store a memory
npx actx query '+m "first-memory" #milestone "AgentCTX is running"'

# Search knowledge
npx actx query '?k "authentication" #code ^3'

# Recall memories
npx actx query '?m #milestone @7d'

Each query returns a structured GatewayResult:

{
  "ok": true,
  "op": "?t",
  "ms": 4,
  "data": {
    "results": [
      { "name": "github.issues.list", "score": 0.95 },
      { "name": "github.issues.create", "score": 0.91 }
    ],
    "count": 2
  }
}

6. Verify Trust

Check that sidecar translations are intact:

npx actx verify

This cryptographically validates every Ed25519 signature in .context/translations/.

What Just Happened?

1. actx init created an Ed25519 keypair and a content-addressed object store
2. actx add registered an MCP backend with role-scoped access
3. actx start booted a 15-stage middleware pipeline (identity → auth → routing → execution)
4. actx query parsed CTX syntax, routed through the gateway, and returned structured results
5. actx verify validated the sidecar trust boundary

Next Steps

• Installation → — Docker Compose, from-source builds, Rust crates
• Configuration → — actx.yaml format, environment variables, secrets
• CTX Language → — learn the full query language