Fozikio

Deployment

cortex-engine works out of the box with SQLite and zero configuration. When you're ready for production — multi-device, multi-user, or cloud-hosted agents — switch to Firestore.

SQLite (Local / Development)

SQLite is the default. No setup required.

npx fozikio init my-agent
npx fozikio serve   # uses SQLite automatically

The database lives at .fozikio/cortex.db. Back it up like any important file.

Good for:

  • Local development
  • Single-agent personal setups
  • Agents running on one machine
  • Offline use

Not ideal for:

  • Multiple machines sharing agent memory
  • Production services with uptime requirements
  • Teams sharing a memory store

Firestore (Production)

Firestore provides real-time sync, cloud backup, and horizontal scale. It's the production-ready option.

Prerequisites

  1. A Google Cloud project with Firestore enabled (Native mode)
  2. A service account with roles/datastore.user permissions
  3. A service account key JSON file

Setup

1. Create a service account

In GCP Console: IAM & Admin → Service Accounts → Create. Grant the Cloud Datastore User role. Download a JSON key.

2. Configure cortex-engine

npx fozikio config --store firestore

Then set your environment variables:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GCLOUD_PROJECT="your-gcp-project-id"

Or set them in .fozikio/agent.yaml:

storage:
  provider: firestore
  project: your-gcp-project-id

3. Start the server

npx fozikio serve

Firestore collections are created automatically on first use.

Cloud Run Deployment

For a hosted MCP server accessible from any client:

Dockerfile

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
EXPOSE 8080
CMD ["npx", "fozikio", "serve", "--port", "8080", "--transport", "sse"]

Deploy

gcloud run deploy cortex-agent \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GCLOUD_PROJECT=your-project-id \
  --set-secrets GOOGLE_APPLICATION_CREDENTIALS=sa-key:latest

Connect your client

Update your .mcp.json to point to the Cloud Run URL:

{
  "mcpServers": {
    "cortex": {
      "url": "https://your-cloud-run-url.run.app/sse",
      "transport": "sse"
    }
  }
}

Environment Variables Reference

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_APPLICATION_CREDENTIALS | Firestore only | Path to GCP service account JSON | | GCLOUD_PROJECT | Firestore only | GCP project ID | | CORTEX_API_TOKEN | Optional | For cortex-telemetry hook — sends retrieval feedback to the API | | OPENAI_API_KEY | OpenAI embeddings only | OpenAI API key | | OLLAMA_HOST | Ollama (non-default host) | Defaults to http://localhost:11434 |

Additional variables may be required for specific LLM providers. See each provider's docs for details.

Migrating SQLite to Firestore

There's no automated migration tool yet. The practical path:

  1. Export your SQLite observations via query() — retrieve all nodes and re-observe them into the Firestore-backed store
  2. For large stores, use digest() to re-ingest content in batches
  3. Threads, journal entries, and beliefs need to be re-created manually or via a custom script

For most personal agents, starting fresh with Firestore is easier than migrating — let the agent rebuild its memory through use.

Production Checklist

  • Use --update-env-vars (not --set-env-vars) when updating Cloud Run environment variables — --set-env-vars replaces all vars
  • Back up your Firestore data via GCP export before any major migrations
  • Monitor sleep_pressure() — high pressure means consolidation isn't running often enough
  • Run npx fozikio health periodically to catch memory graph issues early
  • Set CORTEX_API_TOKEN if you want telemetry feedback to improve retrieval quality