Maintenance & Operational Logic

Standardized commands are provided for maintaining the Cortex workspace, managing Kubernetes deployments via Skaffold, and verifying execution health across the AI subsystem.

---

1. Workspace Commands

All Cortex workspace commands are available from the monorepo root via pnpm.

Command	Description
pnpm cortex:dev	Start Cortex services in Kubernetes using Skaffold (file-sync + hot reload).
pnpm cortex:stop	Stop active Skaffold deployment and delete Kubernetes resources.
pnpm cortex:clean	Clean Skaffold build cache and remove stale Kubernetes resources.
pnpm cortex:up	Start Cortex services using Docker Compose (standalone, no Kubernetes).
pnpm cortex:down	Stop Docker Compose services.
pnpm cortex:logs	Stream aggregated logs from all Docker Compose services.
pnpm cortex:reset	Stop services, prune volumes, and restart from a clean state.
pnpm cortex:typecheck	Run TypeScript compiler checks across all Cortex packages.

---

2. Kubernetes / Skaffold Workflow

The primary development workflow uses Skaffold with Kustomize overlays located in cortex/infrastructure/kubernetes/.

Starting the Stack

pnpm cortex:dev

Skaffold builds all service images, applies the dev Kustomize overlay, and enables file-sync for fast iteration. Port-forwards are configured automatically for local development access.

Stopping the Stack

pnpm cortex:stop

Terminates the Skaffold process and removes all Kubernetes resources in the cortex namespace deployed by the current session.

Cleaning Build Cache

pnpm cortex:clean

Removes Skaffold image caches and cleans stale Kubernetes resources. Use this when images are in an inconsistent state or after a dependency upgrade.

---

3. Docker Compose Standalone Workflow

For environments where Kubernetes is not available, Docker Compose can manage the full Cortex stack independently:

pnpm cortex:up    # Start all services
pnpm cortex:down  # Stop all services
pnpm cortex:logs  # Tail logs from all containers
pnpm cortex:reset # Prune volumes and restart

---

4. Memory Subsystem Docs Sync

The memory-api service bundles the documentation corpus at build time and auto-syncs on startup. To trigger a manual re-sync of the knowledge base without restarting:

Via API

curl -X POST http://localhost:3006/api/memory/ingest/docs

When running in Kubernetes with pnpm cortex:dev, the memory-api service is port-forwarded to localhost:3006 automatically.

Via Dashboard

1. Open the Memory Web Dashboard at https://memory-dev.tupynambalucas.dev.
2. Navigate to the Graph Topology panel.
3. Click the Re-sync Docs button.

The sync is idempotent: only files with changed content hashes are re-embedded.

---

5. Workspace Structure

Path	Purpose
cortex/gateway/	AgentGateway configuration files (config.yaml).
cortex/mcp/guardrails/	ExtMCP gRPC guardrail service.
cortex/mcp/services/	Individual MCP adapter packages (firecrawl, memory, etc.).
cortex/memory/packages/core/	Shared TypeScript models and Zod schemas.
cortex/memory/services/api/	memory-api Fastify backend.
cortex/memory/services/web/	memory-web React dashboard.
cortex/infrastructure/kubernetes/	Skaffold configuration and Kustomize manifests.