Skip to content
Petal Labs Petal Labs Docs

Getting Started

Getting Started with Cortex

Section titled “Getting Started with Cortex”

This guide walks you through installing Cortex, starting the MCP server, and using the core memory primitives.

Installation

Section titled “Installation”
Terminal window
curl -LO https://github.com/petal-labs/cortex/releases/latest/download/cortex_darwin_arm64.tar.gz
tar -xzf cortex_darwin_arm64.tar.gz
sudo mv cortex /usr/local/bin/

Verify the installation:

Terminal window
cortex --version

Quick Start

Section titled “Quick Start”

  1. Start the MCP Server

    The simplest way to run Cortex is with the default stdio transport:

    Terminal window
    cortex serve

    For web-based MCP clients, use SSE transport:

    Terminal window
    cortex serve --transport sse --port 9810

  2. Ingest Some Knowledge

    Add a document to the knowledge store:

    Terminal window
    cortex knowledge ingest \
      --collection docs \
      --title "Getting Started" \
      --file README.md

    Or ingest an entire directory:

    Terminal window
    cortex knowledge ingest-dir \
      --collection docs \
      --dir ./documentation \
      --pattern "*.md"

  3. Search Your Knowledge

    Find relevant information:

    Terminal window
    cortex knowledge search "how to configure"

    Use hybrid search for best results:

    Terminal window
    cortex knowledge search "authentication setup" --mode hybrid

  4. Store Workflow Context

    Save state that persists across runs:

    Terminal window
    cortex context set "project/config" '{"debug": true, "env": "dev"}'

    Retrieve it later:

    Terminal window
    cortex context get "project/config"

  5. Launch the TUI

    Explore your data interactively:

    Terminal window
    cortex tui

    Navigate with 1-5 to switch sections, j/k to move, Enter to select, q to quit.

Configuration

Section titled “Configuration”

Cortex works with sensible defaults, but you can customize behavior via ~/.cortex/config.yaml:

storage:
  backend: sqlite  # or "pgvector" for PostgreSQL
  data_dir: ~/.cortex/data


embedding:
  provider: openai          # openai, anthropic, voyageai, gemini, ollama
  model: text-embedding-3-small
  dimensions: 1536
  batch_size: 100
  cache_size: 1000


summarization:
  provider: anthropic       # LLM provider for conversation summaries
  model: claude-sonnet-4-6
  max_tokens: 1024


conversation:
  auto_summarize_threshold: 50
  semantic_search_enabled: true


knowledge:
  default_chunk_strategy: sentence
  default_chunk_max_tokens: 512
  default_chunk_overlap: 50


entity:
  extraction_mode: full     # off, sampled, whitelist, full
  extraction_model: claude-haiku-4-5


server:
  metrics_enabled: true
  metrics_port: 9811
  structured_logging: true

Storage Backends

Section titled “Storage Backends”

Zero-infrastructure setup using SQLite with the vec0 extension for vector operations:

storage:
  backend: sqlite
  data_dir: ~/.cortex/data

This is the recommended choice for local development and single-node deployments.

Embedding Configuration

Section titled “Embedding Configuration”

Cortex uses the Iris SDK to generate embeddings directly via provider APIs. No separate Iris service required.

embedding:
  provider: openai          # Provider: openai, anthropic, voyageai, gemini, ollama
  model: text-embedding-3-small
  dimensions: 1536
  batch_size: 100           # Texts per API call (reduces round trips)
  cache_size: 1000          # LRU cache entries (reduces API costs)

Environment Variables:

Set the API key for your chosen provider:

Terminal window
# For OpenAI (default)
export OPENAI_API_KEY="sk-..."


# For Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."


# For VoyageAI
export VOYAGEAI_API_KEY="..."


# For Gemini
export GEMINI_API_KEY="..."  # or GOOGLE_API_KEY


# For Ollama (local, no key required)
export OLLAMA_BASE_URL="http://localhost:11434"

Using with MCP Clients

Section titled “Using with MCP Clients”

Claude Desktop

Section titled “Claude Desktop”

Add Cortex to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop to discover Cortex tools.

Custom MCP Clients

Section titled “Custom MCP Clients”

For SSE-based clients, start Cortex with HTTP transport:

Terminal window
cortex serve --transport sse --port 9810

Connect your client to http://localhost:9810.

Namespaces

Section titled “Namespaces”

All data in Cortex is isolated by namespace. Use namespaces to separate:

  • Different projects or workflows
  • Development vs production data
  • Multi-tenant deployments
Terminal window
# Commands accept --namespace flag
cortex knowledge search "query" --namespace acme/research


# Restrict MCP server to a namespace
cortex serve --namespace acme/research

Default namespace is default when not specified.

Observability

Section titled “Observability”

Metrics

Section titled “Metrics”

Enable Prometheus metrics in your config:

server:
  metrics_enabled: true
  metrics_port: 9811

Access metrics at http://localhost:9811/metrics.

Key metrics include:

  • cortex_operations_total - Operations by primitive, action, namespace, status
  • cortex_operation_duration_seconds - Operation latency histogram
  • cortex_search_latency_seconds - Search-specific latency
  • cortex_embedding_requests_total - Embedding API calls

Health Check

Section titled “Health Check”
Terminal window
curl http://localhost:9811/health

Next Steps

Section titled “Next Steps”

Now that Cortex is running: