Configuration

CLI target selection and SDK application configuration are separate. For ordinary CLI operations the order is explicit -d, project-scoped cortex use, configured default, then a sole configured deployment. Ambiguous/stale selections fail. CONVEX_URL and CONVEX_DEPLOY_KEY do not override deployment aliases. CLI 0.38.0 needs Node.js 24.15.0 and selects the project's Convex 1.46.0 executable.

Deployment configuration

cortex config show
cortex config list
cortex config path
cortex config add-deployment local --url http://127.0.0.1:3210 --json-only
cortex config set-path local .
cortex config set-key local
cortex use local
cortex status -d local --check
cortex doctor -d local --json

Use the actual selected deployment URL. set-key prompts privately; do not put administrator secrets in shell arguments/history. Configuration diagnostics redact secrets. Closest project configuration, explicit configuration sources and malformed-source refusal are preserved; read-only status/list/show does not prune registrations. Legacy enabled/app registry fields remain readable but no longer start a supervisor. config enable/disable refuse; select -d on the explicit native operation instead.

cortex dev -d local --local
cortex deploy -d local --local --dry-run
cortex convex logs -d local --lines 50
cortex convex env list -d local

--local asserts the chosen target kind; it does not switch a remote alias to another local deployment. Development runs one foreground child and Ctrl-C stops it. Application scripts and graph lifecycle run separately.

Ordinary SDK scope and maintenance

cortex memory list -d local --space agent-1 --scope-user user-123 --tenant team-a --format json
cortex users export user-123 -d local --tenant team-a --output user-data.json --format json
cortex users delete user-123 -d local --cascade --tenant team-a --dry-run

--scope-user/--tenant select caller data scope; they do not invent a JWT or administrator identity. Exports and cascade erasure require a separate fixed deployment administrator capability. Their omitted tenant means tenantless only, not every tenant. Domain views differ from complete supported-layer administrative user export. Erasure receipts disclose shared/foreign/provenance residuals, partial/unknown outcomes and verification; supported completion does not mean universal physical removal.

SDK graph configuration

import { Cortex } from "@cortexmemory/sdk";

const cortex = await Cortex.create({
  convexUrl: process.env.CONVEX_URL!,
  graphEnabled: false,
  logger: false,
});
try {
  // Use namespaced APIs with verified application scope.
} finally {
  cortex.close();
  await cortex.shutdown();
}

logger:false controls Convex transport logs. Explicit graph off prevents graph driver work. When enabled, the shared resolver selects one complete Neo4j or Memgraph tuple; missing/ambiguous providers and failed connections are errors. Manual adapter injection remains supported and borrowed adapters require explicit owner disposal. CLI ordinary graph policy is --graph-sync auto|off|required.

SDK init/install and template init call the same optional setup service:

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

Graph off needs no Docker. Local resources are project-owned and stop retains volumes. Existing-service configuration uses --graph-mode existing --graph-uri bolt://localhost:7687; credentials come from that provider's environment or a private 0600 file, not URI userinfo/argv passwords. Dry-run makes no configuration/service/dependency writes.

Next application credentials

The recognized Next apps compose app tables with SDK tables and keep native handlers internal. Vercel uses private appAccounts, appSessions, appAuthState, a first-setup token and an opaque HttpOnly eight-hour session. Chat uses persisted normal Auth.js guest/credentials and a fixed server tenant plus per-user memory space. Both need server-only CORTEX_APP_DEPLOYMENT_ADMIN_KEY, CONVEX_URL and exact CORTEX_APP_ORIGIN; Chat also needs AUTH_SECRET, AUTH_URL, CORTEX_APP_TENANT_ID. Use the same localhost host/port locally; never place keys in NEXT_PUBLIC_* variables. Follow the generated README for setup.

For deployment ZIPs use db export, not retired JSON backup/restore/clear. Lifecycle-bearing archives/targets refuse import before mutation; protected restore sessions are unsupported. See CLI reference.

Recall Limits Configuration

New in v0.31.0

Configure default limits for recall() operations to prevent Convex read limit errors in large memory spaces.

Parameter	Type	Required	Default	Description
CORTEX_RECALL_LIMIT_MEMORIES	number	No	20	Max vector memories to fetch per recall
CORTEX_RECALL_LIMIT_FACTS	number	No	15	Max facts to fetch per recall
CORTEX_RECALL_GRAPH_HOPS	number	No	2	Max graph traversal depth (0 to disable graph)
CORTEX_RECALL_GRAPH_ENTITIES_PER_HOP	number	No	5	Entities to expand per graph hop
CORTEX_RECALL_GRAPH_RESULTS_PER_ENTITY	number	No	3	Results fetched per entity from graph
CORTEX_RECALL_LIMIT_TOTAL	number	No	30	Final result cap after merge/rank