Skip to main content

Five-Minute Quickstart

Use Node.js 24.15.0 or newer, CLI 0.38.0 and npm 12.2.0 or newer for the Basic app. Upgrade npm explicitly before installation; the CLI does not switch package managers. This example creates a Basic application with anonymous local Convex setup; optional graph setup is explicit.

npm install -g @cortexmemory/cli@0.38.0
cortex init my-agent --template basic --local --yes --graph none
cd my-agent

Keep the generated .env.local and set your selected deployment's actual URL, private deployment administrator key, and provider key. Basic needs CORTEX_APP_DEPLOYMENT_ADMIN_KEY or a preserved CLI-generated CONVEX_DEPLOY_KEY; a URL alone does not authorize the internal backend. The demo uses echo responses without OpenAI; embeddings and extraction need provider configuration.

CONVEX_URL=http://127.0.0.1:3210
CORTEX_APP_DEPLOYMENT_ADMIN_KEY=your-private-deployment-admin-key
OPENAI_API_KEY=your-private-openai-key
CORTEX_GRAPH_SYNC=false

Register the actual URL from local setup, associate this project, then run one foreground backend:

cortex config add-deployment local --url http://127.0.0.1:3210 --json-only
cortex config set-path local .
cortex dev -d local --local

In another terminal run npm start for terminal chat or npm run server for the Hono HTTP interface. Ctrl-C stops the foreground child. npm run build compiles only; it does not deploy. There are no global app supervisors or port-kill controls.

Backend-only or a Next application​

cortex init backend --template none --local --yes --graph none
cortex templates init demo --template vercel-ai-quickstart --template-version 1.2.0 --catalog-version 1.1.0 --yes --graph none
cortex templates init chat --template chat-sdk --template-version 1.2.0 --catalog-version 1.1.0 --yes --graph none

Use the generated app README for its private composed backend and credentials. Vercel uses npm and server-verified opaque sessions; Chat uses pnpm 10.33.0 and normal Auth.js guest/credentials sessions. Match localhost, including the port, across browser and app/auth origins. Deployment administrator keys are server-only.

Optional graph​

SDK init/install and template init both accept graph choices through the same service. An existing project can use:

cortex graph setup . --graph neo4j --graph-mode local --yes
cortex graph status .
cortex graph stop .
cortex graph start .

Memgraph is also supported. Local resources belong to the selected project and stop preserves volumes. Graph off needs no Docker. An existing service uses --graph-mode existing --graph-uri bolt://localhost:7687 with private credentials; the CLI probes it without graph data mutation.

Inspect and update​

cortex doctor -d local --json
cortex status -d local --check
cortex schema status .
cortex update -d local --sdk-version 0.38.0 --convex-version 1.46.0 --sync --dry-run

SDK updates do not overwrite app/template files. Template updates require the separate templates update channel and recorded ownership. An interrupted update can restore journaled files with templates update <directory> --recover; inspect the original receipt and manually reconcile external effects before acknowledging them with --recover --yes. Recovery never replays dependency, backend or graph work. For a recognized old Next shim lacking MutationCtx, apply the app/template update before SDK backend synchronization. See configuration and the CLI reference for scope, migrations and native ZIP refusal boundaries.